Debian Codegraph @

upstream/debian-trixie/man3/inet.3

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