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