2 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH INET_NET_PTON 3 2014-05-28 "Linux" "Linux Programmer's Manual"
28 inet_net_pton, inet_net_ntop \- Internet network number conversion
31 .B #include <arpa/inet.h>
33 .BI "int inet_net_pton(int " af ", const char *" pres ,
34 .BI " void *" netp ", size_t " nsize );
36 .BI "char *inet_net_ntop(int " af ", const void *" netp ", int " bits ,
37 .BI " char *" pres ", size_t " psize );
40 Link with \fI\-lresolv\fP.
43 Feature Test Macro Requirements for glibc (see
44 .BR feature_test_macros (7)):
57 _BSD_SOURCE || _SVID_SOURCE
62 These functions convert network numbers between
63 presentation (i.e., printable) format and network (i.e., binary) format.
67 specifies the address family for the conversion;
68 the only supported value is
75 a null-terminated string containing an Internet network number in
76 presentation format to network format.
77 The result of the conversion, which is in network byte order,
78 is placed in the buffer pointed to by
82 argument typically points to an
87 argument specifies the number of bytes available in
92 returns the number of bits in the network number field
93 of the result placed in
95 For a discussion of the input presentation format and the return value,
99 the buffer pointed to by
101 should be zeroed out before calling
102 .BR inet_net_pton (),
103 since the call writes only as many bytes as are required
104 for the network number (or as are explicitly specified by
106 which may be less than the number of bytes in a complete network address.
110 function converts the network number in the buffer pointed to by
112 to presentation format;
114 is interpreted as a value in network byte order.
117 argument specifies the number of bits in the network number in
120 The null-terminated presentation-format string
121 is placed in the buffer pointed to by
125 argument specifies the number of bytes available in
127 The presentation string is in CIDR format:
128 a dotted-decimal number representing the network address,
129 followed by a slash, and the size of the network number in bits.
133 returns the number of bits in the network number.
134 On error, it returns \-1, and
136 is set to indicate the cause of the error.
142 On error, it returns NULL, and
144 is set to indicate the cause of the error.
149 specified a value other than
153 The size of the output buffer was insufficient.
156 .RB ( inet_net_pton ())
158 was not in correct presentation format.
164 functions are nonstandard, but widely available.
166 .SS Input presentation format for inet_net_pton()
167 The network number may be specified either
168 as a hexadecimal value
169 or in dotted-decimal notation.
171 Hexadecimal values are indicated by an initial "0x" or "0X".
172 The hexadecimal digits populate the nibbles (half octets) of the
173 network number from left to right in network byte order.
174 .\" If the hexadecimal string is short, the remaining nibbles are zeroed.
176 In dotted-decimal notation, up to four octets are specified,
177 as decimal numbers separated by dots.
178 Thus, any of the following forms are accepted:
185 Each part is a number in the range 0 to 255 that
186 populates one byte of the resulting network number,
187 going from left to right, in network-byte (big endian) order.
188 Where a part is omitted, the resulting byte in the network number is zero.
189 .\" Reading other man pages, some other implementations treat
190 .\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes
191 .\" 'b' in a.b as a 24-bit number that populates right-most three bytes
193 For either hexadecimal or dotted-decimal format,
194 the network number can optionally be followed by a slash
195 and a number in the range 0 to 32,
196 which specifies the size of the network number in bits.
197 .SS Return value of inet_net_pton()
200 is the number of bits in the network number field.
201 If the input presentation string terminates with a slash and
202 an explicit size value, then that size becomes the return value of
203 .BR inet_net_pton ().
204 Otherwise, the return value,
206 is inferred as follows:
208 If the most significant byte of the network number is
209 greater than or equal to 240,
215 if the most significant byte of the network number is
216 greater than or equal to 224,
222 if the most significant byte of the network number is
223 greater than or equal to 192,
229 if the most significant byte of the network number is
230 greater than or equal to 128,
241 value from the above steps is greater than or equal to 8,
242 but the number of octets specified in the network number exceed
246 is set to 8 times the number of octets actually specified.
248 The program below demonstrates the use of
251 .BR inet_net_ntop ().
254 to convert the presentation format network address provided in
255 its first command-line argument to binary form, displays the return value from
256 .BR inet_net_pton ().
259 to convert the binary form back to presentation format,
260 and displays the resulting string.
262 In order to demonstrate that
264 may not write to all bytes of its
266 argument, the program allows an optional second command-line argument,
267 a number used to initialize the buffer before
270 As its final line of output,
271 the program displays all of the bytes of the buffer returned by
273 allowing the user to see which bytes have not been touched by
274 .BR inet_net_pton ().
276 An example run, showing that
278 infers the number of bits in the network number:
282 $ \fB./a.out 193.168\fP
283 inet_net_pton() returned: 24
284 inet_net_ntop() yielded: 193.168.0/24
285 Raw address: c1a80000
291 does not zero out unused bytes in its result buffer:
295 $ \fB./a.out 193.168 0xffffffff\fP
296 inet_net_pton() returned: 24
297 inet_net_ntop() yielded: 193.168.0/24
298 Raw address: c1a800ff
304 will widen the inferred size of the network number,
305 if the supplied number of bytes in the presentation
306 string exceeds the inferred value:
310 $ \fB./a.out 193.168.1.128\fP
311 inet_net_pton() returned: 32
312 inet_net_ntop() yielded: 193.168.1.128/32
313 Raw address: c1a80180
317 Explicitly specifying the size of the network number overrides any
318 inference about its size
319 (but any extra bytes that are explicitly specified will still be used by
320 .BR inet_net_pton ():
321 to populate the result buffer):
325 $ \fB./a.out 193.168.1.128/24\fP
326 inet_net_pton() returned: 24
327 inet_net_ntop() yielded: 193.168.1/24
328 Raw address: c1a80180
333 /* Link with "\-lresolv" */
335 #include <arpa/inet.h>
339 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
343 main(int argc, char *argv[])
351 "Usage: %s presentation\-form [addr\-init\-value]\\n",
356 /* If argv[2] is supplied (a numeric value), use it to initialize
357 the output buffer given to inet_net_pton(), so that we can see
358 that inet_net_pton() initializes only those bytes needed for
359 the network number. If argv[2] is not supplied, then initialize
360 the buffer to zero (as is recommended practice). */
362 addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;
364 /* Convert presentation network number in argv[1] to binary */
366 bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
368 errExit("inet_net_ntop");
370 printf("inet_net_pton() returned: %d\\n", bits);
372 /* Convert binary format back to presentation, using \(aqbits\(aq
373 returned by inet_net_pton() */
375 if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
376 errExit("inet_net_ntop");
378 printf("inet_net_ntop() yielded: %s\\n", buf);
380 /* Display \(aqaddr\(aq in raw form (in network byte order), so we can
381 see bytes not displayed by inet_net_ntop(); some of those bytes
382 may not have been touched by inet_net_ntop(), and so will still
383 have any initial value that was specified in argv[2]. */
385 printf("Raw address: %x\\n", htonl(addr.s_addr));