Debian Codegraph @

upstream/debian-unstable/man3/inet.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH inet 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof,
10 inet_netof \- Internet address manipulation routines
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/socket.h>
17 .B #include <netinet/in.h>
18 .B #include <arpa/inet.h>
19 .P
20 .BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
21 .P
22 .BI "in_addr_t inet_addr(const char *" cp );
23 .BI "in_addr_t inet_network(const char *" cp );
24 .P
25 .BI "[[deprecated]] char *inet_ntoa(struct in_addr " in );
26 .P
27 .BI "[[deprecated]] struct in_addr inet_makeaddr(in_addr_t " net ,
28 .BI " in_addr_t " host );
29 .P
30 .BI "[[deprecated]] in_addr_t inet_lnaof(struct in_addr " in );
31 .BI "[[deprecated]] in_addr_t inet_netof(struct in_addr " in );
32 .fi
33 .P
34 .RS -4
35 Feature Test Macro Requirements for glibc (see
36 .BR feature_test_macros (7)):
37 .RE
38 .P
39 .BR inet_aton (),
40 .BR inet_ntoa ():
41 .nf
42 Since glibc 2.19:
43 _DEFAULT_SOURCE
44 In glibc up to and including 2.19:
45 _BSD_SOURCE || _BSD_SOURCE
46 .fi
47 .SH DESCRIPTION
48 .BR inet_aton ()
49 converts the Internet host address
50 .I cp
51 from the
52 IPv4 numbers-and-dots notation into binary form (in network byte order)
53 and stores it in the structure that
54 .I inp
55 points to.
56 .BR inet_aton ()
57 returns nonzero if the address is valid, zero if not.
58 The address supplied in
59 .I cp
60 can have one of the following forms:
61 .TP 10
62 .I a.b.c.d
63 Each of the four numeric parts specifies a byte of the address;
64 the bytes are assigned in left-to-right order to produce the binary address.
65 .TP
66 .I a.b.c
67 Parts
68 .I a
69 and
70 .I b
71 specify the first two bytes of the binary address.
72 Part
73 .I c
74 is interpreted as a 16-bit value that defines the rightmost two bytes
75 of the binary address.
76 This notation is suitable for specifying (outmoded) Class B
77 network addresses.
78 .TP
79 .I a.b
80 Part
81 .I a
82 specifies the first byte of the binary address.
83 Part
84 .I b
85 is interpreted as a 24-bit value that defines the rightmost three bytes
86 of the binary address.
87 This notation is suitable for specifying (outmoded) Class A
88 network addresses.
89 .TP
90 .I a
91 The value
92 .I a
93 is interpreted as a 32-bit value that is stored directly
94 into the binary address without any byte rearrangement.
95 .P
96 In all of the above forms,
97 components of the dotted address can be specified in decimal,
98 octal (with a leading
99 .IR 0 ),
100 or hexadecimal, with a leading
101 .IR 0X ).
102 Addresses in any of these forms are collectively termed
103 .IR "IPV4 numbers-and-dots notation" .
104 The form that uses exactly four decimal numbers is referred to as
105 .I IPv4 dotted-decimal notation
106 (or sometimes:
107 .IR "IPv4 dotted-quad notation" ).
108 .P
109 .BR inet_aton ()
110 returns 1 if the supplied string was successfully interpreted,
111 or 0 if the string is invalid
112 .RB ( errno
113 is
114 .I not
115 set on error).
116 .P
117 The
118 .BR inet_addr ()
119 function converts the Internet host address
120 .I cp
121 from IPv4 numbers-and-dots notation into binary data in network byte order.
122 If the input is invalid,
123 .B INADDR_NONE
124 (usually \-1) is returned.
125 Use of this function is problematic because \-1 is a valid address
126 (255.255.255.255).
127 Avoid its use in favor of
128 .BR inet_aton (),
129 .BR inet_pton (3),
130 or
131 .BR getaddrinfo (3),
132 which provide a cleaner way to indicate error return.
133 .P
134 The
135 .BR inet_network ()
136 function converts
137 .IR cp ,
138 a string in IPv4 numbers-and-dots notation,
139 into a number in host byte order suitable for use as an
140 Internet network address.
141 On success, the converted address is returned.
142 If the input is invalid, \-1 is returned.
143 .P
144 The
145 .BR inet_ntoa ()
146 function converts the Internet host address
147 .IR in ,
148 given in network byte order,
149 to a string in IPv4 dotted-decimal notation.
150 The string is returned in a statically
151 allocated buffer, which subsequent calls will overwrite.
152 .P
153 The
154 .BR inet_lnaof ()
155 function returns the local network address part
156 of the Internet address
157 .IR in .
158 The returned value is in host byte order.
159 .P
160 The
161 .BR inet_netof ()
162 function returns the network number part of
163 the Internet address
164 .IR in .
165 The returned value is in host byte order.
166 .P
167 The
168 .BR inet_makeaddr ()
169 function is the converse of
170 .BR inet_netof ()
171 and
172 .BR inet_lnaof ().
173 It returns an Internet host address in network byte order,
174 created by combining the network number\
175 .I net
176 with the local address
177 .IR host ,
178 both in host byte order.
179 .P
180 The structure
181 .I in_addr
182 as used in
183 .BR inet_ntoa (),
184 .BR inet_makeaddr (),
185 .BR inet_lnaof (),
186 and
187 .BR inet_netof ()
188 is defined in
189 .I <netinet/in.h>
190 as:
191 .P
192 .in +4n
193 .EX
194 typedef uint32_t in_addr_t;
195 \&
196 struct in_addr {
197 in_addr_t s_addr;
198 };
199 .EE
200 .in
201 .SH ATTRIBUTES
202 For an explanation of the terms used in this section, see
203 .BR attributes (7).
204 .TS
205 allbox;
206 lbx lb lb
207 l l l.
208 Interface Attribute Value
209 T{
210 .na
211 .nh
212 .BR inet_aton (),
213 .BR inet_addr (),
214 .BR inet_network (),
215 .BR inet_ntoa ()
216 T} Thread safety MT-Safe locale
217 T{
218 .na
219 .nh
220 .BR inet_makeaddr (),
221 .BR inet_lnaof (),
222 .BR inet_netof ()
223 T} Thread safety MT-Safe
224 .TE
225 .SH STANDARDS
226 .TP
227 .BR inet_addr ()
228 .TQ
229 .BR inet_ntoa ()
230 POSIX.1-2008.
231 .TP
232 .BR inet_aton ()
233 None.
234 .SH STANDARDS
235 .TP
236 .BR inet_addr ()
237 .TQ
238 .BR inet_ntoa ()
239 POSIX.1-2001, 4.3BSD.
240 .P
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 .P
268 Classful network addresses are now obsolete,
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.
272 .SH NOTES
273 On x86 architectures, the host byte order is Least Significant Byte
274 first (little endian), whereas the network byte order, as used on the
275 Internet, is Most Significant Byte first (big endian).
276 .SH EXAMPLES
277 An example of the use of
278 .BR inet_aton ()
279 and
280 .BR inet_ntoa ()
281 is shown below.
282 Here are some example runs:
283 .P
284 .in +4n
285 .EX
286 .RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal"
287 226.0.0.31
288 .RB "$" " ./a.out 0x7f.1 " " # First byte is in hex"
289 127.0.0.1
290 .EE
291 .in
292 .SS Program source
293 \&
294 .\" SRC BEGIN (inet.c)
295 .EX
296 #define _DEFAULT_SOURCE
297 #include <arpa/inet.h>
298 #include <stdio.h>
299 #include <stdlib.h>
300 \&
301 int
302 main(int argc, char *argv[])
303 {
304 struct in_addr addr;
305 \&
306 if (argc != 2) {
307 fprintf(stderr, "%s <dotted\-address>\[rs]n", argv[0]);
308 exit(EXIT_FAILURE);
309 }
310 \&
311 if (inet_aton(argv[1], &addr) == 0) {
312 fprintf(stderr, "Invalid address\[rs]n");
313 exit(EXIT_FAILURE);
314 }
315 \&
316 printf("%s\[rs]n", inet_ntoa(addr));
317 exit(EXIT_SUCCESS);
318 }
319 .EE
320 .\" SRC END
321 .SH SEE ALSO
322 .BR byteorder (3),
323 .BR getaddrinfo (3),
324 .BR gethostbyname (3),
325 .BR getnameinfo (3),
326 .BR getnetent (3),
327 .BR inet_net_pton (3),
328 .BR inet_ntop (3),
329 .BR inet_pton (3),
330 .BR hosts (5),
331 .BR networks (5)