man3/inet_net_pton.3

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