]>
Commit | Line | Data |
---|---|---|
413b9757 PB |
1 | .\" Copyright (c) 2008 Petr Baudis <pasky@suse.cz> |
2 | .\" and copyright (c) 2009, Linux Foundation, written by Michael Kerrisk | |
3 | .\" <mtk.manpages@gmail.com> | |
4 | .\" | |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
413b9757 PB |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
14 | .\" | |
15 | .\" Since the Linux kernel and libraries are constantly changing, this | |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
22 | .\" | |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
9f9c6de1 | 26 | .\" |
413b9757 PB |
27 | .\" Redistribution and use in source and binary forms, with or without |
28 | .\" modification, are permitted provided that the following conditions | |
29 | .\" are met: | |
30 | .\" | |
31 | .\" 2008-12-08 Petr Baudis <pasky@suse.cz> | |
32 | .\" Rewrite the BSD manpage in the Linux man pages style and account | |
33 | .\" for glibc specificities, provide an example. | |
34 | .\" 2009-01-14 mtk, many edits and changes, rewrote example program. | |
35 | .\" | |
4b8c67d9 | 36 | .TH GETIFADDRS 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
413b9757 PB |
37 | .SH NAME |
38 | getifaddrs, freeifaddrs \- get interface addresses | |
39 | .SH SYNOPSIS | |
40 | .nf | |
41 | .B #include <sys/types.h> | |
42 | .B #include <ifaddrs.h> | |
68e4db0a | 43 | .PP |
413b9757 | 44 | .BI "int getifaddrs(struct ifaddrs **" "ifap" ); |
68e4db0a | 45 | .PP |
413b9757 PB |
46 | .BI "void freeifaddrs(struct ifaddrs *" "ifa" ); |
47 | .fi | |
48 | .SH DESCRIPTION | |
49 | The | |
50 | .BR getifaddrs () | |
51 | function creates a linked list of structures describing | |
52 | the network interfaces of the local system, | |
53 | and stores the address of the first item of the list in | |
54 | .IR *ifap . | |
55 | The list consists of | |
56 | .I ifaddrs | |
57 | structures, defined as follows: | |
51f5698d | 58 | .PP |
413b9757 | 59 | .in +4n |
b8302363 | 60 | .EX |
413b9757 PB |
61 | struct ifaddrs { |
62 | struct ifaddrs *ifa_next; /* Next item in list */ | |
63 | char *ifa_name; /* Name of interface */ | |
64 | unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */ | |
65 | struct sockaddr *ifa_addr; /* Address of interface */ | |
66 | struct sockaddr *ifa_netmask; /* Netmask of interface */ | |
67 | union { | |
68 | struct sockaddr *ifu_broadaddr; | |
69 | /* Broadcast address of interface */ | |
70 | struct sockaddr *ifu_dstaddr; | |
71 | /* Point-to-point destination address */ | |
72 | } ifa_ifu; | |
73 | #define ifa_broadaddr ifa_ifu.ifu_broadaddr | |
74 | #define ifa_dstaddr ifa_ifu.ifu_dstaddr | |
75 | void *ifa_data; /* Address-specific data */ | |
76 | }; | |
b8302363 | 77 | .EE |
413b9757 PB |
78 | .in |
79 | .PP | |
80 | The | |
81 | .I ifa_next | |
82 | field contains a pointer to the next structure on the list, | |
83 | or NULL if this is the last item of the list. | |
84 | .PP | |
85 | The | |
86 | .I ifa_name | |
87 | points to the null-terminated interface name. | |
88 | .\" The constant | |
89 | .\" .B IF NAMESIZE | |
90 | .\" indicates the maximum length of this field. | |
91 | .PP | |
92 | The | |
93 | .I ifa_flags | |
94 | field contains the interface flags, as returned by the | |
95 | .B SIOCGIFFLAGS | |
96 | .BR ioctl (2) | |
97 | operation (see | |
98 | .BR netdevice (7) | |
99 | for a list of these flags). | |
100 | .PP | |
101 | The | |
102 | .I ifa_addr | |
103 | field points to a structure containing the interface address. | |
104 | (The | |
105 | .I sa_family | |
310672d6 | 106 | subfield should be consulted to determine the format of the |
413b9757 | 107 | address structure.) |
b437fdd9 | 108 | This field may contain a null pointer. |
413b9757 PB |
109 | .PP |
110 | The | |
111 | .I ifa_netmask | |
112 | field points to a structure containing the netmask associated with | |
113 | .IR ifa_addr , | |
114 | if applicable for the address family. | |
b437fdd9 | 115 | This field may contain a null pointer. |
413b9757 PB |
116 | .PP |
117 | Depending on whether the bit | |
118 | .B IFF_BROADCAST | |
119 | or | |
120 | .B IFF_POINTOPOINT | |
121 | is set in | |
122 | .I ifa_flags | |
123 | (only one can be set at a time), | |
124 | either | |
125 | .I ifa_broadaddr | |
126 | will contain the broadcast address associated with | |
127 | .I ifa_addr | |
128 | (if applicable for the address family) or | |
129 | .I ifa_dstaddr | |
130 | will contain the destination address of the point-to-point interface. | |
131 | .PP | |
132 | The | |
133 | .I ifa_data | |
134 | field points to a buffer containing address-family-specific data; | |
135 | this field may be NULL if there is no such data for this interface. | |
136 | .PP | |
137 | The data returned by | |
138 | .BR getifaddrs () | |
139 | is dynamically allocated and should be freed using | |
140 | .BR freeifaddrs () | |
141 | when no longer needed. | |
0bb542ed | 142 | .SH RETURN VALUE |
413b9757 PB |
143 | On success, |
144 | .BR getifaddrs () | |
145 | returns zero; | |
c3074d70 | 146 | on error, \-1 is returned, and |
413b9757 PB |
147 | .I errno |
148 | is set appropriately. | |
149 | .SH ERRORS | |
150 | .BR getifaddrs () | |
151 | may fail and set | |
152 | .I errno | |
153 | for any of the errors specified for | |
154 | .BR socket (2), | |
155 | .BR bind (2), | |
413b9757 PB |
156 | .BR getsockname (2), |
157 | .BR recvmsg (2), | |
158 | .BR sendto (2), | |
159 | .BR malloc (3), | |
160 | or | |
161 | .BR realloc (3). | |
162 | .SH VERSIONS | |
163 | The | |
164 | .BR getifaddrs () | |
165 | function first appeared in glibc 2.3, but before glibc 2.3.3, | |
33a0ccb2 | 166 | the implementation supported only IPv4 addresses; |
413b9757 | 167 | IPv6 support was added in glibc 2.3.3. |
33a0ccb2 | 168 | Support of address families other than IPv4 is available only |
d664f7ce | 169 | on kernels that support netlink. |
bad52bdf ZL |
170 | .SH ATTRIBUTES |
171 | For an explanation of the terms used in this section, see | |
172 | .BR attributes (7). | |
173 | .TS | |
174 | allbox; | |
175 | lbw27 lb lb | |
176 | l l l. | |
177 | Interface Attribute Value | |
178 | T{ | |
179 | .BR getifaddrs (), | |
180 | .BR freeifaddrs () | |
181 | T} Thread safety MT-Safe | |
182 | .TE | |
847e0d88 | 183 | .sp 1 |
413b9757 | 184 | .SH CONFORMING TO |
dcd4a298 | 185 | Not in POSIX.1. |
413b9757 PB |
186 | This function first appeared in BSDi and is |
187 | present on the BSD systems, but with slightly different | |
188 | semantics documented\(emreturning one entry per interface, | |
189 | not per address. | |
190 | This means | |
191 | .I ifa_addr | |
192 | and other fields can actually be NULL if the interface has no address, | |
193 | and no link-level address is returned if the interface has an IP address | |
194 | assigned. | |
195 | Also, the way of choosing either | |
196 | .I ifa_broadaddr | |
197 | or | |
198 | .I ifa_dstaddr | |
199 | differs on various systems. | |
200 | .\" , but the BSD-derived documentation generally | |
201 | .\" appears to be confused and obsolete on this point. | |
202 | .\" i.e., commonly it still says one of them will be NULL, even if | |
203 | .\" the ifa_ifu union is already present | |
204 | .SH NOTES | |
205 | The addresses returned on Linux will usually be the IPv4 and IPv6 addresses | |
206 | assigned to the interface, but also one | |
207 | .B AF_PACKET | |
208 | address per interface containing lower-level details about the interface | |
209 | and its physical layer. | |
210 | In this case, the | |
211 | .I ifa_data | |
212 | field may contain a pointer to a | |
bbeb81bd MK |
213 | .IR "struct rtnl_link_stats" , |
214 | defined in | |
215 | .IR <linux/if_link.h> | |
216 | (in Linux 2.4 and earlier, | |
413b9757 PB |
217 | .IR "struct net_device_stats" , |
218 | defined in | |
bbeb81bd | 219 | .IR <linux/netdevice.h> ), |
413b9757 PB |
220 | which contains various interface attributes and statistics. |
221 | .SH EXAMPLE | |
222 | The program below demonstrates the use of | |
223 | .BR getifaddrs (), | |
224 | .BR freeifaddrs (), | |
225 | and | |
d664f7ce | 226 | .BR getnameinfo (3). |
413b9757 | 227 | Here is what we see when running this program on one system: |
e646a1ba | 228 | .PP |
413b9757 | 229 | .in +4n |
e646a1ba | 230 | .EX |
413b9757 | 231 | $ \fB./a.out\fP |
83a1c50f MK |
232 | lo AF_PACKET (17) |
233 | tx_packets = 524; rx_packets = 524 | |
234 | tx_bytes = 38788; rx_bytes = 38788 | |
235 | wlp3s0 AF_PACKET (17) | |
236 | tx_packets = 108391; rx_packets = 130245 | |
237 | tx_bytes = 30420659; rx_bytes = 94230014 | |
238 | em1 AF_PACKET (17) | |
239 | tx_packets = 0; rx_packets = 0 | |
240 | tx_bytes = 0; rx_bytes = 0 | |
241 | lo AF_INET (2) | |
242 | address: <127.0.0.1> | |
243 | wlp3s0 AF_INET (2) | |
244 | address: <192.168.235.137> | |
245 | lo AF_INET6 (10) | |
246 | address: <::1> | |
247 | wlp3s0 AF_INET6 (10) | |
248 | address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0> | |
b8302363 | 249 | .EE |
413b9757 PB |
250 | .in |
251 | .SS Program source | |
252 | \& | |
e7d0bb47 | 253 | .EX |
83a1c50f | 254 | #define _GNU_SOURCE /* To get defns of NI_MAXSERV and NI_MAXHOST */ |
413b9757 PB |
255 | #include <arpa/inet.h> |
256 | #include <sys/socket.h> | |
257 | #include <netdb.h> | |
258 | #include <ifaddrs.h> | |
259 | #include <stdio.h> | |
260 | #include <stdlib.h> | |
261 | #include <unistd.h> | |
83a1c50f | 262 | #include <linux/if_link.h> |
413b9757 | 263 | |
83a1c50f | 264 | int main(int argc, char *argv[]) |
413b9757 | 265 | { |
54457ec1 | 266 | struct ifaddrs *ifaddr, *ifa; |
83a1c50f | 267 | int family, s, n; |
413b9757 PB |
268 | char host[NI_MAXHOST]; |
269 | ||
270 | if (getifaddrs(&ifaddr) == \-1) { | |
271 | perror("getifaddrs"); | |
272 | exit(EXIT_FAILURE); | |
273 | } | |
274 | ||
54457ec1 LM |
275 | /* Walk through linked list, maintaining head pointer so we |
276 | can free list later */ | |
277 | ||
83a1c50f | 278 | for (ifa = ifaddr, n = 0; ifa != NULL; ifa = ifa\->ifa_next, n++) { |
ebd05fec TJ |
279 | if (ifa\->ifa_addr == NULL) |
280 | continue; | |
281 | ||
54457ec1 | 282 | family = ifa\->ifa_addr\->sa_family; |
413b9757 PB |
283 | |
284 | /* Display interface name and family (including symbolic | |
285 | form of the latter for the common families) */ | |
286 | ||
83a1c50f MK |
287 | printf("%\-8s %s (%d)\\n", |
288 | ifa\->ifa_name, | |
289 | (family == AF_PACKET) ? "AF_PACKET" : | |
290 | (family == AF_INET) ? "AF_INET" : | |
291 | (family == AF_INET6) ? "AF_INET6" : "???", | |
292 | family); | |
413b9757 PB |
293 | |
294 | /* For an AF_INET* interface address, display the address */ | |
295 | ||
296 | if (family == AF_INET || family == AF_INET6) { | |
54457ec1 | 297 | s = getnameinfo(ifa\->ifa_addr, |
413b9757 PB |
298 | (family == AF_INET) ? sizeof(struct sockaddr_in) : |
299 | sizeof(struct sockaddr_in6), | |
83a1c50f MK |
300 | host, NI_MAXHOST, |
301 | NULL, 0, NI_NUMERICHOST); | |
413b9757 PB |
302 | if (s != 0) { |
303 | printf("getnameinfo() failed: %s\\n", gai_strerror(s)); | |
304 | exit(EXIT_FAILURE); | |
305 | } | |
83a1c50f MK |
306 | |
307 | printf("\\t\\taddress: <%s>\\n", host); | |
308 | ||
309 | } else if (family == AF_PACKET && ifa\->ifa_data != NULL) { | |
310 | struct rtnl_link_stats *stats = ifa\->ifa_data; | |
311 | ||
312 | printf("\\t\\ttx_packets = %10u; rx_packets = %10u\\n" | |
313 | "\\t\\ttx_bytes = %10u; rx_bytes = %10u\\n", | |
314 | stats\->tx_packets, stats\->rx_packets, | |
315 | stats\->tx_bytes, stats\->rx_bytes); | |
413b9757 | 316 | } |
413b9757 PB |
317 | } |
318 | ||
319 | freeifaddrs(ifaddr); | |
320 | exit(EXIT_SUCCESS); | |
321 | } | |
e7d0bb47 | 322 | .EE |
413b9757 PB |
323 | .SH SEE ALSO |
324 | .BR bind (2), | |
325 | .BR getsockname (2), | |
326 | .BR socket (2), | |
327 | .BR packet (7), | |
328 | .BR ifconfig (8) |