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 SYNOPSIS 50.Fd #include <sys/types.h> 51.Fd #include <sys/socket.h> 52.Fd #include <netinet/in.h> 53.Fd #include <arpa/inet.h> 54.Ft int 55.Fn inet_aton "const char *cp" "struct in_addr *pin" 56.Ft unsigned long 57.Fn inet_addr "const char *cp" 58.Ft unsigned long 59.Fn inet_network "const char *cp" 60.Ft char * 61.Fn inet_ntoa "struct in_addr in" 62.Ft const char * 63.Fn inet_ntop "int af" "const void *src" "char *dst" "size_t size" 64.Ft int 65.Fn inet_pton "int af" "const char *src" "void *dst" 66.Ft struct in_addr 67.Fn inet_makeaddr "unsigned long net" "unsigned long lna" 68.Ft unsigned long 69.Fn inet_lnaof "struct in_addr in" 70.Ft unsigned long 71.Fn inet_netof "struct in_addr in" 72.Sh DESCRIPTION 73The routines 74.Fn inet_aton , 75.Fn inet_addr 76and 77.Fn inet_network 78interpret character strings representing 79numbers expressed in the Internet standard 80.Ql \&. 81notation. 82.Pp 83The 84.Fn inet_pton 85function converts a presentation format address (that is, printable form 86as held in a character string) to network format (usually a 87.Ft struct in_addr 88or some other internal binary representation, in network byte order). 89It returns 1 if the address was valid for the specified address family, or 900 if the address wasn't parseable in the specified address family, or -1 91if some system error occurred (in which case 92.Va errno 93will have been set). 94This function is presently valid for 95.Dv AF_INET 96and 97.Dv AF_INET6 . 98.Pp 99The 100.Fn inet_aton 101routine interprets the specified character string as an Internet address, 102placing the address into the structure provided. 103It returns 1 if the string was successfully interpreted, 104or 0 if the string is invalid. 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. 122This function is presently valid for 123.Dv AF_INET 124and 125.Dv AF_INET6 . 126.Pp 127The routine 128.Fn inet_ntoa 129takes an Internet address and returns an 130.Tn ASCII 131string representing the address in 132.Ql \&. 133notation. The routine 134.Fn inet_makeaddr 135takes an Internet network number and a local 136network address and constructs an Internet address 137from it. The routines 138.Fn inet_netof 139and 140.Fn inet_lnaof 141break apart Internet host addresses, returning 142the network number and local network address part, 143respectively. 144.Pp 145All Internet addresses are returned in network 146order (bytes ordered from left to right). 147All network numbers and local address parts are 148returned as machine format integer values. 149.Sh INTERNET ADDRESSES 150Values specified using the 151.Ql \&. 152notation take one 153of the following forms: 154.Bd -literal -offset indent 155a.b.c.d 156a.b.c 157a.b 158a 159.Ed 160.Pp 161When four parts are specified, each is interpreted 162as a byte of data and assigned, from left to right, 163to the four bytes of an Internet address. Note 164that when an Internet address is viewed as a 32-bit 165integer quantity on the 166.Tn VAX 167the bytes referred to 168above appear as 169.Dq Li d.c.b.a . 170That is, 171.Tn VAX 172bytes are 173ordered from right to left. 174.Pp 175When a three part address is specified, the last 176part is interpreted as a 16-bit quantity and placed 177in the right-most two bytes of the network address. 178This makes the three part address format convenient 179for specifying Class B network addresses as 180.Dq Li 128.net.host . 181.Pp 182When a two part address is supplied, the last part 183is interpreted as a 24-bit quantity and placed in 184the right most three bytes of the network address. 185This makes the two part address format convenient 186for specifying Class A network addresses as 187.Dq Li net.host . 188.Pp 189When only one part is given, the value is stored 190directly in the network address without any byte 191rearrangement. 192.Pp 193All numbers supplied as 194.Dq parts 195in a 196.Ql \&. 197notation 198may be decimal, octal, or hexadecimal, as specified 199in the C language (i.e., a leading 0x or 0X implies 200hexadecimal; otherwise, a leading 0 implies octal; 201otherwise, the number is interpreted as decimal). 202.Pp 203The 204.Fn inet_aton 205and 206.Fn inet_ntoa 207functions are semi-deprecated in favor of the 208.Xr addr2ascii 3 209family. However, since those functions are not yet widely implemented, 210portable programs cannot rely on their presence and will continue 211to use the 212.Xr inet 3 213functions for some time. 214.Sh DIAGNOSTICS 215The constant 216.Dv INADDR_NONE 217is returned by 218.Fn inet_addr 219and 220.Fn inet_network 221for malformed requests. 222.Sh SEE ALSO 223.Xr addr2ascii 3 , 224.Xr gethostbyname 3 , 225.Xr getnetent 3 , 226.Xr hosts 5 , 227.Xr networks 5 228.Rs 229.%R RFC 230.%N 2373 231.%D July 1998 232.%T "IP Version 6 Addressing Architecture" 233.Re 234.Sh STANDARDS 235The 236.Nm inet_ntop 237and 238.Nm inet_pton 239functions conform to 240.St -xns5.2d2.0 . 241Note that 242.Nm inet_pton 243does not accept 1-, 2-, or 3-part dotted addresses; all four parts 244must be specified. 245This is a narrower input set than that accepted by 246.Nm inet_aton . 247.Sh HISTORY 248These 249functions appeared in 250.Bx 4.2 . 251.Sh BUGS 252The value 253.Dv INADDR_NONE 254(0xffffffff) is a valid broadcast address, but 255.Fn inet_addr 256cannot return that value without indicating failure. 257The newer 258.Fn inet_aton 259function does not share this problem. 260The problem of host byte ordering versus network byte ordering is 261confusing. 262The string returned by 263.Fn inet_ntoa 264resides in a static memory area. 265.Pp 266Inet_addr should return a 267.Fa struct in_addr . 268