From baa3a09b5fbd14cf2b6e63b7ebf1592266458e2b Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Wed, 4 Oct 2000 15:47:45 +0000
Subject: [PATCH] Convert macaddr documentation to DocBook, update outdated
information.
---
doc/README.inet | 74 --------------------
doc/src/sgml/datatype.sgml | 137 +++++++++++++++++++++++--------------
doc/src/sgml/func.sgml | 35 +++++++---
doc/src/sgml/oper.sgml | 42 +++++++-----
4 files changed, 135 insertions(+), 153 deletions(-)
delete mode 100644 doc/README.inet
diff --git a/doc/README.inet b/doc/README.inet
deleted file mode 100644
index 69df7dfc2ca..00000000000
--- a/doc/README.inet
+++ /dev/null
@@ -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).
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index a693e772086..f3e7aa83abf 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -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>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 01764b45f2e..c51e8905e10 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -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>
diff --git a/doc/src/sgml/oper.sgml b/doc/src/sgml/oper.sgml
index 112c6f2f3f8..495f3caefc6 100644
--- a/doc/src/sgml/oper.sgml
+++ b/doc/src/sgml/oper.sgml
@@ -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>
--
GitLab