| .\" Copyright (c) 2008 Petr Baudis <pasky@suse.cz> |
| .\" and copyright (c) 2009, Linux Foundation, written by Michael Kerrisk |
| .\" <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2019-03-06 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| getifaddrs, freeifaddrs \- get interface addresses |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/types.h> |
| .B #include <ifaddrs.h> |
| .PP |
| .BI "int getifaddrs(struct ifaddrs **" "ifap" ); |
| .PP |
| .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 appropriately. |
| .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 VERSIONS |
| The |
| .BR getifaddrs () |
| function 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 ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw27 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR getifaddrs (), |
| .BR freeifaddrs () |
| T} Thread safety MT-Safe |
| .TE |
| .sp 1 |
| .SH CONFORMING TO |
| Not in POSIX.1. |
| This function first appeared in BSDi and is |
| present on the BSD systems, but with slightly different |
| semantics documented\(emreturning 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 |
| .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 |
| .IR <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 EXAMPLE |
| 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, *ifa; |
| int family, s, n; |
| 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 (ifa = ifaddr, n = 0; ifa != NULL; ifa = ifa\->ifa_next, n++) { |
| 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) |