diff options
Diffstat (limited to 'man/man3/inet_net_pton.3')
| -rw-r--r-- | man/man3/inet_net_pton.3 | 369 |
1 files changed, 369 insertions, 0 deletions
diff --git a/man/man3/inet_net_pton.3 b/man/man3/inet_net_pton.3 new file mode 100644 index 0000000..09bff61 --- /dev/null +++ b/man/man3/inet_net_pton.3 @@ -0,0 +1,369 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH inet_net_pton 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_net_pton, inet_net_ntop \- Internet network number conversion +.SH LIBRARY +Resolver library +.RI ( libresolv ", " \-lresolv ) +.SH SYNOPSIS +.nf +.B #include <arpa/inet.h> +.P +.BI "int inet_net_pton(int " af ", const char *" pres , +.BI " void " netp [. nsize "], size_t " nsize ); +.BI "char *inet_net_ntop(int " af , +.BI " const void " netp [(. bits " - CHAR_BIT + 1) / CHAR_BIT]," +.BI " int " bits , +.BI " char " pres [. psize "], size_t " psize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR inet_net_pton (), +.BR inet_net_ntop (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE + Before glibc 2.20: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions convert network numbers between +presentation (i.e., printable) format and network (i.e., binary) format. +.P +For both functions, +.I af +specifies the address family for the conversion; +the only supported value is +.BR AF_INET . +.SS inet_net_pton() +The +.BR inet_net_pton () +function converts +.IR pres , +a null-terminated string containing an Internet network number in +presentation format to network format. +The result of the conversion, which is in network byte order, +is placed in the buffer pointed to by +.IR netp . +(The +.I netp +argument typically points to an +.I in_addr +structure.) +The +.I nsize +argument specifies the number of bytes available in +.IR netp . +.P +On success, +.BR inet_net_pton () +returns the number of bits in the network number field +of the result placed in +.IR netp . +For a discussion of the input presentation format and the return value, +see NOTES. +.P +.IR Note : +the buffer pointed to by +.I netp +should be zeroed out before calling +.BR inet_net_pton (), +since the call writes only as many bytes as are required +for the network number (or as are explicitly specified by +.IR pres ), +which may be less than the number of bytes in a complete network address. +.SS inet_net_ntop() +The +.BR inet_net_ntop () +function converts the network number in the buffer pointed to by +.I netp +to presentation format; +.I *netp +is interpreted as a value in network byte order. +The +.I bits +argument specifies the number of bits in the network number in +.IR *netp . +.P +The null-terminated presentation-format string +is placed in the buffer pointed to by +.IR pres . +The +.I psize +argument specifies the number of bytes available in +.IR pres . +The presentation string is in CIDR format: +a dotted-decimal number representing the network address, +followed by a slash, and the size of the network number in bits. +.SH RETURN VALUE +On success, +.BR inet_net_pton () +returns the number of bits in the network number. +On error, it returns \-1, and +.I errno +is set to indicate the error. +.P +On success, +.BR inet_net_ntop () +returns +.IR pres . +On error, it returns NULL, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAFNOSUPPORT +.I af +specified a value other than +.BR AF_INET . +.TP +.B EMSGSIZE +The size of the output buffer was insufficient. +.TP +.B ENOENT +.RB ( inet_net_pton ()) +.I pres +was not in correct presentation format. +.SH STANDARDS +None. +.SH NOTES +.SS Input presentation format for inet_net_pton() +The network number may be specified either +as a hexadecimal value +or in dotted-decimal notation. +.P +Hexadecimal values are indicated by an initial "0x" or "0X". +The hexadecimal digits populate the nibbles (half octets) of the +network number from left to right in network byte order. +.\" If the hexadecimal string is short, the remaining nibbles are zeroed. +.P +In dotted-decimal notation, up to four octets are specified, +as decimal numbers separated by dots. +Thus, any of the following forms are accepted: +.P +.in +4n +.EX +a.b.c.d +a.b.c +a.b +a +.EE +.in +.P +Each part is a number in the range 0 to 255 that +populates one byte of the resulting network number, +going from left to right, in network-byte (big endian) order. +Where a part is omitted, the resulting byte in the network number is zero. +.\" Reading other man pages, some other implementations treat +.\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes +.\" 'b' in a.b as a 24-bit number that populates right-most three bytes +.P +For either hexadecimal or dotted-decimal format, +the network number can optionally be followed by a slash +and a number in the range 0 to 32, +which specifies the size of the network number in bits. +.SS Return value of inet_net_pton() +The return value of +.BR inet_net_pton () +is the number of bits in the network number field. +If the input presentation string terminates with a slash and +an explicit size value, then that size becomes the return value of +.BR inet_net_pton (). +Otherwise, the return value, +.IR bits , +is inferred as follows: +.IP \[bu] 3 +If the most significant byte of the network number is +greater than or equal to 240, +then +.I bits +is 32. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 224, +then +.I bits +is 4. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 192, +then +.I bits +is 24. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 128, +then +.I bits +is 16. +.IP \[bu] +Otherwise, +.I bits +is 8. +.P +If the resulting +.I bits +value from the above steps is greater than or equal to 8, +but the number of octets specified in the network number exceed +.IR "bits/8" , +then +.I bits +is set to 8 times the number of octets actually specified. +.SH EXAMPLES +The program below demonstrates the use of +.BR inet_net_pton () +and +.BR inet_net_ntop (). +It uses +.BR inet_net_pton () +to convert the presentation format network address provided in +its first command-line argument to binary form, displays the return value from +.BR inet_net_pton (). +It then uses +.BR inet_net_ntop () +to convert the binary form back to presentation format, +and displays the resulting string. +.P +In order to demonstrate that +.BR inet_net_pton () +may not write to all bytes of its +.I netp +argument, the program allows an optional second command-line argument, +a number used to initialize the buffer before +.BR inet_net_pton () +is called. +As its final line of output, +the program displays all of the bytes of the buffer returned by +.BR inet_net_pton () +allowing the user to see which bytes have not been touched by +.BR inet_net_pton (). +.P +An example run, showing that +.BR inet_net_pton () +infers the number of bits in the network number: +.P +.in +4n +.EX +$ \fB./a.out 193.168\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a80000 +.EE +.in +.P +Demonstrate that +.BR inet_net_pton () +does not zero out unused bytes in its result buffer: +.P +.in +4n +.EX +$ \fB./a.out 193.168 0xffffffff\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a800ff +.EE +.in +.P +Demonstrate that +.BR inet_net_pton () +will widen the inferred size of the network number, +if the supplied number of bytes in the presentation +string exceeds the inferred value: +.P +.in +4n +.EX +$ \fB./a.out 193.168.1.128\fP +inet_net_pton() returned: 32 +inet_net_ntop() yielded: 193.168.1.128/32 +Raw address: c1a80180 +.EE +.in +.P +Explicitly specifying the size of the network number overrides any +inference about its size +(but any extra bytes that are explicitly specified will still be used by +.BR inet_net_pton (): +to populate the result buffer): +.P +.in +4n +.EX +$ \fB./a.out 193.168.1.128/24\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.1/24 +Raw address: c1a80180 +.EE +.in +.SS Program source +.\" SRC BEGIN (inet_net_pton.c) +.EX +/* Link with "\-lresolv" */ +\& +#include <arpa/inet.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + char buf[100]; + struct in_addr addr; + int bits; +\& + if (argc < 2) { + fprintf(stderr, + "Usage: %s presentation\-form [addr\-init\-value]\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + /* If argv[2] is supplied (a numeric value), use it to initialize + the output buffer given to inet_net_pton(), so that we can see + that inet_net_pton() initializes only those bytes needed for + the network number. If argv[2] is not supplied, then initialize + the buffer to zero (as is recommended practice). */ +\& + addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0; +\& + /* Convert presentation network number in argv[1] to binary. */ +\& + bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr)); + if (bits == \-1) + errExit("inet_net_ntop"); +\& + printf("inet_net_pton() returned: %d\en", bits); +\& + /* Convert binary format back to presentation, using \[aq]bits\[aq] + returned by inet_net_pton(). */ +\& + if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL) + errExit("inet_net_ntop"); +\& + printf("inet_net_ntop() yielded: %s\en", buf); +\& + /* Display \[aq]addr\[aq] in raw form (in network byte order), so we can + see bytes not displayed by inet_net_ntop(); some of those bytes + may not have been touched by inet_net_ntop(), and so will still + have any initial value that was specified in argv[2]. */ +\& + printf("Raw address: %x\en", htonl(addr.s_addr)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR inet (3), +.BR networks (5) |