original/man7/netdevice.7

   1 '\" t
   2 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   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.
   9 .\" %%%LICENSE_END
  10 .\"
  11 .\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $
  12 .\"
  13 .\" Modified, 2004-11-25, mtk, formatting and a few wording fixes
  14 .\"
  15 .\" Modified, 2011-11-02, <bidulock@openss7.org>, added many basic
  16 .\"  but missing ioctls, such as SIOCGIFADDR.
  17 .\"
  18 .TH NETDEVICE  7 2012-04-26 "Linux" "Linux Programmer's Manual"
  19 .SH NAME
  20 netdevice \- low-level access to Linux network devices
  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.
  28
  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 They pass an
  33 .I ifreq
  34 structure:
  35
  36 .in +4n
  37 .nf
  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
  57 struct ifconf {
  58     int                 ifc_len; /* size of buffer */
  59     union {
  60         char           *ifc_buf; /* buffer address */
  61         struct ifreq   *ifc_req; /* array of structures */
  62     };
  63 };
  64 .fi
  65 .in
  66
  67 Normally, the user specifies which device to affect by setting
  68 .I ifr_name
  69 to the name 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 .BR SIOCGIFFLAGS ", " SIOCSIFFLAGS
  94 Get or set the active flag word of the device.
  95 .I ifr_flags
  96 contains a bit mask of the following values:
  97 .\" Do not right adjust text blocks in tables
  98 .na
  99 .TS
 100 tab(:);
 101 c s
 102 l l.
 103 Device flags
 104 IFF_UP:Interface is running.
 105 IFF_BROADCAST:Valid broadcast address set.
 106 IFF_DEBUG:Internal debugging flag.
 107 IFF_LOOPBACK:Interface is a loopback interface.
 108 IFF_POINTOPOINT:Interface is a point-to-point link.
 109 IFF_RUNNING:Resources allocated.
 110 IFF_NOARP:T{
 111 No arp protocol, L2 destination address not set.
 112 T}
 113 IFF_PROMISC:Interface is in promiscuous mode.
 114 IFF_NOTRAILERS:Avoid use of trailers.
 115 IFF_ALLMULTI:Receive all multicast packets.
 116 IFF_MASTER:Master of a load balancing bundle.
 117 IFF_SLAVE:Slave of a load balancing bundle.
 118 IFF_MULTICAST:Supports multicast
 119 IFF_PORTSEL:Is able to select media type via ifmap.
 120 IFF_AUTOMEDIA:Auto media selection active.
 121 IFF_DYNAMIC:T{
 122 The addresses are lost when the interface goes down.
 123 T}
 124 IFF_LOWER_UP:Driver signals L1 up (since Linux 2.6.17)
 125 IFF_DORMANT:Driver signals dormant (since Linux 2.6.17)
 126 IFF_ECHO:Echo sent packets (since Linux 2.6.25)
 127
 128 .TE
 129 .ad
 130 Setting the active flag word is a privileged operation, but any
 131 process may read it.
 132 .TP
 133 .BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS
 134 Get or set extended (private) flags for the device.
 135 .I ifr_flags
 136 contains a bit mask of the following values:
 137 .TS
 138 tab(:);
 139 c s
 140 l l.
 141 Private flags
 142 IFF_802_1Q_VLAN:Interface is 802.1Q VLAN device.
 143 IFF_EBRIDGE:Interface is Ethernet bridging device.
 144 IFF_SLAVE_INACTIVE:Interface is inactive bonding slave.
 145 IFF_MASTER_8023AD:Interface is 802.3ad bonding master.
 146 IFF_MASTER_ALB:Interface is balanced-alb bonding master.
 147 IFF_BONDING:Interface is a bonding master or slave.
 148 IFF_SLAVE_NEEDARP:Interface needs ARPs for validation.
 149 IFF_ISATAP:Interface is RFC4214 ISATAP interface.
 150 .TE
 151 .sp
 152 Setting the extended (private) interface flags is a privileged operation.
 153 .TP
 154 .BR SIOCGIFADDR ", " SIOCSIFADDR
 155 Get or set the address of the device using
 156 .IR ifr_addr .
 157 Setting the interface address is a privileged operation.
 158 For compatibility, only
 159 .B AF_INET
 160 addresses are accepted or returned.
 161 .TP
 162 .BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR
 163 Get or set the destination address of a point-to-point device using
 164 .IR ifr_dstaddr .
 165 For compatibility, only
 166 .B AF_INET
 167 addresses are accepted or returned.
 168 Setting the destination address is a privileged operation.
 169 .TP
 170 .BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR
 171 Get or set the broadcast address for a device using
 172 .IR ifr_brdaddr .
 173 For compatibility, only
 174 .B AF_INET
 175 addresses are accepted or returned.
 176 Setting the broadcast address is a privileged operation.
 177 .TP
 178 .BR SIOCGIFNETMASK ", " SIOCSIFNETMASK
 179 Get or set the network mask for a device using
 180 .IR ifr_netmask .
 181 For compatibility, only
 182 .B AF_INET
 183 addresses are accepted or returned.
 184 Setting the network mask is a privileged operation.
 185 .TP
 186 .BR SIOCGIFMETRIC ", " SIOCSIFMETRIC
 187 Get or set the metric of the device using
 188 .IR ifr_metric .
 189 This is currently not implemented; it sets
 190 .I ifr_metric
 191 to 0 if you attempt to read it and returns
 192 .B EOPNOTSUPP
 193 if you attempt to set it.
 194 .TP
 195 .BR SIOCGIFMTU ", " SIOCSIFMTU
 196 Get or set the MTU (Maximum Transfer Unit) of a device using
 197 .IR ifr_mtu .
 198 Setting the MTU is a privileged operation.
 199 Setting the MTU to
 200 too small values may cause kernel crashes.
 201 .TP
 202 .BR SIOCGIFHWADDR ", " SIOCSIFHWADDR
 203 Get or set the hardware address of a device using
 204 .IR ifr_hwaddr .
 205 The hardware address is specified in a struct
 206 .IR sockaddr .
 207 .I sa_family
 208 contains the ARPHRD_* device type,
 209 .I sa_data
 210 the L2 hardware address starting from byte 0.
 211 Setting the hardware address is a privileged operation.
 212 .TP
 213 .B SIOCSIFHWBROADCAST
 214 Set the hardware broadcast address of a device from
 215 .IR ifr_hwaddr .
 216 This is a privileged operation.
 217 .TP
 218 .BR SIOCGIFMAP ", " SIOCSIFMAP
 219 Get or set the interface's hardware parameters using
 220 .IR ifr_map .
 221 Setting the parameters is a privileged operation.
 222
 223 .in +4n
 224 .nf
 225 struct ifmap {
 226     unsigned long   mem_start;
 227     unsigned long   mem_end;
 228     unsigned short  base_addr;
 229     unsigned char   irq;
 230     unsigned char   dma;
 231     unsigned char   port;
 232 };
 233 .fi
 234 .in
 235
 236 The interpretation of the ifmap structure depends on the device driver
 237 and the architecture.
 238 .TP
 239 .BR SIOCADDMULTI ", " SIOCDELMULTI
 240 Add an address to or delete an address from the device's link layer
 241 multicast filters using
 242 .IR ifr_hwaddr .
 243 These are privileged operations.
 244 See also
 245 .BR packet (7)
 246 for an alternative.
 247 .TP
 248 .BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN
 249 Get or set the transmit queue length of a device using
 250 .IR ifr_qlen .
 251 Setting the transmit queue length is a privileged operation.
 252 .TP
 253 .B SIOCSIFNAME
 254 Changes the name of the interface specified in
 255 .I ifr_name
 256 to
 257 .IR ifr_newname .
 258 This is a privileged operation.
 259 It is only allowed when the interface
 260 is not up.
 261 .TP
 262 .B SIOCGIFCONF
 263 Return a list of interface (transport layer) addresses.
 264 This currently
 265 means only addresses of the
 266 .B AF_INET
 267 (IPv4) family for compatibility.
 268 The user passes a
 269 .I ifconf
 270 structure as argument to the ioctl.
 271 It contains a pointer to an array of
 272 .I ifreq
 273 structures in
 274 .I ifc_req
 275 and its length in bytes in
 276 .IR ifc_len .
 277 The kernel fills the ifreqs with all current L3 interface addresses that
 278 are running:
 279 .I ifr_name
 280 contains the interface name (eth0:1 etc.),
 281 .I ifr_addr
 282 the address.
 283 The kernel returns with the actual length in
 284 .IR ifc_len .
 285 If
 286 .I ifc_len
 287 is equal to the original length the buffer probably has overflowed
 288 and you should retry with a bigger buffer to get all addresses.
 289 When no error occurs the ioctl returns 0;
 290 otherwise \-1.
 291 Overflow is not an error.
 292 .\" Slaving isn't supported in 2.2
 293 .\" .
 294 .\" .TP
 295 .\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE
 296 .\" Get or set the slave device using
 297 .\" .IR ifr_slave .
 298 .\" Setting the slave device is a privileged operation.
 299 .\" .PP
 300 .\" FIXME add amateur radio stuff.
 301 .PP
 302 Most protocols support their own ioctls to configure protocol-specific
 303 interface options.
 304 See the protocol man pages for a description.
 305 For configuring IP addresses see
 306 .BR ip (7).
 307 .PP
 308 In addition some devices support private ioctls.
 309 These are not described here.
 310 .SH NOTES
 311 Strictly speaking,
 312 .B SIOCGIFCONF
 313 and the other ioctls that only accept or return
 314 .B AF_INET
 315 socket addresses,
 316 are IP specific and belong in
 317 .BR ip (7).
 318 .LP
 319 The names of interfaces with no addresses or that don't have the
 320 .B IFF_RUNNING
 321 flag set can be found via
 322 .IR /proc/net/dev .
 323 .LP
 324 Local IPv6 IP addresses can be found via
 325 .I /proc/net
 326 or via
 327 .BR rtnetlink (7).
 328 .SH BUGS
 329 glibc 2.1 is missing the
 330 .I ifr_newname
 331 macro in
 332 .IR <net/if.h> .
 333 Add the following to your program as a workaround:
 334 .sp
 335 .in +4n
 336 .nf
 337 #ifndef ifr_newname
 338 #define ifr_newname     ifr_ifru.ifru_slave
 339 #endif
 340 .fi
 341 .in
 342 .SH SEE ALSO
 343 .BR proc (5),
 344 .BR capabilities (7),
 345 .BR ip (7),
 346 .BR rtnetlink (7)