]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
3d54a910 MK |
2 | .\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
3 | .\" <mtk.manpages@gmail.com> | |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" References consulted: | |
8 | .\" Linux libc source code | |
9 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
10 | .\" 386BSD man pages | |
11 | .\" libc.info (from glibc distribution) | |
12 | .\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith <faith@cs.unc.edu> | |
13 | .\" Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> | |
14 | .\" Changed network into host byte order (for inet_network), | |
15 | .\" Andreas Jaeger <aj@arthur.rhein-neckar.de>, 980130. | |
054f5228 MK |
16 | .\" 2008-06-19, mtk |
17 | .\" Describe the various address forms supported by inet_aton(). | |
18 | .\" Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr(). | |
19 | .\" Add discussion of Classful Addressing, noting that it is obsolete. | |
20 | .\" Added an EXAMPLE program. | |
fea681da | 21 | .\" |
1d767b55 | 22 | .TH INET 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
fea681da | 23 | .SH NAME |
c13182ef | 24 | inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, |
fea681da | 25 | inet_netof \- Internet address manipulation routines |
4508f8a0 AC |
26 | .SH LIBRARY |
27 | Standard C library | |
8fc3b2cf | 28 | .RI ( libc ", " \-lc ) |
fea681da MK |
29 | .SH SYNOPSIS |
30 | .nf | |
31 | .B #include <sys/socket.h> | |
32 | .B #include <netinet/in.h> | |
33 | .B #include <arpa/inet.h> | |
68e4db0a | 34 | .PP |
fea681da | 35 | .BI "int inet_aton(const char *" cp ", struct in_addr *" inp ); |
68e4db0a | 36 | .PP |
fea681da | 37 | .BI "in_addr_t inet_addr(const char *" cp ); |
fea681da | 38 | .BI "in_addr_t inet_network(const char *" cp ); |
68e4db0a | 39 | .PP |
fea681da | 40 | .BI "char *inet_ntoa(struct in_addr " in ); |
68e4db0a | 41 | .PP |
92263c07 | 42 | .BI "struct in_addr inet_makeaddr(in_addr_t " net ", in_addr_t " host ); |
68e4db0a | 43 | .PP |
fea681da | 44 | .BI "in_addr_t inet_lnaof(struct in_addr " in ); |
fea681da MK |
45 | .BI "in_addr_t inet_netof(struct in_addr " in ); |
46 | .fi | |
68e4db0a | 47 | .PP |
d39ad78f | 48 | .RS -4 |
cc4615cc MK |
49 | Feature Test Macro Requirements for glibc (see |
50 | .BR feature_test_macros (7)): | |
d39ad78f | 51 | .RE |
68e4db0a | 52 | .PP |
cc4615cc MK |
53 | .BR inet_aton (), |
54 | .BR inet_ntoa (): | |
7f0ec8ee MK |
55 | .nf |
56 | Since glibc 2.19: | |
57 | _DEFAULT_SOURCE | |
58 | In glibc up to and including 2.19: | |
59 | _BSD_SOURCE || _BSD_SOURCE | |
60 | .fi | |
fea681da | 61 | .SH DESCRIPTION |
60a90ecd MK |
62 | .BR inet_aton () |
63 | converts the Internet host address \fIcp\fP from the | |
054f5228 MK |
64 | IPv4 numbers-and-dots notation into binary form (in network byte order) |
65 | and stores it in the structure that \fIinp\fP points to. | |
60a90ecd | 66 | .BR inet_aton () |
c7094399 | 67 | returns nonzero if the address is valid, zero if not. |
054f5228 MK |
68 | The address supplied in |
69 | .I cp | |
70 | can have one of the following forms: | |
71 | .TP 10 | |
72 | .I a.b.c.d | |
57e5ca03 | 73 | Each of the four numeric parts specifies a byte of the address; |
054f5228 MK |
74 | the bytes are assigned in left-to-right order to produce the binary address. |
75 | .TP | |
76 | .I a.b.c | |
77 | Parts | |
78 | .I a | |
79 | and | |
80 | .I b | |
81 | specify the first two bytes of the binary address. | |
82 | Part | |
83 | .I c | |
84 | is interpreted as a 16-bit value that defines the rightmost two bytes | |
85 | of the binary address. | |
86 | This notation is suitable for specifying (outmoded) Class B | |
87 | network addresses. | |
88 | .TP | |
89 | .I a.b | |
90 | Part | |
91 | .I a | |
92 | specifies the first byte of the binary address. | |
93 | Part | |
94 | .I b | |
95 | is interpreted as a 24-bit value that defines the rightmost three bytes | |
96 | of the binary address. | |
5526923a | 97 | This notation is suitable for specifying (outmoded) Class A |
054f5228 MK |
98 | network addresses. |
99 | .TP | |
100 | .I a | |
101 | The value | |
102 | .I a | |
103 | is interpreted as a 32-bit value that is stored directly | |
104 | into the binary address without any byte rearrangement. | |
105 | .PP | |
106 | In all of the above forms, | |
107 | components of the dotted address can be specified in decimal, | |
108 | octal (with a leading | |
109 | .IR 0 ), | |
110 | or hexadecimal, with a leading | |
111 | .IR 0X ). | |
112 | Addresses in any of these forms are collectively termed | |
113 | .IR "IPV4 numbers-and-dots notation" . | |
114 | The form that uses exactly four decimal numbers is referred to as | |
1ae6b2c7 | 115 | .I IPv4 dotted-decimal notation |
054f5228 MK |
116 | (or sometimes: |
117 | .IR "IPv4 dotted-quad notation" ). | |
847e0d88 | 118 | .PP |
4cbfaed0 MK |
119 | .BR inet_aton () |
120 | returns 1 if the supplied string was successfully interpreted, | |
121 | or 0 if the string is invalid | |
122 | .RB ( errno | |
123 | is | |
124 | .I not | |
125 | set on error). | |
fea681da | 126 | .PP |
60a90ecd MK |
127 | The |
128 | .BR inet_addr () | |
129 | function converts the Internet host address | |
054f5228 | 130 | \fIcp\fP from IPv4 numbers-and-dots notation into binary data in network |
c13182ef | 131 | byte order. |
2f0af33b MK |
132 | If the input is invalid, |
133 | .B INADDR_NONE | |
134 | (usually \-1) is returned. | |
054f5228 MK |
135 | Use of this function is problematic because \-1 is a valid address |
136 | (255.255.255.255). | |
137 | Avoid its use in favor of | |
60a90ecd | 138 | .BR inet_aton (), |
054f5228 MK |
139 | .BR inet_pton (3), |
140 | or | |
a414d0b5 | 141 | .BR getaddrinfo (3), |
054f5228 | 142 | which provide a cleaner way to indicate error return. |
fea681da | 143 | .PP |
60a90ecd MK |
144 | The |
145 | .BR inet_network () | |
054f5228 MK |
146 | function converts |
147 | .IR cp , | |
148 | a string in IPv4 numbers-and-dots notation, | |
149 | into a number in host byte order suitable for use as an | |
150 | Internet network address. | |
151 | On success, the converted address is returned. | |
7cc028fb | 152 | If the input is invalid, \-1 is returned. |
fea681da | 153 | .PP |
60a90ecd MK |
154 | The |
155 | .BR inet_ntoa () | |
156 | function converts the Internet host address | |
054f5228 MK |
157 | \fIin\fP, given in network byte order, to a string in IPv4 |
158 | dotted-decimal notation. | |
c13182ef | 159 | The string is returned in a statically |
fea681da MK |
160 | allocated buffer, which subsequent calls will overwrite. |
161 | .PP | |
60a90ecd | 162 | The |
60a90ecd | 163 | .BR inet_lnaof () |
054f5228 | 164 | function returns the local network address part |
c13182ef | 165 | of the Internet address \fIin\fP. |
054f5228 | 166 | The returned value is in host byte order. |
fea681da | 167 | .PP |
60a90ecd MK |
168 | The |
169 | .BR inet_netof () | |
170 | function returns the network number part of | |
054f5228 MK |
171 | the Internet address \fIin\fP. |
172 | The returned value is in host byte order. | |
173 | .PP | |
174 | The | |
175 | .BR inet_makeaddr () | |
176 | function is the converse of | |
61792fc6 | 177 | .BR inet_netof () |
054f5228 MK |
178 | and |
179 | .BR inet_lnaof (). | |
180 | It returns an Internet host address in network byte order, | |
181 | created by combining the network number \fInet\fP | |
182 | with the local address \fIhost\fP, both in | |
183 | host byte order. | |
fea681da | 184 | .PP |
60a90ecd MK |
185 | The structure \fIin_addr\fP as used in |
186 | .BR inet_ntoa (), | |
187 | .BR inet_makeaddr (), | |
d556548b | 188 | .BR inet_lnaof (), |
60a90ecd MK |
189 | and |
190 | .BR inet_netof () | |
a9a13a50 MK |
191 | is defined in |
192 | .I <netinet/in.h> | |
193 | as: | |
51f5698d | 194 | .PP |
bd191423 | 195 | .in +4n |
bdd915e2 | 196 | .EX |
9f8162f9 MK |
197 | typedef uint32_t in_addr_t; |
198 | ||
fea681da | 199 | struct in_addr { |
9f8162f9 MK |
200 | in_addr_t s_addr; |
201 | }; | |
bdd915e2 | 202 | .EE |
bd191423 | 203 | .in |
b73c9bd5 PH |
204 | .SH ATTRIBUTES |
205 | For an explanation of the terms used in this section, see | |
206 | .BR attributes (7). | |
c466875e MK |
207 | .ad l |
208 | .nh | |
b73c9bd5 PH |
209 | .TS |
210 | allbox; | |
c466875e | 211 | lbx lb lb |
b73c9bd5 PH |
212 | l l l. |
213 | Interface Attribute Value | |
214 | T{ | |
215 | .BR inet_aton (), | |
93ead13c | 216 | .BR inet_addr (), |
93ead13c MS |
217 | .BR inet_network (), |
218 | .BR inet_ntoa () | |
b73c9bd5 PH |
219 | T} Thread safety MT-Safe locale |
220 | T{ | |
b73c9bd5 PH |
221 | .BR inet_makeaddr (), |
222 | .BR inet_lnaof (), | |
b73c9bd5 PH |
223 | .BR inet_netof () |
224 | T} Thread safety MT-Safe | |
225 | .TE | |
c466875e MK |
226 | .hy |
227 | .ad | |
228 | .sp 1 | |
47297adb | 229 | .SH CONFORMING TO |
492a45fe MK |
230 | .BR inet_addr (), |
231 | .BR inet_ntoa (): | |
232 | POSIX.1-2001, POSIX.1-2008, 4.3BSD. | |
847e0d88 | 233 | .PP |
054f5228 | 234 | .BR inet_aton () |
492a45fe | 235 | is not specified in POSIX.1, but is available on most systems. |
19c98696 | 236 | .SH NOTES |
b3f78bdc | 237 | On x86 architectures, the host byte order is Least Significant Byte |
054f5228 MK |
238 | first (little endian), whereas the network byte order, as used on the |
239 | Internet, is Most Significant Byte first (big endian). | |
847e0d88 | 240 | .PP |
054f5228 MK |
241 | .BR inet_lnaof (), |
242 | .BR inet_netof (), | |
243 | and | |
244 | .BR inet_makeaddr () | |
245 | are legacy functions that assume they are dealing with | |
246 | .IR "classful network addresses" . | |
247 | Classful networking divides IPv4 network addresses into host and network | |
248 | components at byte boundaries, as follows: | |
249 | .TP 10 | |
250 | Class A | |
251 | This address type is indicated by the value 0 in the | |
252 | most significant bit of the (network byte ordered) address. | |
253 | The network address is contained in the most significant byte, | |
254 | and the host address occupies the remaining three bytes. | |
255 | .TP | |
256 | Class B | |
257 | This address type is indicated by the binary value 10 in the | |
258 | most significant two bits of the address. | |
259 | The network address is contained in the two most significant bytes, | |
260 | and the host address occupies the remaining two bytes. | |
261 | .TP | |
262 | Class C | |
263 | This address type is indicated by the binary value 110 in the | |
264 | most significant three bits of the address. | |
265 | The network address is contained in the three most significant bytes, | |
266 | and the host address occupies the remaining byte. | |
267 | .PP | |
ab186fbd | 268 | Classful network addresses are now obsolete, |
054f5228 MK |
269 | having been superseded by Classless Inter-Domain Routing (CIDR), |
270 | which divides addresses into network and host components at | |
271 | arbitrary bit (rather than byte) boundaries. | |
a14af333 | 272 | .SH EXAMPLES |
054f5228 MK |
273 | An example of the use of |
274 | .BR inet_aton () | |
275 | and | |
276 | .BR inet_ntoa () | |
277 | is shown below. | |
278 | Here are some example runs: | |
e646a1ba | 279 | .PP |
054f5228 | 280 | .in +4n |
e646a1ba | 281 | .EX |
b43a3b30 | 282 | .RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal" |
054f5228 | 283 | 226.0.0.31 |
b43a3b30 | 284 | .RB "$" " ./a.out 0x7f.1 " " # First byte is in hex" |
054f5228 | 285 | 127.0.0.1 |
b8302363 | 286 | .EE |
054f5228 | 287 | .in |
9c330504 | 288 | .SS Program source |
d84d0300 | 289 | \& |
e7d0bb47 | 290 | .EX |
88d2b3fd | 291 | #define _DEFAULT_SOURCE |
054f5228 MK |
292 | #include <arpa/inet.h> |
293 | #include <stdio.h> | |
294 | #include <stdlib.h> | |
295 | ||
296 | int | |
297 | main(int argc, char *argv[]) | |
298 | { | |
299 | struct in_addr addr; | |
300 | ||
301 | if (argc != 2) { | |
d1a71985 | 302 | fprintf(stderr, "%s <dotted\-address>\en", argv[0]); |
054f5228 MK |
303 | exit(EXIT_FAILURE); |
304 | } | |
305 | ||
306 | if (inet_aton(argv[1], &addr) == 0) { | |
d1a71985 | 307 | fprintf(stderr, "Invalid address\en"); |
054f5228 MK |
308 | exit(EXIT_FAILURE); |
309 | } | |
310 | ||
d1a71985 | 311 | printf("%s\en", inet_ntoa(addr)); |
054f5228 MK |
312 | exit(EXIT_SUCCESS); |
313 | } | |
e7d0bb47 | 314 | .EE |
47297adb | 315 | .SH SEE ALSO |
054f5228 MK |
316 | .BR byteorder (3), |
317 | .BR getaddrinfo (3), | |
fea681da | 318 | .BR gethostbyname (3), |
054f5228 | 319 | .BR getnameinfo (3), |
fea681da | 320 | .BR getnetent (3), |
ebd9e5df | 321 | .BR inet_net_pton (3), |
fea681da MK |
322 | .BR inet_ntop (3), |
323 | .BR inet_pton (3), | |
324 | .BR hosts (5), | |
325 | .BR networks (5) |