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