1getifaddrs(3)              Library Functions Manual              getifaddrs(3)
2
3
4

NAME

6       getifaddrs, freeifaddrs - get interface addresses
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/types.h>
13       #include <ifaddrs.h>
14
15       int getifaddrs(struct ifaddrs **ifap);
16       void freeifaddrs(struct ifaddrs *ifa);
17

DESCRIPTION

19       The  getifaddrs() function creates a linked list of structures describ‐
20       ing the network interfaces of the local system, and stores the  address
21       of  the  first item of the list in *ifap.  The list consists of ifaddrs
22       structures, defined as follows:
23
24           struct ifaddrs {
25               struct ifaddrs  *ifa_next;    /* Next item in list */
26               char            *ifa_name;    /* Name of interface */
27               unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
28               struct sockaddr *ifa_addr;    /* Address of interface */
29               struct sockaddr *ifa_netmask; /* Netmask of interface */
30               union {
31                   struct sockaddr *ifu_broadaddr;
32                                    /* Broadcast address of interface */
33                   struct sockaddr *ifu_dstaddr;
34                                    /* Point-to-point destination address */
35               } ifa_ifu;
36           #define              ifa_broadaddr ifa_ifu.ifu_broadaddr
37           #define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
38               void            *ifa_data;    /* Address-specific data */
39           };
40
41       The ifa_next field contains a pointer to  the  next  structure  on  the
42       list, or NULL if this is the last item of the list.
43
44       The ifa_name points to the null-terminated interface name.
45
46       The  ifa_flags  field  contains the interface flags, as returned by the
47       SIOCGIFFLAGS ioctl(2) operation (see netdevice(7) for a list  of  these
48       flags).
49
50       The  ifa_addr  field points to a structure containing the interface ad‐
51       dress.  (The sa_family subfield should be consulted  to  determine  the
52       format  of  the  address  structure.)   This  field  may contain a null
53       pointer.
54
55       The ifa_netmask field points to a structure containing the netmask  as‐
56       sociated  with  ifa_addr,  if  applicable for the address family.  This
57       field may contain a null pointer.
58
59       Depending on whether the bit IFF_BROADCAST or IFF_POINTOPOINT is set in
60       ifa_flags  (only  one  can be set at a time), either ifa_broadaddr will
61       contain the broadcast address associated with ifa_addr  (if  applicable
62       for the address family) or ifa_dstaddr will contain the destination ad‐
63       dress of the point-to-point interface.
64
65       The ifa_data field points to a  buffer  containing  address-family-spe‐
66       cific  data;  this  field may be NULL if there is no such data for this
67       interface.
68
69       The data returned by getifaddrs() is dynamically allocated  and  should
70       be freed using freeifaddrs() when no longer needed.
71

RETURN VALUE

73       On  success,  getifaddrs()  returns zero; on error, -1 is returned, and
74       errno is set to indicate the error.
75

ERRORS

77       getifaddrs() may fail and set errno for any of the errors specified for
78       socket(2),  bind(2),  getsockname(2), recvmsg(2), sendto(2), malloc(3),
79       or realloc(3).
80

ATTRIBUTES

82       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
83       tributes(7).
84
85       ┌────────────────────────────────────────────┬───────────────┬─────────┐
86Interface                                   Attribute     Value   
87       ├────────────────────────────────────────────┼───────────────┼─────────┤
88getifaddrs(), freeifaddrs()                 │ Thread safety │ MT-Safe │
89       └────────────────────────────────────────────┴───────────────┴─────────┘
90

STANDARDS

92       None.
93

HISTORY

95       This function first appeared in BSDi and is present on the BSD systems,
96       but with slightly different semantics  documented—returning  one  entry
97       per  interface,  not per address.  This means ifa_addr and other fields
98       can actually be NULL if the interface has no address, and no link-level
99       address is returned if the interface has an IP address assigned.  Also,
100       the way of choosing either ifa_broadaddr or ifa_dstaddr differs on var‐
101       ious systems.
102
103       getifaddrs()  first  appeared in glibc 2.3, but before glibc 2.3.3, the
104       implementation supported only IPv4 addresses; IPv6 support was added in
105       glibc  2.3.3.  Support of address families other than IPv4 is available
106       only on kernels that support netlink.
107

NOTES

109       The addresses returned on Linux will usually be the IPv4 and  IPv6  ad‐
110       dresses  assigned  to the interface, but also one AF_PACKET address per
111       interface containing lower-level details about the  interface  and  its
112       physical layer.  In this case, the ifa_data field may contain a pointer
113       to a struct rtnl_link_stats, defined in <linux/if_link.h> (in Linux 2.4
114       and  earlier, struct net_device_stats, defined in <linux/netdevice.h>),
115       which contains various interface attributes and statistics.
116

EXAMPLES

118       The program below demonstrates the use of getifaddrs(),  freeifaddrs(),
119       and  getnameinfo(3).   Here is what we see when running this program on
120       one system:
121
122           $ ./a.out
123           lo       AF_PACKET (17)
124                           tx_packets =        524; rx_packets =        524
125                           tx_bytes   =      38788; rx_bytes   =      38788
126           wlp3s0   AF_PACKET (17)
127                           tx_packets =     108391; rx_packets =     130245
128                           tx_bytes   =   30420659; rx_bytes   =   94230014
129           em1      AF_PACKET (17)
130                           tx_packets =          0; rx_packets =          0
131                           tx_bytes   =          0; rx_bytes   =          0
132           lo       AF_INET (2)
133                           address: <127.0.0.1>
134           wlp3s0   AF_INET (2)
135                           address: <192.168.235.137>
136           lo       AF_INET6 (10)
137                           address: <::1>
138           wlp3s0   AF_INET6 (10)
139                           address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0>
140
141   Program source
142
143       #define _GNU_SOURCE     /* To get defns of NI_MAXSERV and NI_MAXHOST */
144       #include <arpa/inet.h>
145       #include <sys/socket.h>
146       #include <netdb.h>
147       #include <ifaddrs.h>
148       #include <stdio.h>
149       #include <stdlib.h>
150       #include <unistd.h>
151       #include <linux/if_link.h>
152
153       int main(int argc, char *argv[])
154       {
155           struct ifaddrs *ifaddr;
156           int family, s;
157           char host[NI_MAXHOST];
158
159           if (getifaddrs(&ifaddr) == -1) {
160               perror("getifaddrs");
161               exit(EXIT_FAILURE);
162           }
163
164           /* Walk through linked list, maintaining head pointer so we
165              can free list later. */
166
167           for (struct ifaddrs *ifa = ifaddr; ifa != NULL;
168                    ifa = ifa->ifa_next) {
169               if (ifa->ifa_addr == NULL)
170                   continue;
171
172               family = ifa->ifa_addr->sa_family;
173
174               /* Display interface name and family (including symbolic
175                  form of the latter for the common families). */
176
177               printf("%-8s %s (%d)\n",
178                      ifa->ifa_name,
179                      (family == AF_PACKET) ? "AF_PACKET" :
180                      (family == AF_INET) ? "AF_INET" :
181                      (family == AF_INET6) ? "AF_INET6" : "???",
182                      family);
183
184               /* For an AF_INET* interface address, display the address. */
185
186               if (family == AF_INET || family == AF_INET6) {
187                   s = getnameinfo(ifa->ifa_addr,
188                           (family == AF_INET) ? sizeof(struct sockaddr_in) :
189                                                 sizeof(struct sockaddr_in6),
190                           host, NI_MAXHOST,
191                           NULL, 0, NI_NUMERICHOST);
192                   if (s != 0) {
193                       printf("getnameinfo() failed: %s\n", gai_strerror(s));
194                       exit(EXIT_FAILURE);
195                   }
196
197                   printf("\t\taddress: <%s>\n", host);
198
199               } else if (family == AF_PACKET && ifa->ifa_data != NULL) {
200                   struct rtnl_link_stats *stats = ifa->ifa_data;
201
202                   printf("\t\ttx_packets = %10u; rx_packets = %10u\n"
203                          "\t\ttx_bytes   = %10u; rx_bytes   = %10u\n",
204                          stats->tx_packets, stats->rx_packets,
205                          stats->tx_bytes, stats->rx_bytes);
206               }
207           }
208
209           freeifaddrs(ifaddr);
210           exit(EXIT_SUCCESS);
211       }
212

SEE ALSO

214       bind(2), getsockname(2), socket(2), packet(7), ifconfig(8)
215
216
217
218Linux man-pages 6.04              2023-03-30                     getifaddrs(3)
Impressum