diff options
Diffstat (limited to 'man/man3/getifaddrs.3')
| -rw-r--r-- | man/man3/getifaddrs.3 | 313 |
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) |