Skip to content

P
Postgres FD Implementation
Commit 5b0aa112 authored by Tom Lane's avatar Tom Lane
Browse files
Options

Doc: update section 9.12 for new function table layout. 

Also rearrange that page a bit for more consistency and less
duplication.

In passing, fix erroneous examples of the results of abbrev(cidr)
in datatype.sgml, and do a bit of copy-editing there.
parent ab7646ff
Show whitespace changes
Inline Side-by-side
Showing with 510 additions and 410 deletions
doc/src/sgml/datatype.sgml
View file @ 5b0aa112
......@@ -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>
......
doc/src/sgml/func.sgml
View file @ 5b0aa112
......@@ -10558,419 +10558,513 @@ 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>&lt;&lt;</literal>,
<literal>&lt;&lt;=</literal>, <literal>&gt;&gt;</literal>,
<literal>&gt;&gt;=</literal>, and <literal>&amp;&amp;</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>
<para>
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-operators-table">
<title><type>cidr</type> and <type>inet</type> Operators</title>
<tgroup cols="3">
<title>IP Address Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry>Operator</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry role="functableentry">
Operator<?br?>Description<?br?>Example(s)
</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>&lt;</literal> </entry>
<entry>is less than</entry>
<entry><literal>inet '192.168.1.5' &lt; inet '192.168.1.6'</literal></entry>
</row>
<row>
<entry> <literal>&lt;=</literal> </entry>
<entry>is less than or equal</entry>
<entry><literal>inet '192.168.1.5' &lt;= 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>&gt;=</literal> </entry>
<entry>is greater or equal</entry>
<entry><literal>inet '192.168.1.5' &gt;= inet '192.168.1.5'</literal></entry>
</row>
<row>
<entry> <literal>&gt;</literal> </entry>
<entry>is greater than</entry>
<entry><literal>inet '192.168.1.5' &gt; inet '192.168.1.4'</literal></entry>
</row>
<row>
<entry> <literal>&lt;&gt;</literal> </entry>
<entry>is not equal</entry>
<entry><literal>inet '192.168.1.5' &lt;&gt; inet '192.168.1.4'</literal></entry>
<entry role="functableentry">
<type>inet</type> <literal>&lt;&lt;</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' &lt;&lt; inet '192.168.1/24'</literal>
<returnvalue>t</returnvalue>
<?br?>
<literal>inet '192.168.0.5' &lt;&lt; inet '192.168.1/24'</literal>
<returnvalue>f</returnvalue>
<?br?>
<literal>inet '192.168.1/24' &lt;&lt; inet '192.168.1/24'</literal>
<returnvalue>f</returnvalue>
</entry>
</row>
<row>
<entry> <literal>&lt;&lt;</literal> </entry>
<entry>is contained by</entry>
<entry><literal>inet '192.168.1.5' &lt;&lt; inet '192.168.1/24'</literal></entry>
<entry role="functableentry">
<type>inet</type> <literal>&lt;&lt;=</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
<?br?>
Is subnet contained by or equal to subnet?
<?br?>
<literal>inet '192.168.1/24' &lt;&lt;= inet '192.168.1/24'</literal>
<returnvalue>t</returnvalue>
</entry>
</row>
<row>
<entry> <literal>&lt;&lt;=</literal> </entry>
<entry>is contained by or equals</entry>
<entry><literal>inet '192.168.1/24' &lt;&lt;= inet '192.168.1/24'</literal></entry>
<entry role="functableentry">
<type>inet</type> <literal>&gt;&gt;</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
<?br?>
Does subnet strictly contain subnet?
<?br?>
<literal>inet '192.168.1/24' &gt;&gt; inet '192.168.1.5'</literal>
<returnvalue>t</returnvalue>
</entry>
</row>
<row>
<entry> <literal>&gt;&gt;</literal> </entry>
<entry>contains</entry>
<entry><literal>inet '192.168.1/24' &gt;&gt; inet '192.168.1.5'</literal></entry>
<entry role="functableentry">
<type>inet</type> <literal>&gt;&gt;=</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
<?br?>
Does subnet contain or equal subnet?
<?br?>
<literal>inet '192.168.1/24' &gt;&gt;= inet '192.168.1/24'</literal>
<returnvalue>t</returnvalue>
</entry>
</row>
<row>
<entry> <literal>&gt;&gt;=</literal> </entry>
<entry>contains or equals</entry>
<entry><literal>inet '192.168.1/24' &gt;&gt;= inet '192.168.1/24'</literal></entry>
<entry role="functableentry">
<type>inet</type> <literal>&amp;&amp;</literal> <type>inet</type>
<returnvalue>boolean</returnvalue>
<?br?>
Does either subnet contain or equal the other?
<?br?>
<literal>inet '192.168.1/24' &amp;&amp; inet '192.168.1.80/28'</literal>
<returnvalue>t</returnvalue>
<?br?>
<literal>inet '192.168.1/24' &amp;&amp; inet '192.168.2.0/28'</literal>
<returnvalue>f</returnvalue>
</entry>
</row>
<row>
<entry> <literal>&amp;&amp;</literal> </entry>
<entry>contains or is contained by</entry>
<entry><literal>inet '192.168.1/24' &amp;&amp; inet '192.168.1.80/28'</literal></entry>
<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> <literal>~</literal> </entry>
<entry>bitwise NOT</entry>
<entry><literal>~ inet '192.168.1.6'</literal></entry>
<entry role="functableentry">
<type>inet</type> <literal>&amp;</literal> <type>inet</type>
<returnvalue>inet</returnvalue>
<?br?>
Computes bitwise AND.
<?br?>
<literal>inet '192.168.1.6' &amp; inet '0.0.0.255'</literal>
<returnvalue>0.0.0.6</returnvalue>
</entry>
</row>
<row>
<entry> <literal>&amp;</literal> </entry>
<entry>bitwise AND</entry>
<entry><literal>inet '192.168.1.6' &amp; inet '0.0.0.255'</literal></entry>
<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> <literal>|</literal> </entry>
<entry>bitwise OR</entry>
<entry><literal>inet '192.168.1.6' | inet '0.0.0.255'</literal></entry>
<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> <literal>+</literal> </entry>
<entry>addition</entry>
<entry><literal>inet '192.168.1.6' + 25</literal></entry>
<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> <literal>-</literal> </entry>
<entry>subtraction</entry>
<entry><literal>inet '192.168.1.43' - 36</literal></entry>
<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> <literal>-</literal> </entry>
<entry>subtraction</entry>
<entry><literal>inet '192.168.1.43' - inet '192.168.1.19'</literal></entry>
<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>
<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.
</para>
<table id="cidr-inet-functions-table">
<title><type>cidr</type> and <type>inet</type> Functions</title>
<tgroup cols="5">
<title>IP Address Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
<entry role="functableentry">
Function<?br?>Description<?br?>Example(s)
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<entry role="functableentry">
<indexterm>
<primary>abbrev</primary>
</indexterm>
<literal><function>abbrev(<type>inet</type>)</function></literal>
<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>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>broadcast</primary>
</indexterm>
<literal><function>broadcast(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>family</primary>
</indexterm>
<literal><function>family(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>host</primary>
</indexterm>
<literal><function>host(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>hostmask</primary>
</indexterm>
<literal><function>hostmask(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>masklen</primary>
<primary>inet_merge</primary>
</indexterm>
<literal><function>masklen(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>netmask</primary>
<primary>inet_same_family</primary>
</indexterm>
<literal><function>netmask(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>network</primary>
<primary>masklen</primary>
</indexterm>
<literal><function>network(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>set_masklen</primary>
<primary>netmask</primary>
</indexterm>
<literal><function>set_masklen(<type>inet</type>, <type>int</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>text</primary>
<primary>network</primary>
</indexterm>
<literal><function>text(<type>inet</type>)</function></literal>
<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>
<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>
<entry role="functableentry">
<indexterm>
<primary>inet_same_family</primary>
<primary>set_masklen</primary>
</indexterm>
<literal><function>inet_same_family(<type>inet</type>, <type>inet</type>)</function></literal>
<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>
<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>
<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>inet_merge</primary>
<primary>text</primary>
</indexterm>
<literal><function>inet_merge(<type>inet</type>, <type>inet</type>)</function></literal>
<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>
<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>
<tip>
<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>.
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="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.
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>&amp;</literal> and <literal>|</literal>
(NOT, AND and OR), just as shown above for IP addresses.
</para>
<table id="macaddr-functions-table">
<title><type>macaddr</type> Functions</title>
<tgroup cols="5">
<title>MAC Address Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
<entry role="functableentry">
Function<?br?>Description<?br?>Example(s)
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<entry role="functableentry">
<indexterm>
<primary>trunc</primary>
</indexterm>
<literal><function>trunc(<type>macaddr</type>)</function></literal>
<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>
<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>
<para>
The <type>macaddr</type> type also supports the standard relational
operators (<literal>&gt;</literal>, <literal>&lt;=</literal>, etc.) for
lexicographical ordering, and the bitwise arithmetic operators
(<literal>~</literal>, <literal>&amp;</literal> and <literal>|</literal>)
for NOT, AND and OR.
</para>
<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>
<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 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>
<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>
<entry role="functableentry">
<indexterm>
<primary>macaddr8_set7bit</primary>
</indexterm>
<literal><function>macaddr8_set7bit(<type>macaddr8</type>)</function></literal>
<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>
<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>
<para>
The <type>macaddr8</type> type also supports the standard relational
operators (<literal>&gt;</literal>, <literal>&lt;=</literal>, etc.) for
ordering, and the bitwise arithmetic operators (<literal>~</literal>,
<literal>&amp;</literal> and <literal>|</literal>) for NOT, AND and OR.
</para>
</sect1>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment