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