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