Adding upstream version 6.05.01.upstream/6.05.01

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

1 files changed, 314 insertions, 0 deletions

diff --git a/man3/getifaddrs.3 b/man3/getifaddrs.3
new file mode 100644
index 0000000..3f82c93
--- /dev/null
+++ b/man3/getifaddrs.3
@@ -0,0 +1,314 @@
+'\" t
+.\" Copyright (c) 2008 Petr Baudis <pasky@suse.cz>
+.\" and copyright (c) 2009, Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 2008-12-08 Petr Baudis <pasky@suse.cz>
+.\"    Rewrite the BSD manpage in the Linux man pages style and account
+.\"    for glibc specificities, provide an example.
+.\" 2009-01-14 mtk, many edits and changes, rewrote example program.
+.\"
+.TH getifaddrs 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+getifaddrs, freeifaddrs \- get interface addresses
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/types.h>
+.B #include <ifaddrs.h>
+.PP
+.BI "int getifaddrs(struct ifaddrs **" "ifap" );
+.BI "void freeifaddrs(struct ifaddrs *" "ifa" );
+.fi
+.SH DESCRIPTION
+The
+.BR getifaddrs ()
+function creates a linked list of structures describing
+the network interfaces of the local system,
+and stores the address of the first item of the list in
+.IR *ifap .
+The list consists of
+.I ifaddrs
+structures, defined as follows:
+.PP
+.in +4n
+.EX
+struct ifaddrs {
+    struct ifaddrs  *ifa_next;    /* Next item in list */
+    char            *ifa_name;    /* Name of interface */
+    unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
+    struct sockaddr *ifa_addr;    /* Address of interface */
+    struct sockaddr *ifa_netmask; /* Netmask of interface */
+    union {
+        struct sockaddr *ifu_broadaddr;
+                         /* Broadcast address of interface */
+        struct sockaddr *ifu_dstaddr;
+                         /* Point\-to\-point destination address */
+    } ifa_ifu;
+#define              ifa_broadaddr ifa_ifu.ifu_broadaddr
+#define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
+    void            *ifa_data;    /* Address\-specific data */
+};
+.EE
+.in
+.PP
+The
+.I ifa_next
+field contains a pointer to the next structure on the list,
+or NULL if this is the last item of the list.
+.PP
+The
+.I ifa_name
+points to the null-terminated interface name.
+.\" The constant
+.\" .B IF NAMESIZE
+.\" indicates the maximum length of this field.
+.PP
+The
+.I ifa_flags
+field contains the interface flags, as returned by the
+.B SIOCGIFFLAGS
+.BR ioctl (2)
+operation (see
+.BR netdevice (7)
+for a list of these flags).
+.PP
+The
+.I ifa_addr
+field points to a structure containing the interface address.
+(The
+.I sa_family
+subfield should be consulted to determine the format of the
+address structure.)
+This field may contain a null pointer.
+.PP
+The
+.I ifa_netmask
+field points to a structure containing the netmask associated with
+.IR ifa_addr ,
+if applicable for the address family.
+This field may contain a null pointer.
+.PP
+Depending on whether the bit
+.B IFF_BROADCAST
+or
+.B IFF_POINTOPOINT
+is set in
+.I ifa_flags
+(only one can be set at a time),
+either
+.I ifa_broadaddr
+will contain the broadcast address associated with
+.I ifa_addr
+(if applicable for the address family) or
+.I ifa_dstaddr
+will contain the destination address of the point-to-point interface.
+.PP
+The
+.I ifa_data
+field points to a buffer containing address-family-specific data;
+this field may be NULL if there is no such data for this interface.
+.PP
+The data returned by
+.BR getifaddrs ()
+is dynamically allocated and should be freed using
+.BR freeifaddrs ()
+when no longer needed.
+.SH RETURN VALUE
+On success,
+.BR getifaddrs ()
+returns zero;
+on error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.BR getifaddrs ()
+may fail and set
+.I errno
+for any of the errors specified for
+.BR socket (2),
+.BR bind (2),
+.BR getsockname (2),
+.BR recvmsg (2),
+.BR sendto (2),
+.BR malloc (3),
+or
+.BR realloc (3).
+.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 getifaddrs (),
+.BR freeifaddrs ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+None.
+.SH HISTORY
+This function first appeared in BSDi and is
+present on the BSD systems, but with slightly different
+semantics documented\[em]returning one entry per interface,
+not per address.
+This means
+.I ifa_addr
+and other fields can actually be NULL if the interface has no address,
+and no link-level address is returned if the interface has an IP address
+assigned.
+Also, the way of choosing either
+.I ifa_broadaddr
+or
+.I ifa_dstaddr
+differs on various systems.
+.\" , but the BSD-derived documentation generally
+.\" appears to be confused and obsolete on this point.
+.\" i.e., commonly it still says one of them will be NULL, even if
+.\" the ifa_ifu union is already present
+.PP
+.BR getifaddrs ()
+first appeared in glibc 2.3, but before glibc 2.3.3,
+the implementation supported only IPv4 addresses;
+IPv6 support was added in glibc 2.3.3.
+Support of address families other than IPv4 is available only
+on kernels that support netlink.
+.SH NOTES
+The addresses returned on Linux will usually be the IPv4 and IPv6 addresses
+assigned to the interface, but also one
+.B AF_PACKET
+address per interface containing lower-level details about the interface
+and its physical layer.
+In this case, the
+.I ifa_data
+field may contain a pointer to a
+.IR "struct rtnl_link_stats" ,
+defined in
+.I <linux/if_link.h>
+(in Linux 2.4 and earlier,
+.IR "struct net_device_stats" ,
+defined in
+.IR <linux/netdevice.h> ),
+which contains various interface attributes and statistics.
+.SH EXAMPLES
+The program below demonstrates the use of
+.BR getifaddrs (),
+.BR freeifaddrs (),
+and
+.BR getnameinfo (3).
+Here is what we see when running this program on one system:
+.PP
+.in +4n
+.EX
+$ \fB./a.out\fP
+lo       AF_PACKET (17)
+                tx_packets =        524; rx_packets =        524
+                tx_bytes   =      38788; rx_bytes   =      38788
+wlp3s0   AF_PACKET (17)
+                tx_packets =     108391; rx_packets =     130245
+                tx_bytes   =   30420659; rx_bytes   =   94230014
+em1      AF_PACKET (17)
+                tx_packets =          0; rx_packets =          0
+                tx_bytes   =          0; rx_bytes   =          0
+lo       AF_INET (2)
+                address: <127.0.0.1>
+wlp3s0   AF_INET (2)
+                address: <192.168.235.137>
+lo       AF_INET6 (10)
+                address: <::1>
+wlp3s0   AF_INET6 (10)
+                address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0>
+.EE
+.in
+.SS Program source
+\&
+.EX
+#define _GNU_SOURCE     /* To get defns of NI_MAXSERV and NI_MAXHOST */
+#include <arpa/inet.h>
+#include <sys/socket.h>
+#include <netdb.h>
+#include <ifaddrs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <linux/if_link.h>
+\&
+int main(int argc, char *argv[])
+{
+    struct ifaddrs *ifaddr;
+    int family, s;
+    char host[NI_MAXHOST];
+\&
+    if (getifaddrs(&ifaddr) == \-1) {
+        perror("getifaddrs");
+        exit(EXIT_FAILURE);
+    }
+\&
+    /* Walk through linked list, maintaining head pointer so we
+       can free list later. */
+\&
+    for (struct ifaddrs *ifa = ifaddr; ifa != NULL;
+             ifa = ifa\->ifa_next) {
+        if (ifa\->ifa_addr == NULL)
+            continue;
+\&
+        family = ifa\->ifa_addr\->sa_family;
+\&
+        /* Display interface name and family (including symbolic
+           form of the latter for the common families). */
+\&
+        printf("%\-8s %s (%d)\en",
+               ifa\->ifa_name,
+               (family == AF_PACKET) ? "AF_PACKET" :
+               (family == AF_INET) ? "AF_INET" :
+               (family == AF_INET6) ? "AF_INET6" : "???",
+               family);
+\&
+        /* For an AF_INET* interface address, display the address. */
+\&
+        if (family == AF_INET || family == AF_INET6) {
+            s = getnameinfo(ifa\->ifa_addr,
+                    (family == AF_INET) ? sizeof(struct sockaddr_in) :
+                                          sizeof(struct sockaddr_in6),
+                    host, NI_MAXHOST,
+                    NULL, 0, NI_NUMERICHOST);
+            if (s != 0) {
+                printf("getnameinfo() failed: %s\en", gai_strerror(s));
+                exit(EXIT_FAILURE);
+            }
+\&
+            printf("\et\etaddress: <%s>\en", host);
+\&
+        } else if (family == AF_PACKET && ifa\->ifa_data != NULL) {
+            struct rtnl_link_stats *stats = ifa\->ifa_data;
+\&
+            printf("\et\ettx_packets = %10u; rx_packets = %10u\en"
+                   "\et\ettx_bytes   = %10u; rx_bytes   = %10u\en",
+                   stats\->tx_packets, stats\->rx_packets,
+                   stats\->tx_bytes, stats\->rx_bytes);
+        }
+    }
+\&
+    freeifaddrs(ifaddr);
+    exit(EXIT_SUCCESS);
+}
+.EE
+.SH SEE ALSO
+.BR bind (2),
+.BR getsockname (2),
+.BR socket (2),
+.BR packet (7),
+.BR ifconfig (8)