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