1.\" $NetBSD: inet.3,v 1.5 2012/07/25 14:51:15 ginsbach 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.Ar size 124parameter is the size of the 125.Ar buf 126argument. 127.Pp 128The routine 129.Fn inet_ntoa 130takes an Internet address and returns an 131.Tn ASCII 132string representing the address in 133.Qq dotted quad 134notation. 135.Pp 136The routine 137.Fn inet_makeaddr 138takes an Internet network number and a local network address (both in 139host order) and constructs an Internet address from it. 140Note that to convert only a single value to a 141.Ft struct in_addr 142form that value should be passed as the first parameter and 143.Ql 0L 144should be given for the second parameter. 145.Pp 146The routines 147.Fn inet_netof 148and 149.Fn inet_lnaof 150break apart Internet host addresses, returning the network number and 151local network address part, respectively (both in host order). 152.Pp 153All Internet addresses are returned in network 154order (bytes ordered from left to right). 155All network numbers and local address parts are 156returned as machine format integer values. 157.Sh INTERNET ADDRESSES (IP VERSION 4) 158Values specified using the 159.Qq dotted quad 160notation take one 161of the following forms: 162.Bd -literal -offset indent 163a.b.c.d 164a.b.c 165a.b 166a 167.Ed 168.Pp 169When four parts are specified, each is interpreted 170as a byte of data and assigned, from left to right, 171to the four bytes of an Internet address. 172Note that when an Internet address is viewed as a 32-bit 173integer quantity on a system that uses little-endian 174byte order (e.g. 175.Tn Intel i386, i486 176and 177.Tn Pentium 178processors) the bytes referred to above appear as 179.Dq Li d.c.b.a . 180That is, little-endian bytes are ordered from right to left. 181.Pp 182When a three part address is specified, the last 183part is interpreted as a 16-bit quantity and placed 184in the right-most two bytes of the network address. 185This makes the three part address format convenient 186for specifying Class B network addresses as 187.Dq Li 128.net.host . 188.Pp 189When a two part address is supplied, the last part 190is interpreted as a 24-bit quantity and placed in 191the right most three bytes of the network address. 192This makes the two part address format convenient 193for specifying Class A network addresses as 194.Dq Li net.host . 195.Pp 196When only one part is given, the value is stored 197directly in the network address without any byte 198rearrangement. 199.Pp 200All numbers supplied as 201.Dq parts 202in a 203.Qq dotted quad 204notation 205may be decimal, octal, or hexadecimal, as specified 206in the C language (i.e., a leading 0x or 0X implies 207hexadecimal; otherwise, a leading 0 implies octal; 208otherwise, the number is interpreted as decimal). 209.Sh INTERNET ADDRESSES (IP VERSION 6) 210In order to support scoped IPv6 addresses, 211the use of 212.Xr getaddrinfo 3 213and 214.Xr getnameinfo 3 215is recommended rather than the functions presented here. 216.Pp 217The presentation format of an IPv6 address is given in RFC 2373: 218.Pp 219There are three conventional forms for representing IPv6 addresses as 220text strings: 221.Bl -enum 222.It 223The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the 224hexadecimal values of the eight 16-bit pieces of the address. 225Examples: 226.Bd -literal -offset indent 227FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 2281080:0:0:0:8:800:200C:417A 229.Ed 230.Pp 231Note that it is not necessary to write the leading zeros in an 232individual field, but there must be at least one numeral in 233every field (except for the case described in 2). 234.It 235Due to the method of allocating certain styles of IPv6 236addresses, it will be common for addresses to contain long 237strings of zero bits. 238In order to make writing addresses 239containing zero bits easier, a special syntax is available to 240compress the zeros. 241The use of ``::'' indicates multiple groups of 16-bits of zeros. 242The ``::'' can only appear once in an address. 243The ``::'' can also be used to compress the leading 244and/or trailing zeros in an address. 245.Pp 246For example the following addresses: 247.Bd -literal -offset indent 2481080:0:0:0:8:800:200C:417A a unicast address 249FF01:0:0:0:0:0:0:43 a multicast address 2500:0:0:0:0:0:0:1 the loopback address 2510:0:0:0:0:0:0:0 the unspecified addresses 252.Ed 253.Pp 254may be represented as: 255.Bd -literal -offset indent 2561080::8:800:200C:417A a unicast address 257FF01::43 a multicast address 258::1 the loopback address 259:: the unspecified addresses 260.Ed 261.It 262An alternative form that is sometimes more convenient when 263dealing with a mixed environment of IPv4 and IPv6 nodes is 264x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values 265of the six high-order 16-bit pieces of the address, and the 'd's 266are the decimal values of the four low-order 8-bit pieces of the 267address (standard IPv4 representation). 268Examples: 269.Bd -literal -offset indent 2700:0:0:0:0:0:13.1.68.3 2710:0:0:0:0:FFFF:129.144.52.38 272.Ed 273.Pp 274or in compressed form: 275.Bd -literal -offset indent 276::13.1.68.3 277::FFFF:129.144.52.38 278.Ed 279.El 280.Sh DIAGNOSTICS 281The constant 282.Dv INADDR_NONE 283is returned by 284.Fn inet_addr 285and 286.Fn inet_network 287for malformed requests. 288.Sh ERRORS 289The 290.Fn inet_ntop 291and 292.Fn inet_pton 293functions may fail with 294.Bl -tag -width Er 295.It Bq Er EAFNOSUPPORT 296The value of 297.Fa af 298was not 299.Dv AF_INET 300or 301.Dv AF_INET6 . 302.El 303.Pp 304The 305.Fn inet_ntop 306function may fail with 307.Bl -tag -width Er 308.It Bq Er ENOSPC 309The 310.Fa size 311indicated for 312.Fa dst 313was too small to store the presentation form of the network address. 314.El 315.Sh SEE ALSO 316.Xr byteorder 3 , 317.Xr gethostbyname 3 , 318.Xr getnetent 3 , 319.Xr inet_net 3 , 320.Xr hosts 5 , 321.Xr networks 5 322.Rs 323.%R RFC 2373 324.%D July 1998 325.%T "IP Version 6 Addressing Architecture" 326.Re 327.Rs 328.%R RFC 3493 329.%D February 2003 330.%T "Basic Socket Interface Extensions for IPv6" 331.Re 332.Sh STANDARDS 333The 334.Fn inet_ntop 335and 336.Fn inet_pton 337functions conform to 338.St -p1003.1-2001 . 339Note that 340.Fn inet_pton 341does not accept 1-, 2-, or 3-part dotted addresses; all four parts 342must be specified. 343Additionally all four parts of a dotted address must be decimal. 344This is a narrower input set than that accepted by 345.Fn inet_aton . 346.Sh HISTORY 347The 348.Fn inet_addr , 349.Fn inet_network , 350.Fn inet_makeaddr , 351.Fn inet_lnaof 352and 353.Fn inet_netof 354functions appeared in 355.Bx 4.2 . 356They were changed to use 357.Vt in_addr_t 358in place of 359.Vt unsigned long 360in 361.Nx 2.0 . 362The 363.Fn inet_aton 364and 365.Fn inet_ntoa 366functions appeared in 367.Bx 4.3 . 368The 369.Fn inet_pton 370and 371.Fn inet_ntop 372functions appeared in BIND 4.9.4 and thence 373.Nx 1.3 ; 374they were also in 375.St -xns5.2 . 376.Sh BUGS 377The value 378.Dv INADDR_NONE 379(0xffffffff) is a valid broadcast address, but 380.Fn inet_addr 381cannot return that value without indicating failure. 382The newer 383.Fn inet_aton 384function does not share this problem. 385.Pp 386The problem of host byte ordering versus network byte ordering is 387confusing. 388.Pp 389The string returned by 390.Fn inet_ntoa 391resides in a static memory area. 392.Pp 393The function 394.Fn inet_addr 395should return a 396.Vt struct in_addr . 397.Pp 398The function 399.Fn inet_network 400does not support byte rearrangement for one, two, and three 401part addresses. 402