Annotation of src/lib/libc/inet/inet.3, Revision 1.5
1.5 ! ginsbach 1: .\" $NetBSD: inet.3,v 1.4 2012/07/20 19:18:08 ginsbach Exp $
1.1 christos 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: .\"
1.5 ! ginsbach 32: .Dd July 25, 2012
1.1 christos 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.
1.2 christos 122: The
123: .Ar size
124: parameter is the size of the
125: .Ar buf
126: argument.
1.1 christos 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.
1.4 ginsbach 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
1.1 christos 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
1.3 ginsbach 334: .Fn inet_ntop
1.1 christos 335: and
1.3 ginsbach 336: .Fn inet_pton
1.1 christos 337: functions conform to
338: .St -p1003.1-2001 .
339: Note that
1.3 ginsbach 340: .Fn inet_pton
1.5 ! ginsbach 341: does not accept 1-, 2-, or 3-part dotted addresses; all four parts
1.1 christos 342: must be specified.
1.5 ! ginsbach 343: Additionally all four parts of a dotted address must be decimal.
1.1 christos 344: This is a narrower input set than that accepted by
1.3 ginsbach 345: .Fn inet_aton .
1.1 christos 346: .Sh HISTORY
347: The
1.3 ginsbach 348: .Fn inet_addr ,
349: .Fn inet_network ,
350: .Fn inet_makeaddr ,
351: .Fn inet_lnaof
1.1 christos 352: and
1.3 ginsbach 353: .Fn inet_netof
1.1 christos 354: functions appeared in
355: .Bx 4.2 .
356: They were changed to use
1.3 ginsbach 357: .Vt in_addr_t
1.1 christos 358: in place of
1.3 ginsbach 359: .Vt unsigned long
1.1 christos 360: in
361: .Nx 2.0 .
362: The
1.3 ginsbach 363: .Fn inet_aton
1.1 christos 364: and
1.3 ginsbach 365: .Fn inet_ntoa
1.1 christos 366: functions appeared in
367: .Bx 4.3 .
368: The
1.3 ginsbach 369: .Fn inet_pton
1.1 christos 370: and
1.3 ginsbach 371: .Fn inet_ntop
1.1 christos 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
1.4 ginsbach 393: The function
1.1 christos 394: .Fn inet_addr
395: should return a
1.3 ginsbach 396: .Vt struct in_addr .
1.5 ! ginsbach 397: .Pp
! 398: The function
! 399: .Fn inet_network
! 400: does not support byte rearrangement for one, two, and three
! 401: part addresses.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to inet.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / inet