]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | '\" t |
2 | .\" Don't change the first line, it tells man that tbl is needed. | |
3 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. | |
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 | .\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $ | |
bab7e1c7 MK |
9 | .\" |
10 | .\" Modified, 2004-11-25, mtk, formatting and a few wording fixes | |
11 | .\" | |
c13182ef | 12 | .TH NETDEVICE 7 1999-05-02 "Linux Man Page" "Linux Programmer's Manual" |
fea681da MK |
13 | .SH NAME |
14 | netdevice \- Low level access to Linux network devices | |
15 | .SH SYNOPSIS | |
16 | .B "#include <sys/ioctl.h>" | |
17 | .br | |
18 | .B "#include <net/if.h>" | |
19 | .SH DESCRIPTION | |
20 | This man page describes the sockets interface which is used to configure | |
21 | network devices. | |
22 | ||
c13182ef MK |
23 | Linux supports some standard ioctls to configure network devices. |
24 | They can be used on any socket's file descriptor regardless of the | |
25 | family or type. | |
26 | They pass an | |
27 | .B ifreq | |
fea681da MK |
28 | structure: |
29 | ||
30 | .nf | |
fea681da | 31 | struct ifreq { |
bab7e1c7 MK |
32 | char ifr_name[IFNAMSIZ]; /* Interface name */ |
33 | union { | |
34 | struct sockaddr ifr_addr; | |
35 | struct sockaddr ifr_dstaddr; | |
36 | struct sockaddr ifr_broadaddr; | |
37 | struct sockaddr ifr_netmask; | |
38 | struct sockaddr ifr_hwaddr; | |
39 | short ifr_flags; | |
40 | int ifr_ifindex; | |
41 | int ifr_metric; | |
42 | int ifr_mtu; | |
43 | struct ifmap ifr_map; | |
44 | char ifr_slave[IFNAMSIZ]; | |
45 | char ifr_newname[IFNAMSIZ]; | |
46 | char * ifr_data; | |
47 | }; | |
fea681da MK |
48 | }; |
49 | ||
c13182ef | 50 | struct ifconf { |
bab7e1c7 | 51 | int ifc_len; /* size of buffer */ |
c13182ef MK |
52 | union { |
53 | char * ifc_buf; /* buffer address */ | |
bab7e1c7 | 54 | struct ifreq * ifc_req; /* array of structures */ |
c13182ef MK |
55 | }; |
56 | }; | |
fea681da MK |
57 | .fi |
58 | ||
59 | Normally, the user specifies which device to affect by setting | |
60 | .B ifr_name | |
c13182ef MK |
61 | to the name of the interface. |
62 | All other members of the structure may | |
63 | share memory. | |
fea681da MK |
64 | .SH IOCTLS |
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 MK |
68 | capability. |
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 | |
75 | .BR ifr_ifindex , | |
76 | return the name of the interface in | |
77 | .BR ifr_name . | |
78 | This is the only ioctl which returns its result in | |
79 | .BR ifr_name . | |
fea681da MK |
80 | .TP |
81 | .B SIOCGIFINDEX | |
82 | Retrieve the interface index of the interface into | |
83 | .BR ifr_ifindex . | |
fea681da MK |
84 | .TP |
85 | .BR SIOCGIFFLAGS ", " SIOCSIFFLAGS | |
86 | Get or set the active flag word of the device. | |
87 | .B ifr_flags | |
88 | contains a bitmask of the following values: | |
fea681da MK |
89 | .TS |
90 | tab(:); | |
91 | c s | |
92 | l l. | |
93 | Device flags | |
94 | IFF_UP:Interface is running. | |
95 | IFF_BROADCAST:Valid broadcast address set. | |
96 | IFF_DEBUG:Internal debugging flag. | |
97 | IFF_LOOPBACK:Interface is a loopback interface. | |
98 | IFF_POINTOPOINT:Interface is a point-to-point link. | |
99 | IFF_RUNNING:Resources allocated. | |
100 | IFF_NOARP:No arp protocol, L2 destination address not set. | |
101 | IFF_PROMISC:Interface is in promiscuous mode. | |
102 | IFF_NOTRAILERS:Avoid use of trailers. | |
103 | IFF_ALLMULTI:Receive all multicast packets. | |
104 | IFF_MASTER:Master of a load balancing bundle. | |
105 | IFF_SLAVE:Slave of a load balancing bundle. | |
106 | IFF_MULTICAST:Supports multicast | |
107 | IFF_PORTSEL:Is able to select media type via ifmap. | |
108 | IFF_AUTOMEDIA:Auto media selection active. | |
109 | IFF_DYNAMIC:T{ | |
110 | The addresses are lost when the interface goes down. | |
111 | T} | |
c13182ef | 112 | .TE |
fea681da MK |
113 | Setting the active flag word is a privileged operation, but any |
114 | process may read it. | |
115 | .TP | |
116 | .BR SIOCGIFMETRIC ", " SIOCSIFMETRIC | |
117 | Get or set the metric of the device using | |
118 | .BR ifr_metric . | |
119 | This is currently not implemented; it sets | |
120 | .B ifr_metric | |
121 | to 0 if you attempt to read it and returns | |
122 | .B EOPNOTSUPP | |
123 | if you attempt to set it. | |
124 | .TP | |
125 | .BR SIOCGIFMTU ", " SIOCSIFMTU | |
126 | Get or set the MTU (Maximum Transfer Unit) of a device using | |
127 | .BR ifr_mtu . | |
c13182ef MK |
128 | Setting the MTU is a privileged operation. |
129 | Setting the MTU to | |
fea681da MK |
130 | too small values may cause kernel crashes. |
131 | .TP | |
132 | .BR SIOCGIFHWADDR ", " SIOCSIFHWADDR | |
133 | Get or set the hardware address of a device using | |
134 | .BR ifr_hwaddr . | |
135 | The hardware address is specified in a struct | |
136 | .IR sockaddr . | |
c13182ef MK |
137 | .I sa_family |
138 | contains the ARPHRD_* device type, | |
fea681da | 139 | .I sa_data |
c13182ef | 140 | the L2 hardware address starting from byte 0. |
fea681da MK |
141 | Setting the hardware address is a privileged operation. |
142 | .TP | |
143 | .B SIOCSIFHWBROADCAST | |
144 | Set the hardware broadcast address of a device from | |
145 | .BR ifr_hwaddr . | |
146 | This is a privileged operation. | |
147 | .TP | |
148 | .BR SIOCGIFMAP ", " SIOCSIFMAP | |
149 | Get or set the interface's hardware parameters using | |
150 | .BR ifr_map . | |
151 | Setting the parameters is a privileged operation. | |
152 | ||
153 | .nf | |
56185b42 | 154 | struct ifmap { |
bab7e1c7 MK |
155 | unsigned long mem_start; |
156 | unsigned long mem_end; | |
c13182ef MK |
157 | unsigned short base_addr; |
158 | unsigned char irq; | |
159 | unsigned char dma; | |
160 | unsigned char port; | |
fea681da | 161 | }; |
fea681da MK |
162 | .fi |
163 | ||
164 | The interpretation of the ifmap structure depends on the device driver | |
165 | and the architecture. | |
166 | .TP | |
167 | .BR SIOCADDMULTI ", " SIOCDELMULTI | |
168 | Add an address to or delete an address from the device's link layer | |
169 | multicast filters using | |
170 | .BR ifr_hwaddr . | |
171 | These are privileged operations. | |
172 | See also | |
173 | .BR packet (7) | |
174 | for an alternative. | |
175 | .TP | |
176 | .BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN | |
177 | Get or set the transmit queue length of a device using | |
178 | .BR ifr_qlen . | |
179 | Setting the transmit queue length is a privileged operation. | |
180 | .TP | |
181 | .B SIOCSIFNAME | |
c13182ef | 182 | Changes the name of the interface specified in |
fea681da MK |
183 | .BR ifr_name |
184 | to | |
185 | .BR ifr_newname . | |
c13182ef MK |
186 | This is a privileged operation. |
187 | It is only allowed when the interface | |
fea681da MK |
188 | is not up. |
189 | .TP | |
190 | .B SIOCGIFCONF | |
c13182ef MK |
191 | Return a list of interface (transport layer) addresses. |
192 | This currently | |
193 | means only addresses of the AF_INET (IPv4) family for compatibility. | |
194 | The user passes a | |
fea681da | 195 | .B ifconf |
c13182ef MK |
196 | structure as argument to the ioctl. |
197 | It contains a pointer to an array of | |
fea681da | 198 | .I ifreq |
c13182ef | 199 | structures in |
fea681da | 200 | .B ifc_req |
c13182ef | 201 | and its length in bytes in |
a5e0a0e4 | 202 | .BR ifc_len . |
fea681da | 203 | The kernel fills the ifreqs with all current L3 interface addresses that |
c13182ef MK |
204 | are running: |
205 | .I ifr_name | |
206 | contains the interface name (eth0:1 etc.), | |
fea681da MK |
207 | .I ifr_addr |
208 | the address. | |
c13182ef | 209 | The kernel returns with the actual length in |
fea681da | 210 | .IR ifc_len . |
c13182ef | 211 | If |
fea681da MK |
212 | .I ifc_len |
213 | is equal to the original length the buffer probably has overflowed | |
214 | and you should retry with a bigger buffer to get all addresses. | |
215 | When no error occurs the ioctl returns 0; | |
c13182ef MK |
216 | otherwise \-1. |
217 | Overflow is not an error. | |
4c44fdf1 | 218 | .\" FIXME Slaving isn't supported in 2.2 |
bbbc07bc | 219 | .\" . |
fea681da MK |
220 | .\" .TP |
221 | .\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE | |
222 | .\" Get or set the slave device using | |
223 | .\" .BR ifr_slave . | |
224 | .\" Setting the slave device is a privileged operation. | |
225 | .\" .PP | |
a749f870 | 226 | .\" FIXME add amateur radio stuff. |
fea681da | 227 | .PP |
c13182ef MK |
228 | Most protocols support their own ioctls to configure protocol specific |
229 | interface options. | |
230 | See the protocol man pages for a description. | |
231 | For configuring IP addresses see | |
fea681da MK |
232 | .BR ip (7). |
233 | .PP | |
c13182ef | 234 | In addition some devices support private ioctls. |
56185b42 | 235 | These are not described here. |
fea681da | 236 | .SH NOTES |
bab7e1c7 | 237 | Strictly speaking, |
c13182ef MK |
238 | .B SIOCGIFCONF |
239 | is IP specific and belongs in | |
fea681da MK |
240 | .BR ip (7). |
241 | .LP | |
242 | The names of interfaces with no addresses or that don't have the | |
c13182ef | 243 | .B IFF_RUNNING |
fea681da MK |
244 | flag set can be found via |
245 | .IR /proc/net/dev . | |
246 | .LP | |
c13182ef | 247 | Local IPv6 IP addresses can be found via /proc/net or via |
fea681da MK |
248 | .BR rtnetlink (7). |
249 | .SH BUGS | |
c13182ef MK |
250 | glibc 2.1 is missing the |
251 | .I ifr_newname | |
252 | macro in net/if.h. | |
253 | Add the following to your program as a workaround: | |
fea681da MK |
254 | .sp |
255 | .RS | |
256 | .nf | |
fea681da MK |
257 | #ifndef ifr_newname |
258 | #define ifr_newname ifr_ifru.ifru_slave | |
259 | #endif | |
fea681da MK |
260 | .fi |
261 | .RE | |
262 | .SH "SEE ALSO" | |
263 | .BR capabilities (7), | |
264 | .BR ip (7), | |
265 | .BR proc (7), | |
266 | .BR rtnetlink (7) |