Debian Codegraph @

upstream/debian-unstable/man3/inet_net_pton.3

raw
1 .\" Copyright 2014, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH inet_net_pton 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 inet_net_pton, inet_net_ntop \- Internet network number conversion
9 .SH LIBRARY
10 Resolver library
11 .RI ( libresolv ,\~ \-lresolv )
12 .SH SYNOPSIS
13 .nf
14 .B #include <arpa/inet.h>
15 .P
16 .BR "int inet_net_pton(" "size_t nsize;"
17 .BI " int " af ", const char *" pres ,
18 .BI " void " netp [ nsize "], size_t " nsize );
19 .BR "char *inet_net_ntop(" "int bits, size_t psize;"
20 .BI " int " af ,
21 .BI " const void " netp [( bits " \- CHAR_BIT + 1) / CHAR_BIT],"
22 .BI " int " bits ,
23 .BI " char " pres [ psize "], size_t " psize );
24 .fi
25 .P
26 .RS -4
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
29 .RE
30 .P
31 .BR inet_net_pton (),
32 .BR inet_net_ntop ():
33 .nf
34 Since glibc 2.20:
35 _DEFAULT_SOURCE
36 Before glibc 2.20:
37 _BSD_SOURCE || _SVID_SOURCE
38 .fi
39 .SH DESCRIPTION
40 These functions convert network numbers between
41 presentation (i.e., printable) format and network (i.e., binary) format.
42 .P
43 For both functions,
44 .I af
45 specifies the address family for the conversion;
46 the only supported value is
47 .BR AF_INET .
48 .SS inet_net_pton()
49 The
50 .BR inet_net_pton ()
51 function converts
52 .IR pres ,
53 a null-terminated string containing an Internet network number in
54 presentation format to network format.
55 The result of the conversion, which is in network byte order,
56 is placed in the buffer pointed to by
57 .IR netp .
58 (The
59 .I netp
60 argument typically points to an
61 .I in_addr
62 structure.)
63 The
64 .I nsize
65 argument specifies the number of bytes available in
66 .IR netp .
67 .P
68 On success,
69 .BR inet_net_pton ()
70 returns the number of bits in the network number field
71 of the result placed in
72 .IR netp .
73 For a discussion of the input presentation format and the return value,
74 see NOTES.
75 .P
76 .IR Note :
77 the buffer pointed to by
78 .I netp
79 should be zeroed out before calling
80 .BR inet_net_pton (),
81 since the call writes only as many bytes as are required
82 for the network number (or as are explicitly specified by
83 .IR pres ),
84 which may be less than the number of bytes in a complete network address.
85 .SS inet_net_ntop()
86 The
87 .BR inet_net_ntop ()
88 function converts the network number in the buffer pointed to by
89 .I netp
90 to presentation format;
91 .I *netp
92 is interpreted as a value in network byte order.
93 The
94 .I bits
95 argument specifies the number of bits in the network number in
96 .IR *netp .
97 .P
98 The null-terminated presentation-format string
99 is placed in the buffer pointed to by
100 .IR pres .
101 The
102 .I psize
103 argument specifies the number of bytes available in
104 .IR pres .
105 The presentation string is in CIDR format:
106 a dotted-decimal number representing the network address,
107 followed by a slash, and the size of the network number in bits.
108 .SH RETURN VALUE
109 On success,
110 .BR inet_net_pton ()
111 returns the number of bits in the network number.
112 On error, it returns \-1, and
113 .I errno
114 is set to indicate the error.
115 .P
116 On success,
117 .BR inet_net_ntop ()
118 returns
119 .IR pres .
120 On error, it returns NULL, and
121 .I errno
122 is set to indicate the error.
123 .SH ERRORS
124 .TP
125 .B EAFNOSUPPORT
126 .I af
127 specified a value other than
128 .BR AF_INET .
129 .TP
130 .B EMSGSIZE
131 The size of the output buffer was insufficient.
132 .TP
133 .B ENOENT
134 .RB ( inet_net_pton ())
135 .I pres
136 was not in correct presentation format.
137 .SH STANDARDS
138 None.
139 .SH NOTES
140 .SS Input presentation format for inet_net_pton()
141 The network number may be specified either
142 as a hexadecimal value
143 or in dotted-decimal notation.
144 .P
145 Hexadecimal values are indicated by an initial "0x" or "0X".
146 The hexadecimal digits populate the nibbles (half octets) of the
147 network number from left to right in network byte order.
148 .\" If the hexadecimal string is short, the remaining nibbles are zeroed.
149 .P
150 In dotted-decimal notation, up to four octets are specified,
151 as decimal numbers separated by dots.
152 Thus, any of the following forms are accepted:
153 .P
154 .in +4n
155 .EX
156 a.b.c.d
157 a.b.c
158 a.b
159 a
160 .EE
161 .in
162 .P
163 Each part is a number in the range 0 to 255 that
164 populates one byte of the resulting network number,
165 going from left to right, in network-byte (big endian) order.
166 Where a part is omitted, the resulting byte in the network number is zero.
167 .\" Reading other man pages, some other implementations treat
168 .\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes
169 .\" 'b' in a.b as a 24-bit number that populates right-most three bytes
170 .P
171 For either hexadecimal or dotted-decimal format,
172 the network number can optionally be followed by a slash
173 and a number in the range 0 to 32,
174 which specifies the size of the network number in bits.
175 .SS Return value of inet_net_pton()
176 The return value of
177 .BR inet_net_pton ()
178 is the number of bits in the network number field.
179 If the input presentation string terminates with a slash and
180 an explicit size value, then that size becomes the return value of
181 .BR inet_net_pton ().
182 Otherwise, the return value,
183 .IR bits ,
184 is inferred as follows:
185 .IP \[bu] 3
186 If the most significant byte of the network number is
187 greater than or equal to 240,
188 then
189 .I bits
190 is 32.
191 .IP \[bu]
192 Otherwise,
193 if the most significant byte of the network number is
194 greater than or equal to 224,
195 then
196 .I bits
197 is 4.
198 .IP \[bu]
199 Otherwise,
200 if the most significant byte of the network number is
201 greater than or equal to 192,
202 then
203 .I bits
204 is 24.
205 .IP \[bu]
206 Otherwise,
207 if the most significant byte of the network number is
208 greater than or equal to 128,
209 then
210 .I bits
211 is 16.
212 .IP \[bu]
213 Otherwise,
214 .I bits
215 is 8.
216 .P
217 If the resulting
218 .I bits
219 value from the above steps is greater than or equal to 8,
220 but the number of octets specified in the network number exceed
221 .IR "bits/8" ,
222 then
223 .I bits
224 is set to 8 times the number of octets actually specified.
225 .SH EXAMPLES
226 The program below demonstrates the use of
227 .BR inet_net_pton ()
228 and
229 .BR inet_net_ntop ().
230 It uses
231 .BR inet_net_pton ()
232 to convert the presentation format network address provided in
233 its first command-line argument to binary form, displays the return value from
234 .BR inet_net_pton ().
235 It then uses
236 .BR inet_net_ntop ()
237 to convert the binary form back to presentation format,
238 and displays the resulting string.
239 .P
240 In order to demonstrate that
241 .BR inet_net_pton ()
242 may not write to all bytes of its
243 .I netp
244 argument, the program allows an optional second command-line argument,
245 a number used to initialize the buffer before
246 .BR inet_net_pton ()
247 is called.
248 As its final line of output,
249 the program displays all of the bytes of the buffer returned by
250 .BR inet_net_pton ()
251 allowing the user to see which bytes have not been touched by
252 .BR inet_net_pton ().
253 .P
254 An example run, showing that
255 .BR inet_net_pton ()
256 infers the number of bits in the network number:
257 .P
258 .in +4n
259 .EX
260 .RB $ " ./a.out 193.168" ;
261 inet_net_pton() returned: 24
262 inet_net_ntop() yielded: 193.168.0/24
263 Raw address: c1a80000
264 .EE
265 .in
266 .P
267 Demonstrate that
268 .BR inet_net_pton ()
269 does not zero out unused bytes in its result buffer:
270 .P
271 .in +4n
272 .EX
273 .RB $ " ./a.out 193.168 0xffffffff" ;
274 inet_net_pton() returned: 24
275 inet_net_ntop() yielded: 193.168.0/24
276 Raw address: c1a800ff
277 .EE
278 .in
279 .P
280 Demonstrate that
281 .BR inet_net_pton ()
282 will widen the inferred size of the network number,
283 if the supplied number of bytes in the presentation
284 string exceeds the inferred value:
285 .P
286 .in +4n
287 .EX
288 .RB $ " ./a.out 193.168.1.128" ;
289 inet_net_pton() returned: 32
290 inet_net_ntop() yielded: 193.168.1.128/32
291 Raw address: c1a80180
292 .EE
293 .in
294 .P
295 Explicitly specifying the size of the network number overrides any
296 inference about its size
297 (but any extra bytes that are explicitly specified will still be used by
298 .BR inet_net_pton ():
299 to populate the result buffer):
300 .P
301 .in +4n
302 .EX
303 .RB $ " ./a.out 193.168.1.128/24" ;
304 inet_net_pton() returned: 24
305 inet_net_ntop() yielded: 193.168.1/24
306 Raw address: c1a80180
307 .EE
308 .in
309 .SS Program source
310 .\" SRC BEGIN (inet_net_pton.c)
311 .EX
312 /* Link with "\-lresolv" */
313 \&
314 #include <arpa/inet.h>
315 #include <err.h>
316 #include <stdio.h>
317 #include <stdlib.h>
318 \&
319 int
320 main(int argc, char *argv[])
321 {
322 char buf[100];
323 struct in_addr addr;
324 int bits;
325 \&
326 if (argc < 2) {
327 fprintf(stderr,
328 "Usage: %s presentation\-form [addr\-init\-value]\[rs]n",
329 argv[0]);
330 exit(EXIT_FAILURE);
331 }
332 \&
333 /* If argv[2] is supplied (a numeric value), use it to initialize
334 the output buffer given to inet_net_pton(), so that we can see
335 that inet_net_pton() initializes only those bytes needed for
336 the network number. If argv[2] is not supplied, then initialize
337 the buffer to zero (as is recommended practice). */
338 \&
339 addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;
340 \&
341 /* Convert presentation network number in argv[1] to binary. */
342 \&
343 bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
344 if (bits == \-1)
345 err(EXIT_FAILURE, "inet_net_ntop");
346 \&
347 printf("inet_net_pton() returned: %d\[rs]n", bits);
348 \&
349 /* Convert binary format back to presentation, using \[aq]bits\[aq]
350 returned by inet_net_pton(). */
351 \&
352 if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
353 err(EXIT_FAILURE, "inet_net_ntop");
354 \&
355 printf("inet_net_ntop() yielded: %s\[rs]n", buf);
356 \&
357 /* Display \[aq]addr\[aq] in raw form (in network byte order), so we can
358 see bytes not displayed by inet_net_ntop(); some of those bytes
359 may not have been touched by inet_net_ntop(), and so will still
360 have any initial value that was specified in argv[2]. */
361 \&
362 printf("Raw address: %x\[rs]n", htonl(addr.s_addr));
363 \&
364 exit(EXIT_SUCCESS);
365 }
366 .EE
367 .\" SRC END
368 .SH SEE ALSO
369 .BR inet (3),
370 .BR networks (5)