manual/LDP_man-pages/original/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 .TH NETDEVICE  7 2009-01-14 "Linux" "Linux Programmer's Manual"
  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
  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 .I ifreq
  28 structure:
  29
  30 .in +4n
  31 .nf
  32 struct ifreq {
  33     char ifr_name[IFNAMSIZ]; /* Interface name */
  34     union {
  35         struct sockaddr ifr_addr;
  36         struct sockaddr ifr_dstaddr;
  37         struct sockaddr ifr_broadaddr;
  38         struct sockaddr ifr_netmask;
  39         struct sockaddr ifr_hwaddr;
  40         short           ifr_flags;
  41         int             ifr_ifindex;
  42         int             ifr_metric;
  43         int             ifr_mtu;
  44         struct ifmap    ifr_map;
  45         char            ifr_slave[IFNAMSIZ];
  46         char            ifr_newname[IFNAMSIZ];
  47         char           *ifr_data;
  48     };
  49 };
  50
  51 struct ifconf {
  52     int                 ifc_len; /* size of buffer */
  53     union {
  54         char           *ifc_buf; /* buffer address */
  55         struct ifreq   *ifc_req; /* array of structures */
  56     };
  57 };
  58 .fi
  59 .in
  60
  61 Normally, the user specifies which device to affect by setting
  62 .I ifr_name
  63 to the name of the interface.
  64 All other members of the structure may
  65 share memory.
  66 .SS Ioctls
  67 If an ioctl is marked as privileged then using it requires an effective
  68 user ID of 0 or the
  69 .B CAP_NET_ADMIN
  70 capability.
  71 If this is not the case
  72 .B EPERM
  73 will be returned.
  74 .TP
  75 .B SIOCGIFNAME
  76 Given the
  77 .IR ifr_ifindex ,
  78 return the name of the interface in
  79 .IR ifr_name .
  80 This is the only ioctl which returns its result in
  81 .IR ifr_name .
  82 .TP
  83 .B SIOCGIFINDEX
  84 Retrieve the interface index of the interface into
  85 .IR ifr_ifindex .
  86 .TP
  87 .BR SIOCGIFFLAGS ", " SIOCSIFFLAGS
  88 Get or set the active flag word of the device.
  89 .I ifr_flags
  90 contains a bit mask of the following values:
  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:No arp protocol, L2 destination address not set.
 103 IFF_PROMISC:Interface is in promiscuous mode.
 104 IFF_NOTRAILERS:Avoid use of trailers.
 105 IFF_ALLMULTI:Receive all multicast packets.
 106 IFF_MASTER:Master of a load balancing bundle.
 107 IFF_SLAVE:Slave of a load balancing bundle.
 108 IFF_MULTICAST:Supports multicast
 109 IFF_PORTSEL:Is able to select media type via ifmap.
 110 IFF_AUTOMEDIA:Auto media selection active.
 111 IFF_DYNAMIC:T{
 112 The addresses are lost when the interface goes down.
 113 T}
 114 IFF_LOWER_UP:Driver signals L1 up (since Linux 2.6.17)
 115 IFF_DORMANT:Driver signals dormant (since Linux 2.6.17)
 116 IFF_ECHO:Echo sent packets (since Linux 2.6.25)
 117
 118
 119 .TE
 120 Setting the active flag word is a privileged operation, but any
 121 process may read it.
 122 .TP
 123 .BR SIOCGIFMETRIC ", " SIOCSIFMETRIC
 124 Get or set the metric of the device using
 125 .IR ifr_metric .
 126 This is currently not implemented; it sets
 127 .I ifr_metric
 128 to 0 if you attempt to read it and returns
 129 .B EOPNOTSUPP
 130 if you attempt to set it.
 131 .TP
 132 .BR SIOCGIFMTU ", " SIOCSIFMTU
 133 Get or set the MTU (Maximum Transfer Unit) of a device using
 134 .IR ifr_mtu .
 135 Setting the MTU is a privileged operation.
 136 Setting the MTU to
 137 too small values may cause kernel crashes.
 138 .TP
 139 .BR SIOCGIFHWADDR ", " SIOCSIFHWADDR
 140 Get or set the hardware address of a device using
 141 .IR ifr_hwaddr .
 142 The hardware address is specified in a struct
 143 .IR sockaddr .
 144 .I sa_family
 145 contains the ARPHRD_* device type,
 146 .I sa_data
 147 the L2 hardware address starting from byte 0.
 148 Setting the hardware address is a privileged operation.
 149 .TP
 150 .B SIOCSIFHWBROADCAST
 151 Set the hardware broadcast address of a device from
 152 .IR ifr_hwaddr .
 153 This is a privileged operation.
 154 .TP
 155 .BR SIOCGIFMAP ", " SIOCSIFMAP
 156 Get or set the interface's hardware parameters using
 157 .IR ifr_map .
 158 Setting the parameters is a privileged operation.
 159
 160 .in +4n
 161 .nf
 162 struct ifmap {
 163     unsigned long   mem_start;
 164     unsigned long   mem_end;
 165     unsigned short  base_addr;
 166     unsigned char   irq;
 167     unsigned char   dma;
 168     unsigned char   port;
 169 };
 170 .fi
 171 .in
 172
 173 The interpretation of the ifmap structure depends on the device driver
 174 and the architecture.
 175 .TP
 176 .BR SIOCADDMULTI ", " SIOCDELMULTI
 177 Add an address to or delete an address from the device's link layer
 178 multicast filters using
 179 .IR ifr_hwaddr .
 180 These are privileged operations.
 181 See also
 182 .BR packet (7)
 183 for an alternative.
 184 .TP
 185 .BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN
 186 Get or set the transmit queue length of a device using
 187 .IR ifr_qlen .
 188 Setting the transmit queue length is a privileged operation.
 189 .TP
 190 .B SIOCSIFNAME
 191 Changes the name of the interface specified in
 192 .I ifr_name
 193 to
 194 .IR ifr_newname .
 195 This is a privileged operation.
 196 It is only allowed when the interface
 197 is not up.
 198 .TP
 199 .B SIOCGIFCONF
 200 Return a list of interface (transport layer) addresses.
 201 This currently
 202 means only addresses of the
 203 .B AF_INET
 204 (IPv4) family for compatibility.
 205 The user passes a
 206 .I ifconf
 207 structure as argument to the ioctl.
 208 It contains a pointer to an array of
 209 .I ifreq
 210 structures in
 211 .I ifc_req
 212 and its length in bytes in
 213 .IR ifc_len .
 214 The kernel fills the ifreqs with all current L3 interface addresses that
 215 are running:
 216 .I ifr_name
 217 contains the interface name (eth0:1 etc.),
 218 .I ifr_addr
 219 the address.
 220 The kernel returns with the actual length in
 221 .IR ifc_len .
 222 If
 223 .I ifc_len
 224 is equal to the original length the buffer probably has overflowed
 225 and you should retry with a bigger buffer to get all addresses.
 226 When no error occurs the ioctl returns 0;
 227 otherwise \-1.
 228 Overflow is not an error.
 229 .\" Slaving isn't supported in 2.2
 230 .\" .
 231 .\" .TP
 232 .\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE
 233 .\" Get or set the slave device using
 234 .\" .IR ifr_slave .
 235 .\" Setting the slave device is a privileged operation.
 236 .\" .PP
 237 .\" FIXME add amateur radio stuff.
 238 .PP
 239 Most protocols support their own ioctls to configure protocol-specific
 240 interface options.
 241 See the protocol man pages for a description.
 242 For configuring IP addresses see
 243 .BR ip (7).
 244 .PP
 245 In addition some devices support private ioctls.
 246 These are not described here.
 247 .SH NOTES
 248 Strictly speaking,
 249 .B SIOCGIFCONF
 250 is IP specific and belongs in
 251 .BR ip (7).
 252 .LP
 253 The names of interfaces with no addresses or that don't have the
 254 .B IFF_RUNNING
 255 flag set can be found via
 256 .IR /proc/net/dev .
 257 .LP
 258 Local IPv6 IP addresses can be found via
 259 .I /proc/net
 260 or via
 261 .BR rtnetlink (7).
 262 .SH BUGS
 263 glibc 2.1 is missing the
 264 .I ifr_newname
 265 macro in
 266 .IR <net/if.h> .
 267 Add the following to your program as a workaround:
 268 .sp
 269 .in +4n
 270 .nf
 271 #ifndef ifr_newname
 272 #define ifr_newname     ifr_ifru.ifru_slave
 273 #endif
 274 .fi
 275 .in
 276 .SH "SEE ALSO"
 277 .BR proc (5),
 278 .BR capabilities (7),
 279 .BR ip (7),
 280 .BR rtnetlink (7)