]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | '\" t |
fea681da | 2 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
2297bf0e | 3 | .\" |
00acdba1 | 4 | .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
fea681da MK |
5 | .\" Permission is granted to distribute possibly modified copies |
6 | .\" of this page provided the header is included verbatim, | |
7 | .\" and in case of nontrivial modification author and date | |
8 | .\" of the modification is added to the header. | |
8ff7380d | 9 | .\" %%%LICENSE_END |
6a717e5e | 10 | .\" |
fea681da | 11 | .\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $ |
bab7e1c7 MK |
12 | .\" |
13 | .\" Modified, 2004-11-25, mtk, formatting and a few wording fixes | |
14 | .\" | |
c643e947 BB |
15 | .\" Modified, 2011-11-02, <bidulock@openss7.org>, added many basic |
16 | .\" but missing ioctls, such as SIOCGIFADDR. | |
17 | .\" | |
4b8c67d9 | 18 | .TH NETDEVICE 7 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 19 | .SH NAME |
a437cdbc | 20 | netdevice \- low-level access to Linux network devices |
fea681da MK |
21 | .SH SYNOPSIS |
22 | .B "#include <sys/ioctl.h>" | |
23 | .br | |
24 | .B "#include <net/if.h>" | |
25 | .SH DESCRIPTION | |
26 | This man page describes the sockets interface which is used to configure | |
27 | network devices. | |
5711c04f | 28 | .PP |
c13182ef MK |
29 | Linux supports some standard ioctls to configure network devices. |
30 | They can be used on any socket's file descriptor regardless of the | |
31 | family or type. | |
5bdd4260 | 32 | Most of them pass an |
f19a0f03 | 33 | .I ifreq |
fea681da | 34 | structure: |
5711c04f | 35 | .PP |
bd191423 | 36 | .in +4n |
6545cc56 | 37 | .EX |
fea681da | 38 | struct ifreq { |
bab7e1c7 MK |
39 | char ifr_name[IFNAMSIZ]; /* Interface name */ |
40 | union { | |
41 | struct sockaddr ifr_addr; | |
42 | struct sockaddr ifr_dstaddr; | |
43 | struct sockaddr ifr_broadaddr; | |
44 | struct sockaddr ifr_netmask; | |
45 | struct sockaddr ifr_hwaddr; | |
46 | short ifr_flags; | |
47 | int ifr_ifindex; | |
48 | int ifr_metric; | |
49 | int ifr_mtu; | |
50 | struct ifmap ifr_map; | |
51 | char ifr_slave[IFNAMSIZ]; | |
52 | char ifr_newname[IFNAMSIZ]; | |
23adf525 | 53 | char *ifr_data; |
bab7e1c7 | 54 | }; |
fea681da | 55 | }; |
6545cc56 | 56 | .EE |
bd191423 | 57 | .in |
5711c04f | 58 | .PP |
fea681da | 59 | Normally, the user specifies which device to affect by setting |
f19a0f03 | 60 | .I ifr_name |
c13182ef MK |
61 | to the name of the interface. |
62 | All other members of the structure may | |
63 | share memory. | |
2b2581ee | 64 | .SS Ioctls |
f577d7ef | 65 | If an ioctl is marked as privileged, then using it requires an effective |
357cf3fe | 66 | user ID of 0 or the |
fea681da | 67 | .B CAP_NET_ADMIN |
c13182ef | 68 | capability. |
02b69bc6 | 69 | If this is not the case, |
fea681da MK |
70 | .B EPERM |
71 | will be returned. | |
fea681da MK |
72 | .TP |
73 | .B SIOCGIFNAME | |
74 | Given the | |
f19a0f03 | 75 | .IR ifr_ifindex , |
fea681da | 76 | return the name of the interface in |
f19a0f03 | 77 | .IR ifr_name . |
fea681da | 78 | This is the only ioctl which returns its result in |
f19a0f03 | 79 | .IR ifr_name . |
fea681da MK |
80 | .TP |
81 | .B SIOCGIFINDEX | |
82 | Retrieve the interface index of the interface into | |
f19a0f03 | 83 | .IR ifr_ifindex . |
fea681da MK |
84 | .TP |
85 | .BR SIOCGIFFLAGS ", " SIOCSIFFLAGS | |
86 | Get or set the active flag word of the device. | |
f19a0f03 | 87 | .I ifr_flags |
10f5f294 | 88 | contains a bit mask of the following values: |
718588eb BIG |
89 | .\" Do not right adjust text blocks in tables |
90 | .na | |
fea681da MK |
91 | .TS |
92 | tab(:); | |
93 | c s | |
94 | l l. | |
95 | Device flags | |
96 | IFF_UP:Interface is running. | |
97 | IFF_BROADCAST:Valid broadcast address set. | |
98 | IFF_DEBUG:Internal debugging flag. | |
99 | IFF_LOOPBACK:Interface is a loopback interface. | |
100 | IFF_POINTOPOINT:Interface is a point-to-point link. | |
101 | IFF_RUNNING:Resources allocated. | |
718588eb BIG |
102 | IFF_NOARP:T{ |
103 | No arp protocol, L2 destination address not set. | |
104 | T} | |
fea681da MK |
105 | IFF_PROMISC:Interface is in promiscuous mode. |
106 | IFF_NOTRAILERS:Avoid use of trailers. | |
107 | IFF_ALLMULTI:Receive all multicast packets. | |
108 | IFF_MASTER:Master of a load balancing bundle. | |
109 | IFF_SLAVE:Slave of a load balancing bundle. | |
110 | IFF_MULTICAST:Supports multicast | |
111 | IFF_PORTSEL:Is able to select media type via ifmap. | |
112 | IFF_AUTOMEDIA:Auto media selection active. | |
113 | IFF_DYNAMIC:T{ | |
114 | The addresses are lost when the interface goes down. | |
115 | T} | |
6ecda4d1 MK |
116 | IFF_LOWER_UP:Driver signals L1 up (since Linux 2.6.17) |
117 | IFF_DORMANT:Driver signals dormant (since Linux 2.6.17) | |
118 | IFF_ECHO:Echo sent packets (since Linux 2.6.25) | |
c13182ef | 119 | .TE |
718588eb | 120 | .ad |
c7885256 | 121 | .PP |
fea681da MK |
122 | Setting the active flag word is a privileged operation, but any |
123 | process may read it. | |
124 | .TP | |
c643e947 BB |
125 | .BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS |
126 | Get or set extended (private) flags for the device. | |
127 | .I ifr_flags | |
128 | contains a bit mask of the following values: | |
129 | .TS | |
130 | tab(:); | |
131 | c s | |
132 | l l. | |
133 | Private flags | |
134 | IFF_802_1Q_VLAN:Interface is 802.1Q VLAN device. | |
135 | IFF_EBRIDGE:Interface is Ethernet bridging device. | |
136 | IFF_SLAVE_INACTIVE:Interface is inactive bonding slave. | |
137 | IFF_MASTER_8023AD:Interface is 802.3ad bonding master. | |
138 | IFF_MASTER_ALB:Interface is balanced-alb bonding master. | |
139 | IFF_BONDING:Interface is a bonding master or slave. | |
140 | IFF_SLAVE_NEEDARP:Interface needs ARPs for validation. | |
141 | IFF_ISATAP:Interface is RFC4214 ISATAP interface. | |
142 | .TE | |
51f5698d | 143 | .PP |
c643e947 BB |
144 | Setting the extended (private) interface flags is a privileged operation. |
145 | .TP | |
146 | .BR SIOCGIFADDR ", " SIOCSIFADDR | |
147 | Get or set the address of the device using | |
148 | .IR ifr_addr . | |
149 | Setting the interface address is a privileged operation. | |
150 | For compatibility, only | |
151 | .B AF_INET | |
152 | addresses are accepted or returned. | |
153 | .TP | |
154 | .BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR | |
155 | Get or set the destination address of a point-to-point device using | |
156 | .IR ifr_dstaddr . | |
157 | For compatibility, only | |
158 | .B AF_INET | |
159 | addresses are accepted or returned. | |
160 | Setting the destination address is a privileged operation. | |
161 | .TP | |
162 | .BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR | |
163 | Get or set the broadcast address for a device using | |
164 | .IR ifr_brdaddr . | |
165 | For compatibility, only | |
166 | .B AF_INET | |
167 | addresses are accepted or returned. | |
168 | Setting the broadcast address is a privileged operation. | |
169 | .TP | |
170 | .BR SIOCGIFNETMASK ", " SIOCSIFNETMASK | |
171 | Get or set the network mask for a device using | |
172 | .IR ifr_netmask . | |
173 | For compatibility, only | |
174 | .B AF_INET | |
175 | addresses are accepted or returned. | |
176 | Setting the network mask is a privileged operation. | |
177 | .TP | |
fea681da MK |
178 | .BR SIOCGIFMETRIC ", " SIOCSIFMETRIC |
179 | Get or set the metric of the device using | |
f19a0f03 | 180 | .IR ifr_metric . |
fea681da | 181 | This is currently not implemented; it sets |
f19a0f03 | 182 | .I ifr_metric |
fea681da MK |
183 | to 0 if you attempt to read it and returns |
184 | .B EOPNOTSUPP | |
185 | if you attempt to set it. | |
186 | .TP | |
187 | .BR SIOCGIFMTU ", " SIOCSIFMTU | |
188 | Get or set the MTU (Maximum Transfer Unit) of a device using | |
f19a0f03 | 189 | .IR ifr_mtu . |
c13182ef MK |
190 | Setting the MTU is a privileged operation. |
191 | Setting the MTU to | |
fea681da MK |
192 | too small values may cause kernel crashes. |
193 | .TP | |
194 | .BR SIOCGIFHWADDR ", " SIOCSIFHWADDR | |
195 | Get or set the hardware address of a device using | |
f19a0f03 | 196 | .IR ifr_hwaddr . |
fea681da MK |
197 | The hardware address is specified in a struct |
198 | .IR sockaddr . | |
c13182ef MK |
199 | .I sa_family |
200 | contains the ARPHRD_* device type, | |
fea681da | 201 | .I sa_data |
c13182ef | 202 | the L2 hardware address starting from byte 0. |
fea681da MK |
203 | Setting the hardware address is a privileged operation. |
204 | .TP | |
205 | .B SIOCSIFHWBROADCAST | |
206 | Set the hardware broadcast address of a device from | |
f19a0f03 | 207 | .IR ifr_hwaddr . |
fea681da MK |
208 | This is a privileged operation. |
209 | .TP | |
210 | .BR SIOCGIFMAP ", " SIOCSIFMAP | |
211 | Get or set the interface's hardware parameters using | |
f19a0f03 | 212 | .IR ifr_map . |
fea681da | 213 | Setting the parameters is a privileged operation. |
5711c04f | 214 | .IP |
7466c69b | 215 | .in +4n |
b8302363 | 216 | .EX |
56185b42 | 217 | struct ifmap { |
bab7e1c7 MK |
218 | unsigned long mem_start; |
219 | unsigned long mem_end; | |
c13182ef MK |
220 | unsigned short base_addr; |
221 | unsigned char irq; | |
222 | unsigned char dma; | |
223 | unsigned char port; | |
fea681da | 224 | }; |
b8302363 | 225 | .EE |
7466c69b | 226 | .in |
5711c04f | 227 | .IP |
fea681da MK |
228 | The interpretation of the ifmap structure depends on the device driver |
229 | and the architecture. | |
230 | .TP | |
231 | .BR SIOCADDMULTI ", " SIOCDELMULTI | |
232 | Add an address to or delete an address from the device's link layer | |
233 | multicast filters using | |
f19a0f03 | 234 | .IR ifr_hwaddr . |
fea681da MK |
235 | These are privileged operations. |
236 | See also | |
237 | .BR packet (7) | |
238 | for an alternative. | |
239 | .TP | |
240 | .BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN | |
241 | Get or set the transmit queue length of a device using | |
f19a0f03 | 242 | .IR ifr_qlen . |
fea681da MK |
243 | Setting the transmit queue length is a privileged operation. |
244 | .TP | |
245 | .B SIOCSIFNAME | |
c13182ef | 246 | Changes the name of the interface specified in |
0daa9e92 | 247 | .I ifr_name |
fea681da | 248 | to |
f19a0f03 | 249 | .IR ifr_newname . |
c13182ef | 250 | This is a privileged operation. |
33a0ccb2 | 251 | It is allowed only when the interface |
fea681da MK |
252 | is not up. |
253 | .TP | |
254 | .B SIOCGIFCONF | |
c13182ef MK |
255 | Return a list of interface (transport layer) addresses. |
256 | This currently | |
097585ed MK |
257 | means only addresses of the |
258 | .B AF_INET | |
259 | (IPv4) family for compatibility. | |
5bdd4260 | 260 | Unlike the others, this ioctl passes an |
f19a0f03 | 261 | .I ifconf |
5bdd4260 | 262 | structure: |
5711c04f | 263 | .IP |
5bdd4260 | 264 | .in +4n |
b8302363 | 265 | .EX |
5bdd4260 TS |
266 | struct ifconf { |
267 | int ifc_len; /* size of buffer */ | |
268 | union { | |
269 | char *ifc_buf; /* buffer address */ | |
270 | struct ifreq *ifc_req; /* array of structures */ | |
271 | }; | |
272 | }; | |
b8302363 | 273 | .EE |
5bdd4260 | 274 | .in |
5711c04f | 275 | .IP |
5bdd4260 | 276 | If |
f19a0f03 | 277 | .I ifc_req |
5bdd4260 TS |
278 | is NULL, |
279 | .B SIOCGIFCONF | |
280 | returns the necessary buffer size in bytes | |
281 | for receiving all available addresses in | |
f19a0f03 | 282 | .IR ifc_len . |
2b9b829d | 283 | Otherwise, |
5bdd4260 TS |
284 | .I ifc_req |
285 | contains a pointer to an array of | |
286 | .I ifreq | |
287 | structures to be filled with all currently active L3 interface addresses. | |
288 | .I ifc_len | |
289 | contains the size of the array in bytes. | |
290 | Within each | |
291 | .I ifreq | |
292 | structure, | |
c13182ef | 293 | .I ifr_name |
5bdd4260 | 294 | will receive the interface name, and |
fea681da MK |
295 | .I ifr_addr |
296 | the address. | |
5bdd4260 | 297 | The actual number of bytes transferred is returned in |
fea681da | 298 | .IR ifc_len . |
5711c04f | 299 | .IP |
5bdd4260 TS |
300 | If the size specified by |
301 | .I ifc_len | |
302 | is insufficient to store all the addresses, | |
303 | the kernel will skip the exceeding ones and return success. | |
304 | There is no reliable way of detecting this condition once it has occurred. | |
305 | It is therefore recommended to either determine the necessary buffer size | |
306 | beforehand by calling | |
307 | .B SIOCGIFCONF | |
308 | with | |
309 | .I ifc_req | |
310 | set to NULL, or to retry the call with a bigger buffer whenever | |
fea681da | 311 | .I ifc_len |
bc10fe20 DP |
312 | upon return differs by less than |
313 | .I sizeof(struct ifreq) | |
5bdd4260 | 314 | from its original value. |
5711c04f | 315 | .IP |
5bdd4260 TS |
316 | If an error occurs accessing the |
317 | .I ifconf | |
318 | or | |
319 | .I ifreq | |
320 | structures, | |
321 | .B EFAULT | |
322 | will be returned. | |
0e1ad98c | 323 | .\" Slaving isn't supported in 2.2 |
bbbc07bc | 324 | .\" . |
fea681da MK |
325 | .\" .TP |
326 | .\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE | |
327 | .\" Get or set the slave device using | |
f19a0f03 | 328 | .\" .IR ifr_slave . |
fea681da MK |
329 | .\" Setting the slave device is a privileged operation. |
330 | .\" .PP | |
bea08fec | 331 | .\" FIXME . add amateur radio stuff. |
fea681da | 332 | .PP |
e2badfdf | 333 | Most protocols support their own ioctls to configure protocol-specific |
c13182ef MK |
334 | interface options. |
335 | See the protocol man pages for a description. | |
f577d7ef | 336 | For configuring IP addresses, see |
fea681da MK |
337 | .BR ip (7). |
338 | .PP | |
f577d7ef | 339 | In addition, some devices support private ioctls. |
56185b42 | 340 | These are not described here. |
fea681da | 341 | .SH NOTES |
bab7e1c7 | 342 | Strictly speaking, |
c13182ef | 343 | .B SIOCGIFCONF |
33a0ccb2 | 344 | and the other ioctls that accept or return only |
c643e947 BB |
345 | .B AF_INET |
346 | socket addresses, | |
76c637e1 | 347 | are IP-specific and belong in |
fea681da | 348 | .BR ip (7). |
dd3568a1 | 349 | .PP |
fea681da | 350 | The names of interfaces with no addresses or that don't have the |
c13182ef | 351 | .B IFF_RUNNING |
fea681da MK |
352 | flag set can be found via |
353 | .IR /proc/net/dev . | |
dd3568a1 | 354 | .PP |
8c014896 MK |
355 | Local IPv6 IP addresses can be found via |
356 | .I /proc/net | |
357 | or via | |
fea681da MK |
358 | .BR rtnetlink (7). |
359 | .SH BUGS | |
c13182ef MK |
360 | glibc 2.1 is missing the |
361 | .I ifr_newname | |
a9a13a50 MK |
362 | macro in |
363 | .IR <net/if.h> . | |
c13182ef | 364 | Add the following to your program as a workaround: |
51f5698d | 365 | .PP |
a6e2f128 | 366 | .in +4n |
6545cc56 | 367 | .EX |
fea681da MK |
368 | #ifndef ifr_newname |
369 | #define ifr_newname ifr_ifru.ifru_slave | |
370 | #endif | |
6545cc56 | 371 | .EE |
a6e2f128 | 372 | .in |
47297adb | 373 | .SH SEE ALSO |
4d0fb1e4 | 374 | .BR proc (5), |
fea681da MK |
375 | .BR capabilities (7), |
376 | .BR ip (7), | |
fea681da | 377 | .BR rtnetlink (7) |