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