summaryrefslogtreecommitdiffstats
path: root/man/man3/getifaddrs.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/getifaddrs.3')
-rw-r--r--man/man3/getifaddrs.3313
1 files changed, 313 insertions, 0 deletions
diff --git a/man/man3/getifaddrs.3 b/man/man3/getifaddrs.3
new file mode 100644
index 0000000..825e38c
--- /dev/null
+++ b/man/man3/getifaddrs.3
@@ -0,0 +1,313 @@
+'\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.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:
+.P
+.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
+.P
+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.
+.P
+The
+.I ifa_name
+points to the null-terminated interface name.
+.\" The constant
+.\" .B IF NAMESIZE
+.\" indicates the maximum length of this field.
+.P
+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).
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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.
+.P
+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
+.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
+.P
+.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:
+.P
+.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)