1GETIFADDRS(3) Linux Programmer's Manual GETIFADDRS(3)
2
6 getifaddrs, freeifaddrs - get interface addresses
7
9 #include <sys/types.h>
10 #include <ifaddrs.h>
11 int getifaddrs(struct ifaddrs **ifap);
13 void freeifaddrs(struct ifaddrs *ifa);
15
17 The getifaddrs() function creates a linked list of structures describ‐
18 ing the network interfaces of the local system, and stores the address
19 of the first item of the list in *ifap. The list consists of ifaddrs
20 structures, defined as follows:
21 struct ifaddrs {
23 struct ifaddrs *ifa_next; /* Next item in list */
24 char *ifa_name; /* Name of interface */
25 unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */
26 struct sockaddr *ifa_addr; /* Address of interface */
27 struct sockaddr *ifa_netmask; /* Netmask of interface */
28 union {
29 struct sockaddr *ifu_broadaddr;
30 /* Broadcast address of interface */
31 struct sockaddr *ifu_dstaddr;
32 /* Point-to-point destination address */
33 } ifa_ifu;
34 #define ifa_broadaddr ifa_ifu.ifu_broadaddr
35 #define ifa_dstaddr ifa_ifu.ifu_dstaddr
36 void *ifa_data; /* Address-specific data */
37 };
38 The ifa_next field contains a pointer to the next structure on the
40 list, or NULL if this is the last item of the list.
41 The ifa_name points to the null-terminated interface name.
43 The ifa_flags field contains the interface flags, as returned by the
45 SIOCGIFFLAGS ioctl(2) operation (see netdevice(7) for a list of these
46 flags).
47 The ifa_addr field points to a structure containing the interface
49 address. (The sa_family sub-field should be consulted to determine the
50 format of the address structure.)
51 The ifa_netmask field points to a structure containing the netmask
53 associated with ifa_addr, if applicable for the address family.
54 Depending on whether the bit IFF_BROADCAST or IFF_POINTOPOINT is set in
56 ifa_flags (only one can be set at a time), either ifa_broadaddr will
57 contain the broadcast address associated with ifa_addr (if applicable
58 for the address family) or ifa_dstaddr will contain the destination
59 address of the point-to-point interface.
60 The ifa_data field points to a buffer containing address-family-spe‐
62 cific data; this field may be NULL if there is no such data for this
63 interface.
64 The data returned by getifaddrs() is dynamically allocated and should
66 be freed using freeifaddrs() when no longer needed.
67
69 On success, getifaddrs() returns zero; on error, -1 is returned, and
70 errno is set appropriately.
71
73 getifaddrs() may fail and set errno for any of the errors specified for
74 socket(2), bind(2), getsockname(2), recvmsg(2), sendto(2), malloc(3),
75 or realloc(3).
76
78 The getifaddrs() function first appeared in glibc 2.3, but before glibc
79 2.3.3, the implementation only supported IPv4 addresses; IPv6 support
80 was added in glibc 2.3.3. Support of address families other than IPv4
81 is only available on kernels that support netlink.
82
84 Not in POSIX.1-2001. This function first appeared in BSDi and is
85 present on the BSD systems, but with slightly different semantics docu‐
86 mented—returning one entry per interface, not per address. This means
87 ifa_addr and other fields can actually be NULL if the interface has no
88 address, and no link-level address is returned if the interface has an
89 IP address assigned. Also, the way of choosing either ifa_broadaddr or
90 ifa_dstaddr differs on various systems.
91
93 The addresses returned on Linux will usually be the IPv4 and IPv6
94 addresses assigned to the interface, but also one AF_PACKET address per
95 interface containing lower-level details about the interface and its
96 physical layer. In this case, the ifa_data field may contain a pointer
97 to a struct net_device_stats, defined in <linux/netdevice.h>, which
98 contains various interface attributes and statistics.
99
101 The program below demonstrates the use of getifaddrs(), freeifaddrs(),
102 and getnameinfo(3). Here is what we see when running this program on
103 one system:
104 $ ./a.out
106 lo address family: 17 (AF_PACKET)
107 eth0 address family: 17 (AF_PACKET)
108 lo address family: 2 (AF_INET)
109 address: <127.0.0.1>
110 eth0 address family: 2 (AF_INET)
111 address: <10.1.1.4>
112 lo address family: 10 (AF_INET6)
113 address: <::1>
114 eth0 address family: 10 (AF_INET6)
115 address: <fe80::2d0:59ff:feda:eb51%eth0>
116 Program source
118 #include <arpa/inet.h>
120 #include <sys/socket.h>
121 #include <netdb.h>
122 #include <ifaddrs.h>
123 #include <stdio.h>
124 #include <stdlib.h>
125 #include <unistd.h>
126 int
128 main(int argc, char *argv[])
129 {
130 struct ifaddrs *ifaddr, *ifa;
131 int family, s;
132 char host[NI_MAXHOST];
133 if (getifaddrs(&ifaddr) == -1) {
135 perror("getifaddrs");
136 exit(EXIT_FAILURE);
137 }
138 /* Walk through linked list, maintaining head pointer so we
140 can free list later */
141 for (ifa = ifaddr; ifa != NULL; ifa = ifa->ifa_next) {
143 if (ifa->ifa_addr == NULL)
144 continue;
145 family = ifa->ifa_addr->sa_family;
147 /* Display interface name and family (including symbolic
149 form of the latter for the common families) */
150 printf("%s address family: %d%s\n",
152 ifa->ifa_name, family,
153 (family == AF_PACKET) ? " (AF_PACKET)" :
154 (family == AF_INET) ? " (AF_INET)" :
155 (family == AF_INET6) ? " (AF_INET6)" : "");
156 /* For an AF_INET* interface address, display the address */
158 if (family == AF_INET || family == AF_INET6) {
160 s = getnameinfo(ifa->ifa_addr,
161 (family == AF_INET) ? sizeof(struct sockaddr_in) :
162 sizeof(struct sockaddr_in6),
163 host, NI_MAXHOST, NULL, 0, NI_NUMERICHOST);
164 if (s != 0) {
165 printf("getnameinfo() failed: %s\n", gai_strerror(s));
166 exit(EXIT_FAILURE);
167 }
168 printf("\taddress: <%s>\n", host);
169 }
170 }
171 freeifaddrs(ifaddr);
173 exit(EXIT_SUCCESS);
174 }
175
177 bind(2), getsockname(2), socket(2), packet(7), ifconfig(8)
178
180 This page is part of release 3.22 of the Linux man-pages project. A
181 description of the project, and information about reporting bugs, can
182 be found at http://www.kernel.org/doc/man-pages/.
183GNU 2009-01-23 GETIFADDRS(3)