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 3C 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 89The 90.Fn inet_ntop 91and 92.Fn inet_pton 93functions can manipulate both IPv4 and IPv6 addresses. 94The 95.Fn inet_aton , 96.Fn inet_addr , 97.Fn inet_network , 98.Fn inet_makeaddr , 99.Fn inet_lnaof , 100.Fn inet_netof , 101and 102.Fn inet_ntoa 103functions can only manipulate IPv4 addresses. 104.Pp 105The 106.Fn inet_ntop 107function converts a numeric address into a string suitable for presentation. 108The 109.Fa af 110argument specifies the family of the address which can be 111.Dv AF_INET 112or 113.Dv AF_INET6 . 114The 115.Fa addr 116argument points to a buffer that holds an IPv4 address if the 117.Fa af 118argument is 119.Dv AF_INET . 120The 121.Fa addr 122argument points to a buffer that holds an IPv6 address if the 123.Fa af 124argument is 125.Dv AF_INET6 . 126The address must be in network byte order. 127The 128.Fa cp 129argument points to a buffer where the function stores the resulting string. 130The application must specify a non-NULL 131.Fa cp 132argument. 133The 134.Fa size 135argument specifies the size of this buffer. 136For IPv6 addresses, the buffer must be at least 46-octets. 137For IPv4 addresses, the buffer must be at least 16-octets. 138To allow applications to easily declare buffers of the proper size to store IPv4 139and 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 146The 147.Fn inet_pton 148function converts the standard text presentation form of a function to the 149numeric binary form. 150The 151.Fa af 152argument specifies the family of the address. 153Currently, the 154.Dv AF_INET 155and 156.Dv AF_INET6 157address families are supported. 158The 159.Fa cp 160argument points to the string being passed in. 161The 162.Fa addr 163argument points to a buffer where the function stores the numeric address. 164The calling application must ensure that the buffer referred to by 165.Fa addr 166is large enough to hold the numeric address, at least 4 bytes for 167.Dv AF_INET 168or 16 bytes for 169.Dv AF_INET6 . 170.Pp 171The 172.Fn inet_aton , 173.Fn inet_addr , 174and 175.Fn inet_network 176functions interpret character strings that represent numbers expressed in the 177IPv4 standard 178.Ql \&. 179notation, returning numbers suitable for use as IPv4 addresses and IPv4 network 180numbers, respectively. 181The 182.Fn inet_makeaddr 183function uses an IPv4 network number and a local network address to construct 184an IPv4 address. 185The 186.Fn inet_netof 187and 188.Fn inet_lnaof 189functions break apart IPv4 host addresses, then return the network number and 190local network address, respectively. 191.Pp 192The 193.Fn inet_ntoa 194function returns a pointer to a string in the base 256 notation 195.Ql d.d.d.d . 196See the following section on IPv4 addresses. 197.Pp 198Internet addresses are returned in network order, bytes ordered from left to 199right. 200Network numbers and local address parts are returned as machine format integer 201values. 202.Ss IPv6 Addresses 203There are three conventional forms for representing IPv6 addresses as strings: 204.Bl -enum 205.It 206The preferred form is 207.Ql x:x:x:x:x:x:x:x , 208where the 209.Li x No 's 210are the 211hexadecimal values of the eight 16-bit pieces of the address. 212For example, 213.Ql 1080:0:0:0:8:800:200C:417A . 214.Pp 215It is not necessary to write the leading zeros in an individual field. 216There must be at least one numeral in every field, except when the special 217syntax described in the following is used. 218.It 219It is common for addresses to contain long strings of zero bits in some 220methods used to allocate certain IPv6 address styles. 221A special syntax is available to compress the zeros. 222The use of 223.Ql :: 224indicates multiple groups of 16 bits of zeros. 225The 226.Ql :: 227may only appear once in an address. 228The 229.Ql :: 230can also be used to compress the leading and trailing zeros in an address. 231For example, 232.Ql 1080::8:800:200C:417A . 233.It 234The alternative form 235.Ql x:x:x:x:x:x:d.d.d.d 236is sometimes more convenient when dealing with a mixed environment of IPv4 and 237IPv6 nodes. 238The 239.Li x No 's 240in this form represent the hexadecimal values of the six high-order 16-bit 241pieces of the address. 242The 243.Li d No 's 244represent the decimal values of the four low-order 8-bit pieces of the standard 245IPv4 address. 246For example: 247.Bd -literal 248::FFFF:129.144.52.38 . 249::129.144.52.38 250.Ed 251.Pp 252The 253.Ql ::FFFF:d.d.d.d 254and 255.Ql ::d.d.d.d 256pieces are the general forms of an IPv4-mapped IPv6 address and an 257IPv4-compatible IPv6 address. 258.Pp 259The IPv4 portion must be in the 260.Ql d.d.d.d 261form. 262The 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 270The 271.Ql ::FFFF:d 272form is a valid but unconventional representation of the IPv4-compatible IPv6 273address 274.Ql ::255.255.0.d . 275.Pp 276The 277.Ql ::d 278form corresponds to the general IPv6 address 279.Ql 0:0:0:0:0:0:0:d . 280.El 281.Ss IPv4 Addresses 282Values specified using 283.Ql \&. 284notation take one of the following forms: 285.Bd -literal 286d.d.d.d 287d.d.d 288d.d 289d 290.Ed 291.Pp 292When four parts are specified, each part is interpreted as a byte of data and 293assigned from left to right to the four bytes of an IPv4 address. 294.Pp 295When a three-part address is specified, the last part is interpreted as a 29616-bit quantity and placed in the right most two bytes of the network address. 297The three part address format is convenient for specifying Class B network 298addresses such as 299.Ql 128.net.host . 300.Pp 301When a two-part address is supplied, the last part is interpreted as a 24-bit 302quantity and placed in the right most three bytes of the network address. 303The two part address format is convenient for specifying Class A network 304addresses such as 305.Ql net.host . 306.Pp 307When only one part is given, the value is stored directly in the network 308address without any byte rearrangement. 309.Pp 310With the exception of 311.Fn inet_pton , 312numbers supplied as parts in 313.Ql \&. 314notation may be decimal, octal, or hexadecimal, as specified in C language. 315For example, a leading 316.Ql 0x 317or 318.Ql 0X 319implies hexadecimal. 320A leading 321.Ql 0 322implies octal. 323Otherwise, the number is interpreted as decimal. 324.Pp 325For IPv4 addresses, 326.Fn inet_pton 327accepts only a string in standard IPv4 dot notation 328.Ql d.d.d.d . 329.Pp 330Each number has one to three digits with a decimal value between 0 and 255. 331.Pp 332The 333.Fn inet_addr 334function has been obsoleted by 335.Fn inet_aton . 336.Sh RETURN VALUES 337The 338.Fn inet_aton 339function returns nonzero if the address is valid, 340.Li 0 341if the address is invalid. 342.Pp 343The 344.Fn inet_ntop 345function returns a pointer to the buffer that contains a string if the 346conversion succeeds. 347Otherwise, 348.Dv NULL 349is returned. 350Upon failure, 351.Va errno 352is set to 353.Er EAFNOSUPPORT 354if the 355.Fa af 356argument is invalid or 357.Er ENOSPC 358if the size of the result buffer is inadequate. 359.Pp 360The 361.Fn inet_pton 362function returns 363.Li 1 364if the conversion succeeds, 365.Li 0 366if the input is not a valid IPv4 dotted-decimal string or a valid IPv6 367address string. 368The function returns 369.Li -1 370with 371.Va errno 372set to 373.Er EAFNOSUPPORT 374if the 375.Fa af 376argument is unknown. 377.Pp 378The value 379.Dv INADDR_NONE , 380which is equivalent to 381.Li (in_addr_t)(-1) , 382is returned by 383.Fn inet_addr 384and 385.Fn inet_network 386for malformed requests. 387.Pp 388The functions 389.Fn inet_netof 390and 391.Fn inet_lnaof 392break apart IPv4 host addresses, returning the network number and local network 393address part, respectively. 394.Pp 395The function 396.Fn inet_ntoa 397returns a pointer to a string in the base 256 notation 398.Ql d.d.d.d , 399described in the section on IPv4 addresses. 400.Sh MT-LEVEL 401.Sy Safe 402.Sh INTERFACE STABILITY 403The 404.Fn inet_ntop , 405.Fn inet_pton , 406.Fn inet_aton , 407.Fn inet_addr , 408and 409.Fn inet_network 410functions are 411.Sy Committed . 412The 413.Fn inet_lnaof , 414.Fn inet_makeaddr , 415.Fn inet_netof , 416and 417.Fn inet_network 418functions are 419.Sy Obsolete Committed . 420.Sh SEE ALSO 421.Xr inet.h 3HEAD , 422.Xr gethostbyname 3NSL , 423.Xr getipnodebyname 3SOCKET , 424.Xr getnetbyname 3SOCKET , 425.Xr hosts 5 , 426.Xr networks 5 , 427.Xr attributes 7 428.Sh NOTES 429The return value from 430.Fn inet_ntoa 431points to a buffer which is overwritten on each call. 432This buffer is implemented as thread-specific data in multithreaded 433applications. 434.Pp 435IPv4-mapped addresses are not recommended. 436.Sh BUGS 437The problem of host byte ordering versus network byte ordering is confusing. 438.Pp 439A simple way to specify Class C network addresses in a manner similar to that 440for Class B and Class A is needed. 441