Convert macaddr documentation to DocBook, update outdated information.
This commit is contained in:
Peter Eisentraut
parent
2d5ff2f9a0
commit
baa3a09b5f
|
|
@ -1,74 +0,0 @@
|
||||||
PostgreSQL type extensions for IP and MAC addresses.
|
|
||||||
---------------------------------------------------
|
|
||||||
|
|
||||||
$Id: README.inet,v 1.1 1998/10/08 00:19:32 momjian Exp $
|
|
||||||
|
|
||||||
I needed to record IP and MAC level ethernet addresses in a data
|
|
||||||
base, and I really didn't want to store them as plain strings, with
|
|
||||||
no enforced error checking, so I put together the accompanying code
|
|
||||||
as my first experiment with adding a data type to PostgreSQL. I
|
|
||||||
then thought that this might be useful to others, both directly and
|
|
||||||
as a very simple example of how to do this sort of thing, so I
|
|
||||||
submitted it to the PostgreSQL project for inclusion in the contrib
|
|
||||||
directory. Since then, that directory has been modified to contain
|
|
||||||
Aleksei Roudnev's implementation, which is based on mine.
|
|
||||||
|
|
||||||
For those who have seen my previous contribution of these types, note
|
|
||||||
that much has changed: I've modified the IP address type to work the
|
|
||||||
way Paul Vixie did with his CIDR type. In fact, I've pretty much just
|
|
||||||
stolen his solution, modifying it into my framework in such a way as
|
|
||||||
to facilitate the addition of IPV6 handling code in the future. I've
|
|
||||||
pretty much ignored Aleksei's C code, but I've added his SQL code to
|
|
||||||
enter the necessary operators into the various system tables needed to
|
|
||||||
make the types indexable.
|
|
||||||
|
|
||||||
IP addresses are implemented as a struct of fixed in-memory length,
|
|
||||||
but variable on-disk storage size. For IPV4, it contains the address
|
|
||||||
family (AF_INET), the CIDR prefix length and four byte address. For
|
|
||||||
IPV6, the address family will be different, and the address longer.
|
|
||||||
|
|
||||||
The external representation of an IP address generally looks like
|
|
||||||
'158.37.96.15/32'. This address happens to be part of a subnet where
|
|
||||||
I work; '158.37.96.0/24', which itself is a part of the larger subnet
|
|
||||||
allocated to our site, which is '158.37.96.0/21', which again, if you
|
|
||||||
go by the old book, is part of the class "B" net '158.37.0.0/16'.
|
|
||||||
|
|
||||||
Input and output functions are supplied, along with the "normal" <,
|
|
||||||
<=, =, >=, > and <> operators, which all do what you expect. In
|
|
||||||
addition, there are operators to check for networks or addresses being
|
|
||||||
subnets of or addresses contained within other networks. << tests
|
|
||||||
whether the left operand is contained within the right, <<= includes
|
|
||||||
equality, >> and >>= do the same things the opposite way.
|
|
||||||
|
|
||||||
The input and output functions use routines from Paul Vixie's BIND,
|
|
||||||
and I've snarfed the source files inet_net_ntop.c and inet_net_pton.c
|
|
||||||
directly from a recent distribution of that code. They are included
|
|
||||||
here to avoid the need to fetch and install the BIND libraries to be
|
|
||||||
able to use this code. IANAL, but it looks from the copyright
|
|
||||||
messages in the files as if this should be acceptable. Read the
|
|
||||||
documentation in inet_net_pton.c to see the legal input formats.
|
|
||||||
|
|
||||||
MAC level ethernet addresses are implemented as a 6 byte struct that
|
|
||||||
contains the address as unsigned chars. Several input forms are
|
|
||||||
accepted; the following are all the same address: '08002b:010203',
|
|
||||||
'08002b-010203', '0800.2b01.0203', '08-00-2b-01-02-03' and
|
|
||||||
'08:00:2b:01:02:03'. Upper and lower case is accepted for the digits
|
|
||||||
'a' through 'f'. Output is always in the latter of the given forms.
|
|
||||||
|
|
||||||
As with IP addresses, input and output functions are supplied as well
|
|
||||||
as the "normal" operators, which do what you expect. As an extra
|
|
||||||
feature, a function macaddr_manuf() is defined, which returns the name
|
|
||||||
of the manufacturer as a string. This is currently held in a
|
|
||||||
hard-coded struct internal to the C module -- it might be smarter to
|
|
||||||
put this information into an actual data base table, and look up the
|
|
||||||
manufacturer there.
|
|
||||||
|
|
||||||
Many thanks to Aleksei Roudnev and Paul Vixie for their fine work!
|
|
||||||
|
|
||||||
I don't know what changes are needed to the Makefile for other systems
|
|
||||||
than the one I'm running (NetBSD 1.3), but anyway: to install on a BSD
|
|
||||||
system: fix the path names in the Makefile if you need to, then make,
|
|
||||||
make install, slurp the SQL files into psql or whatever, and you're
|
|
||||||
off. Enjoy!
|
|
||||||
|
|
||||||
Bergen, Norway, 1998-08-09, Tom Ivar Helbekkmo (tih@nhh.no).
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.37 2000/09/29 20:21:33 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.38 2000/10/04 15:47:45 petere Exp $
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<chapter id="datatype">
|
<chapter id="datatype">
|
||||||
|
|
@ -1732,67 +1732,78 @@ January 8 04:05:06 1999 PST
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="net-types">
|
<sect1 id="net-types">
|
||||||
<title>IP Version 4 Networks and Host Addresses</title>
|
<title>Network Address Data Types</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <type>cidr</type> type stores networks specified
|
<productname>Postgres</> offers data types to store IP and MAC
|
||||||
in <acronym>CIDR</acronym> (Classless Inter-Domain Routing) notation.
|
addresses. It is preferrable to use these types over plain text
|
||||||
The <type>inet</type> type stores hosts and networks in CIDR notation using a simple
|
types, because these types offer input error checking and several
|
||||||
variation in representation to represent simple host TCP/IP addresses.
|
specialized operators and functions.
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<table tocentry="1" id="net-types-table">
|
||||||
<table tocentry="1">
|
<title>Network Address Data Types</title>
|
||||||
<title><productname>Postgres</productname>IP Version 4 Types</title>
|
|
||||||
<titleabbrev>IPV4</titleabbrev>
|
|
||||||
<tgroup cols="4">
|
<tgroup cols="4">
|
||||||
<thead>
|
<thead>
|
||||||
<row>
|
<row>
|
||||||
<entry>IPV4 Type</entry>
|
<entry>Name</entry>
|
||||||
<entry>Storage</entry>
|
<entry>Storage</entry>
|
||||||
<entry>Description</entry>
|
<entry>Description</entry>
|
||||||
<entry>Range</entry>
|
<entry>Range</entry>
|
||||||
</row>
|
</row>
|
||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry>cidr</entry>
|
<entry>cidr</entry>
|
||||||
<entry>variable</entry>
|
<entry>11 bytes</entry>
|
||||||
<entry>CIDR networks</entry>
|
<entry>IP networks</entry>
|
||||||
<entry>Valid IPV4 CIDR blocks</entry>
|
<entry>valid IPv4 networks</entry>
|
||||||
</row>
|
</row>
|
||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry>inet</entry>
|
<entry>inet</entry>
|
||||||
<entry>variable</entry>
|
<entry>11 bytes</entry>
|
||||||
<entry>nets and hosts</entry>
|
<entry>IP hosts and networks</entry>
|
||||||
<entry>Valid IPV4 CIDR blocks</entry>
|
<entry>valid IPv4 hosts</entry>
|
||||||
</row>
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>macaddr</entry>
|
||||||
|
<entry>6 bytes</entry>
|
||||||
|
<entry>MAC addresses</entry>
|
||||||
|
<entry>customary formats</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
</tbody>
|
</tbody>
|
||||||
</tgroup>
|
</tgroup>
|
||||||
</table>
|
</table>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<sect2>
|
<para>
|
||||||
<title>CIDR</title>
|
IP v6 is not supported, yet.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
|
||||||
|
<sect2 id="cidr-type">
|
||||||
|
<title><type>cidr</></title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <type>cidr</type> type holds a CIDR network.
|
The <type>cidr</type> type holds an IP network. The format for
|
||||||
The format for specifying classless networks is
|
specifying classless networks is <replaceable
|
||||||
<replaceable class="parameter">x.x.x.x/y</replaceable>
|
class="parameter">x.x.x.x/y</> where <replaceable
|
||||||
where <replaceable class="parameter">x.x.x.x</replaceable> is the
|
class="parameter">x.x.x.x</> is the network and <replaceable
|
||||||
network and <replaceable class="parameter">/y</replaceable> is
|
class="parameter">y</> is the number of bits in the netmask. If
|
||||||
the number of bits in the netmask.
|
<replaceable class="parameter">y</> omitted, it is calculated
|
||||||
If <replaceable class="parameter">/y</replaceable> omitted, it is
|
using assumptions from the older classfull naming system except
|
||||||
calculated using assumptions from
|
that it is extended to include at least all of the octets in the
|
||||||
the older classfull naming system except that it is extended to include at least
|
input.
|
||||||
all of the octets in the input.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Here are some examples:
|
Here are some examples:
|
||||||
|
|
||||||
<table tocentry="1">
|
<table tocentry="1">
|
||||||
<title><productname>Postgres</productname>IP Types Examples</title>
|
<title><type>cidr</> Type Input Examples</title>
|
||||||
<tgroup cols="2">
|
<tgroup cols="2">
|
||||||
<thead>
|
<thead>
|
||||||
<row>
|
<row>
|
||||||
|
|
@ -1801,6 +1812,14 @@ January 8 04:05:06 1999 PST
|
||||||
</row>
|
</row>
|
||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry>192.168.100.128/25</entry>
|
||||||
|
<entry>192.168.100.128/25</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>192.168/25</entry>
|
||||||
|
<entry>192.168.0.0/25</entry>
|
||||||
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry>192.168.1</entry>
|
<entry>192.168.1</entry>
|
||||||
<entry>192.168.1/24</entry>
|
<entry>192.168.1/24</entry>
|
||||||
|
|
@ -1839,34 +1858,48 @@ January 8 04:05:06 1999 PST
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2 id="inet-type">
|
||||||
<title id="inet-type"><type>inet</type></title>
|
<title><type>inet</type></title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <type>inet</type> type is designed to hold, in one field, all of the information
|
The <type>inet</type> type holds an IP host address, and
|
||||||
about a host including the CIDR-style subnet that it is in.
|
optionally the identity of the subnet it is in, all in one field.
|
||||||
Note that if you want to store proper CIDR networks,
|
Note that if you want to store networks only, you should use the
|
||||||
you should use the <type>cidr</type> type.
|
<type>cidr</type> type. The <type>inet</type> type is similar to
|
||||||
The <type>inet</type> type is similar to the <type>cidr</type>
|
the <type>cidr</type> type except that the bits in the host part
|
||||||
type except that the bits in the
|
can be non-zero. Functions exist to extract the various elements
|
||||||
host part can be non-zero.
|
of the field.
|
||||||
Functions exist to extract the various elements of the field.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The input format for this function is
|
The input format for this type is <replaceable
|
||||||
<replaceable class="parameter">x.x.x.x/y</replaceable>
|
class="parameter">x.x.x.x/y</replaceable> where <replaceable
|
||||||
where <replaceable class="parameter">x.x.x.x</replaceable> is
|
class="parameter">x.x.x.x</replaceable> is an internet host and
|
||||||
an internet host and <replaceable class="parameter">y</replaceable>
|
<replaceable class="parameter">y</replaceable> is the number of
|
||||||
is the number of bits in the netmask.
|
bits in the netmask. If the <replaceable
|
||||||
If the <replaceable class="parameter">/y</replaceable> part is left off,
|
class="parameter">y</replaceable> part is left off, then the
|
||||||
it is treated as <literal>/32</literal>.
|
netmask is 32 and you are effectively only storing the address of
|
||||||
On output, the <replaceable class="parameter">/y</replaceable> part is not printed
|
a single host.
|
||||||
if it is <literal>/32</literal>.
|
|
||||||
This allows the type to be used as a straight host type by just leaving off
|
|
||||||
the bits part.
|
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 id="macaddr-type">
|
||||||
|
<title><type>macaddr</></>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The <type>macaddr</> type stores MAC addresses, i.e., Ethernet
|
||||||
|
card hardware addresses (although MAC addresses are used for
|
||||||
|
other purposes as well). Input is accepted in various customary
|
||||||
|
formats, including <literal>'08002b:010203'</>,
|
||||||
|
<literal>'08002b-010203'</>, <literal>'0800.2b01.0203'</>,
|
||||||
|
<literal>'08-00-2b-01-02-03'</>, and
|
||||||
|
<literal>'08:00:2b:01:02:03'</>, which would all specify the same
|
||||||
|
address. Upper and lower case is accepted for the digits
|
||||||
|
<literal>a</> through <literal>f</>. Output is always in the
|
||||||
|
latter of the given forms.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
||||||
|
|
@ -945,17 +945,18 @@
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
A double quote ('"') between quotation marks is skipped and is not parsed.
|
A double quote (<quote><literal>"</literal></quote>) between
|
||||||
If you want to write a double quote to output you must preceed
|
quotation marks is skipped and is not parsed. If you want to
|
||||||
it with a double backslash (<literal>'\\"</literal>), for
|
write a double quote to output you must preceed it with a
|
||||||
example <literal>'\\"YYYY Month\\"'</literal>.
|
double backslash (<literal>'\\"</literal>), for example
|
||||||
|
<literal>'\\"YYYY Month\\"'</literal>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>to_char</function> supports text without a leading
|
<function>to_char</function> supports text without a leading
|
||||||
double quote ('"'), but any string
|
double quote but any string
|
||||||
between a quotation marks is rapidly handled and you are
|
between a quotation marks is rapidly handled and you are
|
||||||
guaranteed that it will not be interpreted as a template
|
guaranteed that it will not be interpreted as a template
|
||||||
keyword (example: <literal>'"Hello Year: "YYYY'</literal>).
|
keyword (example: <literal>'"Hello Year: "YYYY'</literal>).
|
||||||
|
|
@ -1473,12 +1474,12 @@ Not defined by this name. Implements the intersection operator '#'
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="cidr-functions">
|
<sect1 id="net-functions">
|
||||||
<title>IP V4 Functions</title>
|
<title>Network Address Type Functions</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<table tocentry="1">
|
<table tocentry="1" id="cidr-inet-functions">
|
||||||
<title><productname>Postgres</productname>IP V4 Functions</title>
|
<title><type>cidr</> and <type>inet</> Functions</title>
|
||||||
<tgroup cols="4">
|
<tgroup cols="4">
|
||||||
<thead>
|
<thead>
|
||||||
<row>
|
<row>
|
||||||
|
|
@ -1509,13 +1510,13 @@ Not defined by this name. Implements the intersection operator '#'
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry>masklen(cidr)</entry>
|
<entry>masklen(cidr)</entry>
|
||||||
<entry>int4</entry>
|
<entry>integer</entry>
|
||||||
<entry>calculate netmask length</entry>
|
<entry>calculate netmask length</entry>
|
||||||
<entry>masklen('192.168.1.5/24')</entry>
|
<entry>masklen('192.168.1.5/24')</entry>
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry>masklen(inet)</entry>
|
<entry>masklen(inet)</entry>
|
||||||
<entry>int4</entry>
|
<entry>integer</entry>
|
||||||
<entry>calculate netmask length</entry>
|
<entry>calculate netmask length</entry>
|
||||||
<entry>masklen('192.168.1.5/24')</entry>
|
<entry>masklen('192.168.1.5/24')</entry>
|
||||||
</row>
|
</row>
|
||||||
|
|
@ -1525,9 +1526,21 @@ Not defined by this name. Implements the intersection operator '#'
|
||||||
<entry>construct netmask as text</entry>
|
<entry>construct netmask as text</entry>
|
||||||
<entry>netmask('192.168.1.5/24')</entry>
|
<entry>netmask('192.168.1.5/24')</entry>
|
||||||
</row>
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>trunc(macaddr)</entry>
|
||||||
|
<entry>macaddr</entry>
|
||||||
|
<entry>set last 3 bytes to zero</entry>
|
||||||
|
<entry>trunc(macaddr '12:34:56:78:90:ab')</entry>
|
||||||
|
</row>
|
||||||
</tbody>
|
</tbody>
|
||||||
</tgroup>
|
</tgroup>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
|
The function <function>trunc</>(<type>macaddr</>) returns a MAC
|
||||||
|
address with the last 3 bytes set to 0. This can be used to
|
||||||
|
associate the remaining prefix with a manufacturer. The directory
|
||||||
|
<filename>contrib/mac</> in the source distribution contains some
|
||||||
|
utilities to create and maintain such an association table.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/oper.sgml,v 1.19 2000/09/29 20:21:34 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/oper.sgml,v 1.20 2000/10/04 15:47:45 petere Exp $
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<Chapter Id="operators">
|
<Chapter Id="operators">
|
||||||
|
|
@ -722,13 +722,15 @@ logical union
|
||||||
</Para>
|
</Para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="cidr-operators">
|
|
||||||
<title>IP V4 CIDR Operators</title>
|
|
||||||
|
|
||||||
<Para>
|
<sect1 id="net-operators">
|
||||||
<TABLE TOCENTRY="1">
|
<title>Network Address Type Operators</title>
|
||||||
<TITLE><ProductName>Postgres</ProductName>IP V4 CIDR Operators</TITLE>
|
|
||||||
<TITLEABBREV>Operators</TITLEABBREV>
|
<sect2 id="cidr-operators">
|
||||||
|
<title><type>cidr</> Operators</title>
|
||||||
|
|
||||||
|
<table tocentry="1" id="cidr-operators-table">
|
||||||
|
<title><type>cidr</> Operators</title>
|
||||||
<TGROUP COLS="3">
|
<TGROUP COLS="3">
|
||||||
<THEAD>
|
<THEAD>
|
||||||
<ROW>
|
<ROW>
|
||||||
|
|
@ -791,16 +793,13 @@ logical union
|
||||||
</TBODY>
|
</TBODY>
|
||||||
</TGROUP>
|
</TGROUP>
|
||||||
</TABLE>
|
</TABLE>
|
||||||
</Para>
|
</sect2>
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="inet-operators">
|
<sect2 id="inet-operators">
|
||||||
<title>IP V4 INET Operators</title>
|
<title><type>inet</> Operators</title>
|
||||||
|
|
||||||
<Para>
|
<table tocentry="1" id="inet-operators-table">
|
||||||
<TABLE TOCENTRY="1">
|
<title><type>inet</> Operators</title>
|
||||||
<TITLE><ProductName>Postgres</ProductName>IP V4 INET Operators</TITLE>
|
|
||||||
<TITLEABBREV>Operators</TITLEABBREV>
|
|
||||||
<TGROUP COLS="3">
|
<TGROUP COLS="3">
|
||||||
<THEAD>
|
<THEAD>
|
||||||
<ROW>
|
<ROW>
|
||||||
|
|
@ -863,7 +862,18 @@ logical union
|
||||||
</TBODY>
|
</TBODY>
|
||||||
</TGROUP>
|
</TGROUP>
|
||||||
</TABLE>
|
</TABLE>
|
||||||
</Para>
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 id="macaddr-operators">
|
||||||
|
<title><type>macaddr</> Operators</>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The <type>macaddr</> type supports the standard relational
|
||||||
|
operators (<literal>></>, <literal><=</>, etc.) for
|
||||||
|
lexicographical ordering.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
</Chapter>
|
</Chapter>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue