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