]>
Commit | Line | Data |
---|---|---|
6227c31d MK |
1 | '\" t |
2 | .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> | |
3 | .\" | |
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. | |
8 | .\" | |
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. | |
13 | .\" | |
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 | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
9ba01802 | 26 | .TH INET_NET_PTON 3 2019-03-06 "Linux" "Linux Programmer's Manual" |
6227c31d MK |
27 | .SH NAME |
28 | inet_net_pton, inet_net_ntop \- Internet network number conversion | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <arpa/inet.h> | |
dbfe9c70 | 32 | .PP |
6227c31d MK |
33 | .BI "int inet_net_pton(int " af ", const char *" pres , |
34 | .BI " void *" netp ", size_t " nsize ); | |
35 | ||
36 | .BI "char *inet_net_ntop(int " af ", const void *" netp ", int " bits , | |
37 | .BI " char *" pres ", size_t " psize ); | |
38 | .fi | |
68e4db0a | 39 | .PP |
2548b252 | 40 | Link with \fI\-lresolv\fP. |
68e4db0a | 41 | .PP |
6227c31d MK |
42 | .in -4n |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
68e4db0a | 46 | .PP |
6227c31d MK |
47 | .BR inet_net_pton (), |
48 | .BR inet_net_ntop (): | |
49 | .ad l | |
50 | .RS 4 | |
51 | .PD 0 | |
52 | .TP 4 | |
53 | Since glibc 2.20: | |
54 | _DEFAULT_SOURCE | |
55 | .TP 4 | |
56 | Before glibc 2.20: | |
57 | _BSD_SOURCE || _SVID_SOURCE | |
58 | .PD | |
59 | .RE | |
60 | .ad b | |
61 | .SH DESCRIPTION | |
62 | These functions convert network numbers between | |
63 | presentation (i.e., printable) format and network (i.e., binary) format. | |
847e0d88 | 64 | .PP |
6227c31d MK |
65 | For both functions, |
66 | .I af | |
67 | specifies the address family for the conversion; | |
68 | the only supported value is | |
69 | .BR AF_INET . | |
70 | .SS inet_net_pton() | |
71 | The | |
72 | .BR inet_net_pton () | |
73 | function converts | |
74 | .IR pres , | |
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 | |
79 | .IR net . | |
80 | (The | |
81 | .I netp | |
82 | argument typically points to an | |
83 | .I in_addr | |
84 | structure.) | |
85 | The | |
86 | .I nsize | |
87 | argument specifies the number of bytes available in | |
88 | .IR netp . | |
847e0d88 | 89 | .PP |
6227c31d MK |
90 | On success, |
91 | .BR inet_net_pton () | |
92 | returns the number of bits in the network number field | |
93 | of the result placed in | |
94 | .IR netp . | |
95 | For a discussion of the input presentation format and the return value, | |
96 | see NOTES. | |
847e0d88 | 97 | .PP |
6227c31d MK |
98 | .IR Note : |
99 | the buffer pointed to by | |
100 | .I netp | |
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 | |
105 | .IR pres ), | |
106 | which may be less than the number of bytes in a complete network address. | |
107 | .SS inet_net_ntop() | |
108 | The | |
109 | .BR inet_net_ntop () | |
110 | function converts the network number in the buffer pointed to by | |
111 | .IR netp | |
112 | to presentation format; | |
113 | .I *netp | |
114 | is interpreted as a value in network byte order. | |
115 | The | |
116 | .I bits | |
117 | argument specifies the number of bits in the network number in | |
118 | .IR *netp . | |
847e0d88 | 119 | .PP |
6227c31d MK |
120 | The null-terminated presentation-format string |
121 | is placed in the buffer pointed to by | |
122 | .IR pres . | |
123 | The | |
124 | .I psize | |
125 | argument specifies the number of bytes available in | |
126 | .IR pres . | |
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. | |
130 | .SH RETURN VALUE | |
131 | On success, | |
132 | .BR inet_net_pton () | |
133 | returns the number of bits in the network number. | |
134 | On error, it returns \-1, and | |
135 | .I errno | |
136 | is set to indicate the cause of the error. | |
847e0d88 | 137 | .PP |
6227c31d MK |
138 | On success, |
139 | .BR inet_net_ntop () | |
140 | returns | |
141 | .IR pres . | |
142 | On error, it returns NULL, and | |
143 | .I errno | |
144 | is set to indicate the cause of the error. | |
145 | .SH ERRORS | |
146 | .TP | |
147 | .B EAFNOSUPPORT | |
148 | .I af | |
149 | specified a value other than | |
150 | .BR AF_INET . | |
151 | .TP | |
152 | .B EMSGSIZE | |
153 | The size of the output buffer was insufficient. | |
154 | .TP | |
155 | .B ENOENT | |
156 | .RB ( inet_net_pton ()) | |
157 | .IR pres | |
158 | was not in correct presentation format. | |
159 | .SH CONFORMING TO | |
160 | The | |
161 | .BR inet_net_pton () | |
162 | and | |
163 | .BR inet_net_ntop () | |
164 | functions are nonstandard, but widely available. | |
165 | .SH NOTES | |
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. | |
847e0d88 | 170 | .PP |
6227c31d MK |
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. | |
847e0d88 | 175 | .PP |
6227c31d MK |
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: | |
847e0d88 | 179 | .PP |
6227c31d MK |
180 | a.b.c.d |
181 | a.b.c | |
182 | a.b | |
183 | a | |
847e0d88 | 184 | .PP |
6227c31d MK |
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 | |
847e0d88 | 192 | .PP |
6227c31d MK |
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() | |
198 | The return value of | |
199 | .BR 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, | |
205 | .IR bits , | |
206 | is inferred as follows: | |
207 | .IP * 3 | |
208 | If the most significant byte of the network number is | |
209 | greater than or equal to 240, | |
210 | then | |
211 | .I bits | |
212 | is 32. | |
213 | .IP * 3 | |
214 | Otherwise, | |
215 | if the most significant byte of the network number is | |
216 | greater than or equal to 224, | |
217 | then | |
218 | .I bits | |
219 | is 4. | |
220 | .IP * 3 | |
221 | Otherwise, | |
222 | if the most significant byte of the network number is | |
223 | greater than or equal to 192, | |
224 | then | |
225 | .I bits | |
226 | is 24. | |
227 | .IP * 3 | |
228 | Otherwise, | |
229 | if the most significant byte of the network number is | |
230 | greater than or equal to 128, | |
231 | then | |
232 | .I bits | |
233 | is 16. | |
234 | .IP * | |
235 | Otherwise, | |
236 | .I bits | |
237 | is 8. | |
238 | .PP | |
239 | If the resulting | |
240 | .I bits | |
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 | |
243 | .IR "bits/8" , | |
244 | then | |
245 | .I bits | |
246 | is set to 8 times the number of octets actually specified. | |
247 | .SH EXAMPLE | |
248 | The program below demonstrates the use of | |
249 | .BR inet_net_pton () | |
250 | and | |
251 | .BR inet_net_ntop (). | |
252 | It uses | |
253 | .BR inet_net_pton () | |
254 | to convert the presentation format network address provided in | |
b660ce1a | 255 | its first command-line argument to binary form, displays the return value from |
6227c31d | 256 | .BR inet_net_pton (). |
fe8b1358 | 257 | It then uses |
6227c31d MK |
258 | .BR inet_net_ntop () |
259 | to convert the binary form back to presentation format, | |
260 | and displays the resulting string. | |
847e0d88 | 261 | .PP |
6227c31d MK |
262 | In order to demonstrate that |
263 | .BR inet_net_pton () | |
264 | may not write to all bytes of its | |
265 | .I netp | |
266 | argument, the program allows an optional second command-line argument, | |
267 | a number used to initialize the buffer before | |
268 | .BR inet_net_pton () | |
269 | is called. | |
270 | As its final line of output, | |
271 | the program displays all of the bytes of the buffer returned by | |
272 | .BR inet_net_pton () | |
273 | allowing the user to see which bytes have not been touched by | |
fe8b1358 | 274 | .BR inet_net_pton (). |
847e0d88 | 275 | .PP |
6227c31d MK |
276 | An example run, showing that |
277 | .BR inet_net_pton () | |
278 | infers the number of bits in the network number: | |
847e0d88 | 279 | .PP |
6227c31d | 280 | .in +4n |
b8302363 | 281 | .EX |
6227c31d MK |
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 | |
b8302363 | 286 | .EE |
6227c31d | 287 | .in |
847e0d88 | 288 | .PP |
6227c31d MK |
289 | Demonstrate that |
290 | .BR inet_net_pton () | |
291 | does not zero out unused bytes in its result buffer: | |
847e0d88 | 292 | .PP |
6227c31d | 293 | .in +4n |
b8302363 | 294 | .EX |
6227c31d MK |
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 | |
b8302363 | 299 | .EE |
6227c31d | 300 | .in |
847e0d88 | 301 | .PP |
6227c31d MK |
302 | Demonstrate that |
303 | .BR inet_net_pton () | |
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: | |
847e0d88 | 307 | .PP |
6227c31d | 308 | .in +4n |
b8302363 | 309 | .EX |
6227c31d MK |
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 | |
b8302363 | 314 | .EE |
6227c31d | 315 | .in |
847e0d88 | 316 | .PP |
6227c31d MK |
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): | |
847e0d88 | 322 | .PP |
6227c31d | 323 | .in +4n |
b8302363 | 324 | .EX |
6227c31d MK |
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 | |
b8302363 | 329 | .EE |
6227c31d MK |
330 | .in |
331 | .SS Program source | |
e7d0bb47 | 332 | .EX |
2548b252 | 333 | /* Link with "\-lresolv" */ |
6227c31d MK |
334 | |
335 | #include <arpa/inet.h> | |
336 | #include <stdio.h> | |
337 | #include <stdlib.h> | |
338 | ||
d1a71985 | 339 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e |
6227c31d MK |
340 | } while (0) |
341 | ||
342 | int | |
343 | main(int argc, char *argv[]) | |
344 | { | |
345 | char buf[100]; | |
346 | struct in_addr addr; | |
347 | int bits; | |
348 | ||
349 | if (argc < 2) { | |
fe8b1358 | 350 | fprintf(stderr, |
d1a71985 | 351 | "Usage: %s presentation\-form [addr\-init\-value]\en", |
6227c31d MK |
352 | argv[0]); |
353 | exit(EXIT_FAILURE); | |
354 | } | |
355 | ||
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). */ | |
361 | ||
362 | addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0; | |
363 | ||
364 | /* Convert presentation network number in argv[1] to binary */ | |
365 | ||
366 | bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr)); | |
367 | if (bits == \-1) | |
368 | errExit("inet_net_ntop"); | |
369 | ||
d1a71985 | 370 | printf("inet_net_pton() returned: %d\en", bits); |
6227c31d MK |
371 | |
372 | /* Convert binary format back to presentation, using \(aqbits\(aq | |
373 | returned by inet_net_pton() */ | |
374 | ||
375 | if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL) | |
376 | errExit("inet_net_ntop"); | |
377 | ||
d1a71985 | 378 | printf("inet_net_ntop() yielded: %s\en", buf); |
6227c31d MK |
379 | |
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]. */ | |
384 | ||
d1a71985 | 385 | printf("Raw address: %x\en", htonl(addr.s_addr)); |
6227c31d MK |
386 | |
387 | exit(EXIT_SUCCESS); | |
388 | } | |
e7d0bb47 | 389 | .EE |
6227c31d MK |
390 | .SH SEE ALSO |
391 | .BR inet (3), | |
392 | .BR networks (5) |