| blob | d028c5e7b59aaa4643fa5e96dbbde66a30adbd6c |
1 .\" $NetBSD: inet.3,v 1.5 2012/07/25 14:51:15 ginsbach Exp $
2 .\"
3 .\" Copyright (c) 1983, 1990, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)inet.3 8.1 (Berkeley) 6/4/93
31 .\"
32 .Dd July 25, 2012
33 .Dt INET 3
34 .Os
35 .Sh NAME
36 .Nm inet_addr ,
37 .Nm inet_aton ,
38 .Nm inet_lnaof ,
39 .Nm inet_makeaddr ,
40 .Nm inet_netof ,
41 .Nm inet_network ,
42 .Nm inet_ntoa ,
43 .Nm inet_ntop ,
44 .Nm inet_pton ,
45 .Nm addr ,
46 .Nm ntoa ,
47 .Nm network
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 .Fn inet_addr "const char *cp"
55 .Ft int
56 .Fn inet_aton "const char *cp" "struct in_addr *addr"
57 .Ft in_addr_t
58 .Fn inet_lnaof "struct in_addr in"
59 .Ft struct in_addr
60 .Fn inet_makeaddr "in_addr_t net" "in_addr_t lna"
61 .Ft in_addr_t
62 .Fn inet_netof "struct in_addr in"
63 .Ft in_addr_t
64 .Fn inet_network "const char *cp"
65 .Ft char *
66 .Fn inet_ntoa "struct in_addr in"
67 .Ft const char *
68 .Fn inet_ntop "int af" "const void * restrict src" "char * restrict dst" "socklen_t size"
69 .Ft int
70 .Fn inet_pton "int af" "const char * restrict src" "void * restrict dst"
71 .Sh DESCRIPTION
72 The routines
73 .Fn inet_aton ,
74 .Fn inet_addr
75 and
76 .Fn inet_network
77 interpret character strings representing
78 numbers expressed in the Internet standard
79 .Qq dotted quad
80 notation.
81 .Pp
82 The
83 .Fn inet_pton
84 function converts a presentation format address (that is, printable form
85 as held in a character string) to network format (usually a
86 .Ft struct in_addr
87 or some other internal binary representation, in network byte order).
88 It returns 1 if the address was valid for the specified address family, or
89 0 if the address wasn't parsable in the specified address family, or -1
90 if some system error occurred (in which case
91 .Va errno
92 will have been set).
93 This function is presently valid for
94 .Dv AF_INET
95 and
96 .Dv AF_INET6 .
97 .Pp
98 The
99 .Fn inet_aton
100 routine interprets the specified character string as an Internet address,
101 placing the address into the structure provided.
102 It returns 1 if the string was successfully interpreted,
103 or 0 if the string is invalid.
104 .Pp
105 The
106 .Fn inet_addr
107 and
108 .Fn inet_network
109 functions return numbers suitable for use
110 as Internet addresses and Internet network
111 numbers, respectively.
112 .Pp
113 The function
114 .Fn inet_ntop
115 converts an address from network format (usually a
116 .Ft struct in_addr
117 or some other binary form, in network byte order) to presentation format
118 (suitable for external display purposes).
119 It returns NULL if a system error occurs (in which case,
120 .Va errno
121 will have been set), or it returns a pointer to the destination string.
122 The
123 .Ar size
124 parameter is the size of the
125 .Ar buf
126 argument.
127 .Pp
128 The routine
129 .Fn inet_ntoa
130 takes an Internet address and returns an
131 .Tn ASCII
132 string representing the address in
133 .Qq dotted quad
134 notation.
135 .Pp
136 The routine
137 .Fn inet_makeaddr
138 takes an Internet network number and a local network address (both in
139 host order) and constructs an Internet address from it.
140 Note that to convert only a single value to a
141 .Ft struct in_addr
142 form that value should be passed as the first parameter and
143 .Ql 0L
144 should be given for the second parameter.
145 .Pp
146 The routines
147 .Fn inet_netof
148 and
149 .Fn inet_lnaof
150 break apart Internet host addresses, returning the network number and
151 local network address part, respectively (both in host order).
152 .Pp
153 All Internet addresses are returned in network
154 order (bytes ordered from left to right).
155 All network numbers and local address parts are
156 returned as machine format integer values.
157 .Sh INTERNET ADDRESSES (IP VERSION 4)
158 Values specified using the
159 .Qq dotted quad
160 notation take one
161 of the following forms:
162 .Bd -literal -offset indent
163 a.b.c.d
164 a.b.c
165 a.b
166 a
167 .Ed
168 .Pp
169 When four parts are specified, each is interpreted
170 as a byte of data and assigned, from left to right,
171 to the four bytes of an Internet address.
172 Note that when an Internet address is viewed as a 32-bit
173 integer quantity on a system that uses little-endian
174 byte order (e.g.
175 .Tn Intel i386, i486
176 and
177 .Tn Pentium
178 processors) the bytes referred to above appear as
179 .Dq Li d.c.b.a .
180 That is, little-endian bytes are ordered from right to left.
181 .Pp
182 When a three part address is specified, the last
183 part is interpreted as a 16-bit quantity and placed
184 in the right-most two bytes of the network address.
185 This makes the three part address format convenient
186 for specifying Class B network addresses as
187 .Dq Li 128.net.host .
188 .Pp
189 When a two part address is supplied, the last part
190 is interpreted as a 24-bit quantity and placed in
191 the right most three bytes of the network address.
192 This makes the two part address format convenient
193 for specifying Class A network addresses as
194 .Dq Li net.host .
195 .Pp
196 When only one part is given, the value is stored
197 directly in the network address without any byte
198 rearrangement.
199 .Pp
200 All numbers supplied as
201 .Dq parts
202 in a
203 .Qq dotted quad
204 notation
205 may be decimal, octal, or hexadecimal, as specified
206 in the C language (i.e., a leading 0x or 0X implies
207 hexadecimal; otherwise, a leading 0 implies octal;
208 otherwise, the number is interpreted as decimal).
209 .Sh INTERNET ADDRESSES (IP VERSION 6)
210 In order to support scoped IPv6 addresses,
211 the use of
212 .Xr getaddrinfo 3
213 and
214 .Xr getnameinfo 3
215 is recommended rather than the functions presented here.
216 .Pp
217 The presentation format of an IPv6 address is given in RFC 2373:
218 .Pp
219 There are three conventional forms for representing IPv6 addresses as
220 text strings:
221 .Bl -enum
222 .It
223 The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the
224 hexadecimal values of the eight 16-bit pieces of the address.
225 Examples:
226 .Bd -literal -offset indent
227 FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
228 1080:0:0:0:8:800:200C:417A
229 .Ed
230 .Pp
231 Note that it is not necessary to write the leading zeros in an
232 individual field, but there must be at least one numeral in
233 every field (except for the case described in 2).
234 .It
235 Due to the method of allocating certain styles of IPv6
236 addresses, it will be common for addresses to contain long
237 strings of zero bits.
238 In order to make writing addresses
239 containing zero bits easier, a special syntax is available to
240 compress the zeros.
241 The use of ``::'' indicates multiple groups of 16-bits of zeros.
242 The ``::'' can only appear once in an address.
243 The ``::'' can also be used to compress the leading
244 and/or trailing zeros in an address.
245 .Pp
246 For example the following addresses:
247 .Bd -literal -offset indent
248 1080:0:0:0:8:800:200C:417A a unicast address
249 FF01:0:0:0:0:0:0:43 a multicast address
250 0:0:0:0:0:0:0:1 the loopback address
251 0:0:0:0:0:0:0:0 the unspecified addresses
252 .Ed
253 .Pp
254 may be represented as:
255 .Bd -literal -offset indent
256 1080::8:800:200C:417A a unicast address
257 FF01::43 a multicast address
258 ::1 the loopback address
259 :: the unspecified addresses
260 .Ed
261 .It
262 An alternative form that is sometimes more convenient when
263 dealing with a mixed environment of IPv4 and IPv6 nodes is
264 x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values
265 of the six high-order 16-bit pieces of the address, and the 'd's
266 are the decimal values of the four low-order 8-bit pieces of the
267 address (standard IPv4 representation).
268 Examples:
269 .Bd -literal -offset indent
270 0:0:0:0:0:0:13.1.68.3
271 0:0:0:0:0:FFFF:129.144.52.38
272 .Ed
273 .Pp
274 or in compressed form:
275 .Bd -literal -offset indent
276 ::13.1.68.3
277 ::FFFF:129.144.52.38
278 .Ed
279 .El
280 .Sh DIAGNOSTICS
281 The constant
282 .Dv INADDR_NONE
283 is returned by
284 .Fn inet_addr
285 and
286 .Fn inet_network
287 for malformed requests.
288 .Sh ERRORS
289 The
290 .Fn inet_ntop
291 and
292 .Fn inet_pton
293 functions may fail with
294 .Bl -tag -width Er
295 .It Bq Er EAFNOSUPPORT
296 The value of
297 .Fa af
298 was not
299 .Dv AF_INET
300 or
301 .Dv AF_INET6 .
302 .El
303 .Pp
304 The
305 .Fn inet_ntop
306 function may fail with
307 .Bl -tag -width Er
308 .It Bq Er ENOSPC
309 The
310 .Fa size
311 indicated for
312 .Fa dst
313 was too small to store the presentation form of the network address.
314 .El
315 .Sh SEE ALSO
316 .Xr byteorder 3 ,
317 .Xr gethostbyname 3 ,
318 .Xr getnetent 3 ,
319 .Xr inet_net 3 ,
320 .Xr hosts 5 ,
321 .Xr networks 5
322 .Rs
323 .%R RFC 2373
324 .%D July 1998
325 .%T "IP Version 6 Addressing Architecture"
326 .Re
327 .Rs
328 .%R RFC 3493
329 .%D February 2003
330 .%T "Basic Socket Interface Extensions for IPv6"
331 .Re
332 .Sh STANDARDS
333 The
334 .Fn inet_ntop
335 and
336 .Fn inet_pton
337 functions conform to
338 .St -p1003.1-2001 .
339 Note that
340 .Fn inet_pton
341 does not accept 1-, 2-, or 3-part dotted addresses; all four parts
342 must be specified.
343 Additionally all four parts of a dotted address must be decimal.
344 This is a narrower input set than that accepted by
345 .Fn inet_aton .
346 .Sh HISTORY
347 The
348 .Fn inet_addr ,
349 .Fn inet_network ,
350 .Fn inet_makeaddr ,
351 .Fn inet_lnaof
352 and
353 .Fn inet_netof
354 functions appeared in
355 .Bx 4.2 .
356 They were changed to use
357 .Vt in_addr_t
358 in place of
359 .Vt unsigned long
360 in
361 .Nx 2.0 .
362 The
363 .Fn inet_aton
364 and
365 .Fn inet_ntoa
366 functions appeared in
367 .Bx 4.3 .
368 The
369 .Fn inet_pton
370 and
371 .Fn inet_ntop
372 functions appeared in BIND 4.9.4 and thence
373 .Nx 1.3 ;
374 they were also in
375 .St -xns5.2 .
376 .Sh BUGS
377 The value
378 .Dv INADDR_NONE
379 (0xffffffff) is a valid broadcast address, but
380 .Fn inet_addr
381 cannot return that value without indicating failure.
382 The newer
383 .Fn inet_aton
384 function does not share this problem.
385 .Pp
386 The problem of host byte ordering versus network byte ordering is
387 confusing.
388 .Pp
389 The string returned by
390 .Fn inet_ntoa
391 resides in a static memory area.
392 .Pp
393 The function
394 .Fn inet_addr
395 should return a
396 .Vt struct in_addr .
397 .Pp
398 The function
399 .Fn inet_network
400 does not support byte rearrangement for one, two, and three
401 part addresses.