begriffs open source - ai-pg/blob - full-docs/src/sgml/html/functions-net.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.12. Network Address Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-geometry.html" title="9.11. Geometric Functions and Operators" /><link rel="next" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.12. Network Address Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-NET"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.12. Network Address Functions and Operators <a href="#FUNCTIONS-NET" class="id_link">#</a></h2></div></div></div><p>
   3    The IP network address types, <code class="type">cidr</code> and <code class="type">inet</code>,
   4    support the usual comparison operators shown in
   5    <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a>
   6    as well as the specialized operators and functions shown in
   7    <a class="xref" href="functions-net.html#CIDR-INET-OPERATORS-TABLE" title="Table 9.39. IP Address Operators">Table 9.39</a> and
   8    <a class="xref" href="functions-net.html#CIDR-INET-FUNCTIONS-TABLE" title="Table 9.40. IP Address Functions">Table 9.40</a>.
   9   </p><p>
  10    Any <code class="type">cidr</code> value can be cast to <code class="type">inet</code> implicitly;
  11    therefore, the operators and functions shown below as operating on
  12    <code class="type">inet</code> also work on <code class="type">cidr</code> values.  (Where there are
  13    separate functions for <code class="type">inet</code> and <code class="type">cidr</code>, it is
  14    because the behavior should be different for the two cases.)
  15    Also, it is permitted to cast an <code class="type">inet</code> value
  16    to <code class="type">cidr</code>.  When this is done, any bits to the right of the
  17    netmask are silently zeroed to create a valid <code class="type">cidr</code> value.
  18   </p><div class="table" id="CIDR-INET-OPERATORS-TABLE"><p class="title"><strong>Table 9.39. IP Address Operators</strong></p><div class="table-contents"><table class="table" summary="IP Address Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
  19         Operator
  20        </p>
  21        <p>
  22         Description
  23        </p>
  24        <p>
  25         Example(s)
  26        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
  27         <code class="type">inet</code> <code class="literal">&lt;&lt;</code> <code class="type">inet</code>
  28         → <code class="returnvalue">boolean</code>
  29        </p>
  30        <p>
  31         Is subnet strictly contained by subnet?
  32         This operator, and the next four, test for subnet inclusion.  They
  33         consider only the network parts of the two addresses (ignoring any
  34         bits to the right of the netmasks) and determine whether one network
  35         is identical to or a subnet of the other.
  36        </p>
  37        <p>
  38         <code class="literal">inet '192.168.1.5' &lt;&lt; inet '192.168.1/24'</code>
  39         → <code class="returnvalue">t</code>
  40        </p>
  41        <p>
  42         <code class="literal">inet '192.168.0.5' &lt;&lt; inet '192.168.1/24'</code>
  43         → <code class="returnvalue">f</code>
  44        </p>
  45        <p>
  46         <code class="literal">inet '192.168.1/24' &lt;&lt; inet '192.168.1/24'</code>
  47         → <code class="returnvalue">f</code>
  48        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  49         <code class="type">inet</code> <code class="literal">&lt;&lt;=</code> <code class="type">inet</code>
  50         → <code class="returnvalue">boolean</code>
  51        </p>
  52        <p>
  53         Is subnet contained by or equal to subnet?
  54        </p>
  55        <p>
  56         <code class="literal">inet '192.168.1/24' &lt;&lt;= inet '192.168.1/24'</code>
  57         → <code class="returnvalue">t</code>
  58        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  59         <code class="type">inet</code> <code class="literal">&gt;&gt;</code> <code class="type">inet</code>
  60         → <code class="returnvalue">boolean</code>
  61        </p>
  62        <p>
  63         Does subnet strictly contain subnet?
  64        </p>
  65        <p>
  66         <code class="literal">inet '192.168.1/24' &gt;&gt; inet '192.168.1.5'</code>
  67         → <code class="returnvalue">t</code>
  68        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  69         <code class="type">inet</code> <code class="literal">&gt;&gt;=</code> <code class="type">inet</code>
  70         → <code class="returnvalue">boolean</code>
  71        </p>
  72        <p>
  73         Does subnet contain or equal subnet?
  74        </p>
  75        <p>
  76         <code class="literal">inet '192.168.1/24' &gt;&gt;= inet '192.168.1/24'</code>
  77         → <code class="returnvalue">t</code>
  78        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  79         <code class="type">inet</code> <code class="literal">&amp;&amp;</code> <code class="type">inet</code>
  80         → <code class="returnvalue">boolean</code>
  81        </p>
  82        <p>
  83         Does either subnet contain or equal the other?
  84        </p>
  85        <p>
  86         <code class="literal">inet '192.168.1/24' &amp;&amp; inet '192.168.1.80/28'</code>
  87         → <code class="returnvalue">t</code>
  88        </p>
  89        <p>
  90         <code class="literal">inet '192.168.1/24' &amp;&amp; inet '192.168.2.0/28'</code>
  91         → <code class="returnvalue">f</code>
  92        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  93         <code class="literal">~</code> <code class="type">inet</code>
  94         → <code class="returnvalue">inet</code>
  95        </p>
  96        <p>
  97         Computes bitwise NOT.
  98        </p>
  99        <p>
 100         <code class="literal">~ inet '192.168.1.6'</code>
 101         → <code class="returnvalue">63.87.254.249</code>
 102        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 103         <code class="type">inet</code> <code class="literal">&amp;</code> <code class="type">inet</code>
 104         → <code class="returnvalue">inet</code>
 105        </p>
 106        <p>
 107         Computes bitwise AND.
 108        </p>
 109        <p>
 110         <code class="literal">inet '192.168.1.6' &amp; inet '0.0.0.255'</code>
 111         → <code class="returnvalue">0.0.0.6</code>
 112        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 113         <code class="type">inet</code> <code class="literal">|</code> <code class="type">inet</code>
 114         → <code class="returnvalue">inet</code>
 115        </p>
 116        <p>
 117         Computes bitwise OR.
 118        </p>
 119        <p>
 120         <code class="literal">inet '192.168.1.6' | inet '0.0.0.255'</code>
 121         → <code class="returnvalue">192.168.1.255</code>
 122        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 123         <code class="type">inet</code> <code class="literal">+</code> <code class="type">bigint</code>
 124         → <code class="returnvalue">inet</code>
 125        </p>
 126        <p>
 127         Adds an offset to an address.
 128        </p>
 129        <p>
 130         <code class="literal">inet '192.168.1.6' + 25</code>
 131         → <code class="returnvalue">192.168.1.31</code>
 132        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 133         <code class="type">bigint</code> <code class="literal">+</code> <code class="type">inet</code>
 134         → <code class="returnvalue">inet</code>
 135        </p>
 136        <p>
 137         Adds an offset to an address.
 138        </p>
 139        <p>
 140         <code class="literal">200 + inet '::ffff:fff0:1'</code>
 141         → <code class="returnvalue">::ffff:255.240.0.201</code>
 142        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 143         <code class="type">inet</code> <code class="literal">-</code> <code class="type">bigint</code>
 144         → <code class="returnvalue">inet</code>
 145        </p>
 146        <p>
 147         Subtracts an offset from an address.
 148        </p>
 149        <p>
 150         <code class="literal">inet '192.168.1.43' - 36</code>
 151         → <code class="returnvalue">192.168.1.7</code>
 152        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 153         <code class="type">inet</code> <code class="literal">-</code> <code class="type">inet</code>
 154         → <code class="returnvalue">bigint</code>
 155        </p>
 156        <p>
 157         Computes the difference of two addresses.
 158        </p>
 159        <p>
 160         <code class="literal">inet '192.168.1.43' - inet '192.168.1.19'</code>
 161         → <code class="returnvalue">24</code>
 162        </p>
 163        <p>
 164         <code class="literal">inet '::1' - inet '::ffff:1'</code>
 165         → <code class="returnvalue">-4294901760</code>
 166        </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="CIDR-INET-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.40. IP Address Functions</strong></p><div class="table-contents"><table class="table" summary="IP Address Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
 167         Function
 168        </p>
 169        <p>
 170         Description
 171        </p>
 172        <p>
 173         Example(s)
 174        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
 175         <a id="id-1.5.8.18.5.2.2.1.1.1.1" class="indexterm"></a>
 176         <code class="function">abbrev</code> ( <code class="type">inet</code> )
 177         → <code class="returnvalue">text</code>
 178        </p>
 179        <p>
 180         Creates an abbreviated display format as text.
 181         (The result is the same as the <code class="type">inet</code> output function
 182         produces; it is <span class="quote">“<span class="quote">abbreviated</span>”</span> only in comparison to the
 183         result of an explicit cast to <code class="type">text</code>, which for historical
 184         reasons will never suppress the netmask part.)
 185        </p>
 186        <p>
 187         <code class="literal">abbrev(inet '10.1.0.0/32')</code>
 188         → <code class="returnvalue">10.1.0.0</code>
 189        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 190         <code class="function">abbrev</code> ( <code class="type">cidr</code> )
 191         → <code class="returnvalue">text</code>
 192        </p>
 193        <p>
 194         Creates an abbreviated display format as text.
 195         (The abbreviation consists of dropping all-zero octets to the right
 196         of the netmask; more examples are in
 197         <a class="xref" href="datatype-net-types.html#DATATYPE-NET-CIDR-TABLE" title="Table 8.22. cidr Type Input Examples">Table 8.22</a>.)
 198        </p>
 199        <p>
 200         <code class="literal">abbrev(cidr '10.1.0.0/16')</code>
 201         → <code class="returnvalue">10.1/16</code>
 202        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 203         <a id="id-1.5.8.18.5.2.2.3.1.1.1" class="indexterm"></a>
 204         <code class="function">broadcast</code> ( <code class="type">inet</code> )
 205         → <code class="returnvalue">inet</code>
 206        </p>
 207        <p>
 208         Computes the broadcast address for the address's network.
 209        </p>
 210        <p>
 211         <code class="literal">broadcast(inet '192.168.1.5/24')</code>
 212         → <code class="returnvalue">192.168.1.255/24</code>
 213        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 214         <a id="id-1.5.8.18.5.2.2.4.1.1.1" class="indexterm"></a>
 215         <code class="function">family</code> ( <code class="type">inet</code> )
 216         → <code class="returnvalue">integer</code>
 217        </p>
 218        <p>
 219         Returns the address's family: <code class="literal">4</code> for IPv4,
 220         <code class="literal">6</code> for IPv6.
 221        </p>
 222        <p>
 223         <code class="literal">family(inet '::1')</code>
 224         → <code class="returnvalue">6</code>
 225        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 226         <a id="id-1.5.8.18.5.2.2.5.1.1.1" class="indexterm"></a>
 227         <code class="function">host</code> ( <code class="type">inet</code> )
 228         → <code class="returnvalue">text</code>
 229        </p>
 230        <p>
 231         Returns the IP address as text, ignoring the netmask.
 232        </p>
 233        <p>
 234         <code class="literal">host(inet '192.168.1.0/24')</code>
 235         → <code class="returnvalue">192.168.1.0</code>
 236        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 237         <a id="id-1.5.8.18.5.2.2.6.1.1.1" class="indexterm"></a>
 238         <code class="function">hostmask</code> ( <code class="type">inet</code> )
 239         → <code class="returnvalue">inet</code>
 240        </p>
 241        <p>
 242         Computes the host mask for the address's network.
 243        </p>
 244        <p>
 245         <code class="literal">hostmask(inet '192.168.23.20/30')</code>
 246         → <code class="returnvalue">0.0.0.3</code>
 247        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 248         <a id="id-1.5.8.18.5.2.2.7.1.1.1" class="indexterm"></a>
 249         <code class="function">inet_merge</code> ( <code class="type">inet</code>, <code class="type">inet</code> )
 250         → <code class="returnvalue">cidr</code>
 251        </p>
 252        <p>
 253         Computes the smallest network that includes both of the given networks.
 254        </p>
 255        <p>
 256         <code class="literal">inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')</code>
 257         → <code class="returnvalue">192.168.0.0/22</code>
 258        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 259         <a id="id-1.5.8.18.5.2.2.8.1.1.1" class="indexterm"></a>
 260         <code class="function">inet_same_family</code> ( <code class="type">inet</code>, <code class="type">inet</code> )
 261         → <code class="returnvalue">boolean</code>
 262        </p>
 263        <p>
 264         Tests whether the addresses belong to the same IP family.
 265        </p>
 266        <p>
 267         <code class="literal">inet_same_family(inet '192.168.1.5/24', inet '::1')</code>
 268         → <code class="returnvalue">f</code>
 269        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 270         <a id="id-1.5.8.18.5.2.2.9.1.1.1" class="indexterm"></a>
 271         <code class="function">masklen</code> ( <code class="type">inet</code> )
 272         → <code class="returnvalue">integer</code>
 273        </p>
 274        <p>
 275         Returns the netmask length in bits.
 276        </p>
 277        <p>
 278         <code class="literal">masklen(inet '192.168.1.5/24')</code>
 279         → <code class="returnvalue">24</code>
 280        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 281         <a id="id-1.5.8.18.5.2.2.10.1.1.1" class="indexterm"></a>
 282         <code class="function">netmask</code> ( <code class="type">inet</code> )
 283         → <code class="returnvalue">inet</code>
 284        </p>
 285        <p>
 286         Computes the network mask for the address's network.
 287        </p>
 288        <p>
 289         <code class="literal">netmask(inet '192.168.1.5/24')</code>
 290         → <code class="returnvalue">255.255.255.0</code>
 291        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 292         <a id="id-1.5.8.18.5.2.2.11.1.1.1" class="indexterm"></a>
 293         <code class="function">network</code> ( <code class="type">inet</code> )
 294         → <code class="returnvalue">cidr</code>
 295        </p>
 296        <p>
 297         Returns the network part of the address, zeroing out
 298         whatever is to the right of the netmask.
 299         (This is equivalent to casting the value to <code class="type">cidr</code>.)
 300        </p>
 301        <p>
 302         <code class="literal">network(inet '192.168.1.5/24')</code>
 303         → <code class="returnvalue">192.168.1.0/24</code>
 304        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 305         <a id="id-1.5.8.18.5.2.2.12.1.1.1" class="indexterm"></a>
 306         <code class="function">set_masklen</code> ( <code class="type">inet</code>, <code class="type">integer</code> )
 307         → <code class="returnvalue">inet</code>
 308        </p>
 309        <p>
 310         Sets the netmask length for an <code class="type">inet</code> value.
 311         The address part does not change.
 312        </p>
 313        <p>
 314         <code class="literal">set_masklen(inet '192.168.1.5/24', 16)</code>
 315         → <code class="returnvalue">192.168.1.5/16</code>
 316        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 317         <code class="function">set_masklen</code> ( <code class="type">cidr</code>, <code class="type">integer</code> )
 318         → <code class="returnvalue">cidr</code>
 319        </p>
 320        <p>
 321         Sets the netmask length for a <code class="type">cidr</code> value.
 322         Address bits to the right of the new netmask are set to zero.
 323        </p>
 324        <p>
 325         <code class="literal">set_masklen(cidr '192.168.1.0/24', 16)</code>
 326         → <code class="returnvalue">192.168.0.0/16</code>
 327        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 328         <a id="id-1.5.8.18.5.2.2.14.1.1.1" class="indexterm"></a>
 329         <code class="function">text</code> ( <code class="type">inet</code> )
 330         → <code class="returnvalue">text</code>
 331        </p>
 332        <p>
 333         Returns the unabbreviated IP address and netmask length as text.
 334         (This has the same result as an explicit cast to <code class="type">text</code>.)
 335        </p>
 336        <p>
 337         <code class="literal">text(inet '192.168.1.5')</code>
 338         → <code class="returnvalue">192.168.1.5/32</code>
 339        </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="tip"><h3 class="title">Tip</h3><p>
 340     The <code class="function">abbrev</code>, <code class="function">host</code>,
 341     and <code class="function">text</code> functions are primarily intended to offer
 342     alternative display formats for IP addresses.
 343    </p></div><p>
 344    The MAC address types, <code class="type">macaddr</code> and <code class="type">macaddr8</code>,
 345    support the usual comparison operators shown in
 346    <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a>
 347    as well as the specialized functions shown in
 348    <a class="xref" href="functions-net.html#MACADDR-FUNCTIONS-TABLE" title="Table 9.41. MAC Address Functions">Table 9.41</a>.
 349    In addition, they support the bitwise logical operators
 350    <code class="literal">~</code>, <code class="literal">&amp;</code> and <code class="literal">|</code>
 351    (NOT, AND and OR), just as shown above for IP addresses.
 352   </p><div class="table" id="MACADDR-FUNCTIONS-TABLE"><p class="title"><strong>Table 9.41. MAC Address Functions</strong></p><div class="table-contents"><table class="table" summary="MAC Address Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
 353         Function
 354        </p>
 355        <p>
 356         Description
 357        </p>
 358        <p>
 359         Example(s)
 360        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
 361         <a id="id-1.5.8.18.8.2.2.1.1.1.1" class="indexterm"></a>
 362         <code class="function">trunc</code> ( <code class="type">macaddr</code> )
 363         → <code class="returnvalue">macaddr</code>
 364        </p>
 365        <p>
 366         Sets the last 3 bytes of the address to zero.  The remaining prefix
 367         can be associated with a particular manufacturer (using data not
 368         included in <span class="productname">PostgreSQL</span>).
 369        </p>
 370        <p>
 371         <code class="literal">trunc(macaddr '12:34:56:78:90:ab')</code>
 372         → <code class="returnvalue">12:34:56:00:00:00</code>
 373        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 374         <code class="function">trunc</code> ( <code class="type">macaddr8</code> )
 375         → <code class="returnvalue">macaddr8</code>
 376        </p>
 377        <p>
 378         Sets the last 5 bytes of the address to zero.  The remaining prefix
 379         can be associated with a particular manufacturer (using data not
 380         included in <span class="productname">PostgreSQL</span>).
 381        </p>
 382        <p>
 383         <code class="literal">trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')</code>
 384         → <code class="returnvalue">12:34:56:00:00:00:00:00</code>
 385        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 386         <a id="id-1.5.8.18.8.2.2.3.1.1.1" class="indexterm"></a>
 387         <code class="function">macaddr8_set7bit</code> ( <code class="type">macaddr8</code> )
 388         → <code class="returnvalue">macaddr8</code>
 389        </p>
 390        <p>
 391         Sets the 7th bit of the address to one, creating what is known as
 392         modified EUI-64, for inclusion in an IPv6 address.
 393        </p>
 394        <p>
 395         <code class="literal">macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')</code>
 396         → <code class="returnvalue">02:34:56:ff:fe:ab:cd:ef</code>
 397        </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-geometry.html" title="9.11. Geometric Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-textsearch.html" title="9.13. Text Search Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.11. Geometric Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.13. Text Search Functions and Operators</td></tr></table></div></body></html>