lib/libc/net/inet.3

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