lib/libc/inet.3

   1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright 1989 AT&T
  19 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
  20 .\" Copyright 2018 Nexenta Systems, Inc.
  21 .\"
  22 .Dd July 22, 2018
  23 .Dt INET 3
  24 .Os
  25 .Sh NAME
  26 .Nm inet ,
  27 .Nm inet6 ,
  28 .Nm inet_ntop ,
  29 .Nm inet_pton ,
  30 .Nm inet_aton ,
  31 .Nm inet_addr ,
  32 .Nm inet_network ,
  33 .Nm inet_makeaddr ,
  34 .Nm inet_lnaof ,
  35 .Nm inet_netof ,
  36 .Nm inet_ntoa
  37 .Nd Internet address manipulation
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In sys/socket.h
  43 .In netinet/in.h
  44 .In arpa/inet.h
  45 .Ft const char *
  46 .Fo inet_ntop
  47 .Fa "int af"
  48 .Fa "const void *addr"
  49 .Fa "char *cp"
  50 .Fa "size_t size"
  51 .Fc
  52 .Ft int
  53 .Fo inet_pton
  54 .Fa "int af"
  55 .Fa "const char *cp"
  56 .Fa "void *addr"
  57 .Fc
  58 .Ft int
  59 .Fo inet_aton
  60 .Fa "const char *cp"
  61 .Fa "struct in_addr *addr"
  62 .Fc
  63 .Ft in_addr_t
  64 .Fo inet_addr
  65 .Fa "const char *cp"
  66 .Fc
  67 .Ft in_addr_t
  68 .Fo inet_network
  69 .Fa "const char *cp"
  70 .Fc
  71 .Ft struct in_addr
  72 .Fo inet_makeaddr
  73 .Fa "const int net"
  74 .Fa "const int lna"
  75 .Fc
  76 .Ft in_addr_t
  77 .Fo inet_lnaof
  78 .Fa "const struct in_addr in"
  79 .Fc
  80 .Ft in_addr_t
  81 .Fo inet_netof
  82 .Fa "const struct in_addr in"
  83 .Fc
  84 .Ft char *
  85 .Fo inet_ntoa
  86 .Fa "const struct in_addr in"
  87 .Fc
  88 .Sh DESCRIPTION
  89 The
  90 .Fn inet_ntop
  91 and
  92 .Fn inet_pton
  93 functions can manipulate both IPv4 and IPv6 addresses.
  94 The
  95 .Fn inet_aton ,
  96 .Fn inet_addr ,
  97 .Fn inet_network ,
  98 .Fn inet_makeaddr ,
  99 .Fn inet_lnaof ,
 100 .Fn inet_netof ,
 101 and
 102 .Fn inet_ntoa
 103 functions can only manipulate IPv4 addresses.
 104 .Pp
 105 The
 106 .Fn inet_ntop
 107 function converts a numeric address into a string suitable for presentation.
 108 The
 109 .Fa af
 110 argument specifies the family of the address which can be
 111 .Dv AF_INET
 112 or
 113 .Dv AF_INET6 .
 114 The
 115 .Fa addr
 116 argument points to a buffer that holds an IPv4 address if the
 117 .Fa af
 118 argument is
 119 .Dv AF_INET .
 120 The
 121 .Fa addr
 122 argument points to a buffer that holds an IPv6 address if the
 123 .Fa af
 124 argument is
 125 .Dv AF_INET6 .
 126 The address must be in network byte order.
 127 The
 128 .Fa cp
 129 argument points to a buffer where the function stores the resulting string.
 130 The application must specify a non-NULL
 131 .Fa cp
 132 argument.
 133 The
 134 .Fa size
 135 argument specifies the size of this buffer.
 136 For IPv6 addresses, the buffer must be at least 46-octets.
 137 For IPv4 addresses, the buffer must be at least 16-octets.
 138 To allow applications to easily declare buffers of the proper size to store IPv4
 139 and IPv6 addresses in string form, the following two constants are defined in
 140 .In netinet/in.h :
 141 .Bd -literal
 142 #define INET_ADDRSTRLEN    16
 143 #define INET6_ADDRSTRLEN   46
 144 .Ed
 145 .Pp
 146 The
 147 .Fn inet_pton
 148 function converts the standard text presentation form of a function to the
 149 numeric binary form.
 150 The
 151 .Fa af
 152 argument specifies the family of the address.
 153 Currently, the
 154 .Dv AF_INET
 155 and
 156 .Dv AF_INET6
 157 address families are supported.
 158 The
 159 .Fa cp
 160 argument points to the string being passed in.
 161 The
 162 .Fa addr
 163 argument points to a buffer where the function stores the numeric address.
 164 The calling application must ensure that the buffer referred to by
 165 .Fa addr
 166 is large enough to hold the numeric address, at least 4 bytes for
 167 .Dv AF_INET
 168 or 16 bytes for
 169 .Dv AF_INET6 .
 170 .Pp
 171 The
 172 .Fn inet_aton ,
 173 .Fn inet_addr ,
 174 and
 175 .Fn inet_network
 176 functions interpret character strings that represent numbers expressed in the
 177 IPv4 standard
 178 .Ql \&.
 179 notation, returning numbers suitable for use as IPv4 addresses and IPv4 network
 180 numbers, respectively.
 181 The
 182 .Fn inet_makeaddr
 183 function uses an IPv4 network number and a local network address to construct
 184 an IPv4 address.
 185 The
 186 .Fn inet_netof
 187 and
 188 .Fn inet_lnaof
 189 functions break apart IPv4 host addresses, then return the network number and
 190 local network address, respectively.
 191 .Pp
 192 The
 193 .Fn inet_ntoa
 194 function returns a pointer to a string in the base 256 notation
 195 .Ql d.d.d.d .
 196 See the following section on IPv4 addresses.
 197 .Pp
 198 Internet addresses are returned in network order, bytes ordered from left to
 199 right.
 200 Network numbers and local address parts are returned as machine format integer
 201 values.
 202 .Ss IPv6 Addresses
 203 There are three conventional forms for representing IPv6 addresses as strings:
 204 .Bl -enum
 205 .It
 206 The preferred form is
 207 .Ql x:x:x:x:x:x:x:x ,
 208 where the
 209 .Li x No 's
 210 are the
 211 hexadecimal values of the eight 16-bit pieces of the address.
 212 For example,
 213 .Ql 1080:0:0:0:8:800:200C:417A .
 214 .Pp
 215 It is not necessary to write the leading zeros in an individual field.
 216 There must be at least one numeral in every field, except when the special
 217 syntax described in the following is used.
 218 .It
 219 It is common for addresses to contain long strings of zero bits in some
 220 methods used to allocate certain IPv6 address styles.
 221 A special syntax is available to compress the zeros.
 222 The use of
 223 .Ql ::
 224 indicates multiple groups of 16 bits of zeros.
 225 The
 226 .Ql ::
 227 may only appear once in an address.
 228 The
 229 .Ql ::
 230 can also be used to compress the leading and trailing zeros in an address.
 231 For example,
 232 .Ql 1080::8:800:200C:417A .
 233 .It
 234 The alternative form
 235 .Ql x:x:x:x:x:x:d.d.d.d
 236 is sometimes more convenient when dealing with a mixed environment of IPv4 and
 237 IPv6 nodes.
 238 The
 239 .Li x No 's
 240 in this form represent the hexadecimal values of the six high-order 16-bit
 241 pieces of the address.
 242 The
 243 .Li d No 's
 244 represent the decimal values of the four low-order 8-bit pieces of the standard
 245 IPv4 address.
 246 For example:
 247 .Bd -literal
 248 ::FFFF:129.144.52.38 .
 249 ::129.144.52.38
 250 .Ed
 251 .Pp
 252 The
 253 .Ql ::FFFF:d.d.d.d
 254 and
 255 .Ql ::d.d.d.d
 256 pieces are the general forms of an IPv4-mapped IPv6 address and an
 257 IPv4-compatible IPv6 address.
 258 .Pp
 259 The IPv4 portion must be in the
 260 .Ql d.d.d.d
 261 form.
 262 The following forms are invalid:
 263 .Bd -literal
 264 ::FFFF:d.d.d
 265 ::FFFF:d.d
 266 ::d.d.d
 267 ::d.d
 268 .Ed
 269 .Pp
 270 The
 271 .Ql ::FFFF:d
 272 form is a valid but unconventional representation of the IPv4-compatible IPv6
 273 address
 274 .Ql ::255.255.0.d .
 275 .Pp
 276 The
 277 .Ql ::d
 278 form corresponds to the general IPv6 address
 279 .Ql 0:0:0:0:0:0:0:d .
 280 .El
 281 .Ss IPv4 Addresses
 282 Values specified using
 283 .Ql \&.
 284 notation take one of the following forms:
 285 .Bd -literal
 286 d.d.d.d
 287 d.d.d
 288 d.d
 289 d
 290 .Ed
 291 .Pp
 292 When four parts are specified, each part is interpreted as a byte of data and
 293 assigned from left to right to the four bytes of an IPv4 address.
 294 .Pp
 295 When a three-part address is specified, the last part is interpreted as a
 296 16-bit quantity and placed in the right most two bytes of the network address.
 297 The three part address format is convenient for specifying Class B network
 298 addresses such as
 299 .Ql 128.net.host .
 300 .Pp
 301 When a two-part address is supplied, the last part is interpreted as a 24-bit
 302 quantity and placed in the right most three bytes of the network address.
 303 The two part address format is convenient for specifying Class A network
 304 addresses such as
 305 .Ql net.host .
 306 .Pp
 307 When only one part is given, the value is stored directly in the network
 308 address without any byte rearrangement.
 309 .Pp
 310 With the exception of
 311 .Fn inet_pton ,
 312 numbers supplied as parts in
 313 .Ql \&.
 314 notation may be decimal, octal, or hexadecimal, as specified in C language.
 315 For example, a leading
 316 .Ql 0x
 317 or
 318 .Ql 0X
 319 implies hexadecimal.
 320 A leading
 321 .Ql 0
 322 implies octal.
 323 Otherwise, the number is interpreted as decimal.
 324 .Pp
 325 For IPv4 addresses,
 326 .Fn inet_pton
 327 accepts only a string in standard IPv4 dot notation
 328 .Ql d.d.d.d .
 329 .Pp
 330 Each number has one to three digits with a decimal value between 0 and 255.
 331 .Pp
 332 The
 333 .Fn inet_addr
 334 function has been obsoleted by
 335 .Fn inet_aton .
 336 .Sh RETURN VALUES
 337 The
 338 .Fn inet_aton
 339 function returns nonzero if the address is valid,
 340 .Li 0
 341 if the address is invalid.
 342 .Pp
 343 The
 344 .Fn inet_ntop
 345 function returns a pointer to the buffer that contains a string if the
 346 conversion succeeds.
 347 Otherwise,
 348 .Dv NULL
 349 is returned.
 350 Upon failure,
 351 .Va errno
 352 is set to
 353 .Er EAFNOSUPPORT
 354 if the
 355 .Fa af
 356 argument is invalid or
 357 .Er ENOSPC
 358 if the size of the result buffer is inadequate.
 359 .Pp
 360 The
 361 .Fn inet_pton
 362 function returns
 363 .Li 1
 364 if the conversion succeeds,
 365 .Li 0
 366 if the input is not a valid IPv4 dotted-decimal string or a valid IPv6
 367 address string.
 368 The function returns
 369 .Li -1
 370 with
 371 .Va errno
 372 set to
 373 .Er EAFNOSUPPORT
 374 if the
 375 .Fa af
 376 argument is unknown.
 377 .Pp
 378 The value
 379 .Dv INADDR_NONE ,
 380 which is equivalent to
 381 .Li (in_addr_t)(-1) ,
 382 is returned by
 383 .Fn inet_addr
 384 and
 385 .Fn inet_network
 386 for malformed requests.
 387 .Pp
 388 The functions
 389 .Fn inet_netof
 390 and
 391 .Fn inet_lnaof
 392 break apart IPv4 host addresses, returning the network number and local network
 393 address part, respectively.
 394 .Pp
 395 The function
 396 .Fn inet_ntoa
 397 returns a pointer to a string in the base 256 notation
 398 .Ql d.d.d.d ,
 399 described in the section on IPv4 addresses.
 400 .Sh MT-LEVEL
 401 .Sy Safe
 402 .Sh INTERFACE STABILITY
 403 The
 404 .Fn inet_ntop ,
 405 .Fn inet_pton ,
 406 .Fn inet_aton ,
 407 .Fn inet_addr ,
 408 and
 409 .Fn inet_network
 410 functions are
 411 .Sy Committed .
 412 The
 413 .Fn inet_lnaof ,
 414 .Fn inet_makeaddr ,
 415 .Fn inet_netof ,
 416 and
 417 .Fn inet_network
 418 functions are
 419 .Sy Obsolete Committed .
 420 .Sh SEE ALSO
 421 .Xr inet.h 3HEAD ,
 422 .Xr gethostbyname 3C ,
 423 .Xr getipnodebyname 3C ,
 424 .Xr getnetbyname 3C ,
 425 .Xr hosts 4 ,
 426 .Xr networks 4 ,
 427 .Xr attributes 5
 428 .Sh NOTES
 429 The return value from
 430 .Fn inet_ntoa
 431 points to a buffer which is overwritten on each call.
 432 This buffer is implemented as thread-specific data in multithreaded
 433 applications.
 434 .Pp
 435 IPv4-mapped addresses are not recommended.
 436 .Sh BUGS
 437 The problem of host byte ordering versus network byte ordering is confusing.
 438 .Pp
 439 A simple way to specify Class C network addresses in a manner similar to that
 440 for Class B and Class A is needed.