diff --git a/doc/README.inet b/doc/README.inet deleted file mode 100644 index 69df7dfc2c..0000000000 --- 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 a693e77208..f3e7aa83ab 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ @@ -1732,67 +1732,78 @@ January 8 04:05:06 1999 PST - IP Version 4 Networks and Host Addresses + Network Address Data Types - The cidr type stores networks specified - in CIDR (Classless Inter-Domain Routing) notation. - The inet type stores hosts and networks in CIDR notation using a simple - variation in representation to represent simple host TCP/IP addresses. - + 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. - - - <productname>Postgres</productname>IP Version 4 Types - IPV4 +
+ Network Address Data Types - IPV4 Type + Name Storage Description Range + cidr - variable - CIDR networks - Valid IPV4 CIDR blocks + 11 bytes + IP networks + valid IPv4 networks + inet - variable - nets and hosts - Valid IPV4 CIDR blocks + 11 bytes + IP hosts and networks + valid IPv4 hosts + + + macaddr + 6 bytes + MAC addresses + customary formats + +
- - CIDR + + IP v6 is not supported, yet. + + + + + <type>cidr</> - The cidr type holds a CIDR network. - The format for specifying classless networks is - x.x.x.x/y - where x.x.x.x is the - network and /y is - the number of bits in the netmask. - If /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. + The cidr type holds an IP network. The format for + specifying classless networks is x.x.x.x/y where x.x.x.x is the network and y is the number of bits in the netmask. If + 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. Here are some examples: - <productname>Postgres</productname>IP Types Examples + <type>cidr</> Type Input Examples @@ -1801,6 +1812,14 @@ January 8 04:05:06 1999 PST + + 192.168.100.128/25 + 192.168.100.128/25 + + + 192.168/25 + 192.168.0.0/25 + 192.168.1 192.168.1/24 @@ -1839,34 +1858,48 @@ January 8 04:05:06 1999 PST - - <type>inet</type> + + <type>inet</type> - The inet 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 cidr type. - The inet type is similar to the cidr - type except that the bits in the - host part can be non-zero. - Functions exist to extract the various elements of the field. + The inet 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 + cidr type. The inet type is similar to + the cidr type except that the bits in the host part + can be non-zero. Functions exist to extract the various elements + of the field. - The input format for this function is - x.x.x.x/y - where x.x.x.x is - an internet host and y - is the number of bits in the netmask. - If the /y part is left off, - it is treated as /32. - On output, the /y part is not printed - if it is /32. - 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 x.x.x.x/y where x.x.x.x is an internet host and + y is the number of + bits in the netmask. If the y part is left off, then the + netmask is 32 and you are effectively only storing the address of + a single host. + + + <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 01764b45f2..c51e8905e1 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 + + Network Address Type Functions -
- <productname>Postgres</productname>IP V4 Functions +
+ <type>cidr</> and <type>inet</> Functions @@ -1509,13 +1510,13 @@ Not defined by this name. Implements the intersection operator '#' masklen(cidr) - int4 + integer calculate netmask length masklen('192.168.1.5/24') masklen(inet) - int4 + integer calculate netmask length masklen('192.168.1.5/24') @@ -1525,9 +1526,21 @@ Not defined by this name. Implements the intersection operator '#' construct netmask as textnetmask('192.168.1.5/24') + + trunc(macaddr) + macaddr + set last 3 bytes to zero + trunc(macaddr '12:34:56:78:90:ab') +
+ + The function trunc(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 + contrib/mac in the source distribution contains some + utilities to create and maintain such an association table. diff --git a/doc/src/sgml/oper.sgml b/doc/src/sgml/oper.sgml index 112c6f2f3f..495f3caefc 100644 --- a/doc/src/sgml/oper.sgml +++ b/doc/src/sgml/oper.sgml @@ -1,5 +1,5 @@ @@ -722,13 +722,15 @@ logical union - - IP V4 CIDR Operators - - - <ProductName>Postgres</ProductName>IP V4 CIDR Operators - Operators + + Network Address Type Operators + + + <type>cidr</> Operators + +
+ <type>cidr</> Operators @@ -791,16 +793,13 @@ logical union
- - + - - IP V4 INET Operators + + <type>inet</> Operators - - - <ProductName>Postgres</ProductName>IP V4 INET Operators - Operators +
+ <type>inet</> Operators @@ -863,7 +862,18 @@ logical union
- + + + + <type>macaddr</> Operators</> + + <para> + The <type>macaddr</> type supports the standard relational + operators (<literal>></>, <literal><=</>, etc.) for + lexicographical ordering. + </para> + </sect2> + </sect1> </Chapter>