Merging upstream version 6.8.

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

1 files changed, 336 insertions, 0 deletions

diff --git a/man/man3/inet.3 b/man/man3/inet.3
new file mode 100644
index 0000000..04cfdb7
--- /dev/null
+++ b/man/man3/inet.3
@@ -0,0 +1,336 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\"     Linux libc source code
+.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\"     386BSD man pages
+.\"     libc.info (from glibc distribution)
+.\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith <faith@cs.unc.edu>
+.\" Modified Sun Sep  3 20:29:36 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
+.\" Changed network into host byte order (for inet_network),
+.\"     Andreas Jaeger <aj@arthur.rhein-neckar.de>, 980130.
+.\" 2008-06-19, mtk
+.\"     Describe the various address forms supported by inet_aton().
+.\"     Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr().
+.\"     Add discussion of Classful Addressing, noting that it is obsolete.
+.\"     Added an EXAMPLE program.
+.\"
+.TH inet 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof,
+inet_netof \- Internet address manipulation routines
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.B #include <netinet/in.h>
+.B #include <arpa/inet.h>
+.P
+.BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
+.P
+.BI "in_addr_t inet_addr(const char *" cp );
+.BI "in_addr_t inet_network(const char *" cp );
+.P
+.BI "[[deprecated]] char *inet_ntoa(struct in_addr " in );
+.P
+.BI "[[deprecated]] struct in_addr inet_makeaddr(in_addr_t " net ,
+.BI "                                            in_addr_t " host );
+.P
+.BI "[[deprecated]] in_addr_t inet_lnaof(struct in_addr " in );
+.BI "[[deprecated]] in_addr_t inet_netof(struct in_addr " in );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR inet_aton (),
+.BR inet_ntoa ():
+.nf
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    In glibc up to and including 2.19:
+        _BSD_SOURCE || _BSD_SOURCE
+.fi
+.SH DESCRIPTION
+.BR inet_aton ()
+converts the Internet host address \fIcp\fP from the
+IPv4 numbers-and-dots notation into binary form (in network byte order)
+and stores it in the structure that \fIinp\fP points to.
+.BR inet_aton ()
+returns nonzero if the address is valid, zero if not.
+The address supplied in
+.I cp
+can have one of the following forms:
+.TP 10
+.I a.b.c.d
+Each of the four numeric parts specifies a byte of the address;
+the bytes are assigned in left-to-right order to produce the binary address.
+.TP
+.I a.b.c
+Parts
+.I a
+and
+.I b
+specify the first two bytes of the binary address.
+Part
+.I c
+is interpreted as a 16-bit value that defines the rightmost two bytes
+of the binary address.
+This notation is suitable for specifying (outmoded) Class B
+network addresses.
+.TP
+.I a.b
+Part
+.I a
+specifies the first byte of the binary address.
+Part
+.I b
+is interpreted as a 24-bit value that defines the rightmost three bytes
+of the binary address.
+This notation is suitable for specifying (outmoded) Class A
+network addresses.
+.TP
+.I a
+The value
+.I a
+is interpreted as a 32-bit value that is stored directly
+into the binary address without any byte rearrangement.
+.P
+In all of the above forms,
+components of the dotted address can be specified in decimal,
+octal (with a leading
+.IR 0 ),
+or hexadecimal, with a leading
+.IR 0X ).
+Addresses in any of these forms are collectively termed
+.IR "IPV4 numbers-and-dots notation" .
+The form that uses exactly four decimal numbers is referred to as
+.I IPv4 dotted-decimal notation
+(or sometimes:
+.IR "IPv4 dotted-quad notation" ).
+.P
+.BR inet_aton ()
+returns 1 if the supplied string was successfully interpreted,
+or 0 if the string is invalid
+.RB ( errno
+is
+.I not
+set on error).
+.P
+The
+.BR inet_addr ()
+function converts the Internet host address
+\fIcp\fP from IPv4 numbers-and-dots notation into binary data in network
+byte order.
+If the input is invalid,
+.B INADDR_NONE
+(usually \-1) is returned.
+Use of this function is problematic because \-1 is a valid address
+(255.255.255.255).
+Avoid its use in favor of
+.BR inet_aton (),
+.BR inet_pton (3),
+or
+.BR getaddrinfo (3),
+which provide a cleaner way to indicate error return.
+.P
+The
+.BR inet_network ()
+function converts
+.IR cp ,
+a string in IPv4 numbers-and-dots notation,
+into a number in host byte order suitable for use as an
+Internet network address.
+On success, the converted address is returned.
+If the input is invalid, \-1 is returned.
+.P
+The
+.BR inet_ntoa ()
+function converts the Internet host address
+\fIin\fP, given in network byte order, to a string in IPv4
+dotted-decimal notation.
+The string is returned in a statically
+allocated buffer, which subsequent calls will overwrite.
+.P
+The
+.BR inet_lnaof ()
+function returns the local network address part
+of the Internet address \fIin\fP.
+The returned value is in host byte order.
+.P
+The
+.BR inet_netof ()
+function returns the network number part of
+the Internet address \fIin\fP.
+The returned value is in host byte order.
+.P
+The
+.BR inet_makeaddr ()
+function is the converse of
+.BR inet_netof ()
+and
+.BR inet_lnaof ().
+It returns an Internet host address in network byte order,
+created by combining the network number \fInet\fP
+with the local address \fIhost\fP, both in
+host byte order.
+.P
+The structure \fIin_addr\fP as used in
+.BR inet_ntoa (),
+.BR inet_makeaddr (),
+.BR inet_lnaof (),
+and
+.BR inet_netof ()
+is defined in
+.I <netinet/in.h>
+as:
+.P
+.in +4n
+.EX
+typedef uint32_t in_addr_t;
+\&
+struct in_addr {
+    in_addr_t s_addr;
+};
+.EE
+.in
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR inet_aton (),
+.BR inet_addr (),
+.BR inet_network (),
+.BR inet_ntoa ()
+T}	Thread safety	MT-Safe locale
+T{
+.na
+.nh
+.BR inet_makeaddr (),
+.BR inet_lnaof (),
+.BR inet_netof ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+.TP
+.BR inet_addr ()
+.TQ
+.BR inet_ntoa ()
+POSIX.1-2008.
+.TP
+.BR inet_aton ()
+None.
+.SH STANDARDS
+.TP
+.BR inet_addr ()
+.TQ
+.BR inet_ntoa ()
+POSIX.1-2001, 4.3BSD.
+.P
+.BR inet_lnaof (),
+.BR inet_netof (),
+and
+.BR inet_makeaddr ()
+are legacy functions that assume they are dealing with
+.IR "classful network addresses" .
+Classful networking divides IPv4 network addresses into host and network
+components at byte boundaries, as follows:
+.TP 10
+Class A
+This address type is indicated by the value 0 in the
+most significant bit of the (network byte ordered) address.
+The network address is contained in the most significant byte,
+and the host address occupies the remaining three bytes.
+.TP
+Class B
+This address type is indicated by the binary value 10 in the
+most significant two bits of the address.
+The network address is contained in the two most significant bytes,
+and the host address occupies the remaining two bytes.
+.TP
+Class C
+This address type is indicated by the binary value 110 in the
+most significant three bits of the address.
+The network address is contained in the three most significant bytes,
+and the host address occupies the remaining byte.
+.P
+Classful network addresses are now obsolete,
+having been superseded by Classless Inter-Domain Routing (CIDR),
+which divides addresses into network and host components at
+arbitrary bit (rather than byte) boundaries.
+.SH NOTES
+On x86 architectures, the host byte order is Least Significant Byte
+first (little endian), whereas the network byte order, as used on the
+Internet, is Most Significant Byte first (big endian).
+.SH EXAMPLES
+An example of the use of
+.BR inet_aton ()
+and
+.BR inet_ntoa ()
+is shown below.
+Here are some example runs:
+.P
+.in +4n
+.EX
+.RB "$" " ./a.out 226.000.000.037" "      # Last byte is in octal"
+226.0.0.31
+.RB "$" " ./a.out 0x7f.1         " "      # First byte is in hex"
+127.0.0.1
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (inet.c)
+.EX
+#define _DEFAULT_SOURCE
+#include <arpa/inet.h>
+#include <stdio.h>
+#include <stdlib.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    struct in_addr addr;
+\&
+    if (argc != 2) {
+        fprintf(stderr, "%s <dotted\-address>\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    if (inet_aton(argv[1], &addr) == 0) {
+        fprintf(stderr, "Invalid address\en");
+        exit(EXIT_FAILURE);
+    }
+\&
+    printf("%s\en", inet_ntoa(addr));
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR byteorder (3),
+.BR getaddrinfo (3),
+.BR gethostbyname (3),
+.BR getnameinfo (3),
+.BR getnetent (3),
+.BR inet_net_pton (3),
+.BR inet_ntop (3),
+.BR inet_pton (3),
+.BR hosts (5),
+.BR networks (5)