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