original/man3/inet_net_pton.3

   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 .\"
  26 .TH INET_NET_PTON 3 2014-05-28 "Linux" "Linux Programmer's Manual"
  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>
  32
  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
  39 .sp
  40 Link with \fI\-lresolv\fP.
  41 .sp
  42 .in -4n
  43 Feature Test Macro Requirements for glibc (see
  44 .BR feature_test_macros (7)):
  45 .in
  46 .sp
  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.
  64
  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 .
  89
  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.
  97
  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 .
 119
 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.
 137
 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.
 170
 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.
 175
 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:
 179
 180     a.b.c.d
 181     a.b.c
 182     a.b
 183     a
 184
 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
 192
 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
 255 its first command-line argument to binary form, displays the return value from
 256 .BR inet_net_pton ().
 257 It then uses
 258 .BR inet_net_ntop ()
 259 to convert the binary form back to presentation format,
 260 and displays the resulting string.
 261
 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
 274 .BR inet_net_pton ().
 275
 276 An example run, showing that
 277 .BR inet_net_pton ()
 278 infers the number of bits in the network number:
 279
 280 .in +4n
 281 .nf
 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
 286 .fi
 287 .in
 288
 289 Demonstrate that
 290 .BR inet_net_pton ()
 291 does not zero out unused bytes in its result buffer:
 292
 293 .in +4n
 294 .nf
 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
 299 .fi
 300 .in
 301
 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:
 307
 308 .in +4n
 309 .nf
 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
 314 .fi
 315 .in
 316
 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):
 322
 323 .in +4n
 324 .nf
 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
 329 .fi
 330 .in
 331 .SS Program source
 332 .nf
 333 /* Link with "\-lresolv" */
 334
 335 #include <arpa/inet.h>
 336 #include <stdio.h>
 337 #include <stdlib.h>
 338
 339 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 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) {
 350         fprintf(stderr,
 351                 "Usage: %s presentation\-form [addr\-init\-value]\\n",
 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
 370     printf("inet_net_pton() returned: %d\\n", bits);
 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
 378     printf("inet_net_ntop() yielded:  %s\\n", buf);
 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
 385     printf("Raw address:              %x\\n", htonl(addr.s_addr));
 386
 387     exit(EXIT_SUCCESS);
 388 }
 389 .fi
 390 .SH SEE ALSO
 391 .BR inet (3),
 392 .BR networks (5)
 393 .SH COLOPHON
 394 This page is part of release 3.68 of the Linux
 395 .I man-pages
 396 project.
 397 A description of the project,
 398 information about reporting bugs,
 399 and the latest version of this page,
 400 can be found at
 401 \%http://www.kernel.org/doc/man\-pages/.