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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy