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 .\" 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$
  34 .\"
  35 .Dd June 14, 2004
  36 .Dt INET 3
  37 .Os
  38 .Sh NAME
  39 .Nm inet_aton ,
  40 .Nm inet_addr ,
  41 .Nm inet_network ,
  42 .Nm inet_ntoa ,
  43 .Nm inet_ntop ,
  44 .Nm inet_pton ,
  45 .Nm inet_makeaddr ,
  46 .Nm inet_lnaof ,
  47 .Nm inet_netof
  48 .Nd Internet address manipulation routines
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In sys/types.h
  53 .In sys/socket.h
  54 .In netinet/in.h
  55 .In arpa/inet.h
  56 .Ft int
  57 .Fn inet_aton "const char *cp" "struct in_addr *pin"
  58 .Ft in_addr_t
  59 .Fn inet_addr "const char *cp"
  60 .Ft in_addr_t
  61 .Fn inet_network "const char *cp"
  62 .Ft char *
  63 .Fn inet_ntoa "struct in_addr in"
  64 .Ft const char *
  65 .Fo inet_ntop
  66 .Fa "int af"
  67 .Fa "const void * restrict src"
  68 .Fa "char * restrict dst"
  69 .Fa "socklen_t size"
  70 .Fc
  71 .Ft int
  72 .Fn inet_pton "int af" "const char * restrict src" "void * restrict dst"
  73 .Ft struct in_addr
  74 .Fn inet_makeaddr "in_addr_t net" "in_addr_t lna"
  75 .Ft in_addr_t
  76 .Fn inet_lnaof "struct in_addr in"
  77 .Ft in_addr_t
  78 .Fn inet_netof "struct in_addr in"
  79 .Sh DESCRIPTION
  80 The routines
  81 .Fn inet_aton ,
  82 .Fn inet_addr
  83 and
  84 .Fn inet_network
  85 interpret character strings representing
  86 numbers expressed in the Internet standard
  87 .Ql .\&
  88 notation.
  89 .Pp
  90 The
  91 .Fn inet_pton
  92 function converts a presentation format address (that is, printable form
  93 as held in a character string) to network format (usually a
  94 .Ft struct in_addr
  95 or some other internal binary representation, in network byte order).
  96 It returns 1 if the address was valid for the specified address family, or
  97 0 if the address wasn't parseable in the specified address family, or -1
  98 if some system error occurred (in which case
  99 .Va errno
 100 will have been set).
 101 This function is presently valid for
 102 .Dv AF_INET
 103 and
 104 .Dv AF_INET6 .
 105 .Pp
 106 The
 107 .Fn inet_aton
 108 routine interprets the specified character string as an Internet address,
 109 placing the address into the structure provided.
 110 It returns 1 if the string was successfully interpreted,
 111 or 0 if the string is invalid.
 112 The
 113 .Fn inet_addr
 114 and
 115 .Fn inet_network
 116 functions return numbers suitable for use
 117 as Internet addresses and Internet network
 118 numbers, respectively.
 119 .Pp
 120 The function
 121 .Fn inet_ntop
 122 converts an address
 123 .Fa *src
 124 from network format
 125 (usually a
 126 .Ft struct in_addr
 127 or some other binary form, in network byte order) to presentation format
 128 (suitable for external display purposes).
 129 The
 130 .Fa size
 131 argument specifies the size, in bytes, of the buffer
 132 .Fa *dst .
 133 It returns NULL if a system error occurs (in which case,
 134 .Va errno
 135 will have been set), or it returns a pointer to the destination string.
 136 This function is presently valid for
 137 .Dv AF_INET
 138 and
 139 .Dv AF_INET6 .
 140 .Pp
 141 The routine
 142 .Fn inet_ntoa
 143 takes an Internet address and returns an
 144 .Tn ASCII
 145 string representing the address in
 146 .Ql .\&
 147 notation.
 148 The routine
 149 .Fn inet_makeaddr
 150 takes an Internet network number and a local
 151 network address and constructs an Internet address
 152 from it.
 153 The routines
 154 .Fn inet_netof
 155 and
 156 .Fn inet_lnaof
 157 break apart Internet host addresses, returning
 158 the network number and local network address part,
 159 respectively.
 160 .Pp
 161 All Internet addresses are returned in network
 162 order (bytes ordered from left to right).
 163 All network numbers and local address parts are
 164 returned as machine byte order integer values.
 165 .Sh INTERNET ADDRESSES
 166 Values specified using the
 167 .Ql .\&
 168 notation take one
 169 of the following forms:
 170 .Bd -literal -offset indent
 171 a.b.c.d
 172 a.b.c
 173 a.b
 174 a
 175 .Ed
 176 .Pp
 177 When four parts are specified, each is interpreted
 178 as a byte of data and assigned, from left to right,
 179 to the four bytes of an Internet address.
 180 Note
 181 that when an Internet address is viewed as a 32-bit
 182 integer quantity on the
 183 .Tn VAX
 184 the bytes referred to
 185 above appear as
 186 .Dq Li d.c.b.a .
 187 That is,
 188 .Tn VAX
 189 bytes are
 190 ordered from right to left.
 191 .Pp
 192 When a three part address is specified, the last
 193 part is interpreted as a 16-bit quantity and placed
 194 in the right-most two bytes of the network address.
 195 This makes the three part address format convenient
 196 for specifying Class B network addresses as
 197 .Dq Li 128.net.host .
 198 .Pp
 199 When a two part address is supplied, the last part
 200 is interpreted as a 24-bit quantity and placed in
 201 the right most three bytes of the network address.
 202 This makes the two part address format convenient
 203 for specifying Class A network addresses as
 204 .Dq Li net.host .
 205 .Pp
 206 When only one part is given, the value is stored
 207 directly in the network address without any byte
 208 rearrangement.
 209 .Pp
 210 All numbers supplied as
 211 .Dq parts
 212 in a
 213 .Ql .\&
 214 notation
 215 may be decimal, octal, or hexadecimal, as specified
 216 in the C language (i.e., a leading 0x or 0X implies
 217 hexadecimal; otherwise, a leading 0 implies octal;
 218 otherwise, the number is interpreted as decimal).
 219 .Pp
 220 The
 221 .Fn inet_aton
 222 and
 223 .Fn inet_ntoa
 224 functions are semi-deprecated in favor of the
 225 .Xr addr2ascii 3
 226 family.
 227 However, since those functions are not yet widely implemented,
 228 portable programs cannot rely on their presence and will continue
 229 to use the
 230 .Xr inet 3
 231 functions for some time.
 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 addr2ascii 3 ,
 258 .Xr byteorder 3 ,
 259 .Xr gethostbyname 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 Inet_addr should return a
 303 .Fa struct in_addr .