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