1INET_NET_PTON(3)           Linux Programmer's Manual          INET_NET_PTON(3)
2
3
4

NAME

6       inet_net_pton, inet_net_ntop - Internet network number conversion
7

SYNOPSIS

9       #include <arpa/inet.h>
10
11       int inet_net_pton(int af, const char *pres,
12                         void *netp, size_t nsize);
13
14       char *inet_net_ntop(int af, const void *netp, int bits,
15                           char *pres, size_t psize);
16
17       Link with -lresolv.
18
19   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20
21       inet_net_pton(), inet_net_ntop():
22           Since glibc 2.20:
23               _DEFAULT_SOURCE
24           Before glibc 2.20:
25               _BSD_SOURCE || _SVID_SOURCE
26

DESCRIPTION

28       These  functions  convert  network  numbers between presentation (i.e.,
29       printable) format and network (i.e., binary) format.
30
31       For both functions, af specifies the address family for the conversion;
32       the only supported value is AF_INET.
33
34   inet_net_pton()
35       The  inet_net_pton()  function  converts pres, a null-terminated string
36       containing an Internet network number in presentation format to network
37       format.   The result of the conversion, which is in network byte order,
38       is placed in the buffer pointed to by net.  (The  netp  argument  typi‐
39       cally  points  to  an in_addr structure.)  The nsize argument specifies
40       the number of bytes available in netp.
41
42       On success, inet_net_pton() returns the number of bits in  the  network
43       number  field  of  the  result placed in netp.  For a discussion of the
44       input presentation format and the return value, see NOTES.
45
46       Note: the buffer pointed to by netp should be zeroed out before calling
47       inet_net_pton(),  since  the  call  writes  only  as  many bytes as are
48       required for the network number (or  as  are  explicitly  specified  by
49       pres), which may be less than the number of bytes in a complete network
50       address.
51
52   inet_net_ntop()
53       The inet_net_ntop() function converts the network number in the  buffer
54       pointed  to  by  netp to presentation format; *netp is interpreted as a
55       value in network byte order.  The bits argument specifies the number of
56       bits in the network number in *netp.
57
58       The  null-terminated presentation-format string is placed in the buffer
59       pointed to by pres.  The psize argument specifies the number  of  bytes
60       available  in  pres.  The presentation string is in CIDR format: a dot‐
61       ted-decimal number representing the  network  address,  followed  by  a
62       slash, and the size of the network number in bits.
63

RETURN VALUE

65       On  success,  inet_net_pton() returns the number of bits in the network
66       number.  On error, it returns -1, and errno  is  set  to  indicate  the
67       cause of the error.
68
69       On  success,  inet_net_ntop() returns pres.  On error, it returns NULL,
70       and errno is set to indicate the cause of the error.
71

ERRORS

73       EAFNOSUPPORT
74              af specified a value other than AF_INET.
75
76       EMSGSIZE
77              The size of the output buffer was insufficient.
78
79       ENOENT (inet_net_pton()) pres was not in correct presentation format.
80

CONFORMING TO

82       The inet_net_pton() and inet_net_ntop() functions are nonstandard,  but
83       widely available.
84

NOTES

86   Input presentation format for inet_net_pton()
87       The network number may be specified either as a hexadecimal value or in
88       dotted-decimal notation.
89
90       Hexadecimal values are indicated by an initial "0x" or "0X".  The hexa‐
91       decimal digits populate the nibbles (half octets) of the network number
92       from left to right in network byte order.
93
94       In dotted-decimal notation, up to four octets are specified, as decimal
95       numbers  separated  by  dots.   Thus,  any  of  the following forms are
96       accepted:
97
98           a.b.c.d
99           a.b.c
100           a.b
101           a
102
103       Each part is a number in the range 0 to 255 that populates one byte  of
104       the resulting network number, going from left to right, in network-byte
105       (big endian) order.  Where a part is omitted, the resulting byte in the
106       network number is zero.
107
108       For either hexadecimal or dotted-decimal format, the network number can
109       optionally be followed by a slash and a number in the range  0  to  32,
110       which specifies the size of the network number in bits.
111
112   Return value of inet_net_pton()
113       The  return  value of inet_net_pton() is the number of bits in the net‐
114       work number field.  If the input presentation string terminates with  a
115       slash  and  an  explicit  size value, then that size becomes the return
116       value of  inet_net_pton().   Otherwise,  the  return  value,  bits,  is
117       inferred as follows:
118
119       *  If  the  most significant byte of the network number is greater than
120          or equal to 240, then bits is 32.
121
122       *  Otherwise, if the most significant byte of  the  network  number  is
123          greater than or equal to 224, then bits is 4.
124
125       *  Otherwise,  if  the  most  significant byte of the network number is
126          greater than or equal to 192, then bits is 24.
127
128       *  Otherwise, if the most significant byte of  the  network  number  is
129          greater than or equal to 128, then bits is 16.
130
131       *  Otherwise, bits is 8.
132
133       If  the  resulting  bits  value from the above steps is greater than or
134       equal to 8, but the number of octets specified in  the  network  number
135       exceed  bits/8,  then bits is set to 8 times the number of octets actu‐
136       ally specified.
137

EXAMPLES

139       The  program  below  demonstrates  the  use  of   inet_net_pton()   and
140       inet_net_ntop().   It  uses inet_net_pton() to convert the presentation
141       format network address provided in its first command-line  argument  to
142       binary  form,  displays the return value from inet_net_pton().  It then
143       uses inet_net_ntop() to convert the binary form  back  to  presentation
144       format, and displays the resulting string.
145
146       In order to demonstrate that inet_net_pton() may not write to all bytes
147       of its netp argument, the program allows an  optional  second  command-
148       line   argument,   a  number  used  to  initialize  the  buffer  before
149       inet_net_pton() is called.  As its final line of  output,  the  program
150       displays  all  of  the  bytes of the buffer returned by inet_net_pton()
151       allowing the  user  to  see  which  bytes  have  not  been  touched  by
152       inet_net_pton().
153
154       An  example run, showing that inet_net_pton() infers the number of bits
155       in the network number:
156
157           $ ./a.out 193.168
158           inet_net_pton() returned: 24
159           inet_net_ntop() yielded:  193.168.0/24
160           Raw address:              c1a80000
161
162       Demonstrate that inet_net_pton() does not zero out unused bytes in  its
163       result buffer:
164
165           $ ./a.out 193.168 0xffffffff
166           inet_net_pton() returned: 24
167           inet_net_ntop() yielded:  193.168.0/24
168           Raw address:              c1a800ff
169
170       Demonstrate  that  inet_net_pton()  will widen the inferred size of the
171       network number, if the supplied number of  bytes  in  the  presentation
172       string exceeds the inferred value:
173
174           $ ./a.out 193.168.1.128
175           inet_net_pton() returned: 32
176           inet_net_ntop() yielded:  193.168.1.128/32
177           Raw address:              c1a80180
178
179       Explicitly  specifying  the  size  of  the network number overrides any
180       inference about its size (but any extra bytes that are explicitly spec‐
181       ified  will  still  be  used by inet_net_pton(): to populate the result
182       buffer):
183
184           $ ./a.out 193.168.1.128/24
185           inet_net_pton() returned: 24
186           inet_net_ntop() yielded:  193.168.1/24
187           Raw address:              c1a80180
188
189   Program source
190       /* Link with "-lresolv" */
191
192       #include <arpa/inet.h>
193       #include <stdio.h>
194       #include <stdlib.h>
195
196       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
197                               } while (0)
198
199       int
200       main(int argc, char *argv[])
201       {
202           char buf[100];
203           struct in_addr addr;
204           int bits;
205
206           if (argc < 2) {
207               fprintf(stderr,
208                       "Usage: %s presentation-form [addr-init-value]\n",
209                       argv[0]);
210               exit(EXIT_FAILURE);
211           }
212
213           /* If argv[2] is supplied (a numeric value), use it to initialize
214              the output buffer given to inet_net_pton(), so that we can see
215              that inet_net_pton() initializes only those bytes needed for
216              the network number. If argv[2] is not supplied, then initialize
217              the buffer to zero (as is recommended practice). */
218
219           addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;
220
221           /* Convert presentation network number in argv[1] to binary */
222
223           bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
224           if (bits == -1)
225               errExit("inet_net_ntop");
226
227           printf("inet_net_pton() returned: %d\n", bits);
228
229           /* Convert binary format back to presentation, using 'bits'
230              returned by inet_net_pton() */
231
232           if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
233               errExit("inet_net_ntop");
234
235           printf("inet_net_ntop() yielded:  %s\n", buf);
236
237           /* Display 'addr' in raw form (in network byte order), so we can
238              see bytes not displayed by inet_net_ntop(); some of those bytes
239              may not have been touched by inet_net_ntop(), and so will still
240              have any initial value that was specified in argv[2]. */
241
242           printf("Raw address:              %x\n", htonl(addr.s_addr));
243
244           exit(EXIT_SUCCESS);
245       }
246

SEE ALSO

248       inet(3), networks(5)
249

COLOPHON

251       This page is part of release 5.07 of the Linux  man-pages  project.   A
252       description  of  the project, information about reporting bugs, and the
253       latest    version    of    this    page,    can     be     found     at
254       https://www.kernel.org/doc/man-pages/.
255
256
257
258Linux                             2020-06-09                  INET_NET_PTON(3)
Impressum