1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH INET_NET_PTON 3 2021-03-22 "Linux" "Linux Programmer's Manual"
27 inet_net_pton, inet_net_ntop \- Internet network number conversion
30 .B #include <arpa/inet.h>
32 .BI "int inet_net_pton(int " af ", const char *" pres ,
33 .BI " void *" netp ", size_t " nsize );
34 .BI "char *inet_net_ntop(int " af ", const void *" netp ", int " bits ,
35 .BI " char *" pres ", size_t " psize );
38 Link with \fI\-lresolv\fP.
41 Feature Test Macro Requirements for glibc (see
42 .BR feature_test_macros (7)):
51 _BSD_SOURCE || _SVID_SOURCE
54 These functions convert network numbers between
55 presentation (i.e., printable) format and network (i.e., binary) format.
59 specifies the address family for the conversion;
60 the only supported value is
67 a null-terminated string containing an Internet network number in
68 presentation format to network format.
69 The result of the conversion, which is in network byte order,
70 is placed in the buffer pointed to by
74 argument typically points to an
79 argument specifies the number of bytes available in
84 returns the number of bits in the network number field
85 of the result placed in
87 For a discussion of the input presentation format and the return value,
91 the buffer pointed to by
93 should be zeroed out before calling
95 since the call writes only as many bytes as are required
96 for the network number (or as are explicitly specified by
98 which may be less than the number of bytes in a complete network address.
102 function converts the network number in the buffer pointed to by
104 to presentation format;
106 is interpreted as a value in network byte order.
109 argument specifies the number of bits in the network number in
112 The null-terminated presentation-format string
113 is placed in the buffer pointed to by
117 argument specifies the number of bytes available in
119 The presentation string is in CIDR format:
120 a dotted-decimal number representing the network address,
121 followed by a slash, and the size of the network number in bits.
125 returns the number of bits in the network number.
126 On error, it returns \-1, and
128 is set to indicate the error.
134 On error, it returns NULL, and
136 is set to indicate the error.
141 specified a value other than
145 The size of the output buffer was insufficient.
148 .RB ( inet_net_pton ())
150 was not in correct presentation format.
156 functions are nonstandard, but widely available.
158 .SS Input presentation format for inet_net_pton()
159 The network number may be specified either
160 as a hexadecimal value
161 or in dotted-decimal notation.
163 Hexadecimal values are indicated by an initial "0x" or "0X".
164 The hexadecimal digits populate the nibbles (half octets) of the
165 network number from left to right in network byte order.
166 .\" If the hexadecimal string is short, the remaining nibbles are zeroed.
168 In dotted-decimal notation, up to four octets are specified,
169 as decimal numbers separated by dots.
170 Thus, any of the following forms are accepted:
177 Each part is a number in the range 0 to 255 that
178 populates one byte of the resulting network number,
179 going from left to right, in network-byte (big endian) order.
180 Where a part is omitted, the resulting byte in the network number is zero.
181 .\" Reading other man pages, some other implementations treat
182 .\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes
183 .\" 'b' in a.b as a 24-bit number that populates right-most three bytes
185 For either hexadecimal or dotted-decimal format,
186 the network number can optionally be followed by a slash
187 and a number in the range 0 to 32,
188 which specifies the size of the network number in bits.
189 .SS Return value of inet_net_pton()
192 is the number of bits in the network number field.
193 If the input presentation string terminates with a slash and
194 an explicit size value, then that size becomes the return value of
195 .BR inet_net_pton ().
196 Otherwise, the return value,
198 is inferred as follows:
200 If the most significant byte of the network number is
201 greater than or equal to 240,
207 if the most significant byte of the network number is
208 greater than or equal to 224,
214 if the most significant byte of the network number is
215 greater than or equal to 192,
221 if the most significant byte of the network number is
222 greater than or equal to 128,
233 value from the above steps is greater than or equal to 8,
234 but the number of octets specified in the network number exceed
238 is set to 8 times the number of octets actually specified.
240 The program below demonstrates the use of
243 .BR inet_net_ntop ().
246 to convert the presentation format network address provided in
247 its first command-line argument to binary form, displays the return value from
248 .BR inet_net_pton ().
251 to convert the binary form back to presentation format,
252 and displays the resulting string.
254 In order to demonstrate that
256 may not write to all bytes of its
258 argument, the program allows an optional second command-line argument,
259 a number used to initialize the buffer before
262 As its final line of output,
263 the program displays all of the bytes of the buffer returned by
265 allowing the user to see which bytes have not been touched by
266 .BR inet_net_pton ().
268 An example run, showing that
270 infers the number of bits in the network number:
274 $ \fB./a.out 193.168\fP
275 inet_net_pton() returned: 24
276 inet_net_ntop() yielded: 193.168.0/24
277 Raw address: c1a80000
283 does not zero out unused bytes in its result buffer:
287 $ \fB./a.out 193.168 0xffffffff\fP
288 inet_net_pton() returned: 24
289 inet_net_ntop() yielded: 193.168.0/24
290 Raw address: c1a800ff
296 will widen the inferred size of the network number,
297 if the supplied number of bytes in the presentation
298 string exceeds the inferred value:
302 $ \fB./a.out 193.168.1.128\fP
303 inet_net_pton() returned: 32
304 inet_net_ntop() yielded: 193.168.1.128/32
305 Raw address: c1a80180
309 Explicitly specifying the size of the network number overrides any
310 inference about its size
311 (but any extra bytes that are explicitly specified will still be used by
312 .BR inet_net_pton ():
313 to populate the result buffer):
317 $ \fB./a.out 193.168.1.128/24\fP
318 inet_net_pton() returned: 24
319 inet_net_ntop() yielded: 193.168.1/24
320 Raw address: c1a80180
325 /* Link with "\-lresolv" */
327 #include <arpa/inet.h>
331 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
335 main(int argc, char *argv[])
343 "Usage: %s presentation\-form [addr\-init\-value]\en",
348 /* If argv[2] is supplied (a numeric value), use it to initialize
349 the output buffer given to inet_net_pton(), so that we can see
350 that inet_net_pton() initializes only those bytes needed for
351 the network number. If argv[2] is not supplied, then initialize
352 the buffer to zero (as is recommended practice). */
354 addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;
356 /* Convert presentation network number in argv[1] to binary. */
358 bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
360 errExit("inet_net_ntop");
362 printf("inet_net_pton() returned: %d\en", bits);
364 /* Convert binary format back to presentation, using \(aqbits\(aq
365 returned by inet_net_pton(). */
367 if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
368 errExit("inet_net_ntop");
370 printf("inet_net_ntop() yielded: %s\en", buf);
372 /* Display \(aqaddr\(aq in raw form (in network byte order), so we can
373 see bytes not displayed by inet_net_ntop(); some of those bytes
374 may not have been touched by inet_net_ntop(), and so will still
375 have any initial value that was specified in argv[2]. */
377 printf("Raw address: %x\en", htonl(addr.s_addr));