begriffs open source - ai-pg/blob - full-docs/txt/functions-net.txt

   1
   2 9.12. Network Address Functions and Operators #
   3
   4    The IP network address types, cidr and inet, support the usual
   5    comparison operators shown in Table 9.1 as well as the specialized
   6    operators and functions shown in Table 9.39 and Table 9.40.
   7
   8    Any cidr value can be cast to inet implicitly; therefore, the operators
   9    and functions shown below as operating on inet also work on cidr
  10    values. (Where there are separate functions for inet and cidr, it is
  11    because the behavior should be different for the two cases.) Also, it
  12    is permitted to cast an inet value to cidr. When this is done, any bits
  13    to the right of the netmask are silently zeroed to create a valid cidr
  14    value.
  15
  16    Table 9.39. IP Address Operators
  17
  18    Operator
  19
  20    Description
  21
  22    Example(s)
  23
  24    inet << inet → boolean
  25
  26    Is subnet strictly contained by subnet? This operator, and the next
  27    four, test for subnet inclusion. They consider only the network parts
  28    of the two addresses (ignoring any bits to the right of the netmasks)
  29    and determine whether one network is identical to or a subnet of the
  30    other.
  31
  32    inet '192.168.1.5' << inet '192.168.1/24' → t
  33
  34    inet '192.168.0.5' << inet '192.168.1/24' → f
  35
  36    inet '192.168.1/24' << inet '192.168.1/24' → f
  37
  38    inet <<= inet → boolean
  39
  40    Is subnet contained by or equal to subnet?
  41
  42    inet '192.168.1/24' <<= inet '192.168.1/24' → t
  43
  44    inet >> inet → boolean
  45
  46    Does subnet strictly contain subnet?
  47
  48    inet '192.168.1/24' >> inet '192.168.1.5' → t
  49
  50    inet >>= inet → boolean
  51
  52    Does subnet contain or equal subnet?
  53
  54    inet '192.168.1/24' >>= inet '192.168.1/24' → t
  55
  56    inet && inet → boolean
  57
  58    Does either subnet contain or equal the other?
  59
  60    inet '192.168.1/24' && inet '192.168.1.80/28' → t
  61
  62    inet '192.168.1/24' && inet '192.168.2.0/28' → f
  63
  64    ~ inet → inet
  65
  66    Computes bitwise NOT.
  67
  68    ~ inet '192.168.1.6' → 63.87.254.249
  69
  70    inet & inet → inet
  71
  72    Computes bitwise AND.
  73
  74    inet '192.168.1.6' & inet '0.0.0.255' → 0.0.0.6
  75
  76    inet | inet → inet
  77
  78    Computes bitwise OR.
  79
  80    inet '192.168.1.6' | inet '0.0.0.255' → 192.168.1.255
  81
  82    inet + bigint → inet
  83
  84    Adds an offset to an address.
  85
  86    inet '192.168.1.6' + 25 → 192.168.1.31
  87
  88    bigint + inet → inet
  89
  90    Adds an offset to an address.
  91
  92    200 + inet '::ffff:fff0:1' → ::ffff:255.240.0.201
  93
  94    inet - bigint → inet
  95
  96    Subtracts an offset from an address.
  97
  98    inet '192.168.1.43' - 36 → 192.168.1.7
  99
 100    inet - inet → bigint
 101
 102    Computes the difference of two addresses.
 103
 104    inet '192.168.1.43' - inet '192.168.1.19' → 24
 105
 106    inet '::1' - inet '::ffff:1' → -4294901760
 107
 108    Table 9.40. IP Address Functions
 109
 110    Function
 111
 112    Description
 113
 114    Example(s)
 115
 116    abbrev ( inet ) → text
 117
 118    Creates an abbreviated display format as text. (The result is the same
 119    as the inet output function produces; it is “abbreviated” only in
 120    comparison to the result of an explicit cast to text, which for
 121    historical reasons will never suppress the netmask part.)
 122
 123    abbrev(inet '10.1.0.0/32') → 10.1.0.0
 124
 125    abbrev ( cidr ) → text
 126
 127    Creates an abbreviated display format as text. (The abbreviation
 128    consists of dropping all-zero octets to the right of the netmask; more
 129    examples are in Table 8.22.)
 130
 131    abbrev(cidr '10.1.0.0/16') → 10.1/16
 132
 133    broadcast ( inet ) → inet
 134
 135    Computes the broadcast address for the address's network.
 136
 137    broadcast(inet '192.168.1.5/24') → 192.168.1.255/24
 138
 139    family ( inet ) → integer
 140
 141    Returns the address's family: 4 for IPv4, 6 for IPv6.
 142
 143    family(inet '::1') → 6
 144
 145    host ( inet ) → text
 146
 147    Returns the IP address as text, ignoring the netmask.
 148
 149    host(inet '192.168.1.0/24') → 192.168.1.0
 150
 151    hostmask ( inet ) → inet
 152
 153    Computes the host mask for the address's network.
 154
 155    hostmask(inet '192.168.23.20/30') → 0.0.0.3
 156
 157    inet_merge ( inet, inet ) → cidr
 158
 159    Computes the smallest network that includes both of the given networks.
 160
 161    inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24') →
 162    192.168.0.0/22
 163
 164    inet_same_family ( inet, inet ) → boolean
 165
 166    Tests whether the addresses belong to the same IP family.
 167
 168    inet_same_family(inet '192.168.1.5/24', inet '::1') → f
 169
 170    masklen ( inet ) → integer
 171
 172    Returns the netmask length in bits.
 173
 174    masklen(inet '192.168.1.5/24') → 24
 175
 176    netmask ( inet ) → inet
 177
 178    Computes the network mask for the address's network.
 179
 180    netmask(inet '192.168.1.5/24') → 255.255.255.0
 181
 182    network ( inet ) → cidr
 183
 184    Returns the network part of the address, zeroing out whatever is to the
 185    right of the netmask. (This is equivalent to casting the value to
 186    cidr.)
 187
 188    network(inet '192.168.1.5/24') → 192.168.1.0/24
 189
 190    set_masklen ( inet, integer ) → inet
 191
 192    Sets the netmask length for an inet value. The address part does not
 193    change.
 194
 195    set_masklen(inet '192.168.1.5/24', 16) → 192.168.1.5/16
 196
 197    set_masklen ( cidr, integer ) → cidr
 198
 199    Sets the netmask length for a cidr value. Address bits to the right of
 200    the new netmask are set to zero.
 201
 202    set_masklen(cidr '192.168.1.0/24', 16) → 192.168.0.0/16
 203
 204    text ( inet ) → text
 205
 206    Returns the unabbreviated IP address and netmask length as text. (This
 207    has the same result as an explicit cast to text.)
 208
 209    text(inet '192.168.1.5') → 192.168.1.5/32
 210
 211 Tip
 212
 213    The abbrev, host, and text functions are primarily intended to offer
 214    alternative display formats for IP addresses.
 215
 216    The MAC address types, macaddr and macaddr8, support the usual
 217    comparison operators shown in Table 9.1 as well as the specialized
 218    functions shown in Table 9.41. In addition, they support the bitwise
 219    logical operators ~, & and | (NOT, AND and OR), just as shown above for
 220    IP addresses.
 221
 222    Table 9.41. MAC Address Functions
 223
 224    Function
 225
 226    Description
 227
 228    Example(s)
 229
 230    trunc ( macaddr ) → macaddr
 231
 232    Sets the last 3 bytes of the address to zero. The remaining prefix can
 233    be associated with a particular manufacturer (using data not included
 234    in PostgreSQL).
 235
 236    trunc(macaddr '12:34:56:78:90:ab') → 12:34:56:00:00:00
 237
 238    trunc ( macaddr8 ) → macaddr8
 239
 240    Sets the last 5 bytes of the address to zero. The remaining prefix can
 241    be associated with a particular manufacturer (using data not included
 242    in PostgreSQL).
 243
 244    trunc(macaddr8 '12:34:56:78:90:ab:cd:ef') → 12:34:56:00:00:00:00:00
 245
 246    macaddr8_set7bit ( macaddr8 ) → macaddr8
 247
 248    Sets the 7th bit of the address to one, creating what is known as
 249    modified EUI-64, for inclusion in an IPv6 address.
 250
 251    macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef') →
 252    02:34:56:ff:fe:ab:cd:ef