1.\" $NetBSD: inet.3,v 1.7 2023/01/18 23:16:05 riastradh Exp $ 2.\" 3.\" Copyright (c) 1983, 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)inet.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd July 25, 2012 33.Dt INET 3 34.Os 35.Sh NAME 36.Nm inet_addr , 37.Nm inet_aton , 38.Nm inet_lnaof , 39.Nm inet_makeaddr , 40.Nm inet_netof , 41.Nm inet_network , 42.Nm inet_ntoa , 43.Nm inet_ntop , 44.Nm inet_pton , 45.Nm addr , 46.Nm ntoa , 47.Nm network 48.Nd Internet address manipulation routines 49.Sh LIBRARY 50.Lb libc 51.Sh SYNOPSIS 52.In arpa/inet.h 53.Ft in_addr_t 54.Fn inet_addr "const char *cp" 55.Ft int 56.Fn inet_aton "const char *cp" "struct in_addr *addr" 57.Ft in_addr_t 58.Fn inet_lnaof "struct in_addr in" 59.Ft struct in_addr 60.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" 61.Ft in_addr_t 62.Fn inet_netof "struct in_addr in" 63.Ft in_addr_t 64.Fn inet_network "const char *cp" 65.Ft char * 66.Fn inet_ntoa "struct in_addr in" 67.Ft const char * 68.Fn inet_ntop "int af" "const void * restrict src" "char * restrict dst" "socklen_t size" 69.Ft int 70.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" 71.Sh DESCRIPTION 72The routines 73.Fn inet_aton , 74.Fn inet_addr 75and 76.Fn inet_network 77interpret character strings representing 78numbers expressed in the Internet standard 79.Qq dotted quad 80notation. 81.Pp 82The 83.Fn inet_pton 84function converts a presentation format address (that is, printable form 85as held in a character string) to network format (usually a 86.Ft struct in_addr 87or some other internal binary representation, in network byte order). 88It returns 1 if the address was valid for the specified address family, or 890 if the address wasn't parsable in the specified address family, or -1 90if some system error occurred (in which case 91.Va errno 92will have been set). 93This function is presently valid for 94.Dv AF_INET 95and 96.Dv AF_INET6 . 97.Pp 98The 99.Fn inet_aton 100routine interprets the specified character string as an Internet address, 101placing the address into the structure provided. 102It returns 1 if the string was successfully interpreted, 103or 0 if the string is invalid. 104.Pp 105The 106.Fn inet_addr 107and 108.Fn inet_network 109functions return numbers suitable for use 110as Internet addresses and Internet network 111numbers, respectively. 112.Pp 113The function 114.Fn inet_ntop 115converts an address from network format (usually a 116.Ft struct in_addr 117or some other binary form, in network byte order) to presentation format 118(suitable for external display purposes). 119It returns NULL if a system error occurs (in which case, 120.Va errno 121will have been set), or it returns a pointer to the destination string. 122The 123.Fa size 124parameter is the size of the 125.Fa dst 126buffer. 127For 128.Dv AF_INET , 129this must have space for 130.Dv INET_ADDRSTRLEN Pq 16 131bytes; for 132.Dv AF_INET6 , 133this must have space for 134.Dv INET6_ADDRSTRLEN Pq 46 135bytes. 136.Pp 137The routine 138.Fn inet_ntoa 139takes an Internet address and returns an 140.Tn ASCII 141string representing the address in 142.Qq dotted quad 143notation. 144.Pp 145The routine 146.Fn inet_makeaddr 147takes an Internet network number and a local network address (both in 148host order) and constructs an Internet address from it. 149Note that to convert only a single value to a 150.Ft struct in_addr 151form that value should be passed as the first parameter and 152.Ql 0L 153should be given for the second parameter. 154.Pp 155The routines 156.Fn inet_netof 157and 158.Fn inet_lnaof 159break apart Internet host addresses, returning the network number and 160local network address part, respectively (both in host order). 161.Pp 162All Internet addresses are returned in network 163order (bytes ordered from left to right). 164All network numbers and local address parts are 165returned as machine format integer values. 166.Sh INTERNET ADDRESSES (IP VERSION 4) 167Values specified using the 168.Qq dotted quad 169notation take one 170of the following forms: 171.Bd -literal -offset indent 172a.b.c.d 173a.b.c 174a.b 175a 176.Ed 177.Pp 178When four parts are specified, each is interpreted 179as a byte of data and assigned, from left to right, 180to the four bytes of an Internet address. 181Note that when an Internet address is viewed as a 32-bit 182integer quantity on a system that uses little-endian 183byte order (e.g. 184.Tn Intel i386, i486 185and 186.Tn Pentium 187processors) the bytes referred to above appear as 188.Dq Li d.c.b.a . 189That is, little-endian bytes are ordered from right to left. 190.Pp 191When a three part address is specified, the last 192part is interpreted as a 16-bit quantity and placed 193in the right-most two bytes of the network address. 194This makes the three part address format convenient 195for specifying Class B network addresses as 196.Dq Li 128.net.host . 197.Pp 198When a two part address is supplied, the last part 199is interpreted as a 24-bit quantity and placed in 200the right most three bytes of the network address. 201This makes the two part address format convenient 202for specifying Class A network addresses as 203.Dq Li net.host . 204.Pp 205When only one part is given, the value is stored 206directly in the network address without any byte 207rearrangement. 208.Pp 209All numbers supplied as 210.Dq parts 211in a 212.Qq dotted quad 213notation 214may be decimal, octal, or hexadecimal, as specified 215in the C language (i.e., a leading 0x or 0X implies 216hexadecimal; otherwise, a leading 0 implies octal; 217otherwise, the number is interpreted as decimal). 218.Sh INTERNET ADDRESSES (IP VERSION 6) 219In order to support scoped IPv6 addresses, 220the use of 221.Xr getaddrinfo 3 222and 223.Xr getnameinfo 3 224is recommended rather than the functions presented here. 225.Pp 226The presentation format of an IPv6 address is given in RFC 2373: 227.Pp 228There are three conventional forms for representing IPv6 addresses as 229text strings: 230.Bl -enum 231.It 232The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the 233hexadecimal values of the eight 16-bit pieces of the address. 234Examples: 235.Bd -literal -offset indent 236FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 2371080:0:0:0:8:800:200C:417A 238.Ed 239.Pp 240Note that it is not necessary to write the leading zeros in an 241individual field, but there must be at least one numeral in 242every field (except for the case described in 2). 243.It 244Due to the method of allocating certain styles of IPv6 245addresses, it will be common for addresses to contain long 246strings of zero bits. 247In order to make writing addresses 248containing zero bits easier, a special syntax is available to 249compress the zeros. 250The use of ``::'' indicates multiple groups of 16-bits of zeros. 251The ``::'' can only appear once in an address. 252The ``::'' can also be used to compress the leading 253and/or trailing zeros in an address. 254.Pp 255For example the following addresses: 256.Bd -literal -offset indent 2571080:0:0:0:8:800:200C:417A a unicast address 258FF01:0:0:0:0:0:0:43 a multicast address 2590:0:0:0:0:0:0:1 the loopback address 2600:0:0:0:0:0:0:0 the unspecified addresses 261.Ed 262.Pp 263may be represented as: 264.Bd -literal -offset indent 2651080::8:800:200C:417A a unicast address 266FF01::43 a multicast address 267::1 the loopback address 268:: the unspecified addresses 269.Ed 270.It 271An alternative form that is sometimes more convenient when 272dealing with a mixed environment of IPv4 and IPv6 nodes is 273x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values 274of the six high-order 16-bit pieces of the address, and the 'd's 275are the decimal values of the four low-order 8-bit pieces of the 276address (standard IPv4 representation). 277Examples: 278.Bd -literal -offset indent 2790:0:0:0:0:0:13.1.68.3 2800:0:0:0:0:FFFF:129.144.52.38 281.Ed 282.Pp 283or in compressed form: 284.Bd -literal -offset indent 285::13.1.68.3 286::FFFF:129.144.52.38 287.Ed 288.El 289.Sh RETURN VALUES 290The constant 291.Dv INADDR_NONE 292is returned by 293.Fn inet_addr 294and 295.Fn inet_network 296for malformed requests. 297.Sh ERRORS 298The 299.Fn inet_ntop 300and 301.Fn inet_pton 302functions may fail with 303.Bl -tag -width Er 304.It Bq Er EAFNOSUPPORT 305The value of 306.Fa af 307was not 308.Dv AF_INET 309or 310.Dv AF_INET6 . 311.El 312.Pp 313The 314.Fn inet_ntop 315function may fail with 316.Bl -tag -width Er 317.It Bq Er ENOSPC 318The 319.Fa size 320indicated for 321.Fa dst 322was too small to store the presentation form of the network address. 323.El 324.Sh SEE ALSO 325.Xr byteorder 3 , 326.Xr gethostbyname 3 , 327.Xr getnetent 3 , 328.Xr inet_net 3 , 329.Xr hosts 5 , 330.Xr networks 5 331.Rs 332.%R RFC 2373 333.%D July 1998 334.%T "IP Version 6 Addressing Architecture" 335.Re 336.Rs 337.%R RFC 3493 338.%D February 2003 339.%T "Basic Socket Interface Extensions for IPv6" 340.Re 341.Sh STANDARDS 342The 343.Fn inet_ntop 344and 345.Fn inet_pton 346functions conform to 347.St -p1003.1-2001 . 348Note that 349.Fn inet_pton 350does not accept 1-, 2-, or 3-part dotted addresses; all four parts 351must be specified. 352Additionally all four parts of a dotted address must be decimal. 353This is a narrower input set than that accepted by 354.Fn inet_aton . 355.Sh HISTORY 356The 357.Fn inet_addr , 358.Fn inet_network , 359.Fn inet_makeaddr , 360.Fn inet_lnaof 361and 362.Fn inet_netof 363functions appeared in 364.Bx 4.2 . 365They were changed to use 366.Vt in_addr_t 367in place of 368.Vt unsigned long 369in 370.Nx 2.0 . 371The 372.Fn inet_aton 373and 374.Fn inet_ntoa 375functions appeared in 376.Bx 4.3 . 377The 378.Fn inet_pton 379and 380.Fn inet_ntop 381functions appeared in BIND 4.9.4 and thence 382.Nx 1.3 ; 383they were also in 384.St -xns5.2 . 385.Sh BUGS 386The value 387.Dv INADDR_NONE 388(0xffffffff) is a valid broadcast address, but 389.Fn inet_addr 390cannot return that value without indicating failure. 391The newer 392.Fn inet_aton 393function does not share this problem. 394.Pp 395The problem of host byte ordering versus network byte ordering is 396confusing. 397.Pp 398The string returned by 399.Fn inet_ntoa 400resides in a static memory area. 401.Pp 402The function 403.Fn inet_addr 404should return a 405.Vt struct in_addr . 406.Pp 407The function 408.Fn inet_network 409does not support byte rearrangement for one, two, and three 410part addresses. 411