| blob | 30f42d41f8b8146d328fe586b5aa3a1eeaedb93b |
1 .\" $NetBSD: inet.3,v 1.1 2004/05/20 23:13:02 christos 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 June 30, 2003
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 .Pp
123 The routine
124 .Fn inet_ntoa
125 takes an Internet address and returns an
126 .Tn ASCII
127 string representing the address in
128 .Qq dotted quad
129 notation.
130 .Pp
131 The routine
132 .Fn inet_makeaddr
133 takes an Internet network number and a local network address (both in
134 host order) and constructs an Internet address from it.
135 Note that to convert only a single value to a
136 .Ft struct in_addr
137 form that value should be passed as the first parameter and
138 .Ql 0L
139 should be given for the second parameter.
140 .Pp
141 The routines
142 .Fn inet_netof
143 and
144 .Fn inet_lnaof
145 break apart Internet host addresses, returning the network number and
146 local network address part, respectively (both in host order).
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 format integer values.
152 .Sh INTERNET ADDRESSES (IP VERSION 4)
153 Values specified using the
154 .Qq dotted quad
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.
167 Note that when an Internet address is viewed as a 32-bit
168 integer quantity on a system that uses little-endian
169 byte order (e.g.
170 .Tn Intel i386, i486
171 and
172 .Tn Pentium
173 processors) the bytes referred to above appear as
174 .Dq Li d.c.b.a .
175 That is, little-endian bytes are 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 .Qq dotted quad
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 .Sh INTERNET ADDRESSES (IP VERSION 6)
205 In order to support scoped IPv6 addresses,
206 the use of
207 .Xr getaddrinfo 3
208 and
209 .Xr getnameinfo 3
210 is recommended rather than the functions presented here.
211 .Pp
212 The presentation format of an IPv6 address is given in RFC 2373:
213 .Pp
214 There are three conventional forms for representing IPv6 addresses as
215 text strings:
216 .Bl -enum
217 .It
218 The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the
219 hexadecimal values of the eight 16-bit pieces of the address.
220 Examples:
221 .Bd -literal -offset indent
222 FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
223 1080:0:0:0:8:800:200C:417A
224 .Ed
225 .Pp
226 Note that it is not necessary to write the leading zeros in an
227 individual field, but there must be at least one numeral in
228 every field (except for the case described in 2).
229 .It
230 Due to the method of allocating certain styles of IPv6
231 addresses, it will be common for addresses to contain long
232 strings of zero bits.
233 In order to make writing addresses
234 containing zero bits easier, a special syntax is available to
235 compress the zeros.
236 The use of ``::'' indicates multiple groups of 16-bits of zeros.
237 The ``::'' can only appear once in an address.
238 The ``::'' can also be used to compress the leading
239 and/or trailing zeros in an address.
240 .Pp
241 For example the following addresses:
242 .Bd -literal -offset indent
243 1080:0:0:0:8:800:200C:417A a unicast address
244 FF01:0:0:0:0:0:0:43 a multicast address
245 0:0:0:0:0:0:0:1 the loopback address
246 0:0:0:0:0:0:0:0 the unspecified addresses
247 .Ed
248 .Pp
249 may be represented as:
250 .Bd -literal -offset indent
251 1080::8:800:200C:417A a unicast address
252 FF01::43 a multicast address
253 ::1 the loopback address
254 :: the unspecified addresses
255 .Ed
256 .It
257 An alternative form that is sometimes more convenient when
258 dealing with a mixed environment of IPv4 and IPv6 nodes is
259 x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values
260 of the six high-order 16-bit pieces of the address, and the 'd's
261 are the decimal values of the four low-order 8-bit pieces of the
262 address (standard IPv4 representation).
263 Examples:
264 .Bd -literal -offset indent
265 0:0:0:0:0:0:13.1.68.3
266 0:0:0:0:0:FFFF:129.144.52.38
267 .Ed
268 .Pp
269 or in compressed form:
270 .Bd -literal -offset indent
271 ::13.1.68.3
272 ::FFFF:129.144.52.38
273 .Ed
274 .El
275 .Sh DIAGNOSTICS
276 The constant
277 .Dv INADDR_NONE
278 is returned by
279 .Fn inet_addr
280 and
281 .Fn inet_network
282 for malformed requests.
283 .Sh SEE ALSO
284 .Xr byteorder 3 ,
285 .Xr gethostbyname 3 ,
286 .Xr getnetent 3 ,
287 .Xr inet_net 3 ,
288 .Xr hosts 5 ,
289 .Xr networks 5
290 .Rs
291 .%R RFC 2373
292 .%D July 1998
293 .%T "IP Version 6 Addressing Architecture"
294 .Re
295 .Rs
296 .%R RFC 3493
297 .%D February 2003
298 .%T "Basic Socket Interface Extensions for IPv6"
299 .Re
300 .Sh STANDARDS
301 The
302 .Nm inet_ntop
303 and
304 .Nm inet_pton
305 functions conform to
306 .St -p1003.1-2001 .
307 Note that
308 .Nm inet_pton
309 does not accept 1-, 2-, or 3-part dotted addresses; all four parts
310 must be specified.
311 This is a narrower input set than that accepted by
312 .Nm inet_aton .
313 .Sh HISTORY
314 The
315 .Nm inet_addr ,
316 .Nm inet_network ,
317 .Nm inet_makeaddr ,
318 .Nm inet_lnaof
319 and
320 .Nm inet_netof
321 functions appeared in
322 .Bx 4.2 .
323 They were changed to use
324 .Va in_addr_t
325 in place of
326 .Va unsigned long
327 in
328 .Nx 2.0 .
329 The
330 .Nm inet_aton
331 and
332 .Nm inet_ntoa
333 functions appeared in
334 .Bx 4.3 .
335 The
336 .Nm inet_pton
337 and
338 .Nm inet_ntop
339 functions appeared in BIND 4.9.4 and thence
340 .Nx 1.3 ;
341 they were also in
342 .St -xns5.2 .
343 .Sh BUGS
344 The value
345 .Dv INADDR_NONE
346 (0xffffffff) is a valid broadcast address, but
347 .Fn inet_addr
348 cannot return that value without indicating failure.
349 The newer
350 .Fn inet_aton
351 function does not share this problem.
352 .Pp
353 The problem of host byte ordering versus network byte ordering is
354 confusing.
355 .Pp
356 The string returned by
357 .Fn inet_ntoa
358 resides in a static memory area.
359 .Pp
360 .Fn inet_addr
361 should return a
362 .Fa "struct in_addr" .