diff options
Diffstat (limited to 'man3/inet_net_pton.3')
| -rw-r--r-- | man3/inet_net_pton.3 | 369 |
1 files changed, 0 insertions, 369 deletions
diff --git a/man3/inet_net_pton.3 b/man3/inet_net_pton.3 deleted file mode 100644 index e8264e8..0000000 --- a/man3/inet_net_pton.3 +++ /dev/null @@ -1,369 +0,0 @@ -.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH inet_net_pton 3 2023-10-31 "Linux man-pages 6.7" -.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) |