Debian Codegraph @

upstream/debian-unstable/man7/netdevice.7

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