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, 2007 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_ntoa_r , 40.Nm inet_ntop , 41.Nm inet_pton , 42.Nm inet_makeaddr , 43.Nm inet_lnaof , 44.Nm inet_netof 45.Nd Internet address manipulation routines 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In sys/types.h 50.In sys/socket.h 51.In netinet/in.h 52.In arpa/inet.h 53.Ft int 54.Fn inet_aton "const char *cp" "struct in_addr *pin" 55.Ft in_addr_t 56.Fn inet_addr "const char *cp" 57.Ft in_addr_t 58.Fn inet_network "const char *cp" 59.Ft char * 60.Fn inet_ntoa "struct in_addr in" 61.Ft char * 62.Fo inet_ntoa_r 63.Fa "struct in_addr in" 64.Fa "char *buf" 65.Fa "socklen_t size" 66.Fc 67.Ft const char * 68.Fo inet_ntop 69.Fa "int af" 70.Fa "const void * restrict src" 71.Fa "char * restrict dst" 72.Fa "socklen_t size" 73.Fc 74.Ft int 75.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" 76.Ft struct in_addr 77.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" 78.Ft in_addr_t 79.Fn inet_lnaof "struct in_addr in" 80.Ft in_addr_t 81.Fn inet_netof "struct in_addr in" 82.Sh DESCRIPTION 83The routines 84.Fn inet_aton , 85.Fn inet_addr 86and 87.Fn inet_network 88interpret character strings representing 89numbers expressed in the Internet standard 90.Ql .\& 91notation. 92.Pp 93The 94.Fn inet_pton 95function converts a presentation format address (that is, printable form 96as held in a character string) to network format (usually a 97.Ft struct in_addr 98or some other internal binary representation, in network byte order). 99It returns 1 if the address was valid for the specified address family, or 1000 if the address was not parseable in the specified address family, or -1 101if some system error occurred (in which case 102.Va errno 103will have been set). 104This function is presently valid for 105.Dv AF_INET 106and 107.Dv AF_INET6 . 108.Pp 109The 110.Fn inet_aton 111routine interprets the specified character string as an Internet address, 112placing the address into the structure provided. 113It returns 1 if the string was successfully interpreted, 114or 0 if the string is invalid. 115The 116.Fn inet_addr 117and 118.Fn inet_network 119functions return numbers suitable for use 120as Internet addresses and Internet network 121numbers, respectively. 122.Pp 123The function 124.Fn inet_ntop 125converts an address 126.Fa *src 127from network format 128(usually a 129.Ft struct in_addr 130or some other binary form, in network byte order) to presentation format 131(suitable for external display purposes). 132The 133.Fa size 134argument specifies the size, in bytes, of the buffer 135.Fa *dst . 136.Dv INET_ADDRSTRLEN 137and 138.Dv INET6_ADDRSTRLEN 139define the maximum size required to convert an address of the respective 140type. 141It returns NULL if a system error occurs (in which case, 142.Va errno 143will have been set), or it returns a pointer to the destination string. 144This function is presently valid for 145.Dv AF_INET 146and 147.Dv AF_INET6 . 148.Pp 149The routine 150.Fn inet_ntoa 151takes an Internet address and returns an 152.Tn ASCII 153string representing the address in 154.Ql .\& 155notation. 156The routine 157.Fn inet_ntoa_r 158is the reentrant version of 159.Fn inet_ntoa . 160The routine 161.Fn inet_makeaddr 162takes an Internet network number and a local 163network address and constructs an Internet address 164from it. 165The routines 166.Fn inet_netof 167and 168.Fn inet_lnaof 169break apart Internet host addresses, returning 170the network number and local network address part, 171respectively. 172.Pp 173All Internet addresses are returned in network 174order (bytes ordered from left to right). 175All network numbers and local address parts are 176returned as machine byte order integer values. 177.Sh INTERNET ADDRESSES 178Values specified using the 179.Ql .\& 180notation take one 181of the following forms: 182.Bd -literal -offset indent 183a.b.c.d 184a.b.c 185a.b 186a 187.Ed 188.Pp 189When four parts are specified, each is interpreted 190as a byte of data and assigned, from left to right, 191to the four bytes of an Internet address. 192Note 193that when an Internet address is viewed as a 32-bit 194integer quantity on the 195.Tn VAX 196the bytes referred to 197above appear as 198.Dq Li d.c.b.a . 199That is, 200.Tn VAX 201bytes are 202ordered from right to left. 203.Pp 204When a three part address is specified, the last 205part is interpreted as a 16-bit quantity and placed 206in the right-most two bytes of the network address. 207This makes the three part address format convenient 208for specifying Class B network addresses as 209.Dq Li 128.net.host . 210.Pp 211When a two part address is supplied, the last part 212is interpreted as a 24-bit quantity and placed in 213the right most three bytes of the network address. 214This makes the two part address format convenient 215for specifying Class A network addresses as 216.Dq Li net.host . 217.Pp 218When only one part is given, the value is stored 219directly in the network address without any byte 220rearrangement. 221.Pp 222All numbers supplied as 223.Dq parts 224in a 225.Ql .\& 226notation 227may be decimal, octal, or hexadecimal, as specified 228in the C language (i.e., a leading 0x or 0X implies 229hexadecimal; otherwise, a leading 0 implies octal; 230otherwise, the number is interpreted as decimal). 231.Sh DIAGNOSTICS 232The constant 233.Dv INADDR_NONE 234is returned by 235.Fn inet_addr 236and 237.Fn inet_network 238for malformed requests. 239.Sh ERRORS 240The 241.Fn inet_ntop 242call fails if: 243.Bl -tag -width Er 244.It Bq Er ENOSPC 245.Fa size 246was not large enough to store the presentation form of the address. 247.It Bq Er EAFNOSUPPORT 248.Fa *src 249was not an 250.Dv AF_INET 251or 252.Dv AF_INET6 253family address. 254.El 255.Sh SEE ALSO 256.Xr byteorder 3 , 257.Xr getaddrinfo 3 , 258.Xr gethostbyname 3 , 259.Xr getnameinfo 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 302The 303.Fn inet_addr 304function should return a 305.Fa struct in_addr . 306