man7/netdevice.7

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