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 2014-01-24 "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 Most of them 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 .fi
  57 .in
  58
  59 Normally, the user specifies which device to affect by setting
  60 .I ifr_name
  61 to the name of the interface.
  62 All other members of the structure may
  63 share memory.
  64 .SS Ioctls
  65 If an ioctl is marked as privileged, then using it requires an effective
  66 user ID of 0 or the
  67 .B CAP_NET_ADMIN
  68 capability.
  69 If this is not the case,
  70 .B EPERM
  71 will be returned.
  72 .TP
  73 .B SIOCGIFNAME
  74 Given the
  75 .IR ifr_ifindex ,
  76 return the name of the interface in
  77 .IR ifr_name .
  78 This is the only ioctl which returns its result in
  79 .IR ifr_name .
  80 .TP
  81 .B SIOCGIFINDEX
  82 Retrieve the interface index of the interface into
  83 .IR ifr_ifindex .
  84 .TP
  85 .BR SIOCGIFFLAGS ", " SIOCSIFFLAGS
  86 Get or set the active flag word of the device.
  87 .I ifr_flags
  88 contains a bit mask of the following values:
  89 .\" Do not right adjust text blocks in tables
  90 .na
  91 .TS
  92 tab(:);
  93 c s
  94 l l.
  95 Device flags
  96 IFF_UP:Interface is running.
  97 IFF_BROADCAST:Valid broadcast address set.
  98 IFF_DEBUG:Internal debugging flag.
  99 IFF_LOOPBACK:Interface is a loopback interface.
 100 IFF_POINTOPOINT:Interface is a point-to-point link.
 101 IFF_RUNNING:Resources allocated.
 102 IFF_NOARP:T{
 103 No arp protocol, L2 destination address not set.
 104 T}
 105 IFF_PROMISC:Interface is in promiscuous mode.
 106 IFF_NOTRAILERS:Avoid use of trailers.
 107 IFF_ALLMULTI:Receive all multicast packets.
 108 IFF_MASTER:Master of a load balancing bundle.
 109 IFF_SLAVE:Slave of a load balancing bundle.
 110 IFF_MULTICAST:Supports multicast
 111 IFF_PORTSEL:Is able to select media type via ifmap.
 112 IFF_AUTOMEDIA:Auto media selection active.
 113 IFF_DYNAMIC:T{
 114 The addresses are lost when the interface goes down.
 115 T}
 116 IFF_LOWER_UP:Driver signals L1 up (since Linux 2.6.17)
 117 IFF_DORMANT:Driver signals dormant (since Linux 2.6.17)
 118 IFF_ECHO:Echo sent packets (since Linux 2.6.25)
 119
 120 .TE
 121 .ad
 122 Setting the active flag word is a privileged operation, but any
 123 process may read it.
 124 .TP
 125 .BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS
 126 Get or set extended (private) flags for the device.
 127 .I ifr_flags
 128 contains a bit mask of the following values:
 129 .TS
 130 tab(:);
 131 c s
 132 l l.
 133 Private flags
 134 IFF_802_1Q_VLAN:Interface is 802.1Q VLAN device.
 135 IFF_EBRIDGE:Interface is Ethernet bridging device.
 136 IFF_SLAVE_INACTIVE:Interface is inactive bonding slave.
 137 IFF_MASTER_8023AD:Interface is 802.3ad bonding master.
 138 IFF_MASTER_ALB:Interface is balanced-alb bonding master.
 139 IFF_BONDING:Interface is a bonding master or slave.
 140 IFF_SLAVE_NEEDARP:Interface needs ARPs for validation.
 141 IFF_ISATAP:Interface is RFC4214 ISATAP interface.
 142 .TE
 143 .sp
 144 Setting the extended (private) interface flags is a privileged operation.
 145 .TP
 146 .BR SIOCGIFADDR ", " SIOCSIFADDR
 147 Get or set the address of the device using
 148 .IR ifr_addr .
 149 Setting the interface address is a privileged operation.
 150 For compatibility, only
 151 .B AF_INET
 152 addresses are accepted or returned.
 153 .TP
 154 .BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR
 155 Get or set the destination address of a point-to-point device using
 156 .IR ifr_dstaddr .
 157 For compatibility, only
 158 .B AF_INET
 159 addresses are accepted or returned.
 160 Setting the destination address is a privileged operation.
 161 .TP
 162 .BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR
 163 Get or set the broadcast address for a device using
 164 .IR ifr_brdaddr .
 165 For compatibility, only
 166 .B AF_INET
 167 addresses are accepted or returned.
 168 Setting the broadcast address is a privileged operation.
 169 .TP
 170 .BR SIOCGIFNETMASK ", " SIOCSIFNETMASK
 171 Get or set the network mask for a device using
 172 .IR ifr_netmask .
 173 For compatibility, only
 174 .B AF_INET
 175 addresses are accepted or returned.
 176 Setting the network mask is a privileged operation.
 177 .TP
 178 .BR SIOCGIFMETRIC ", " SIOCSIFMETRIC
 179 Get or set the metric of the device using
 180 .IR ifr_metric .
 181 This is currently not implemented; it sets
 182 .I ifr_metric
 183 to 0 if you attempt to read it and returns
 184 .B EOPNOTSUPP
 185 if you attempt to set it.
 186 .TP
 187 .BR SIOCGIFMTU ", " SIOCSIFMTU
 188 Get or set the MTU (Maximum Transfer Unit) of a device using
 189 .IR ifr_mtu .
 190 Setting the MTU is a privileged operation.
 191 Setting the MTU to
 192 too small values may cause kernel crashes.
 193 .TP
 194 .BR SIOCGIFHWADDR ", " SIOCSIFHWADDR
 195 Get or set the hardware address of a device using
 196 .IR ifr_hwaddr .
 197 The hardware address is specified in a struct
 198 .IR sockaddr .
 199 .I sa_family
 200 contains the ARPHRD_* device type,
 201 .I sa_data
 202 the L2 hardware address starting from byte 0.
 203 Setting the hardware address is a privileged operation.
 204 .TP
 205 .B SIOCSIFHWBROADCAST
 206 Set the hardware broadcast address of a device from
 207 .IR ifr_hwaddr .
 208 This is a privileged operation.
 209 .TP
 210 .BR SIOCGIFMAP ", " SIOCSIFMAP
 211 Get or set the interface's hardware parameters using
 212 .IR ifr_map .
 213 Setting the parameters is a privileged operation.
 214
 215 .in +4n
 216 .nf
 217 struct ifmap {
 218     unsigned long   mem_start;
 219     unsigned long   mem_end;
 220     unsigned short  base_addr;
 221     unsigned char   irq;
 222     unsigned char   dma;
 223     unsigned char   port;
 224 };
 225 .fi
 226 .in
 227
 228 The interpretation of the ifmap structure depends on the device driver
 229 and the architecture.
 230 .TP
 231 .BR SIOCADDMULTI ", " SIOCDELMULTI
 232 Add an address to or delete an address from the device's link layer
 233 multicast filters using
 234 .IR ifr_hwaddr .
 235 These are privileged operations.
 236 See also
 237 .BR packet (7)
 238 for an alternative.
 239 .TP
 240 .BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN
 241 Get or set the transmit queue length of a device using
 242 .IR ifr_qlen .
 243 Setting the transmit queue length is a privileged operation.
 244 .TP
 245 .B SIOCSIFNAME
 246 Changes the name of the interface specified in
 247 .I ifr_name
 248 to
 249 .IR ifr_newname .
 250 This is a privileged operation.
 251 It is allowed only when the interface
 252 is not up.
 253 .TP
 254 .B SIOCGIFCONF
 255 Return a list of interface (transport layer) addresses.
 256 This currently
 257 means only addresses of the
 258 .B AF_INET
 259 (IPv4) family for compatibility.
 260 Unlike the others, this ioctl passes an
 261 .I ifconf
 262 structure:
 263
 264 .in +4n
 265 .nf
 266 struct ifconf {
 267     int                 ifc_len; /* size of buffer */
 268     union {
 269         char           *ifc_buf; /* buffer address */
 270         struct ifreq   *ifc_req; /* array of structures */
 271     };
 272 };
 273 .fi
 274 .in
 275
 276 If
 277 .I ifc_req
 278 is NULL,
 279 .B SIOCGIFCONF
 280 returns the necessary buffer size in bytes
 281 for receiving all available addresses in
 282 .IR ifc_len .
 283 Otherwise,
 284 .I ifc_req
 285 contains a pointer to an array of
 286 .I ifreq
 287 structures to be filled with all currently active L3 interface addresses.
 288 .I ifc_len
 289 contains the size of the array in bytes.
 290 Within each
 291 .I ifreq
 292 structure,
 293 .I ifr_name
 294 will receive the interface name, and
 295 .I ifr_addr
 296 the address.
 297 The actual number of bytes transferred is returned in
 298 .IR ifc_len .
 299
 300 If the size specified by
 301 .I ifc_len
 302 is insufficient to store all the addresses,
 303 the kernel will skip the exceeding ones and return success.
 304 There is no reliable way of detecting this condition once it has occurred.
 305 It is therefore recommended to either determine the necessary buffer size
 306 beforehand by calling
 307 .B SIOCGIFCONF
 308 with
 309 .I ifc_req
 310 set to NULL, or to retry the call with a bigger buffer whenever
 311 .I ifc_len
 312 upon return differs by less than
 313 .I sizeof(struct ifreq)
 314 from its original value.
 315
 316 If an error occurs accessing the
 317 .I ifconf
 318 or
 319 .I ifreq
 320 structures,
 321 .B EFAULT
 322 will be returned.
 323 .\" Slaving isn't supported in 2.2
 324 .\" .
 325 .\" .TP
 326 .\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE
 327 .\" Get or set the slave device using
 328 .\" .IR ifr_slave .
 329 .\" Setting the slave device is a privileged operation.
 330 .\" .PP
 331 .\" FIXME . add amateur radio stuff.
 332 .PP
 333 Most protocols support their own ioctls to configure protocol-specific
 334 interface options.
 335 See the protocol man pages for a description.
 336 For configuring IP addresses, see
 337 .BR ip (7).
 338 .PP
 339 In addition, some devices support private ioctls.
 340 These are not described here.
 341 .SH NOTES
 342 Strictly speaking,
 343 .B SIOCGIFCONF
 344 and the other ioctls that accept or return only
 345 .B AF_INET
 346 socket addresses,
 347 are IP-specific and belong in
 348 .BR ip (7).
 349 .LP
 350 The names of interfaces with no addresses or that don't have the
 351 .B IFF_RUNNING
 352 flag set can be found via
 353 .IR /proc/net/dev .
 354 .LP
 355 Local IPv6 IP addresses can be found via
 356 .I /proc/net
 357 or via
 358 .BR rtnetlink (7).
 359 .SH BUGS
 360 glibc 2.1 is missing the
 361 .I ifr_newname
 362 macro in
 363 .IR <net/if.h> .
 364 Add the following to your program as a workaround:
 365 .sp
 366 .in +4n
 367 .nf
 368 #ifndef ifr_newname
 369 #define ifr_newname     ifr_ifru.ifru_slave
 370 #endif
 371 .fi
 372 .in
 373 .SH SEE ALSO
 374 .BR proc (5),
 375 .BR capabilities (7),
 376 .BR ip (7),
 377 .BR rtnetlink (7)