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