1INET_NET_PTON(3) Linux Programmer's Manual INET_NET_PTON(3)
2
6 inet_net_pton, inet_net_ntop - Internet network number conversion
7
9 #include <arpa/inet.h>
10 int inet_net_pton(int af, const char *pres,
12 void *netp, size_t nsize);
13 char *inet_net_ntop(int af, const void *netp, int bits,
14 char *pres, size_t psize);
15 Link with -lresolv.
17 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19 inet_net_pton(), inet_net_ntop():
21 Since glibc 2.20:
22 _DEFAULT_SOURCE
23 Before glibc 2.20:
24 _BSD_SOURCE || _SVID_SOURCE
25
27 These functions convert network numbers between presentation (i.e.,
28 printable) format and network (i.e., binary) format.
29 For both functions, af specifies the address family for the conversion;
31 the only supported value is AF_INET.
32 inet_net_pton()
34 The inet_net_pton() function converts pres, a null-terminated string
35 containing an Internet network number in presentation format to network
36 format. The result of the conversion, which is in network byte order,
37 is placed in the buffer pointed to by net. (The netp argument typi‐
38 cally points to an in_addr structure.) The nsize argument specifies
39 the number of bytes available in netp.
40 On success, inet_net_pton() returns the number of bits in the network
42 number field of the result placed in netp. For a discussion of the in‐
43 put presentation format and the return value, see NOTES.
44 Note: the buffer pointed to by netp should be zeroed out before calling
46 inet_net_pton(), since the call writes only as many bytes as are re‐
47 quired for the network number (or as are explicitly specified by pres),
48 which may be less than the number of bytes in a complete network ad‐
49 dress.
50 inet_net_ntop()
52 The inet_net_ntop() function converts the network number in the buffer
53 pointed to by netp to presentation format; *netp is interpreted as a
54 value in network byte order. The bits argument specifies the number of
55 bits in the network number in *netp.
56 The null-terminated presentation-format string is placed in the buffer
58 pointed to by pres. The psize argument specifies the number of bytes
59 available in pres. The presentation string is in CIDR format: a dot‐
60 ted-decimal number representing the network address, followed by a
61 slash, and the size of the network number in bits.
62
64 On success, inet_net_pton() returns the number of bits in the network
65 number. On error, it returns -1, and errno is set to indicate the er‐
66 ror.
67 On success, inet_net_ntop() returns pres. On error, it returns NULL,
69 and errno is set to indicate the error.
70
72 EAFNOSUPPORT
73 af specified a value other than AF_INET.
74 EMSGSIZE
76 The size of the output buffer was insufficient.
77 ENOENT (inet_net_pton()) pres was not in correct presentation format.
79
81 The inet_net_pton() and inet_net_ntop() functions are nonstandard, but
82 widely available.
83
85 Input presentation format for inet_net_pton()
86 The network number may be specified either as a hexadecimal value or in
87 dotted-decimal notation.
88 Hexadecimal values are indicated by an initial "0x" or "0X". The hexa‐
90 decimal digits populate the nibbles (half octets) of the network number
91 from left to right in network byte order.
92 In dotted-decimal notation, up to four octets are specified, as decimal
94 numbers separated by dots. Thus, any of the following forms are ac‐
95 cepted:
96 a.b.c.d
98 a.b.c
99 a.b
100 a
101 Each part is a number in the range 0 to 255 that populates one byte of
103 the resulting network number, going from left to right, in network-byte
104 (big endian) order. Where a part is omitted, the resulting byte in the
105 network number is zero.
106 For either hexadecimal or dotted-decimal format, the network number can
108 optionally be followed by a slash and a number in the range 0 to 32,
109 which specifies the size of the network number in bits.
110 Return value of inet_net_pton()
112 The return value of inet_net_pton() is the number of bits in the net‐
113 work number field. If the input presentation string terminates with a
114 slash and an explicit size value, then that size becomes the return
115 value of inet_net_pton(). Otherwise, the return value, bits, is in‐
116 ferred as follows:
117 * If the most significant byte of the network number is greater than
119 or equal to 240, then bits is 32.
120 * Otherwise, if the most significant byte of the network number is
122 greater than or equal to 224, then bits is 4.
123 * Otherwise, if the most significant byte of the network number is
125 greater than or equal to 192, then bits is 24.
126 * Otherwise, if the most significant byte of the network number is
128 greater than or equal to 128, then bits is 16.
129 * Otherwise, bits is 8.
131 If the resulting bits value from the above steps is greater than or
133 equal to 8, but the number of octets specified in the network number
134 exceed bits/8, then bits is set to 8 times the number of octets actu‐
135 ally specified.
136
138 The program below demonstrates the use of inet_net_pton() and
139 inet_net_ntop(). It uses inet_net_pton() to convert the presentation
140 format network address provided in its first command-line argument to
141 binary form, displays the return value from inet_net_pton(). It then
142 uses inet_net_ntop() to convert the binary form back to presentation
143 format, and displays the resulting string.
144 In order to demonstrate that inet_net_pton() may not write to all bytes
146 of its netp argument, the program allows an optional second command-
147 line argument, a number used to initialize the buffer before
148 inet_net_pton() is called. As its final line of output, the program
149 displays all of the bytes of the buffer returned by inet_net_pton() al‐
150 lowing the user to see which bytes have not been touched by
151 inet_net_pton().
152 An example run, showing that inet_net_pton() infers the number of bits
154 in the network number:
155 $ ./a.out 193.168
157 inet_net_pton() returned: 24
158 inet_net_ntop() yielded: 193.168.0/24
159 Raw address: c1a80000
160 Demonstrate that inet_net_pton() does not zero out unused bytes in its
162 result buffer:
163 $ ./a.out 193.168 0xffffffff
165 inet_net_pton() returned: 24
166 inet_net_ntop() yielded: 193.168.0/24
167 Raw address: c1a800ff
168 Demonstrate that inet_net_pton() will widen the inferred size of the
170 network number, if the supplied number of bytes in the presentation
171 string exceeds the inferred value:
172 $ ./a.out 193.168.1.128
174 inet_net_pton() returned: 32
175 inet_net_ntop() yielded: 193.168.1.128/32
176 Raw address: c1a80180
177 Explicitly specifying the size of the network number overrides any in‐
179 ference about its size (but any extra bytes that are explicitly speci‐
180 fied will still be used by inet_net_pton(): to populate the result buf‐
181 fer):
182 $ ./a.out 193.168.1.128/24
184 inet_net_pton() returned: 24
185 inet_net_ntop() yielded: 193.168.1/24
186 Raw address: c1a80180
187 Program source
189 /* Link with "-lresolv" */
190 #include <arpa/inet.h>
192 #include <stdio.h>
193 #include <stdlib.h>
194 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
196 } while (0)
197 int
199 main(int argc, char *argv[])
200 {
201 char buf[100];
202 struct in_addr addr;
203 int bits;
204 if (argc < 2) {
206 fprintf(stderr,
207 "Usage: %s presentation-form [addr-init-value]\n",
208 argv[0]);
209 exit(EXIT_FAILURE);
210 }
211 /* If argv[2] is supplied (a numeric value), use it to initialize
213 the output buffer given to inet_net_pton(), so that we can see
214 that inet_net_pton() initializes only those bytes needed for
215 the network number. If argv[2] is not supplied, then initialize
216 the buffer to zero (as is recommended practice). */
217 addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;
219 /* Convert presentation network number in argv[1] to binary. */
221 bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
223 if (bits == -1)
224 errExit("inet_net_ntop");
225 printf("inet_net_pton() returned: %d\n", bits);
227 /* Convert binary format back to presentation, using 'bits'
229 returned by inet_net_pton(). */
230 if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
232 errExit("inet_net_ntop");
233 printf("inet_net_ntop() yielded: %s\n", buf);
235 /* Display 'addr' in raw form (in network byte order), so we can
237 see bytes not displayed by inet_net_ntop(); some of those bytes
238 may not have been touched by inet_net_ntop(), and so will still
239 have any initial value that was specified in argv[2]. */
240 printf("Raw address: %x\n", htonl(addr.s_addr));
242 exit(EXIT_SUCCESS);
244 }
245
247 inet(3), networks(5)
248
250 This page is part of release 5.13 of the Linux man-pages project. A
251 description of the project, information about reporting bugs, and the
252 latest version of this page, can be found at
253 https://www.kernel.org/doc/man-pages/.
254Linux 2021-03-22 INET_NET_PTON(3)