Debian Codegraph @

upstream/debian-trixie/man7/netdevice.7

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