1.\" Copyright (c) 1983, 1990, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)inet.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd June 14, 2004 36.Dt INET 3 37.Os 38.Sh NAME 39.Nm inet_aton , 40.Nm inet_addr , 41.Nm inet_network , 42.Nm inet_ntoa , 43.Nm inet_ntop , 44.Nm inet_pton , 45.Nm inet_makeaddr , 46.Nm inet_lnaof , 47.Nm inet_netof 48.Nd Internet address manipulation routines 49.Sh LIBRARY 50.Lb libc 51.Sh SYNOPSIS 52.In sys/types.h 53.In sys/socket.h 54.In netinet/in.h 55.In arpa/inet.h 56.Ft int 57.Fn inet_aton "const char *cp" "struct in_addr *pin" 58.Ft in_addr_t 59.Fn inet_addr "const char *cp" 60.Ft in_addr_t 61.Fn inet_network "const char *cp" 62.Ft char * 63.Fn inet_ntoa "struct in_addr in" 64.Ft const char * 65.Fo inet_ntop 66.Fa "int af" 67.Fa "const void * restrict src" 68.Fa "char * restrict dst" 69.Fa "socklen_t size" 70.Fc 71.Ft int 72.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" 73.Ft struct in_addr 74.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" 75.Ft in_addr_t 76.Fn inet_lnaof "struct in_addr in" 77.Ft in_addr_t 78.Fn inet_netof "struct in_addr in" 79.Sh DESCRIPTION 80The routines 81.Fn inet_aton , 82.Fn inet_addr 83and 84.Fn inet_network 85interpret character strings representing 86numbers expressed in the Internet standard 87.Ql .\& 88notation. 89.Pp 90The 91.Fn inet_pton 92function converts a presentation format address (that is, printable form 93as held in a character string) to network format (usually a 94.Ft struct in_addr 95or some other internal binary representation, in network byte order). 96It returns 1 if the address was valid for the specified address family, or 970 if the address wasn't parseable in the specified address family, or -1 98if some system error occurred (in which case 99.Va errno 100will have been set). 101This function is presently valid for 102.Dv AF_INET 103and 104.Dv AF_INET6 . 105.Pp 106The 107.Fn inet_aton 108routine interprets the specified character string as an Internet address, 109placing the address into the structure provided. 110It returns 1 if the string was successfully interpreted, 111or 0 if the string is invalid. 112The 113.Fn inet_addr 114and 115.Fn inet_network 116functions return numbers suitable for use 117as Internet addresses and Internet network 118numbers, respectively. 119.Pp 120The function 121.Fn inet_ntop 122converts an address 123.Fa *src 124from network format 125(usually a 126.Ft struct in_addr 127or some other binary form, in network byte order) to presentation format 128(suitable for external display purposes). 129The 130.Fa size 131argument specifies the size, in bytes, of the buffer 132.Fa *dst . 133It returns NULL if a system error occurs (in which case, 134.Va errno 135will have been set), or it returns a pointer to the destination string. 136This function is presently valid for 137.Dv AF_INET 138and 139.Dv AF_INET6 . 140.Pp 141The routine 142.Fn inet_ntoa 143takes an Internet address and returns an 144.Tn ASCII 145string representing the address in 146.Ql .\& 147notation. 148The routine 149.Fn inet_makeaddr 150takes an Internet network number and a local 151network address and constructs an Internet address 152from it. 153The routines 154.Fn inet_netof 155and 156.Fn inet_lnaof 157break apart Internet host addresses, returning 158the network number and local network address part, 159respectively. 160.Pp 161All Internet addresses are returned in network 162order (bytes ordered from left to right). 163All network numbers and local address parts are 164returned as machine byte order integer values. 165.Sh INTERNET ADDRESSES 166Values specified using the 167.Ql .\& 168notation take one 169of the following forms: 170.Bd -literal -offset indent 171a.b.c.d 172a.b.c 173a.b 174a 175.Ed 176.Pp 177When four parts are specified, each is interpreted 178as a byte of data and assigned, from left to right, 179to the four bytes of an Internet address. 180Note 181that when an Internet address is viewed as a 32-bit 182integer quantity on the 183.Tn VAX 184the bytes referred to 185above appear as 186.Dq Li d.c.b.a . 187That is, 188.Tn VAX 189bytes are 190ordered from right to left. 191.Pp 192When a three part address is specified, the last 193part is interpreted as a 16-bit quantity and placed 194in the right-most two bytes of the network address. 195This makes the three part address format convenient 196for specifying Class B network addresses as 197.Dq Li 128.net.host . 198.Pp 199When a two part address is supplied, the last part 200is interpreted as a 24-bit quantity and placed in 201the right most three bytes of the network address. 202This makes the two part address format convenient 203for specifying Class A network addresses as 204.Dq Li net.host . 205.Pp 206When only one part is given, the value is stored 207directly in the network address without any byte 208rearrangement. 209.Pp 210All numbers supplied as 211.Dq parts 212in a 213.Ql .\& 214notation 215may be decimal, octal, or hexadecimal, as specified 216in the C language (i.e., a leading 0x or 0X implies 217hexadecimal; otherwise, a leading 0 implies octal; 218otherwise, the number is interpreted as decimal). 219.Pp 220The 221.Fn inet_aton 222and 223.Fn inet_ntoa 224functions are semi-deprecated in favor of the 225.Xr addr2ascii 3 226family. 227However, since those functions are not yet widely implemented, 228portable programs cannot rely on their presence and will continue 229to use the 230.Xr inet 3 231functions for some time. 232.Sh DIAGNOSTICS 233The constant 234.Dv INADDR_NONE 235is returned by 236.Fn inet_addr 237and 238.Fn inet_network 239for malformed requests. 240.Sh ERRORS 241The 242.Fn inet_ntop 243call fails if: 244.Bl -tag -width Er 245.It Bq Er ENOSPC 246.Fa size 247was not large enough to store the presentation form of the address. 248.It Bq Er EAFNOSUPPORT 249.Fa *src 250was not an 251.Dv AF_INET 252or 253.Dv AF_INET6 254family address. 255.El 256.Sh SEE ALSO 257.Xr addr2ascii 3 , 258.Xr byteorder 3 , 259.Xr gethostbyname 3 , 260.Xr getnetent 3 , 261.Xr inet_net 3 , 262.Xr hosts 5 , 263.Xr networks 5 264.Rs 265.%R RFC 266.%N 2373 267.%D July 1998 268.%T "IP Version 6 Addressing Architecture" 269.Re 270.Sh STANDARDS 271The 272.Fn inet_ntop 273and 274.Fn inet_pton 275functions conform to 276.St -xns5.2 . 277Note that 278.Fn inet_pton 279does not accept 1-, 2-, or 3-part dotted addresses; all four parts 280must be specified and are interpreted only as decimal values. 281This is a narrower input set than that accepted by 282.Fn inet_aton . 283.Sh HISTORY 284These 285functions appeared in 286.Bx 4.2 . 287.Sh BUGS 288The value 289.Dv INADDR_NONE 290(0xffffffff) is a valid broadcast address, but 291.Fn inet_addr 292cannot return that value without indicating failure. 293The newer 294.Fn inet_aton 295function does not share this problem. 296The problem of host byte ordering versus network byte ordering is 297confusing. 298The string returned by 299.Fn inet_ntoa 300resides in a static memory area. 301.Pp 302Inet_addr should return a 303.Fa struct in_addr . 304