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. 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.Dd November 9, 2021 29.Dt INET 3 30.Os 31.Sh NAME 32.Nm inet_aton , 33.Nm inet_addr , 34.Nm inet_network , 35.Nm inet_ntoa , 36.Nm inet_ntoa_r , 37.Nm inet_ntop , 38.Nm inet_pton , 39.Nm inet_makeaddr , 40.Nm inet_lnaof , 41.Nm inet_netof 42.Nd Internet address manipulation routines 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/socket.h 48.In netinet/in.h 49.In arpa/inet.h 50.Ft int 51.Fn inet_aton "const char *cp" "struct in_addr *pin" 52.Ft in_addr_t 53.Fn inet_addr "const char *cp" 54.Ft in_addr_t 55.Fn inet_network "const char *cp" 56.Ft char * 57.Fn inet_ntoa "struct in_addr in" 58.Ft char * 59.Fo inet_ntoa_r 60.Fa "struct in_addr in" 61.Fa "char *buf" 62.Fa "socklen_t size" 63.Fc 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 was not 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 . 133.Dv INET_ADDRSTRLEN 134and 135.Dv INET6_ADDRSTRLEN 136define the maximum size required to convert an address of the respective 137type. 138It returns NULL if a system error occurs (in which case, 139.Va errno 140will have been set), or it returns a pointer to the destination string. 141This function is presently valid for 142.Dv AF_INET 143and 144.Dv AF_INET6 . 145.Pp 146The routine 147.Fn inet_ntoa 148takes an Internet address and returns an 149.Tn ASCII 150string representing the address in 151.Ql .\& 152notation. 153The routine 154.Fn inet_ntoa_r 155is the reentrant version of 156.Fn inet_ntoa . 157The deprecated routine 158.Fn inet_makeaddr 159takes an Internet network number and a local 160host address on that network, and constructs an Internet address 161from it. 162It should only be assumed to work for historical class A/B/C networks. 163The deprecated routines 164.Fn inet_netof 165and 166.Fn inet_lnaof 167break apart Internet host addresses, returning 168the network number and local host address part, 169respectively, 170assuming the historical class A/B/C network masks. 171.Pp 172All Internet addresses are returned in network 173order (bytes ordered from left to right). 174All network numbers and local address parts are 175returned as machine byte order integer values. 176.Sh INTERNET ADDRESSES (IP VERSION 4) 177The 178.Fn inet_aton 179and 180.Fn inet_addr 181functions accept IPv4 182values specified using the 183.Ql .\& 184notation in one 185of the following forms: 186.Bd -literal -offset indent 187a.b.c.d 188a.b.c 189a.b 190a 191.Ed 192.Pp 193When four parts are specified, each is interpreted 194as a byte of data and assigned, from left to right, 195to the four bytes of an Internet address. 196.Pp 197When a three part address is specified, the last 198part is interpreted as a 16-bit quantity and placed 199in the least significant two bytes of the network address. 200.Pp 201When a two part address is supplied, the last part 202is interpreted as a 24-bit quantity and placed in 203the least significant three bytes of the network address. 204.Pp 205When only one part is given, the value is stored 206directly in the network address without any byte 207rearrangement. 208.Pp 209All numbers supplied as 210.Dq parts 211in a 212.Ql .\& 213notation 214may be decimal, octal, or hexadecimal, as specified 215in the C language (i.e., a leading 0x or 0X implies 216hexadecimal; otherwise, a leading 0 implies octal; 217otherwise, the number is interpreted as decimal). 218.Pp 219Note that 220.Fn inet_pton 221does not accept 1-, 2-, or 3-part dotted addresses; all four parts 222must be specified and are interpreted only as decimal values. 223This is a narrower input set than that accepted by 224.Fn inet_aton . 225.Sh DIAGNOSTICS 226The constant 227.Dv INADDR_NONE 228is returned by 229.Fn inet_addr 230and 231.Fn inet_network 232for malformed requests. 233.Sh ERRORS 234The 235.Fn inet_ntop 236call fails if: 237.Bl -tag -width Er 238.It Bq Er ENOSPC 239.Fa size 240was not large enough to store the presentation form of the address. 241.It Bq Er EAFNOSUPPORT 242.Fa *src 243was not an 244.Dv AF_INET 245or 246.Dv AF_INET6 247family address. 248.El 249.Sh SEE ALSO 250.Xr byteorder 3 , 251.Xr getaddrinfo 3 , 252.Xr gethostbyname 3 , 253.Xr getnameinfo 3 , 254.Xr getnetent 3 , 255.Xr inet_net 3 , 256.Xr hosts 5 , 257.Xr networks 5 258.Rs 259.%R RFC 260.%N 2373 261.%D July 1998 262.%T "IP Version 6 Addressing Architecture" 263.Re 264.Sh STANDARDS 265The 266.Fn inet_ntop 267and 268.Fn inet_pton 269functions conform to 270.St -xns5.2 . 271.Sh HISTORY 272These 273functions appeared in 274.Bx 4.2 . 275.Sh BUGS 276The value 277.Dv INADDR_NONE 278(0xffffffff) is a valid broadcast address, but 279.Fn inet_addr 280cannot return that value without indicating failure. 281The newer 282.Fn inet_aton 283function does not share this problem. 284The problem of host byte ordering versus network byte ordering is 285confusing. 286The string returned by 287.Fn inet_ntoa 288resides in a static memory area. 289.Pp 290The 291.Fn inet_addr 292function should return a 293.Fa struct in_addr . 294