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