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