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 17, 1996 36.Dt INET 3 37.Os BSD 4.2 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.Fd #include <sys/types.h> 53.Fd #include <sys/socket.h> 54.Fd #include <netinet/in.h> 55.Fd #include <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.Fn inet_ntop "int af" "const void *src" "char *dst" "size_t size" 66.Ft int 67.Fn inet_pton "int af" "const char *src" "void *dst" 68.Ft struct in_addr 69.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" 70.Ft in_addr_t 71.Fn inet_lnaof "struct in_addr in" 72.Ft in_addr_t 73.Fn inet_netof "struct in_addr in" 74.Sh DESCRIPTION 75The routines 76.Fn inet_aton , 77.Fn inet_addr 78and 79.Fn inet_network 80interpret character strings representing 81numbers expressed in the Internet standard 82.Ql .\& 83notation. 84.Pp 85The 86.Fn inet_pton 87function converts a presentation format address (that is, printable form 88as held in a character string) to network format (usually a 89.Ft struct in_addr 90or some other internal binary representation, in network byte order). 91It returns 1 if the address was valid for the specified address family, or 920 if the address wasn't parseable in the specified address family, or -1 93if some system error occurred (in which case 94.Va errno 95will have been set). 96This function is presently valid for 97.Dv AF_INET 98and 99.Dv AF_INET6 . 100.Pp 101The 102.Fn inet_aton 103routine interprets the specified character string as an Internet address, 104placing the address into the structure provided. 105It returns 1 if the string was successfully interpreted, 106or 0 if the string is invalid. 107The 108.Fn inet_addr 109and 110.Fn inet_network 111functions return numbers suitable for use 112as Internet addresses and Internet network 113numbers, respectively. 114.Pp 115The function 116.Fn inet_ntop 117converts an address from network format (usually a 118.Ft struct in_addr 119or some other binary form, in network byte order) to presentation format 120(suitable for external display purposes). 121It returns NULL if a system error occurs (in which case, 122.Va errno 123will have been set), or it returns a pointer to the destination string. 124This function is presently valid for 125.Dv AF_INET 126and 127.Dv AF_INET6 . 128.Pp 129The routine 130.Fn inet_ntoa 131takes an Internet address and returns an 132.Tn ASCII 133string representing the address in 134.Ql .\& 135notation. The routine 136.Fn inet_makeaddr 137takes an Internet network number and a local 138network address and constructs an Internet address 139from it. The routines 140.Fn inet_netof 141and 142.Fn inet_lnaof 143break apart Internet host addresses, returning 144the network number and local network address part, 145respectively. 146.Pp 147All Internet addresses are returned in network 148order (bytes ordered from left to right). 149All network numbers and local address parts are 150returned as machine byte order integer values. 151.Sh INTERNET ADDRESSES 152Values specified using the 153.Ql .\& 154notation take one 155of the following forms: 156.Bd -literal -offset indent 157a.b.c.d 158a.b.c 159a.b 160a 161.Ed 162.Pp 163When four parts are specified, each is interpreted 164as a byte of data and assigned, from left to right, 165to the four bytes of an Internet address. Note 166that when an Internet address is viewed as a 32-bit 167integer quantity on the 168.Tn VAX 169the bytes referred to 170above appear as 171.Dq Li d.c.b.a . 172That is, 173.Tn VAX 174bytes are 175ordered 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.Ql .\& 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.Pp 205The 206.Fn inet_aton 207and 208.Fn inet_ntoa 209functions are semi-deprecated in favor of the 210.Xr addr2ascii 3 211family. However, since those functions are not yet widely implemented, 212portable programs cannot rely on their presence and will continue 213to use the 214.Xr inet 3 215functions for some time. 216.Sh DIAGNOSTICS 217The constant 218.Dv INADDR_NONE 219is returned by 220.Fn inet_addr 221and 222.Fn inet_network 223for malformed requests. 224.Sh SEE ALSO 225.Xr addr2ascii 3 , 226.Xr gethostbyname 3 , 227.Xr getnetent 3 , 228.Xr hosts 5 , 229.Xr networks 5 230.Rs 231.%R RFC 232.%N 2373 233.%D July 1998 234.%T "IP Version 6 Addressing Architecture" 235.Re 236.Sh STANDARDS 237The 238.Fn inet_ntop 239and 240.Fn inet_pton 241functions conform to 242.St -xns5.2 . 243Note that 244.Fn inet_pton 245does not accept 1-, 2-, or 3-part dotted addresses; all four parts 246must be specified. 247This is a narrower input set than that accepted by 248.Fn inet_aton . 249.Sh HISTORY 250These 251functions appeared in 252.Bx 4.2 . 253.Sh BUGS 254The value 255.Dv INADDR_NONE 256(0xffffffff) is a valid broadcast address, but 257.Fn inet_addr 258cannot return that value without indicating failure. 259The newer 260.Fn inet_aton 261function does not share this problem. 262The problem of host byte ordering versus network byte ordering is 263confusing. 264The string returned by 265.Fn inet_ntoa 266resides in a static memory area. 267.Pp 268Inet_addr should return a 269.Fa struct in_addr . 270