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 .\" 4. 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 .\" $FreeBSD: src/lib/libc/net/inet.3,v 1.36 2007/06/14 07:13:28 delphij Exp $
  30 .\"
  31 .Dd June 14, 2007
  32 .Dt INET 3
  33 .Os
  34 .Sh NAME
  35 .Nm inet_addr ,
  36 .Nm inet_aton ,
  37 .Nm inet_lnaof ,
  38 .Nm inet_makeaddr ,
  39 .Nm inet_netof ,
  40 .Nm inet_network ,
  41 .Nm inet_ntoa ,
  42 .Nm inet_ntoa_r ,
  43 .Nm inet_ntop ,
  44 .Nm inet_pton
  45 .Nd Internet address manipulation routines
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In arpa/inet.h
  50 .Ft in_addr_t
  51 .Fo inet_addr
  52 .Fa "const char *cp"
  53 .Fc
  54 .Ft int
  55 .Fo inet_aton
  56 .Fa "const char *cp"
  57 .Fa "struct in_addr *pin"
  58 .Fc
  59 .Ft in_addr_t
  60 .Fo inet_lnaof
  61 .Fa "struct in_addr in"
  62 .Fc
  63 .Ft struct in_addr
  64 .Fo inet_makeaddr
  65 .Fa "in_addr_t net"
  66 .Fa "in_addr_t lna"
  67 .Fc
  68 .Ft in_addr_t
  69 .Fo inet_netof
  70 .Fa "struct in_addr in"
  71 .Fc
  72 .Ft in_addr_t
  73 .Fo inet_network
  74 .Fa "const char *cp"
  75 .Fc
  76 .Ft char *
  77 .Fo inet_ntoa
  78 .Fa "struct in_addr in"
  79 .Fc
  80 .Ft char *
  81 .Fo inet_ntoa_r
  82 .Fa "struct in_addr in"
  83 .Fa "char *buf"
  84 .Fa "socklen_t size"
  85 .Fc
  86 .Ft const char *
  87 .Fo inet_ntop
  88 .Fa "int af"
  89 .Fa "const void * restrict src"
  90 .Fa "char * restrict dst"
  91 .Fa "socklen_t size"
  92 .Fc
  93 .Ft int
  94 .Fo inet_pton
  95 .Fa "int af"
  96 .Fa "const char * restrict src"
  97 .Fa "void * restrict dst"
  98 .Fc
  99 .Sh DESCRIPTION
 100 The routines
 101 .Fn inet_aton ,
 102 .Fn inet_addr
 103 and
 104 .Fn inet_network
 105 interpret character strings representing
 106 numbers expressed in the Internet standard
 107 .Ql .\&
 108 notation.
 109 .Pp
 110 The
 111 .Fn inet_pton
 112 function converts a presentation format address (that is, printable form
 113 as held in a character string) to network format (usually a
 114 .Ft struct in_addr
 115 or some other internal binary representation, in network byte order).
 116 It returns 1 if the address was valid for the specified address family, or
 117 0 if the address was not parseable in the specified address family, or -1
 118 if some system error occurred (in which case
 119 .Va errno
 120 will have been set).
 121 This function is presently valid for
 122 .Dv AF_INET
 123 and
 124 .Dv AF_INET6 .
 125 .Pp
 126 The
 127 .Fn inet_aton
 128 routine interprets the specified character string as an Internet address,
 129 placing the address into the structure provided.
 130 It returns 1 if the string was successfully interpreted,
 131 or 0 if the string is invalid.
 132 The
 133 .Fn inet_addr
 134 and
 135 .Fn inet_network
 136 functions return numbers suitable for use
 137 as Internet addresses and Internet network
 138 numbers, respectively.
 139 .Pp
 140 The function
 141 .Fn inet_ntop
 142 converts an address
 143 .Fa *src
 144 from network format
 145 (usually a
 146 .Ft struct in_addr
 147 or some other binary form, in network byte order) to presentation format
 148 (suitable for external display purposes).
 149 The
 150 .Fa size
 151 argument specifies the size, in bytes, of the buffer
 152 .Fa *dst .
 153 .Dv INET_ADDRSTRLEN
 154 and
 155 .Dv INET6_ADDRSTRLEN
 156 define the maximum size required to convert an address of the respective
 157 type.
 158 It returns NULL if a system error occurs (in which case,
 159 .Va errno
 160 will have been set), or it returns a pointer to the destination string.
 161 This function is presently valid for
 162 .Dv AF_INET
 163 and
 164 .Dv AF_INET6 .
 165 .Pp
 166 The routine
 167 .Fn inet_ntoa
 168 takes an Internet address and returns an
 169 .Tn ASCII
 170 string representing the address in
 171 .Ql .\&
 172 notation.
 173 The routine
 174 .Fn inet_ntoa_r
 175 is the reentrant version of
 176 .Fn inet_ntoa .
 177 The routine
 178 .Fn inet_makeaddr
 179 takes an Internet network number and a local
 180 network address and constructs an Internet address
 181 from it.
 182 The routines
 183 .Fn inet_netof
 184 and
 185 .Fn inet_lnaof
 186 break apart Internet host addresses, returning
 187 the network number and local network address part,
 188 respectively.
 189 .Pp
 190 All Internet addresses are returned in network
 191 order (bytes ordered from left to right).
 192 All network numbers and local address parts are
 193 returned as machine byte order integer values.
 194 .Sh INTERNET ADDRESSES
 195 Values specified using the
 196 .Ql .\&
 197 notation take one
 198 of the following forms:
 199 .Bd -literal -offset indent
 200 a.b.c.d
 201 a.b.c
 202 a.b
 203 a
 204 .Ed
 205 .Pp
 206 When four parts are specified, each is interpreted
 207 as a byte of data and assigned, from left to right,
 208 to the four bytes of an Internet address.
 209 Note
 210 that when an Internet address is viewed as a 32-bit
 211 integer quantity on the
 212 .Tn VAX
 213 the bytes referred to
 214 above appear as
 215 .Dq Li d.c.b.a .
 216 That is,
 217 .Tn VAX
 218 bytes are
 219 ordered from right to left.
 220 .Pp
 221 When a three part address is specified, the last
 222 part is interpreted as a 16-bit quantity and placed
 223 in the right-most two bytes of the network address.
 224 This makes the three part address format convenient
 225 for specifying Class B network addresses as
 226 .Dq Li 128.net.host .
 227 .Pp
 228 When a two part address is supplied, the last part
 229 is interpreted as a 24-bit quantity and placed in
 230 the right most three bytes of the network address.
 231 This makes the two part address format convenient
 232 for specifying Class A network addresses as
 233 .Dq Li net.host .
 234 .Pp
 235 When only one part is given, the value is stored
 236 directly in the network address without any byte
 237 rearrangement.
 238 .Pp
 239 All numbers supplied as
 240 .Dq parts
 241 in a
 242 .Ql .\&
 243 notation
 244 may be decimal, octal, or hexadecimal, as specified
 245 in the C language (i.e., a leading 0x or 0X implies
 246 hexadecimal; otherwise, a leading 0 implies octal;
 247 otherwise, the number is interpreted as decimal).
 248 .Sh DIAGNOSTICS
 249 The constant
 250 .Dv INADDR_NONE
 251 is returned by
 252 .Fn inet_addr
 253 and
 254 .Fn inet_network
 255 for malformed requests.
 256 .Sh ERRORS
 257 The
 258 .Fn inet_ntop
 259 call fails if:
 260 .Bl -tag -width Er
 261 .It Bq Er EAFNOSUPPORT
 262 .Fa *src
 263 was not an
 264 .Dv AF_INET
 265 or
 266 .Dv AF_INET6
 267 family address.
 268 .It Bq Er ENOSPC
 269 .Fa size
 270 was not large enough to store the presentation form of the address.
 271 .El
 272 .Sh LEGACY SYNOPSIS
 273 .Fd #include <sys/types.h>
 274 .Fd #include <sys/socket.h>
 275 .Fd #include <netinet/in.h>
 276 .Fd #include <arpa/inet.h>
 277 .Pp
 278 These include files are necessary for all functions.
 279 .Sh SEE ALSO
 280 .Xr byteorder 3 ,
 281 .Xr getaddrinfo 3 ,
 282 .Xr gethostbyname 3 ,
 283 .Xr getnameinfo 3 ,
 284 .Xr getnetent 3 ,
 285 .Xr inet_net 3 ,
 286 .Xr hosts 5 ,
 287 .Xr networks 5
 288 .Rs
 289 .%R RFC
 290 .%N 2373
 291 .%D July 1998
 292 .%T "IP Version 6 Addressing Architecture"
 293 .Re
 294 .Sh STANDARDS
 295 The
 296 .Fn inet_ntop
 297 and
 298 .Fn inet_pton
 299 functions conform to
 300 .St -xns5.2 .
 301 Note that
 302 .Fn inet_pton
 303 does not accept 1-, 2-, or 3-part dotted addresses; all four parts
 304 must be specified and are interpreted only as decimal values.
 305 This is a narrower input set than that accepted by
 306 .Fn inet_aton .
 307 .Sh HISTORY
 308 These
 309 functions appeared in
 310 .Bx 4.2 .
 311 .Sh BUGS
 312 The value
 313 .Dv INADDR_NONE
 314 (0xffffffff) is a valid broadcast address, but
 315 .Fn inet_addr
 316 cannot return that value without indicating failure.
 317 The newer
 318 .Fn inet_aton
 319 function does not share this problem.
 320 The problem of host byte ordering versus network byte ordering is
 321 confusing.
 322 The string returned by
 323 .Fn inet_ntoa
 324 resides in a static memory area.
 325 .Pp
 326 The
 327 .Fn inet_addr
 328 function should return a
 329 .Fa struct in_addr .