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