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.\" From: @(#)inet.3 8.1 (Berkeley) 6/4/93 29.\" 30.Dd November 9, 2021 31.Dt INET 3 32.Os 33.Sh NAME 34.Nm inet_aton , 35.Nm inet_addr , 36.Nm inet_network , 37.Nm inet_ntoa , 38.Nm inet_ntoa_r , 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 char * 61.Fo inet_ntoa_r 62.Fa "struct in_addr in" 63.Fa "char *buf" 64.Fa "socklen_t size" 65.Fc 66.Ft const char * 67.Fo inet_ntop 68.Fa "int af" 69.Fa "const void * restrict src" 70.Fa "char * restrict dst" 71.Fa "socklen_t size" 72.Fc 73.Ft int 74.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" 75.Ft struct in_addr 76.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna" 77.Ft in_addr_t 78.Fn inet_lnaof "struct in_addr in" 79.Ft in_addr_t 80.Fn inet_netof "struct in_addr in" 81.Sh DESCRIPTION 82The routines 83.Fn inet_aton , 84.Fn inet_addr 85and 86.Fn inet_network 87interpret character strings representing 88numbers expressed in the Internet standard 89.Ql .\& 90notation. 91.Pp 92The 93.Fn inet_pton 94function converts a presentation format address (that is, printable form 95as held in a character string) to network format (usually a 96.Ft struct in_addr 97or some other internal binary representation, in network byte order). 98It returns 1 if the address was valid for the specified address family, or 990 if the address was not parseable in the specified address family, or -1 100if some system error occurred (in which case 101.Va errno 102will have been set). 103This function is presently valid for 104.Dv AF_INET 105and 106.Dv AF_INET6 . 107.Pp 108The 109.Fn inet_aton 110routine interprets the specified character string as an Internet address, 111placing the address into the structure provided. 112It returns 1 if the string was successfully interpreted, 113or 0 if the string is invalid. 114The 115.Fn inet_addr 116and 117.Fn inet_network 118functions return numbers suitable for use 119as Internet addresses and Internet network 120numbers, respectively. 121.Pp 122The function 123.Fn inet_ntop 124converts an address 125.Fa *src 126from network format 127(usually a 128.Ft struct in_addr 129or some other binary form, in network byte order) to presentation format 130(suitable for external display purposes). 131The 132.Fa size 133argument specifies the size, in bytes, of the buffer 134.Fa *dst . 135.Dv INET_ADDRSTRLEN 136and 137.Dv INET6_ADDRSTRLEN 138define the maximum size required to convert an address of the respective 139type. 140It returns NULL if a system error occurs (in which case, 141.Va errno 142will have been set), or it returns a pointer to the destination string. 143This function is presently valid for 144.Dv AF_INET 145and 146.Dv AF_INET6 . 147.Pp 148The routine 149.Fn inet_ntoa 150takes an Internet address and returns an 151.Tn ASCII 152string representing the address in 153.Ql .\& 154notation. 155The routine 156.Fn inet_ntoa_r 157is the reentrant version of 158.Fn inet_ntoa . 159The deprecated routine 160.Fn inet_makeaddr 161takes an Internet network number and a local 162host address on that network, and constructs an Internet address 163from it. 164It should only be assumed to work for historical class A/B/C networks. 165The deprecated routines 166.Fn inet_netof 167and 168.Fn inet_lnaof 169break apart Internet host addresses, returning 170the network number and local host address part, 171respectively, 172assuming the historical class A/B/C network masks. 173.Pp 174All Internet addresses are returned in network 175order (bytes ordered from left to right). 176All network numbers and local address parts are 177returned as machine byte order integer values. 178.Sh INTERNET ADDRESSES (IP VERSION 4) 179The 180.Fn inet_aton 181and 182.Fn inet_addr 183functions accept IPv4 184values specified using the 185.Ql .\& 186notation in one 187of the following forms: 188.Bd -literal -offset indent 189a.b.c.d 190a.b.c 191a.b 192a 193.Ed 194.Pp 195When four parts are specified, each is interpreted 196as a byte of data and assigned, from left to right, 197to the four bytes of an Internet address. 198.Pp 199When a three part address is specified, the last 200part is interpreted as a 16-bit quantity and placed 201in the least significant two bytes of the network address. 202.Pp 203When a two part address is supplied, the last part 204is interpreted as a 24-bit quantity and placed in 205the least significant three bytes of the network address. 206.Pp 207When only one part is given, the value is stored 208directly in the network address without any byte 209rearrangement. 210.Pp 211All numbers supplied as 212.Dq parts 213in a 214.Ql .\& 215notation 216may be decimal, octal, or hexadecimal, as specified 217in the C language (i.e., a leading 0x or 0X implies 218hexadecimal; otherwise, a leading 0 implies octal; 219otherwise, the number is interpreted as decimal). 220.Pp 221Note that 222.Fn inet_pton 223does not accept 1-, 2-, or 3-part dotted addresses; all four parts 224must be specified and are interpreted only as decimal values. 225This is a narrower input set than that accepted by 226.Fn inet_aton . 227.Sh DIAGNOSTICS 228The constant 229.Dv INADDR_NONE 230is returned by 231.Fn inet_addr 232and 233.Fn inet_network 234for malformed requests. 235.Sh ERRORS 236The 237.Fn inet_ntop 238call fails if: 239.Bl -tag -width Er 240.It Bq Er ENOSPC 241.Fa size 242was not large enough to store the presentation form of the address. 243.It Bq Er EAFNOSUPPORT 244.Fa *src 245was not an 246.Dv AF_INET 247or 248.Dv AF_INET6 249family address. 250.El 251.Sh SEE ALSO 252.Xr byteorder 3 , 253.Xr getaddrinfo 3 , 254.Xr gethostbyname 3 , 255.Xr getnameinfo 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 . 273.Sh HISTORY 274These 275functions appeared in 276.Bx 4.2 . 277.Sh BUGS 278The value 279.Dv INADDR_NONE 280(0xffffffff) is a valid broadcast address, but 281.Fn inet_addr 282cannot return that value without indicating failure. 283The newer 284.Fn inet_aton 285function does not share this problem. 286The problem of host byte ordering versus network byte ordering is 287confusing. 288The string returned by 289.Fn inet_ntoa 290resides in a static memory area. 291.Pp 292The 293.Fn inet_addr 294function should return a 295.Fa struct in_addr . 296