]>
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 | .\" | |
bbeb81bd | 36 | .TH GETIFADDRS 3 2012-11-11 "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> | |
43 | .sp | |
44 | .BI "int getifaddrs(struct ifaddrs **" "ifap" ); | |
45 | .sp | |
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: | |
58 | .sp | |
59 | .in +4n | |
60 | .nf | |
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 | }; | |
77 | .fi | |
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.) |
d6eac69b | 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. | |
d6eac69b | 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, | |
166 | the implementation only supported IPv4 addresses; | |
167 | IPv6 support was added in glibc 2.3.3. | |
d664f7ce PB |
168 | Support of address families other than IPv4 is only available |
169 | on kernels that support netlink. | |
413b9757 PB |
170 | .SH CONFORMING TO |
171 | Not in POSIX.1-2001. | |
172 | This function first appeared in BSDi and is | |
173 | present on the BSD systems, but with slightly different | |
174 | semantics documented\(emreturning one entry per interface, | |
175 | not per address. | |
176 | This means | |
177 | .I ifa_addr | |
178 | and other fields can actually be NULL if the interface has no address, | |
179 | and no link-level address is returned if the interface has an IP address | |
180 | assigned. | |
181 | Also, the way of choosing either | |
182 | .I ifa_broadaddr | |
183 | or | |
184 | .I ifa_dstaddr | |
185 | differs on various systems. | |
186 | .\" , but the BSD-derived documentation generally | |
187 | .\" appears to be confused and obsolete on this point. | |
188 | .\" i.e., commonly it still says one of them will be NULL, even if | |
189 | .\" the ifa_ifu union is already present | |
190 | .SH NOTES | |
191 | The addresses returned on Linux will usually be the IPv4 and IPv6 addresses | |
192 | assigned to the interface, but also one | |
193 | .B AF_PACKET | |
194 | address per interface containing lower-level details about the interface | |
195 | and its physical layer. | |
196 | In this case, the | |
197 | .I ifa_data | |
198 | field may contain a pointer to a | |
bbeb81bd MK |
199 | .IR "struct rtnl_link_stats" , |
200 | defined in | |
201 | .IR <linux/if_link.h> | |
202 | (in Linux 2.4 and earlier, | |
413b9757 PB |
203 | .IR "struct net_device_stats" , |
204 | defined in | |
bbeb81bd | 205 | .IR <linux/netdevice.h> ), |
413b9757 PB |
206 | which contains various interface attributes and statistics. |
207 | .SH EXAMPLE | |
208 | The program below demonstrates the use of | |
209 | .BR getifaddrs (), | |
210 | .BR freeifaddrs (), | |
211 | and | |
d664f7ce | 212 | .BR getnameinfo (3). |
413b9757 PB |
213 | Here is what we see when running this program on one system: |
214 | .in +4n | |
215 | .nf | |
216 | ||
217 | $ \fB./a.out\fP | |
218 | lo address family: 17 (AF_PACKET) | |
219 | eth0 address family: 17 (AF_PACKET) | |
220 | lo address family: 2 (AF_INET) | |
221 | address: <127.0.0.1> | |
222 | eth0 address family: 2 (AF_INET) | |
223 | address: <10.1.1.4> | |
224 | lo address family: 10 (AF_INET6) | |
225 | address: <::1> | |
226 | eth0 address family: 10 (AF_INET6) | |
227 | address: <fe80::2d0:59ff:feda:eb51%eth0> | |
228 | .fi | |
229 | .in | |
230 | .SS Program source | |
231 | \& | |
232 | .nf | |
233 | #include <arpa/inet.h> | |
234 | #include <sys/socket.h> | |
235 | #include <netdb.h> | |
236 | #include <ifaddrs.h> | |
237 | #include <stdio.h> | |
238 | #include <stdlib.h> | |
239 | #include <unistd.h> | |
240 | ||
241 | int | |
242 | main(int argc, char *argv[]) | |
243 | { | |
54457ec1 | 244 | struct ifaddrs *ifaddr, *ifa; |
413b9757 PB |
245 | int family, s; |
246 | char host[NI_MAXHOST]; | |
247 | ||
248 | if (getifaddrs(&ifaddr) == \-1) { | |
249 | perror("getifaddrs"); | |
250 | exit(EXIT_FAILURE); | |
251 | } | |
252 | ||
54457ec1 LM |
253 | /* Walk through linked list, maintaining head pointer so we |
254 | can free list later */ | |
255 | ||
906472fd | 256 | for (ifa = ifaddr; ifa != NULL; ifa = ifa\->ifa_next) { |
ebd05fec TJ |
257 | if (ifa\->ifa_addr == NULL) |
258 | continue; | |
259 | ||
54457ec1 | 260 | family = ifa\->ifa_addr\->sa_family; |
413b9757 PB |
261 | |
262 | /* Display interface name and family (including symbolic | |
263 | form of the latter for the common families) */ | |
264 | ||
d664f7ce | 265 | printf("%s\t address family: %d%s\\n", |
54457ec1 | 266 | ifa\->ifa_name, family, |
413b9757 PB |
267 | (family == AF_PACKET) ? " (AF_PACKET)" : |
268 | (family == AF_INET) ? " (AF_INET)" : | |
269 | (family == AF_INET6) ? " (AF_INET6)" : ""); | |
270 | ||
271 | /* For an AF_INET* interface address, display the address */ | |
272 | ||
273 | if (family == AF_INET || family == AF_INET6) { | |
54457ec1 | 274 | s = getnameinfo(ifa\->ifa_addr, |
413b9757 PB |
275 | (family == AF_INET) ? sizeof(struct sockaddr_in) : |
276 | sizeof(struct sockaddr_in6), | |
277 | host, NI_MAXHOST, NULL, 0, NI_NUMERICHOST); | |
278 | if (s != 0) { | |
279 | printf("getnameinfo() failed: %s\\n", gai_strerror(s)); | |
280 | exit(EXIT_FAILURE); | |
281 | } | |
282 | printf("\\taddress: <%s>\\n", host); | |
283 | } | |
413b9757 PB |
284 | } |
285 | ||
286 | freeifaddrs(ifaddr); | |
287 | exit(EXIT_SUCCESS); | |
288 | } | |
289 | .fi | |
290 | .SH SEE ALSO | |
291 | .BR bind (2), | |
292 | .BR getsockname (2), | |
293 | .BR socket (2), | |
294 | .BR packet (7), | |
295 | .BR ifconfig (8) |