Debian Codegraph @

upstream/debian-unstable/man3/getifaddrs.3

raw
1 '\" t
2 .\" Copyright 2008, Petr Baudis <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getifaddrs 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getifaddrs, freeifaddrs \- get interface addresses
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/types.h>
16 .B #include <ifaddrs.h>
17 .P
18 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
19 .BI "void freeifaddrs(struct ifaddrs *" "ifa" );
20 .fi
21 .SH DESCRIPTION
22 The
23 .BR getifaddrs ()
24 function creates a linked list of structures describing
25 the network interfaces of the local system,
26 and stores the address of the first item of the list in
27 .IR *ifap .
28 The list consists of
29 .I ifaddrs
30 structures, defined as follows:
31 .P
32 .in +4n
33 .EX
34 struct ifaddrs {
35 struct ifaddrs *ifa_next; /* Next item in list */
36 char *ifa_name; /* Name of interface */
37 unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */
38 struct sockaddr *ifa_addr; /* Address of interface */
39 struct sockaddr *ifa_netmask; /* Netmask of interface */
40 union {
41 struct sockaddr *ifu_broadaddr;
42 /* Broadcast address of interface */
43 struct sockaddr *ifu_dstaddr;
44 /* Point\-to\-point destination address */
45 } ifa_ifu;
46 #define ifa_broadaddr ifa_ifu.ifu_broadaddr
47 #define ifa_dstaddr ifa_ifu.ifu_dstaddr
48 void *ifa_data; /* Address\-specific data */
49 };
50 .EE
51 .in
52 .P
53 The
54 .I ifa_next
55 field contains a pointer to the next structure on the list,
56 or NULL if this is the last item of the list.
57 .P
58 The
59 .I ifa_name
60 points to the null-terminated interface name.
61 .\" The constant
62 .\" .B IF NAMESIZE
63 .\" indicates the maximum length of this field.
64 .P
65 The
66 .I ifa_flags
67 field contains the interface flags, as returned by the
68 .B SIOCGIFFLAGS
69 .BR ioctl (2)
70 operation (see
71 .BR netdevice (7)
72 for a list of these flags).
73 .P
74 The
75 .I ifa_addr
76 field points to a structure containing the interface address.
77 (The
78 .I sa_family
79 subfield should be consulted to determine the format of the
80 address structure.)
81 This field may contain a null pointer.
82 .P
83 The
84 .I ifa_netmask
85 field points to a structure containing the netmask associated with
86 .IR ifa_addr ,
87 if applicable for the address family.
88 This field may contain a null pointer.
89 .P
90 Depending on whether the bit
91 .B IFF_BROADCAST
92 or
93 .B IFF_POINTOPOINT
94 is set in
95 .I ifa_flags
96 (only one can be set at a time),
97 either
98 .I ifa_broadaddr
99 will contain the broadcast address associated with
100 .I ifa_addr
101 (if applicable for the address family) or
102 .I ifa_dstaddr
103 will contain the destination address of the point-to-point interface.
104 .P
105 The
106 .I ifa_data
107 field points to a buffer containing address-family-specific data;
108 this field may be NULL if there is no such data for this interface.
109 .P
110 The data returned by
111 .BR getifaddrs ()
112 is dynamically allocated and should be freed using
113 .BR freeifaddrs ()
114 when no longer needed.
115 .SH RETURN VALUE
116 On success,
117 .BR getifaddrs ()
118 returns zero;
119 on error, \-1 is returned, and
120 .I errno
121 is set to indicate the error.
122 .SH ERRORS
123 .BR getifaddrs ()
124 may fail and set
125 .I errno
126 for any of the errors specified for
127 .BR socket (2),
128 .BR bind (2),
129 .BR getsockname (2),
130 .BR recvmsg (2),
131 .BR sendto (2),
132 .BR malloc (3),
133 or
134 .BR realloc (3).
135 .SH ATTRIBUTES
136 For an explanation of the terms used in this section, see
137 .BR attributes (7).
138 .TS
139 allbox;
140 lbx lb lb
141 l l l.
142 Interface Attribute Value
143 T{
144 .na
145 .nh
146 .BR getifaddrs (),
147 .BR freeifaddrs ()
148 T} Thread safety MT-Safe
149 .TE
150 .SH STANDARDS
151 None.
152 .SH HISTORY
153 This function first appeared in BSDi and is
154 present on the BSD systems, but with slightly different
155 semantics documented\[em]returning one entry per interface,
156 not per address.
157 This means
158 .I ifa_addr
159 and other fields can actually be NULL if the interface has no address,
160 and no link-level address is returned if the interface has an IP address
161 assigned.
162 Also, the way of choosing either
163 .I ifa_broadaddr
164 or
165 .I ifa_dstaddr
166 differs on various systems.
167 .\" , but the BSD-derived documentation generally
168 .\" appears to be confused and obsolete on this point.
169 .\" i.e., commonly it still says one of them will be NULL, even if
170 .\" the ifa_ifu union is already present
171 .P
172 .BR getifaddrs ()
173 first appeared in glibc 2.3, but before glibc 2.3.3,
174 the implementation supported only IPv4 addresses;
175 IPv6 support was added in glibc 2.3.3.
176 Support of address families other than IPv4 is available only
177 on kernels that support netlink.
178 .SH NOTES
179 The addresses returned on Linux will usually be the IPv4 and IPv6 addresses
180 assigned to the interface, but also one
181 .B AF_PACKET
182 address per interface containing lower-level details about the interface
183 and its physical layer.
184 In this case, the
185 .I ifa_data
186 field may contain a pointer to a
187 .IR "struct rtnl_link_stats" ,
188 defined in
189 .I <linux/if_link.h>
190 (in Linux 2.4 and earlier,
191 .IR "struct net_device_stats" ,
192 defined in
193 .IR <linux/netdevice.h> ),
194 which contains various interface attributes and statistics.
195 .SH EXAMPLES
196 The program below demonstrates the use of
197 .BR getifaddrs (),
198 .BR freeifaddrs (),
199 and
200 .BR getnameinfo (3).
201 Here is what we see when running this program on one system:
202 .P
203 .in +4n
204 .EX
205 .RB $ " ./a.out" ;
206 lo AF_PACKET (17)
207 tx_packets = 524; rx_packets = 524
208 tx_bytes = 38788; rx_bytes = 38788
209 wlp3s0 AF_PACKET (17)
210 tx_packets = 108391; rx_packets = 130245
211 tx_bytes = 30420659; rx_bytes = 94230014
212 em1 AF_PACKET (17)
213 tx_packets = 0; rx_packets = 0
214 tx_bytes = 0; rx_bytes = 0
215 lo AF_INET (2)
216 address: <127.0.0.1>
217 wlp3s0 AF_INET (2)
218 address: <192.168.235.137>
219 lo AF_INET6 (10)
220 address: <::1>
221 wlp3s0 AF_INET6 (10)
222 address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0>
223 .EE
224 .in
225 .SS Program source
226 \&
227 .EX
228 #define _GNU_SOURCE /* To get defns of NI_MAXSERV and NI_MAXHOST */
229 #include <arpa/inet.h>
230 #include <sys/socket.h>
231 #include <netdb.h>
232 #include <ifaddrs.h>
233 #include <stdio.h>
234 #include <stdlib.h>
235 #include <unistd.h>
236 #include <linux/if_link.h>
237 \&
238 int main(int argc, char *argv[])
239 {
240 struct ifaddrs *ifaddr;
241 int family, s;
242 char host[NI_MAXHOST];
243 \&
244 if (getifaddrs(&ifaddr) == \-1) {
245 perror("getifaddrs");
246 exit(EXIT_FAILURE);
247 }
248 \&
249 /* Walk through linked list, maintaining head pointer so we
250 can free list later. */
251 \&
252 for (struct ifaddrs *ifa = ifaddr; ifa != NULL;
253 ifa = ifa\->ifa_next) {
254 if (ifa\->ifa_addr == NULL)
255 continue;
256 \&
257 family = ifa\->ifa_addr\->sa_family;
258 \&
259 /* Display interface name and family (including symbolic
260 form of the latter for the common families). */
261 \&
262 printf("%\-8s %s (%d)\[rs]n",
263 ifa\->ifa_name,
264 (family == AF_PACKET) ? "AF_PACKET" :
265 (family == AF_INET) ? "AF_INET" :
266 (family == AF_INET6) ? "AF_INET6" : "???",
267 family);
268 \&
269 /* For an AF_INET* interface address, display the address. */
270 \&
271 if (family == AF_INET || family == AF_INET6) {
272 s = getnameinfo(ifa\->ifa_addr,
273 (family == AF_INET) ? sizeof(struct sockaddr_in) :
274 sizeof(struct sockaddr_in6),
275 host, NI_MAXHOST,
276 NULL, 0, NI_NUMERICHOST);
277 if (s != 0) {
278 printf("getnameinfo() failed: %s\[rs]n", gai_strerror(s));
279 exit(EXIT_FAILURE);
280 }
281 \&
282 printf("\[rs]t\[rs]taddress: <%s>\[rs]n", host);
283 \&
284 } else if (family == AF_PACKET && ifa\->ifa_data != NULL) {
285 struct rtnl_link_stats *stats = ifa\->ifa_data;
286 \&
287 printf("\[rs]t\[rs]ttx_packets = %10u; rx_packets = %10u\[rs]n"
288 "\[rs]t\[rs]ttx_bytes = %10u; rx_bytes = %10u\[rs]n",
289 stats\->tx_packets, stats\->rx_packets,
290 stats\->tx_bytes, stats\->rx_bytes);
291 }
292 }
293 \&
294 freeifaddrs(ifaddr);
295 exit(EXIT_SUCCESS);
296 }
297 .EE
298 .SH SEE ALSO
299 .BR bind (2),
300 .BR getsockname (2),
301 .BR socket (2),
302 .BR packet (7),
303 .BR ifconfig (8)