Skip to content

Commit a210023

Browse files
tglsfdctglsfdc
committed
Adjust INET/CIDR display conventions and reimplement some INET/CIDR
functions, per recent discussions on pghackers. For now, I have called the verbose-display formatting function text(), but will reconsider if enough people object. initdb forced.
1 parent d7f8ffa commit a210023

File tree

10 files changed

+273
-255
lines changed

10 files changed

+273
-255
lines changed

‎doc/src/sgml/datatype.sgml

Lines changed: 55 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.38 2000/10/04 15:47:45 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.39 2000/11/10 20:13:25 tgl Exp $
33
-->
44

55
<chapter id="datatype">
@@ -65,7 +65,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.38 2000/10/04 15:47:45 pe
6565
<row>
6666
<entry>cidr</entry>
6767
<entry></entry>
68-
<entry>IP version 4 network or host address</entry>
68+
<entry>IP network address</entry>
6969
</row>
7070
<row>
7171
<entry>circle</entry>
@@ -95,7 +95,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.38 2000/10/04 15:47:45 pe
9595
<row>
9696
<entry>inet</entry>
9797
<entry></entry>
98-
<entry>IP version 4 network or host address</entry>
98+
<entry>IP network or host address</entry>
9999
</row>
100100
<row>
101101
<entry>int2</entry>
@@ -1736,7 +1736,7 @@ January 8 04:05:06 1999 PST
17361736

17371737
<para>
17381738
<productname>Postgres</> offers data types to store IP and MAC
1739-
addresses. It is preferrable to use these types over plain text
1739+
addresses. It is preferable to use these types over plain text
17401740
types, because these types offer input error checking and several
17411741
specialized operators and functions.
17421742

@@ -1755,16 +1755,16 @@ January 8 04:05:06 1999 PST
17551755

17561756
<row>
17571757
<entry>cidr</entry>
1758-
<entry>11 bytes</entry>
1758+
<entry>12 bytes</entry>
17591759
<entry>IP networks</entry>
17601760
<entry>valid IPv4 networks</entry>
17611761
</row>
17621762

17631763
<row>
17641764
<entry>inet</entry>
1765-
<entry>11 bytes</entry>
1765+
<entry>12 bytes</entry>
17661766
<entry>IP hosts and networks</entry>
1767-
<entry>valid IPv4 hosts</entry>
1767+
<entry>valid IPv4 hosts or networks</entry>
17681768
</row>
17691769

17701770
<row>
@@ -1784,19 +1784,48 @@ January 8 04:05:06 1999 PST
17841784
</para>
17851785

17861786

1787+
<sect2 id="inet-type">
1788+
<title><type>inet</type></title>
1789+
1790+
<para>
1791+
The <type>inet</type> type holds an IP host address, and
1792+
optionally the identity of the subnet it is in, all in one field.
1793+
The subnet identity is represented by the number of bits in the
1794+
network part of the address (the "netmask"). If the netmask is 32,
1795+
then the value does not indicate a subnet, only a single host.
1796+
Note that if you want to accept networks only, you should use the
1797+
<type>cidr</type> type rather than <type>inet</type>.
1798+
</para>
1799+
1800+
<para>
1801+
The input format for this type is <replaceable
1802+
class="parameter">x.x.x.x/y</replaceable> where <replaceable
1803+
class="parameter">x.x.x.x</replaceable> is an IP address and
1804+
<replaceable class="parameter">y</replaceable> is the number of
1805+
bits in the netmask. If the <replaceable
1806+
class="parameter">y</replaceable> part is left off, then the
1807+
netmask is 32, and the value represents just a single host.
1808+
On display, the <replaceable class="parameter">/y</replaceable>
1809+
portion is suppressed if the netmask is 32.
1810+
</para>
1811+
</sect2>
1812+
17871813
<sect2 id="cidr-type">
17881814
<title><type>cidr</></title>
17891815

17901816
<para>
1791-
The <type>cidr</type> type holds an IP network. The format for
1817+
The <type>cidr</type> type holds an IP network specification.
1818+
Input and output formats follow Classless Internet Domain Routing
1819+
conventions.
1820+
The format for
17921821
specifying classless networks is <replaceable
17931822
class="parameter">x.x.x.x/y</> where <replaceable
17941823
class="parameter">x.x.x.x</> is the network and <replaceable
17951824
class="parameter">y</> is the number of bits in the netmask. If
17961825
<replaceable class="parameter">y</> omitted, it is calculated
1797-
using assumptions from the older classfull naming system except
1798-
that it is extended to include at least all of the octets in the
1799-
input.
1826+
using assumptions from the older classful numbering system, except
1827+
that it will be at least large enough to include all of the octets
1828+
written in the input.
18001829
</para>
18011830

18021831
<para>
@@ -1816,6 +1845,10 @@ January 8 04:05:06 1999 PST
18161845
<entry>192.168.100.128/25</entry>
18171846
<entry>192.168.100.128/25</entry>
18181847
</row>
1848+
<row>
1849+
<entry>192.168/24</entry>
1850+
<entry>192.168.0/24</entry>
1851+
</row>
18191852
<row>
18201853
<entry>192.168/25</entry>
18211854
<entry>192.168.0.0/25</entry>
@@ -1856,30 +1889,19 @@ January 8 04:05:06 1999 PST
18561889
</tgroup>
18571890
</table>
18581891
</para>
1859-
</sect2>
1860-
1861-
<sect2 id="inet-type">
1862-
<title><type>inet</type></title>
18631892

18641893
<para>
1865-
The <type>inet</type> type holds an IP host address, and
1866-
optionally the identity of the subnet it is in, all in one field.
1867-
Note that if you want to store networks only, you should use the
1868-
<type>cidr</type> type. The <type>inet</type> type is similar to
1869-
the <type>cidr</type> type except that the bits in the host part
1870-
can be non-zero. Functions exist to extract the various elements
1871-
of the field.
1872-
</para>
1873-
1874-
<para>
1875-
The input format for this type is <replaceable
1876-
class="parameter">x.x.x.x/y</replaceable> where <replaceable
1877-
class="parameter">x.x.x.x</replaceable> is an internet host and
1878-
<replaceable class="parameter">y</replaceable> is the number of
1879-
bits in the netmask. If the <replaceable
1880-
class="parameter">y</replaceable> part is left off, then the
1881-
netmask is 32 and you are effectively only storing the address of
1882-
a single host.
1894+
The essential difference between <type>inet</type> and <type>cidr</type>
1895+
data types is that <type>inet</type> accepts values with nonzero bits to
1896+
the right of the netmask, whereas <type>cidr</type> does not.
1897+
1898+
<tip>
1899+
<para>
1900+
If you do not like the output format for <type>inet</type> or
1901+
<type>cidr</type> values, try the <function>host</>() and
1902+
<function>text</>() functions.
1903+
</para>
1904+
</tip>
18831905
</para>
18841906
</sect2>
18851907

‎doc/src/sgml/func.sgml

Lines changed: 55 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1480,62 +1480,98 @@ Not defined by this name. Implements the intersection operator '#'
14801480
<para>
14811481
<table tocentry="1" id="cidr-inet-functions">
14821482
<title><type>cidr</> and <type>inet</> Functions</title>
1483-
<tgroup cols="4">
1483+
<tgroup cols="5">
14841484
<thead>
14851485
<row>
14861486
<entry>Function</entry>
14871487
<entry>Returns</entry>
14881488
<entry>Description</entry>
14891489
<entry>Example</entry>
1490+
<entry>Result</entry>
14901491
</row>
14911492
</thead>
14921493
<tbody>
1493-
<row>
1494-
<entry>broadcast(cidr)</entry>
1495-
<entry>text</entry>
1496-
<entry>construct broadcast address as text</entry>
1497-
<entry>broadcast('192.168.1.5/24')</entry>
1498-
</row>
14991494
<row>
15001495
<entry>broadcast(inet)</entry>
1501-
<entry>text</entry>
1502-
<entry>construct broadcast address as text</entry>
1496+
<entry>inet</entry>
1497+
<entry>broadcast address for network</entry>
15031498
<entry>broadcast('192.168.1.5/24')</entry>
1499+
<entry>192.168.1.255/24</entry>
15041500
</row>
15051501
<row>
15061502
<entry>host(inet)</entry>
15071503
<entry>text</entry>
1508-
<entry>extract host address as text</entry>
1504+
<entry>extract IP address as text</entry>
15091505
<entry>host('192.168.1.5/24')</entry>
1510-
</row>
1511-
<row>
1512-
<entry>masklen(cidr)</entry>
1513-
<entry>integer</entry>
1514-
<entry>calculate netmask length</entry>
1515-
<entry>masklen('192.168.1.5/24')</entry>
1506+
<entry>192.168.1.5</entry>
15161507
</row>
15171508
<row>
15181509
<entry>masklen(inet)</entry>
15191510
<entry>integer</entry>
1520-
<entry>calculate netmask length</entry>
1511+
<entry>extract netmask length</entry>
15211512
<entry>masklen('192.168.1.5/24')</entry>
1513+
<entry>24</entry>
15221514
</row>
15231515
<row>
15241516
<entry>netmask(inet)</entry>
1525-
<entry>text</entry>
1526-
<entry>construct netmask as text</entry>
1517+
<entry>inet</entry>
1518+
<entry>construct netmask for network</entry>
15271519
<entry>netmask('192.168.1.5/24')</entry>
1520+
<entry>255.255.255.0</entry>
1521+
</row>
1522+
<row>
1523+
<entry>network(inet)</entry>
1524+
<entry>cidr</entry>
1525+
<entry>extract network part of address</entry>
1526+
<entry>network('192.168.1.5/24')</entry>
1527+
<entry>192.168.1/24</entry>
1528+
</row>
1529+
<row>
1530+
<entry>text(inet)</entry>
1531+
<entry>text</entry>
1532+
<entry>extract IP address and masklen as text</entry>
1533+
<entry>text(inet '192.168.1.5')</entry>
1534+
<entry>192.168.1.5/32</entry>
1535+
</row>
1536+
</tbody>
1537+
</tgroup>
1538+
</table>
1539+
</para>
1540+
1541+
<para>
1542+
All of the functions for <type>inet</type> can be applied to
1543+
<type>cidr</type> values as well. The <function>host</>() and
1544+
<function>text</>() functions are primarily intended to offer
1545+
alternative display formats.
1546+
</para>
1547+
1548+
<para>
1549+
<table tocentry="1" id="macaddr-functions">
1550+
<title><type>macaddr</> Functions</title>
1551+
<tgroup cols="5">
1552+
<thead>
1553+
<row>
1554+
<entry>Function</entry>
1555+
<entry>Returns</entry>
1556+
<entry>Description</entry>
1557+
<entry>Example</entry>
1558+
<entry>Result</entry>
15281559
</row>
1560+
</thead>
1561+
<tbody>
15291562
<row>
15301563
<entry>trunc(macaddr)</entry>
15311564
<entry>macaddr</entry>
15321565
<entry>set last 3 bytes to zero</entry>
15331566
<entry>trunc(macaddr '12:34:56:78:90:ab')</entry>
1567+
<entry>12:34:56:00:00:00</entry>
15341568
</row>
15351569
</tbody>
15361570
</tgroup>
15371571
</table>
1572+
</para>
15381573

1574+
<para>
15391575
The function <function>trunc</>(<type>macaddr</>) returns a MAC
15401576
address with the last 3 bytes set to 0. This can be used to
15411577
associate the remaining prefix with a manufacturer. The directory

‎doc/src/sgml/oper.sgml

Lines changed: 15 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/oper.sgml,v 1.21 2000/10/24 20:13:31 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/oper.sgml,v 1.22 2000/11/10 20:13:25 tgl Exp $
33
-->
44

55
<Chapter Id="operators">
@@ -756,80 +756,11 @@ logical union
756756
<sect1 id="net-operators">
757757
<title>Network Address Type Operators</title>
758758

759-
<sect2 id="cidr-operators">
760-
<title><type>cidr</> Operators</title>
759+
<sect2 id="cidr-inet-operators">
760+
<title><type>cidr</> and <type>inet</> Operators</title>
761761

762-
<table tocentry="1" id="cidr-operators-table">
763-
<title><type>cidr</> Operators</title>
764-
<TGROUP COLS="3">
765-
<THEAD>
766-
<ROW>
767-
<ENTRY>Operator</ENTRY>
768-
<ENTRY>Description</ENTRY>
769-
<ENTRY>Usage</ENTRY>
770-
</ROW>
771-
</THEAD>
772-
<TBODY>
773-
<ROW>
774-
<ENTRY> &lt; </ENTRY>
775-
<ENTRY>Less than</ENTRY>
776-
<ENTRY>'192.168.1.5'::cidr &lt; '192.168.1.6'::cidr</ENTRY>
777-
</ROW>
778-
<ROW>
779-
<ENTRY> &lt;= </ENTRY>
780-
<ENTRY>Less than or equal</ENTRY>
781-
<ENTRY>'192.168.1.5'::cidr &lt;= '192.168.1.5'::cidr</ENTRY>
782-
</ROW>
783-
<ROW>
784-
<ENTRY> = </ENTRY>
785-
<ENTRY>Equals</ENTRY>
786-
<ENTRY>'192.168.1.5'::cidr = '192.168.1.5'::cidr</ENTRY>
787-
</ROW>
788-
<ROW>
789-
<ENTRY> &gt;= </ENTRY>
790-
<ENTRY>Greater or equal</ENTRY>
791-
<ENTRY>'192.168.1.5'::cidr &gt;= '192.168.1.5'::cidr</ENTRY>
792-
</ROW>
793-
<ROW>
794-
<ENTRY> &gt; </ENTRY>
795-
<ENTRY>Greater</ENTRY>
796-
<ENTRY>'192.168.1.5'::cidr &gt; '192.168.1.4'::cidr</ENTRY>
797-
</ROW>
798-
<ROW>
799-
<ENTRY> &lt;&gt; </ENTRY>
800-
<ENTRY>Not equal</ENTRY>
801-
<ENTRY>'192.168.1.5'::cidr &lt;&gt; '192.168.1.4'::cidr</ENTRY>
802-
</ROW>
803-
<ROW>
804-
<ENTRY> &lt;&lt; </ENTRY>
805-
<ENTRY>is contained within</ENTRY>
806-
<ENTRY>'192.168.1.5'::cidr &lt;&lt; '192.168.1/24'::cidr</ENTRY>
807-
</ROW>
808-
<ROW>
809-
<ENTRY> &lt;&lt;= </ENTRY>
810-
<ENTRY>is contained within or equals</ENTRY>
811-
<ENTRY>'192.168.1/24'::cidr &lt;&lt;= '192.168.1/24'::cidr</ENTRY>
812-
</ROW>
813-
<ROW>
814-
<ENTRY> &gt;&gt; </ENTRY>
815-
<ENTRY>contains</ENTRY>
816-
<ENTRY>'192.168.1/24'::cidr &gt;&gt; '192.168.1.5'::cidr</ENTRY>
817-
</ROW>
818-
<ROW>
819-
<ENTRY> &gt;&gt;= </ENTRY>
820-
<ENTRY>contains or equals</ENTRY>
821-
<ENTRY>'192.168.1/24'::cidr &gt;&gt;= '192.168.1/24'::cidr</ENTRY>
822-
</ROW>
823-
</TBODY>
824-
</TGROUP>
825-
</TABLE>
826-
</sect2>
827-
828-
<sect2 id="inet-operators">
829-
<title><type>inet</> Operators</title>
830-
831-
<table tocentry="1" id="inet-operators-table">
832-
<title><type>inet</> Operators</title>
762+
<table tocentry="1" id="cidr-inet-operators-table">
763+
<title><type>cidr</> and <type>inet</> Operators</title>
833764
<TGROUP COLS="3">
834765
<THEAD>
835766
<ROW>
@@ -892,6 +823,16 @@ logical union
892823
</TBODY>
893824
</TGROUP>
894825
</TABLE>
826+
827+
<para>
828+
All of the operators for <type>inet</type> can be applied to
829+
<type>cidr</type> values as well. The operators
830+
<literal>&lt;&lt;</> <literal>&lt;&lt;=</>
831+
<literal>&gt;&gt;</> <literal>&gt;&gt;=</>
832+
test for subnet inclusion: they consider only the network parts
833+
of the two addresses, ignoring any host part, and determine whether
834+
one network part is identical to or a subnet of the other.
835+
</para>
895836
</sect2>
896837

897838
<sect2 id="macaddr-operators">

0 commit comments

Comments
 (0)