Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)