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">
|
||||
|
|
@ -1732,67 +1732,78 @@ January 8 04:05:06 1999 PST
|
|||
</sect1>
|
||||
|
||||
<sect1 id="net-types">
|
||||
<title>IP Version 4 Networks and Host Addresses</title>
|
||||
<title>Network Address Data Types</title>
|
||||
|
||||
<para>
|
||||
The <type>cidr</type> type stores networks specified
|
||||
in <acronym>CIDR</acronym> (Classless Inter-Domain Routing) notation.
|
||||
The <type>inet</type> type stores hosts and networks in CIDR notation using a simple
|
||||
variation in representation to represent simple host TCP/IP addresses.
|
||||
</para>
|
||||
<productname>Postgres</> offers data types to store IP and MAC
|
||||
addresses. It is preferrable to use these types over plain text
|
||||
types, because these types offer input error checking and several
|
||||
specialized operators and functions.
|
||||
|
||||
<para>
|
||||
<table tocentry="1">
|
||||
<title><productname>Postgres</productname>IP Version 4 Types</title>
|
||||
<titleabbrev>IPV4</titleabbrev>
|
||||
<table tocentry="1" id="net-types-table">
|
||||
<title>Network Address Data Types</title>
|
||||
<tgroup cols="4">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>IPV4 Type</entry>
|
||||
<entry>Name</entry>
|
||||
<entry>Storage</entry>
|
||||
<entry>Description</entry>
|
||||
<entry>Range</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
|
||||
<row>
|
||||
<entry>cidr</entry>
|
||||
<entry>variable</entry>
|
||||
<entry>CIDR networks</entry>
|
||||
<entry>Valid IPV4 CIDR blocks</entry>
|
||||
<entry>11 bytes</entry>
|
||||
<entry>IP networks</entry>
|
||||
<entry>valid IPv4 networks</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>inet</entry>
|
||||
<entry>variable</entry>
|
||||
<entry>nets and hosts</entry>
|
||||
<entry>Valid IPV4 CIDR blocks</entry>
|
||||
<entry>11 bytes</entry>
|
||||
<entry>IP hosts and networks</entry>
|
||||
<entry>valid IPv4 hosts</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>macaddr</entry>
|
||||
<entry>6 bytes</entry>
|
||||
<entry>MAC addresses</entry>
|
||||
<entry>customary formats</entry>
|
||||
</row>
|
||||
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
|
||||
<sect2>
|
||||
<title>CIDR</title>
|
||||
<para>
|
||||
IP v6 is not supported, yet.
|
||||
</para>
|
||||
|
||||
|
||||
<sect2 id="cidr-type">
|
||||
<title><type>cidr</></title>
|
||||
|
||||
<para>
|
||||
The <type>cidr</type> type holds a CIDR network.
|
||||
The format for specifying classless networks is
|
||||
<replaceable class="parameter">x.x.x.x/y</replaceable>
|
||||
where <replaceable class="parameter">x.x.x.x</replaceable> is the
|
||||
network and <replaceable class="parameter">/y</replaceable> is
|
||||
the number of bits in the netmask.
|
||||
If <replaceable class="parameter">/y</replaceable> omitted, it is
|
||||
calculated using assumptions from
|
||||
the older classfull naming system except that it is extended to include at least
|
||||
all of the octets in the input.
|
||||
The <type>cidr</type> type holds an IP network. The format for
|
||||
specifying classless networks is <replaceable
|
||||
class="parameter">x.x.x.x/y</> where <replaceable
|
||||
class="parameter">x.x.x.x</> is the network and <replaceable
|
||||
class="parameter">y</> is the number of bits in the netmask. If
|
||||
<replaceable class="parameter">y</> omitted, it is calculated
|
||||
using assumptions from the older classfull naming system except
|
||||
that it is extended to include at least all of the octets in the
|
||||
input.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Here are some examples:
|
||||
|
||||
<table tocentry="1">
|
||||
<title><productname>Postgres</productname>IP Types Examples</title>
|
||||
<title><type>cidr</> Type Input Examples</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
|
|
@ -1801,6 +1812,14 @@ January 8 04:05:06 1999 PST
|
|||
</row>
|
||||
</thead>
|
||||
<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>
|
||||
<entry>192.168.1</entry>
|
||||
<entry>192.168.1/24</entry>
|
||||
|
|
@ -1839,34 +1858,48 @@ January 8 04:05:06 1999 PST
|
|||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title id="inet-type"><type>inet</type></title>
|
||||
<sect2 id="inet-type">
|
||||
<title><type>inet</type></title>
|
||||
|
||||
<para>
|
||||
The <type>inet</type> type is designed to hold, in one field, all of the information
|
||||
about a host including the CIDR-style subnet that it is in.
|
||||
Note that if you want to store proper CIDR networks,
|
||||
you should use the <type>cidr</type> type.
|
||||
The <type>inet</type> type is similar to the <type>cidr</type>
|
||||
type except that the bits in the
|
||||
host part can be non-zero.
|
||||
Functions exist to extract the various elements of the field.
|
||||
The <type>inet</type> type holds an IP host address, and
|
||||
optionally the identity of the subnet it is in, all in one field.
|
||||
Note that if you want to store networks only, you should use the
|
||||
<type>cidr</type> type. The <type>inet</type> type is similar to
|
||||
the <type>cidr</type> type except that the bits in the host part
|
||||
can be non-zero. Functions exist to extract the various elements
|
||||
of the field.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The input format for this function is
|
||||
<replaceable class="parameter">x.x.x.x/y</replaceable>
|
||||
where <replaceable class="parameter">x.x.x.x</replaceable> is
|
||||
an internet host and <replaceable class="parameter">y</replaceable>
|
||||
is the number of bits in the netmask.
|
||||
If the <replaceable class="parameter">/y</replaceable> part is left off,
|
||||
it is treated as <literal>/32</literal>.
|
||||
On output, the <replaceable class="parameter">/y</replaceable> part is not printed
|
||||
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.
|
||||
The input format for this type is <replaceable
|
||||
class="parameter">x.x.x.x/y</replaceable> where <replaceable
|
||||
class="parameter">x.x.x.x</replaceable> is an internet host and
|
||||
<replaceable class="parameter">y</replaceable> is the number of
|
||||
bits in the netmask. If the <replaceable
|
||||
class="parameter">y</replaceable> part is left off, then the
|
||||
netmask is 32 and you are effectively only storing the address of
|
||||
a single host.
|
||||
</para>
|
||||
</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>
|
||||
|
||||
</chapter>
|
||||
|
|
|
|||
|
|
@ -945,17 +945,18 @@
|
|||
|
||||
<listitem>
|
||||
<para>
|
||||
A double quote ('"') between quotation marks is skipped and is not parsed.
|
||||
If you want to write a double quote to output you must preceed
|
||||
it with a double backslash (<literal>'\\"</literal>), for
|
||||
example <literal>'\\"YYYY Month\\"'</literal>.
|
||||
A double quote (<quote><literal>"</literal></quote>) between
|
||||
quotation marks is skipped and is not parsed. If you want to
|
||||
write a double quote to output you must preceed it with a
|
||||
double backslash (<literal>'\\"</literal>), for example
|
||||
<literal>'\\"YYYY Month\\"'</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
<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
|
||||
guaranteed that it will not be interpreted as a template
|
||||
keyword (example: <literal>'"Hello Year: "YYYY'</literal>).
|
||||
|
|
@ -1473,12 +1474,12 @@ Not defined by this name. Implements the intersection operator '#'
|
|||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="cidr-functions">
|
||||
<title>IP V4 Functions</title>
|
||||
<sect1 id="net-functions">
|
||||
<title>Network Address Type Functions</title>
|
||||
|
||||
<para>
|
||||
<table tocentry="1">
|
||||
<title><productname>Postgres</productname>IP V4 Functions</title>
|
||||
<table tocentry="1" id="cidr-inet-functions">
|
||||
<title><type>cidr</> and <type>inet</> Functions</title>
|
||||
<tgroup cols="4">
|
||||
<thead>
|
||||
<row>
|
||||
|
|
@ -1509,13 +1510,13 @@ Not defined by this name. Implements the intersection operator '#'
|
|||
</row>
|
||||
<row>
|
||||
<entry>masklen(cidr)</entry>
|
||||
<entry>int4</entry>
|
||||
<entry>integer</entry>
|
||||
<entry>calculate netmask length</entry>
|
||||
<entry>masklen('192.168.1.5/24')</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>masklen(inet)</entry>
|
||||
<entry>int4</entry>
|
||||
<entry>integer</entry>
|
||||
<entry>calculate netmask length</entry>
|
||||
<entry>masklen('192.168.1.5/24')</entry>
|
||||
</row>
|
||||
|
|
@ -1525,9 +1526,21 @@ Not defined by this name. Implements the intersection operator '#'
|
|||
<entry>construct netmask as text</entry>
|
||||
<entry>netmask('192.168.1.5/24')</entry>
|
||||
</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>
|
||||
</tgroup>
|
||||
</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>
|
||||
|
||||
</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">
|
||||
|
|
@ -722,13 +722,15 @@ logical union
|
|||
</Para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="cidr-operators">
|
||||
<title>IP V4 CIDR Operators</title>
|
||||
|
||||
<Para>
|
||||
<TABLE TOCENTRY="1">
|
||||
<TITLE><ProductName>Postgres</ProductName>IP V4 CIDR Operators</TITLE>
|
||||
<TITLEABBREV>Operators</TITLEABBREV>
|
||||
<sect1 id="net-operators">
|
||||
<title>Network Address Type Operators</title>
|
||||
|
||||
<sect2 id="cidr-operators">
|
||||
<title><type>cidr</> Operators</title>
|
||||
|
||||
<table tocentry="1" id="cidr-operators-table">
|
||||
<title><type>cidr</> Operators</title>
|
||||
<TGROUP COLS="3">
|
||||
<THEAD>
|
||||
<ROW>
|
||||
|
|
@ -791,16 +793,13 @@ logical union
|
|||
</TBODY>
|
||||
</TGROUP>
|
||||
</TABLE>
|
||||
</Para>
|
||||
</sect1>
|
||||
</sect2>
|
||||
|
||||
<sect1 id="inet-operators">
|
||||
<title>IP V4 INET Operators</title>
|
||||
<sect2 id="inet-operators">
|
||||
<title><type>inet</> Operators</title>
|
||||
|
||||
<Para>
|
||||
<TABLE TOCENTRY="1">
|
||||
<TITLE><ProductName>Postgres</ProductName>IP V4 INET Operators</TITLE>
|
||||
<TITLEABBREV>Operators</TITLEABBREV>
|
||||
<table tocentry="1" id="inet-operators-table">
|
||||
<title><type>inet</> Operators</title>
|
||||
<TGROUP COLS="3">
|
||||
<THEAD>
|
||||
<ROW>
|
||||
|
|
@ -863,7 +862,18 @@ logical union
|
|||
</TBODY>
|
||||
</TGROUP>
|
||||
</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>
|
||||
|
||||
</Chapter>
|
||||
|
|
|
|||
Loading…
Reference in New Issue