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