1NETDEVICE(7)               Linux Programmer's Manual              NETDEVICE(7)
2
3
4

NAME

6       netdevice - low-level access to Linux network devices
7

SYNOPSIS

9       #include <sys/ioctl.h>
10       #include <net/if.h>
11

DESCRIPTION

13       This  man page describes the sockets interface which is used to config‐
14       ure network devices.
15
16       Linux supports some standard ioctls to configure network devices.  They
17       can be used on any socket's file descriptor regardless of the family or
18       type.  Most of them pass an ifreq structure:
19
20           struct ifreq {
21               char ifr_name[IFNAMSIZ]; /* Interface name */
22               union {
23                   struct sockaddr ifr_addr;
24                   struct sockaddr ifr_dstaddr;
25                   struct sockaddr ifr_broadaddr;
26                   struct sockaddr ifr_netmask;
27                   struct sockaddr ifr_hwaddr;
28                   short           ifr_flags;
29                   int             ifr_ifindex;
30                   int             ifr_metric;
31                   int             ifr_mtu;
32                   struct ifmap    ifr_map;
33                   char            ifr_slave[IFNAMSIZ];
34                   char            ifr_newname[IFNAMSIZ];
35                   char           *ifr_data;
36               };
37           };
38
39       AF_INET6 is an exception.  It passes an in6_ifreq structure:
40
41           struct in6_ifreq {
42               struct in6_addr     ifr6_addr;
43               u32                 ifr6_prefixlen;
44               int                 ifr6_ifindex; /* Interface index */
45           };
46
47       Normally, the user specifies which device to affect by setting ifr_name
48       to the name of the interface or ifr6_ifindex to the index of the inter‐
49       face.  All other members of the structure may share memory.
50
51   Ioctls
52       If an ioctl is marked as privileged, then using it requires  an  effec‐
53       tive  user ID of 0 or the CAP_NET_ADMIN capability.  If this is not the
54       case, EPERM will be returned.
55
56       SIOCGIFNAME
57              Given the ifr_ifindex, return  the  name  of  the  interface  in
58              ifr_name.   This  is  the only ioctl which returns its result in
59              ifr_name.
60
61       SIOCGIFINDEX
62              Retrieve the interface index of the interface into ifr_ifindex.
63
64       SIOCGIFFLAGS, SIOCSIFFLAGS
65              Get or set the active flag word of the device.   ifr_flags  con‐
66              tains a bit mask of the following values:
67
68                                      Device flags
69              IFF_UP            Interface is running.
70              IFF_BROADCAST     Valid broadcast address set.
71              IFF_DEBUG         Internal debugging flag.
72              IFF_LOOPBACK      Interface is a loopback interface.
73              IFF_POINTOPOINT   Interface is a point-to-point link.
74              IFF_RUNNING       Resources allocated.
75              IFF_NOARP         No arp protocol, L2 destination address not
76                                set.
77              IFF_PROMISC       Interface is in promiscuous mode.
78              IFF_NOTRAILERS    Avoid use of trailers.
79              IFF_ALLMULTI      Receive all multicast packets.
80              IFF_MASTER        Master of a load balancing bundle.
81              IFF_SLAVE         Slave of a load balancing bundle.
82              IFF_MULTICAST     Supports multicast
83              IFF_PORTSEL       Is able to select media type via ifmap.
84              IFF_AUTOMEDIA     Auto media selection active.
85              IFF_DYNAMIC       The addresses are lost when the interface
86                                goes down.
87              IFF_LOWER_UP      Driver signals L1 up (since Linux 2.6.17)
88              IFF_DORMANT       Driver signals dormant (since Linux 2.6.17)
89              IFF_ECHO          Echo sent packets (since Linux 2.6.25)
90
91       Setting the active flag word is a privileged operation, but any process
92       may read it.
93
94       SIOCGIFPFLAGS, SIOCSIFPFLAGS
95              Get or set extended (private) flags for the  device.   ifr_flags
96              contains a bit mask of the following values:
97
98                                      Private flags
99              IFF_802_1Q_VLAN      Interface is 802.1Q VLAN device.
100              IFF_EBRIDGE          Interface is Ethernet bridging device.
101              IFF_SLAVE_INACTIVE   Interface is inactive bonding slave.
102              IFF_MASTER_8023AD    Interface is 802.3ad bonding master.
103              IFF_MASTER_ALB       Interface is balanced-alb bonding master.
104              IFF_BONDING          Interface is a bonding master or slave.
105              IFF_SLAVE_NEEDARP    Interface needs ARPs for validation.
106              IFF_ISATAP           Interface is RFC4214 ISATAP interface.
107
108       Setting  the  extended (private) interface flags is a privileged opera‐
109       tion.
110
111       SIOCGIFADDR, SIOCSIFADDR, SIOCDIFADDR
112              Get, set, or delete the address of the device using ifr_addr, or
113              ifr6_addr  with  ifr6_prefixlen.  Setting or deleting the inter‐
114              face address is  a  privileged  operation.   For  compatibility,
115              SIOCGIFADDR  returns only AF_INET addresses, SIOCSIFADDR accepts
116              AF_INET and AF_INET6 addresses,  and  SIOCDIFADDR  deletes  only
117              AF_INET6 addresses.  A AF_INET address can be deleted by setting
118              it to zero via SIOCSIFADDR.
119
120       SIOCGIFDSTADDR, SIOCSIFDSTADDR
121              Get or set the destination address of  a  point-to-point  device
122              using  ifr_dstaddr.   For  compatibility, only AF_INET addresses
123              are accepted or returned.  Setting the destination address is  a
124              privileged operation.
125
126       SIOCGIFBRDADDR, SIOCSIFBRDADDR
127              Get or set the broadcast address for a device using ifr_brdaddr.
128              For compatibility, only AF_INET addresses are  accepted  or  re‐
129              turned.   Setting  the  broadcast address is a privileged opera‐
130              tion.
131
132       SIOCGIFNETMASK, SIOCSIFNETMASK
133              Get or set the network mask for a device using ifr_netmask.  For
134              compatibility,  only AF_INET addresses are accepted or returned.
135              Setting the network mask is a privileged operation.
136
137       SIOCGIFMETRIC, SIOCSIFMETRIC
138              Get or set the metric of the device using ifr_metric.   This  is
139              currently  not  implemented;  it sets ifr_metric to 0 if you at‐
140              tempt to read it and returns EOPNOTSUPP if you  attempt  to  set
141              it.
142
143       SIOCGIFMTU, SIOCSIFMTU
144              Get  or  set  the  MTU (Maximum Transfer Unit) of a device using
145              ifr_mtu.  Setting the MTU is a  privileged  operation.   Setting
146              the MTU to too small values may cause kernel crashes.
147
148       SIOCGIFHWADDR, SIOCSIFHWADDR
149              Get  or  set  the hardware address of a device using ifr_hwaddr.
150              The hardware address is specified in a struct sockaddr.  sa_fam‐
151              ily  contains  the ARPHRD_* device type, sa_data the L2 hardware
152              address starting from byte 0.  Setting the hardware address is a
153              privileged operation.
154
155       SIOCSIFHWBROADCAST
156              Set  the hardware broadcast address of a device from ifr_hwaddr.
157              This is a privileged operation.
158
159       SIOCGIFMAP, SIOCSIFMAP
160              Get or set the interface's hardware  parameters  using  ifr_map.
161              Setting the parameters is a privileged operation.
162
163                  struct ifmap {
164                      unsigned long   mem_start;
165                      unsigned long   mem_end;
166                      unsigned short  base_addr;
167                      unsigned char   irq;
168                      unsigned char   dma;
169                      unsigned char   port;
170                  };
171
172              The  interpretation of the ifmap structure depends on the device
173              driver and the architecture.
174
175       SIOCADDMULTI, SIOCDELMULTI
176              Add an address to or delete an address from  the  device's  link
177              layer  multicast filters using ifr_hwaddr.  These are privileged
178              operations.  See also packet(7) for an alternative.
179
180       SIOCGIFTXQLEN, SIOCSIFTXQLEN
181              Get or set the transmit queue length of a device using ifr_qlen.
182              Setting the transmit queue length is a privileged operation.
183
184       SIOCSIFNAME
185              Changes  the  name  of  the  interface  specified in ifr_name to
186              ifr_newname.  This is a privileged  operation.   It  is  allowed
187              only when the interface is not up.
188
189       SIOCGIFCONF
190              Return a list of interface (network layer) addresses.  This cur‐
191              rently means only addresses of the  AF_INET  (IPv4)  family  for
192              compatibility.   Unlike  the others, this ioctl passes an ifconf
193              structure:
194
195                  struct ifconf {
196                      int               ifc_len; /* size of buffer */
197                      union {
198                          char         *ifc_buf; /* buffer address */
199                          struct ifreq *ifc_req; /* array of structures */
200                      };
201                  };
202
203              If ifc_req is NULL, SIOCGIFCONF  returns  the  necessary  buffer
204              size  in bytes for receiving all available addresses in ifc_len.
205              Otherwise, ifc_req contains a  pointer  to  an  array  of  ifreq
206              structures  to  be filled with all currently active L3 interface
207              addresses.  ifc_len contains the size of  the  array  in  bytes.
208              Within each ifreq structure, ifr_name will receive the interface
209              name, and ifr_addr the address.   The  actual  number  of  bytes
210              transferred is returned in ifc_len.
211
212              If  the  size  specified by ifc_len is insufficient to store all
213              the addresses, the kernel will skip the exceeding ones  and  re‐
214              turn success.  There is no reliable way of detecting this condi‐
215              tion once it has occurred.  It is therefore recommended  to  ei‐
216              ther  determine  the necessary buffer size beforehand by calling
217              SIOCGIFCONF with ifc_req set to NULL, or to retry the call  with
218              a  bigger  buffer  whenever  ifc_len upon return differs by less
219              than sizeof(struct ifreq) from its original value.
220
221              If an error occurs accessing the  ifconf  or  ifreq  structures,
222              EFAULT will be returned.
223
224       Most  protocols support their own ioctls to configure protocol-specific
225       interface options.  See the protocol man pages for a description.   For
226       configuring IP addresses, see ip(7).
227
228       In  addition,  some  devices support private ioctls.  These are not de‐
229       scribed here.
230

NOTES

232       SIOCGIFCONF and the other ioctls that accept  or  return  only  AF_INET
233       socket  addresses  are  IP-specific  and perhaps should rather be docu‐
234       mented in ip(7).
235
236       The names of interfaces with  no  addresses  or  that  don't  have  the
237       IFF_RUNNING flag set can be found via /proc/net/dev.
238
239       AF_INET6  IPv6 addresses can be read from /proc/net/if_inet6 or via rt‐
240       netlink(7).  Adding a new IPv6 address and deleting  an  existing  IPv6
241       address  can  be  done  via  SIOCSIFADDR  and  SIOCDIFADDR  or  via rt‐
242       netlink(7).  Retrieving or changing destination  IPv6  addresses  of  a
243       point-to-point interface is possible only via rtnetlink(7).
244

BUGS

246       glibc 2.1 is missing the ifr_newname macro in <net/if.h>.  Add the fol‐
247       lowing to your program as a workaround:
248
249           #ifndef ifr_newname
250           #define ifr_newname     ifr_ifru.ifru_slave
251           #endif
252

SEE ALSO

254       proc(5), capabilities(7), ip(7), rtnetlink(7)
255

COLOPHON

257       This page is part of release 5.12 of the Linux  man-pages  project.   A
258       description  of  the project, information about reporting bugs, and the
259       latest    version    of    this    page,    can     be     found     at
260       https://www.kernel.org/doc/man-pages/.
261
262
263
264Linux                             2021-03-22                      NETDEVICE(7)
Impressum