diff options
| -rw-r--r-- | doc/src/sgml/datatype.sgml | 32 | ||||
| -rw-r--r-- | doc/src/sgml/func.sgml | 888 |
2 files changed, 510 insertions, 410 deletions
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index c2e42f31c00..22eda0f4e9e 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -2854,7 +2854,7 @@ SELECT EXTRACT(days from '80 hours'::interval); <entry><literal>iso_8601</literal></entry> <entry>P1Y2M</entry> <entry>P3DT4H5M6S</entry> - <entry>P-1Y-2M3DT-4H-5M-6S</entry> + <entry>P-1Y-2M3D&zwsp;T-4H-5M-6S</entry> </row> </tbody> </tgroup> @@ -3559,8 +3559,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <replaceable class="parameter">y</replaceable> is the number of bits in the netmask. If the <replaceable class="parameter">/y</replaceable> - portion is missing, the - netmask is 32 for IPv4 and 128 for IPv6, so the value represents + portion is omitted, the + netmask is taken to be 32 for IPv4 or 128 for IPv6, + so the value represents just a single host. On display, the <replaceable class="parameter">/y</replaceable> portion is suppressed if the netmask specifies a single host. @@ -3580,7 +3581,8 @@ SELECT person.name, holidays.num_weeks FROM person, holidays conventions. The format for specifying networks is <replaceable class="parameter">address/y</replaceable> where <replaceable - class="parameter">address</replaceable> is the network represented as an + class="parameter">address</replaceable> is the network's lowest + address represented as an IPv4 or IPv6 address, and <replaceable class="parameter">y</replaceable> is the number of bits in the netmask. If <replaceable class="parameter">y</replaceable> is omitted, it is calculated @@ -3668,12 +3670,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <row> <entry>2001:4f8:3:ba::/64</entry> <entry>2001:4f8:3:ba::/64</entry> - <entry>2001:4f8:3:ba::/64</entry> + <entry>2001:4f8:3:ba/64</entry> </row> <row> - <entry>2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128</entry> - <entry>2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128</entry> - <entry>2001:4f8:3:ba:2e0:81ff:fe22:d1f1</entry> + <entry>2001:4f8:3:ba:&zwsp;2e0:81ff:fe22:d1f1/128</entry> + <entry>2001:4f8:3:ba:&zwsp;2e0:81ff:fe22:d1f1/128</entry> + <entry>2001:4f8:3:ba:&zwsp;2e0:81ff:fe22:d1f1/128</entry> </row> <row> <entry>::ffff:1.2.3.0/120</entry> @@ -3738,7 +3740,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <member><literal>'08002b010203'</literal></member> </simplelist> - These examples would all specify the same address. Upper and + These examples all specify the same address. Upper and lower case is accepted for the digits <literal>a</literal> through <literal>f</literal>. Output is always in the first of the forms shown. @@ -3805,14 +3807,17 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <member><literal>'08002b0102030405'</literal></member> </simplelist> - These examples would all specify the same address. Upper and + These examples all specify the same address. Upper and lower case is accepted for the digits <literal>a</literal> through <literal>f</literal>. Output is always in the first of the forms shown. + </para> - The last six input formats that are mentioned above are not part - of any standard. + <para> + The last six input formats shown above are not part of any standard. + </para> + <para> To convert a traditional 48 bit MAC address in EUI-48 format to modified EUI-64 format to be included as the host portion of an IPv6 address, use <function>macaddr8_set7bit</function> as shown: @@ -4655,7 +4660,8 @@ SELECT * FROM pg_attribute <entry><type>regoperator</type></entry> <entry><structname>pg_operator</structname></entry> <entry>operator with argument types</entry> - <entry><literal>*(integer,integer)</literal> or <literal>-(NONE,integer)</literal></entry> + <entry><literal>*(integer,&zwsp;integer)</literal> + or <literal>-(NONE,&zwsp;integer)</literal></entry> </row> <row> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 63b870de048..606defc5157 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -10558,418 +10558,512 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple <title>Network Address Functions and Operators</title> <para> - <xref linkend="cidr-inet-operators-table"/> shows the operators - available for the <type>cidr</type> and <type>inet</type> types. - The operators <literal><<</literal>, - <literal><<=</literal>, <literal>>></literal>, - <literal>>>=</literal>, and <literal>&&</literal> - test for subnet inclusion. They - consider only the network parts of the two addresses (ignoring any - host part) and determine whether one network is identical to - or a subnet of the other. + The IP network address types, <type>cidr</type> and <type>inet</type>, + support the usual comparison operators shown in + <xref linkend="functions-comparison-op-table"/> + as well as the specialized operators and functions shown in + <xref linkend="cidr-inet-operators-table"/> and + <xref linkend="cidr-inet-functions-table"/>. </para> - <table id="cidr-inet-operators-table"> - <title><type>cidr</type> and <type>inet</type> Operators</title> - <tgroup cols="3"> - <thead> - <row> - <entry>Operator</entry> - <entry>Description</entry> - <entry>Example</entry> - </row> - </thead> - <tbody> - <row> - <entry> <literal><</literal> </entry> - <entry>is less than</entry> - <entry><literal>inet '192.168.1.5' < inet '192.168.1.6'</literal></entry> - </row> - <row> - <entry> <literal><=</literal> </entry> - <entry>is less than or equal</entry> - <entry><literal>inet '192.168.1.5' <= inet '192.168.1.5'</literal></entry> - </row> - <row> - <entry> <literal>=</literal> </entry> - <entry>equals</entry> - <entry><literal>inet '192.168.1.5' = inet '192.168.1.5'</literal></entry> - </row> - <row> - <entry> <literal>>=</literal> </entry> - <entry>is greater or equal</entry> - <entry><literal>inet '192.168.1.5' >= inet '192.168.1.5'</literal></entry> - </row> - <row> - <entry> <literal>></literal> </entry> - <entry>is greater than</entry> - <entry><literal>inet '192.168.1.5' > inet '192.168.1.4'</literal></entry> - </row> - <row> - <entry> <literal><></literal> </entry> - <entry>is not equal</entry> - <entry><literal>inet '192.168.1.5' <> inet '192.168.1.4'</literal></entry> - </row> - <row> - <entry> <literal><<</literal> </entry> - <entry>is contained by</entry> - <entry><literal>inet '192.168.1.5' << inet '192.168.1/24'</literal></entry> - </row> - <row> - <entry> <literal><<=</literal> </entry> - <entry>is contained by or equals</entry> - <entry><literal>inet '192.168.1/24' <<= inet '192.168.1/24'</literal></entry> - </row> - <row> - <entry> <literal>>></literal> </entry> - <entry>contains</entry> - <entry><literal>inet '192.168.1/24' >> inet '192.168.1.5'</literal></entry> - </row> - <row> - <entry> <literal>>>=</literal> </entry> - <entry>contains or equals</entry> - <entry><literal>inet '192.168.1/24' >>= inet '192.168.1/24'</literal></entry> - </row> - <row> - <entry> <literal>&&</literal> </entry> - <entry>contains or is contained by</entry> - <entry><literal>inet '192.168.1/24' && inet '192.168.1.80/28'</literal></entry> - </row> - <row> - <entry> <literal>~</literal> </entry> - <entry>bitwise NOT</entry> - <entry><literal>~ inet '192.168.1.6'</literal></entry> - </row> - <row> - <entry> <literal>&</literal> </entry> - <entry>bitwise AND</entry> - <entry><literal>inet '192.168.1.6' & inet '0.0.0.255'</literal></entry> - </row> - <row> - <entry> <literal>|</literal> </entry> - <entry>bitwise OR</entry> - <entry><literal>inet '192.168.1.6' | inet '0.0.0.255'</literal></entry> - </row> - <row> - <entry> <literal>+</literal> </entry> - <entry>addition</entry> - <entry><literal>inet '192.168.1.6' + 25</literal></entry> - </row> - <row> - <entry> <literal>-</literal> </entry> - <entry>subtraction</entry> - <entry><literal>inet '192.168.1.43' - 36</literal></entry> - </row> - <row> - <entry> <literal>-</literal> </entry> - <entry>subtraction</entry> - <entry><literal>inet '192.168.1.43' - inet '192.168.1.19'</literal></entry> - </row> - </tbody> - </tgroup> - </table> - <para> - <xref linkend="cidr-inet-functions-table"/> shows the functions - available for use with the <type>cidr</type> and <type>inet</type> - types. The <function>abbrev</function>, <function>host</function>, - and <function>text</function> - functions are primarily intended to offer alternative display - formats. + Any <type>cidr</type> value can be cast to <type>inet</type> implicitly; + therefore, the operators and functions shown below as operating on + <type>inet</type> also work on <type>cidr</type> values. (Where there are + separate functions for <type>inet</type> and <type>cidr</type>, it is + because the behavior should be different for the two cases.) + Also, it is permitted to cast an <type>inet</type> value + to <type>cidr</type>. When this is done, any bits to the right of the + netmask are silently zeroed to create a valid <type>cidr</type> value. </para> - <table id="cidr-inet-functions-table"> - <title><type>cidr</type> and <type>inet</type> Functions</title> - <tgroup cols="5"> - <thead> - <row> - <entry>Function</entry> - <entry>Return Type</entry> - <entry>Description</entry> - <entry>Example</entry> - <entry>Result</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <indexterm> - <primary>abbrev</primary> - </indexterm> - <literal><function>abbrev(<type>inet</type>)</function></literal> - </entry> - <entry><type>text</type></entry> - <entry>abbreviated display format as text</entry> - <entry><literal>abbrev(inet '10.1.0.0/16')</literal></entry> - <entry><literal>10.1.0.0/16</literal></entry> - </row> - <row> - <entry><literal><function>abbrev(<type>cidr</type>)</function></literal></entry> - <entry><type>text</type></entry> - <entry>abbreviated display format as text</entry> - <entry><literal>abbrev(cidr '10.1.0.0/16')</literal></entry> - <entry><literal>10.1/16</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>broadcast</primary> - </indexterm> - <literal><function>broadcast(<type>inet</type>)</function></literal> - </entry> - <entry><type>inet</type></entry> - <entry>broadcast address for network</entry> - <entry><literal>broadcast('192.168.1.5/24')</literal></entry> - <entry><literal>192.168.1.255/24</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>family</primary> - </indexterm> - <literal><function>family(<type>inet</type>)</function></literal> - </entry> - <entry><type>int</type></entry> - <entry>extract family of address; <literal>4</literal> for IPv4, - <literal>6</literal> for IPv6</entry> - <entry><literal>family('::1')</literal></entry> - <entry><literal>6</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>host</primary> - </indexterm> - <literal><function>host(<type>inet</type>)</function></literal> - </entry> - <entry><type>text</type></entry> - <entry>extract IP address as text</entry> - <entry><literal>host('192.168.1.5/24')</literal></entry> - <entry><literal>192.168.1.5</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>hostmask</primary> - </indexterm> - <literal><function>hostmask(<type>inet</type>)</function></literal> - </entry> - <entry><type>inet</type></entry> - <entry>construct host mask for network</entry> - <entry><literal>hostmask('192.168.23.20/30')</literal></entry> - <entry><literal>0.0.0.3</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>masklen</primary> - </indexterm> - <literal><function>masklen(<type>inet</type>)</function></literal> - </entry> - <entry><type>int</type></entry> - <entry>extract netmask length</entry> - <entry><literal>masklen('192.168.1.5/24')</literal></entry> - <entry><literal>24</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>netmask</primary> - </indexterm> - <literal><function>netmask(<type>inet</type>)</function></literal> - </entry> - <entry><type>inet</type></entry> - <entry>construct netmask for network</entry> - <entry><literal>netmask('192.168.1.5/24')</literal></entry> - <entry><literal>255.255.255.0</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>network</primary> - </indexterm> - <literal><function>network(<type>inet</type>)</function></literal> - </entry> - <entry><type>cidr</type></entry> - <entry>extract network part of address</entry> - <entry><literal>network('192.168.1.5/24')</literal></entry> - <entry><literal>192.168.1.0/24</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>set_masklen</primary> - </indexterm> - <literal><function>set_masklen(<type>inet</type>, <type>int</type>)</function></literal> - </entry> - <entry><type>inet</type></entry> - <entry>set netmask length for <type>inet</type> value</entry> - <entry><literal>set_masklen('192.168.1.5/24', 16)</literal></entry> - <entry><literal>192.168.1.5/16</literal></entry> - </row> - <row> - <entry><literal><function>set_masklen(<type>cidr</type>, <type>int</type>)</function></literal></entry> - <entry><type>cidr</type></entry> - <entry>set netmask length for <type>cidr</type> value</entry> - <entry><literal>set_masklen('192.168.1.0/24'::cidr, 16)</literal></entry> - <entry><literal>192.168.0.0/16</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>text</primary> - </indexterm> - <literal><function>text(<type>inet</type>)</function></literal> - </entry> - <entry><type>text</type></entry> - <entry>extract IP address and netmask length as text</entry> - <entry><literal>text(inet '192.168.1.5')</literal></entry> - <entry><literal>192.168.1.5/32</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>inet_same_family</primary> - </indexterm> - <literal><function>inet_same_family(<type>inet</type>, <type>inet</type>)</function></literal> - </entry> - <entry><type>boolean</type></entry> - <entry>are the addresses from the same family?</entry> - <entry><literal>inet_same_family('192.168.1.5/24', '::1')</literal></entry> - <entry><literal>false</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>inet_merge</primary> - </indexterm> - <literal><function>inet_merge(<type>inet</type>, <type>inet</type>)</function></literal> - </entry> - <entry><type>cidr</type></entry> - <entry>the smallest network which includes both of the given networks</entry> - <entry><literal>inet_merge('192.168.1.5/24', '192.168.2.5/24')</literal></entry> - <entry><literal>192.168.0.0/22</literal></entry> - </row> - </tbody> - </tgroup> - </table> + <table id="cidr-inet-operators-table"> + <title>IP Address Operators</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="functableentry"> + Operator<?br?>Description<?br?>Example(s) + </entry> + </row> + </thead> - <para> - Any <type>cidr</type> value can be cast to <type>inet</type> implicitly - or explicitly; therefore, the functions shown above as operating on - <type>inet</type> also work on <type>cidr</type> values. (Where there are - separate functions for <type>inet</type> and <type>cidr</type>, it is because - the behavior should be different for the two cases.) - Also, it is permitted to cast an <type>inet</type> value to <type>cidr</type>. - When this is done, any bits to the right of the netmask are silently zeroed - to create a valid <type>cidr</type> value. - In addition, - you can cast a text value to <type>inet</type> or <type>cidr</type> - using normal casting syntax: for example, - <literal>inet(<replaceable>expression</replaceable>)</literal> or - <literal><replaceable>colname</replaceable>::cidr</literal>. - </para> + <tbody> + <row> + <entry role="functableentry"> + <type>inet</type> <literal><<</literal> <type>inet</type> + <returnvalue>boolean</returnvalue> + <?br?> + Is subnet strictly contained by subnet? + This operator, and the next four, test for subnet inclusion. They + consider only the network parts of the two addresses (ignoring any + bits to the right of the netmasks) and determine whether one network + is identical to or a subnet of the other. + <?br?> + <literal>inet '192.168.1.5' << inet '192.168.1/24'</literal> + <returnvalue>t</returnvalue> + <?br?> + <literal>inet '192.168.0.5' << inet '192.168.1/24'</literal> + <returnvalue>f</returnvalue> + <?br?> + <literal>inet '192.168.1/24' << inet '192.168.1/24'</literal> + <returnvalue>f</returnvalue> + </entry> + </row> - <para> - <xref linkend="macaddr-functions-table"/> shows the functions - available for use with the <type>macaddr</type> type. The function - <literal><function>trunc(<type>macaddr</type>)</function></literal> returns a MAC - address with the last 3 bytes set to zero. This can be used to - associate the remaining prefix with a manufacturer. - </para> + <row> + <entry role="functableentry"> + <type>inet</type> <literal><<=</literal> <type>inet</type> + <returnvalue>boolean</returnvalue> + <?br?> + Is subnet contained by or equal to subnet? + <?br?> + <literal>inet '192.168.1/24' <<= inet '192.168.1/24'</literal> + <returnvalue>t</returnvalue> + </entry> + </row> - <table id="macaddr-functions-table"> - <title><type>macaddr</type> Functions</title> - <tgroup cols="5"> - <thead> - <row> - <entry>Function</entry> - <entry>Return Type</entry> - <entry>Description</entry> - <entry>Example</entry> - <entry>Result</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <indexterm> - <primary>trunc</primary> - </indexterm> - <literal><function>trunc(<type>macaddr</type>)</function></literal> - </entry> - <entry><type>macaddr</type></entry> - <entry>set last 3 bytes to zero</entry> - <entry><literal>trunc(macaddr '12:34:56:78:90:ab')</literal></entry> - <entry><literal>12:34:56:00:00:00</literal></entry> - </row> - </tbody> - </tgroup> - </table> + <row> + <entry role="functableentry"> + <type>inet</type> <literal>>></literal> <type>inet</type> + <returnvalue>boolean</returnvalue> + <?br?> + Does subnet strictly contain subnet? + <?br?> + <literal>inet '192.168.1/24' >> inet '192.168.1.5'</literal> + <returnvalue>t</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <type>inet</type> <literal>>>=</literal> <type>inet</type> + <returnvalue>boolean</returnvalue> + <?br?> + Does subnet contain or equal subnet? + <?br?> + <literal>inet '192.168.1/24' >>= inet '192.168.1/24'</literal> + <returnvalue>t</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <type>inet</type> <literal>&&</literal> <type>inet</type> + <returnvalue>boolean</returnvalue> + <?br?> + Does either subnet contain or equal the other? + <?br?> + <literal>inet '192.168.1/24' && inet '192.168.1.80/28'</literal> + <returnvalue>t</returnvalue> + <?br?> + <literal>inet '192.168.1/24' && inet '192.168.2.0/28'</literal> + <returnvalue>f</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <literal>~</literal> <type>inet</type> + <returnvalue>inet</returnvalue> + <?br?> + Computes bitwise NOT. + <?br?> + <literal>~ inet '192.168.1.6'</literal> + <returnvalue>63.87.254.249</returnvalue> + </entry> + </row> + <row> + <entry role="functableentry"> + <type>inet</type> <literal>&</literal> <type>inet</type> + <returnvalue>inet</returnvalue> + <?br?> + Computes bitwise AND. + <?br?> + <literal>inet '192.168.1.6' & inet '0.0.0.255'</literal> + <returnvalue>0.0.0.6</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <type>inet</type> <literal>|</literal> <type>inet</type> + <returnvalue>inet</returnvalue> + <?br?> + Computes bitwise OR. + <?br?> + <literal>inet '192.168.1.6' | inet '0.0.0.255'</literal> + <returnvalue>192.168.1.255</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <type>inet</type> <literal>+</literal> <type>bigint</type> + <returnvalue>inet</returnvalue> + <?br?> + Adds an offset to an address. + <?br?> + <literal>inet '192.168.1.6' + 25</literal> + <returnvalue>192.168.1.31</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <type>bigint</type> <literal>+</literal> <type>inet</type> + <returnvalue>inet</returnvalue> + <?br?> + Adds an offset to an address. + <?br?> + <literal>200 + inet '::ffff:fff0:1'</literal> + <returnvalue>::ffff:255.240.0.201</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <type>inet</type> <literal>-</literal> <type>bigint</type> + <returnvalue>inet</returnvalue> + <?br?> + Subtracts an offset from an address. + <?br?> + <literal>inet '192.168.1.43' - 36</literal> + <returnvalue>192.168.1.7</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <type>inet</type> <literal>-</literal> <type>inet</type> + <returnvalue>bigint</returnvalue> + <?br?> + Computes the difference of two addresses. + <?br?> + <literal>inet '192.168.1.43' - inet '192.168.1.19'</literal> + <returnvalue>24</returnvalue> + <?br?> + <literal>inet '::1' - inet '::ffff:1'</literal> + <returnvalue>-4294901760</returnvalue> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="cidr-inet-functions-table"> + <title>IP Address Functions</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="functableentry"> + Function<?br?>Description<?br?>Example(s) + </entry> + </row> + </thead> + + <tbody> + <row> + <entry role="functableentry"> + <indexterm> + <primary>abbrev</primary> + </indexterm> + <function>abbrev</function> ( <type>inet</type> ) + <returnvalue>text</returnvalue> + <?br?> + Creates an abbreviated display format as text. + (The result is the same as the <type>inet</type> output function + produces; it is <quote>abbreviated</quote> only in comparison to the + result of an explicit cast to <type>text</type>, which for historical + reasons will never suppress the netmask part.) + <?br?> + <literal>abbrev(inet '10.1.0.0/32')</literal> + <returnvalue>10.1.0.0</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <function>abbrev</function> ( <type>cidr</type> ) + <returnvalue>text</returnvalue> + <?br?> + Creates an abbreviated display format as text. + (The abbreviation consists of dropping all-zero octets to the right + of the netmask; more examples are in + <xref linkend="datatype-net-cidr-table"/>.) + <?br?> + <literal>abbrev(cidr '10.1.0.0/16')</literal> + <returnvalue>10.1/16</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>broadcast</primary> + </indexterm> + <function>broadcast</function> ( <type>inet</type> ) + <returnvalue>inet</returnvalue> + <?br?> + Computes the broadcast address for the address's network. + <?br?> + <literal>broadcast(inet '192.168.1.5/24')</literal> + <returnvalue>192.168.1.255/24</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>family</primary> + </indexterm> + <function>family</function> ( <type>inet</type> ) + <returnvalue>integer</returnvalue> + <?br?> + Returns the address's family: <literal>4</literal> for IPv4, + <literal>6</literal> for IPv6. + <?br?> + <literal>family(inet '::1')</literal> + <returnvalue>6</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>host</primary> + </indexterm> + <function>host</function> ( <type>inet</type> ) + <returnvalue>text</returnvalue> + <?br?> + Returns the IP address as text, ignoring the netmask. + <?br?> + <literal>host(inet '192.168.1.0/24')</literal> + <returnvalue>192.168.1.0</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>hostmask</primary> + </indexterm> + <function>hostmask</function> ( <type>inet</type> ) + <returnvalue>inet</returnvalue> + <?br?> + Computes the host mask for the address's network. + <?br?> + <literal>hostmask(inet '192.168.23.20/30')</literal> + <returnvalue>0.0.0.3</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>inet_merge</primary> + </indexterm> + <function>inet_merge</function> ( <type>inet</type>, <type>inet</type> ) + <returnvalue>cidr</returnvalue> + <?br?> + Computes the smallest network that includes both of the given networks. + <?br?> + <literal>inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')</literal> + <returnvalue>192.168.0.0/22</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>inet_same_family</primary> + </indexterm> + <function>inet_same_family</function> ( <type>inet</type>, <type>inet</type> ) + <returnvalue>boolean</returnvalue> + <?br?> + Tests whether the addresses belong to the same IP family. + <?br?> + <literal>inet_same_family(inet '192.168.1.5/24', inet '::1')</literal> + <returnvalue>f</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>masklen</primary> + </indexterm> + <function>masklen</function> ( <type>inet</type> ) + <returnvalue>integer</returnvalue> + <?br?> + Returns the netmask length in bits. + <?br?> + <literal>masklen(inet '192.168.1.5/24')</literal> + <returnvalue>24</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>netmask</primary> + </indexterm> + <function>netmask</function> ( <type>inet</type> ) + <returnvalue>inet</returnvalue> + <?br?> + Computes the network mask for the address's network. + <?br?> + <literal>netmask(inet '192.168.1.5/24')</literal> + <returnvalue>255.255.255.0</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>network</primary> + </indexterm> + <function>network</function> ( <type>inet</type> ) + <returnvalue>cidr</returnvalue> + <?br?> + Returns the network part of the address, zeroing out + whatever is to the right of the netmask. + (This is equivalent to casting the value to <type>cidr</type>.) + <?br?> + <literal>network(inet '192.168.1.5/24')</literal> + <returnvalue>192.168.1.0/24</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>set_masklen</primary> + </indexterm> + <function>set_masklen</function> ( <type>inet</type>, <type>integer</type> ) + <returnvalue>inet</returnvalue> + <?br?> + Sets the netmask length for an <type>inet</type> value. + The address part does not change. + <?br?> + <literal>set_masklen(inet '192.168.1.5/24', 16)</literal> + <returnvalue>192.168.1.5/16</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <function>set_masklen</function> ( <type>cidr</type>, <type>integer</type> ) + <returnvalue>cidr</returnvalue> + <?br?> + Sets the netmask length for a <type>cidr</type> value. + Address bits to the right of the new netmask are set to zero. + <?br?> + <literal>set_masklen(cidr '192.168.1.0/24', 16)</literal> + <returnvalue>192.168.0.0/16</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>text</primary> + </indexterm> + <function>text</function> ( <type>inet</type> ) + <returnvalue>text</returnvalue> + <?br?> + Returns the unabbreviated IP address and netmask length as text. + (This has the same result as an explicit cast to <type>text</type>.) + <?br?> + <literal>text(inet '192.168.1.5')</literal> + <returnvalue>192.168.1.5/32</returnvalue> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <tip> <para> - The <type>macaddr</type> type also supports the standard relational - operators (<literal>></literal>, <literal><=</literal>, etc.) for - lexicographical ordering, and the bitwise arithmetic operators - (<literal>~</literal>, <literal>&</literal> and <literal>|</literal>) - for NOT, AND and OR. + The <function>abbrev</function>, <function>host</function>, + and <function>text</function> functions are primarily intended to offer + alternative display formats for IP addresses. </para> + </tip> - <para> - <xref linkend="macaddr8-functions-table"/> shows the functions - available for use with the <type>macaddr8</type> type. The function - <literal><function>trunc(<type>macaddr8</type>)</function></literal> returns a MAC - address with the last 5 bytes set to zero. This can be used to - associate the remaining prefix with a manufacturer. + <para> + The MAC address types, <type>macaddr</type> and <type>macaddr8</type>, + support the usual comparison operators shown in + <xref linkend="functions-comparison-op-table"/> + as well as the specialized functions shown in + <xref linkend="macaddr-functions-table"/>. + In addition, they support the bitwise logical operators + <literal>~</literal>, <literal>&</literal> and <literal>|</literal> + (NOT, AND and OR), just as shown above for IP addresses. </para> - <table id="macaddr8-functions-table"> - <title><type>macaddr8</type> Functions</title> - <tgroup cols="5"> - <thead> - <row> - <entry>Function</entry> - <entry>Return Type</entry> - <entry>Description</entry> - <entry>Example</entry> - <entry>Result</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <indexterm> - <primary>trunc</primary> - </indexterm> - <literal><function>trunc(<type>macaddr8</type>)</function></literal> - </entry> - <entry><type>macaddr8</type></entry> - <entry>set last 5 bytes to zero</entry> - <entry><literal>trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')</literal></entry> - <entry><literal>12:34:56:00:00:00:00:00</literal></entry> - </row> - <row> - <entry> - <indexterm> - <primary>macaddr8_set7bit</primary> - </indexterm> - <literal><function>macaddr8_set7bit(<type>macaddr8</type>)</function></literal> - </entry> - <entry><type>macaddr8</type></entry> - <entry>set 7th bit to one, also known as modified EUI-64, for inclusion in an IPv6 address</entry> - <entry><literal>macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')</literal></entry> - <entry><literal>02:34:56:ff:fe:ab:cd:ef</literal></entry> - </row> - </tbody> - </tgroup> - </table> + <table id="macaddr-functions-table"> + <title>MAC Address Functions</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="functableentry"> + Function<?br?>Description<?br?>Example(s) + </entry> + </row> + </thead> - <para> - The <type>macaddr8</type> type also supports the standard relational - operators (<literal>></literal>, <literal><=</literal>, etc.) for - ordering, and the bitwise arithmetic operators (<literal>~</literal>, - <literal>&</literal> and <literal>|</literal>) for NOT, AND and OR. - </para> + <tbody> + <row> + <entry role="functableentry"> + <indexterm> + <primary>trunc</primary> + </indexterm> + <function>trunc</function> ( <type>macaddr</type> ) + <returnvalue>macaddr</returnvalue> + <?br?> + Sets the last 3 bytes of the address to zero. The remaining prefix + can be associated with a particular manufacturer (using data not + included in <productname>PostgreSQL</productname>). + <?br?> + <literal>trunc(macaddr '12:34:56:78:90:ab')</literal> + <returnvalue>12:34:56:00:00:00</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <function>trunc</function> ( <type>macaddr8</type> ) + <returnvalue>macaddr8</returnvalue> + <?br?> + Sets the last 5 bytes of the address to zero. The remaining prefix + can be associated with a particular manufacturer (using data not + included in <productname>PostgreSQL</productname>). + <?br?> + <literal>trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')</literal> + <returnvalue>12:34:56:00:00:00:00:00</returnvalue> + </entry> + </row> + + <row> + <entry role="functableentry"> + <indexterm> + <primary>macaddr8_set7bit</primary> + </indexterm> + <function>macaddr8_set7bit</function> ( <type>macaddr8</type> ) + <returnvalue>macaddr8</returnvalue> + <?br?> + Sets the 7th bit of the address to one, creating what is known as + modified EUI-64, for inclusion in an IPv6 address. + <?br?> + <literal>macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')</literal> + <returnvalue>02:34:56:ff:fe:ab:cd:ef</returnvalue> + </entry> + </row> + </tbody> + </tgroup> + </table> </sect1> |