diff options
Diffstat (limited to '')
| -rw-r--r-- | man7/netdevice.7 | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/man7/netdevice.7 b/man7/netdevice.7 new file mode 100644 index 0000000..a0f0049 --- /dev/null +++ b/man7/netdevice.7 @@ -0,0 +1,421 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. +.\" +.\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $ +.\" +.\" Modified, 2004-11-25, mtk, formatting and a few wording fixes +.\" +.\" Modified, 2011-11-02, <bidulock@openss7.org>, added many basic +.\" but missing ioctls, such as SIOCGIFADDR. +.\" +.TH netdevice 7 2023-07-15 "Linux man-pages 6.05.01" +.SH NAME +netdevice \- low-level access to Linux network devices +.SH SYNOPSIS +.nf +.B "#include <sys/ioctl.h>" +.B "#include <net/if.h>" +.fi +.SH DESCRIPTION +This man page describes the sockets interface which is used to configure +network devices. +.PP +Linux supports some standard ioctls to configure network devices. +They can be used on any socket's file descriptor regardless of the +family or type. +Most of them pass an +.I ifreq +structure: +.PP +.in +4n +.EX +struct ifreq { + char ifr_name[IFNAMSIZ]; /* Interface name */ + union { + struct sockaddr ifr_addr; + struct sockaddr ifr_dstaddr; + struct sockaddr ifr_broadaddr; + struct sockaddr ifr_netmask; + struct sockaddr ifr_hwaddr; + short ifr_flags; + int ifr_ifindex; + int ifr_metric; + int ifr_mtu; + struct ifmap ifr_map; + char ifr_slave[IFNAMSIZ]; + char ifr_newname[IFNAMSIZ]; + char *ifr_data; + }; +}; +.EE +.in +.PP +.B AF_INET6 +is an exception. +It passes an +.I in6_ifreq +structure: +.PP +.in +4n +.EX +struct in6_ifreq { + struct in6_addr ifr6_addr; + u32 ifr6_prefixlen; + int ifr6_ifindex; /* Interface index */ +}; +.EE +.in +.PP +Normally, the user specifies which device to affect by setting +.I ifr_name +to the name of the interface or +.I ifr6_ifindex +to the index of the interface. +All other members of the structure may +share memory. +.SS Ioctls +If an ioctl is marked as privileged, then using it requires an effective +user ID of 0 or the +.B CAP_NET_ADMIN +capability. +If this is not the case, +.B EPERM +will be returned. +.TP +.B SIOCGIFNAME +Given the +.IR ifr_ifindex , +return the name of the interface in +.IR ifr_name . +This is the only ioctl which returns its result in +.IR ifr_name . +.TP +.B SIOCGIFINDEX +Retrieve the interface index of the interface into +.IR ifr_ifindex . +.TP +.BR SIOCGIFFLAGS ", " SIOCSIFFLAGS +Get or set the active flag word of the device. +.I ifr_flags +contains a bit mask of the following values: +.\" Do not right adjust text blocks in tables +.na +.TS +tab(:); +c s +l l. +Device flags +IFF_UP:Interface is running. +IFF_BROADCAST:Valid broadcast address set. +IFF_DEBUG:Internal debugging flag. +IFF_LOOPBACK:Interface is a loopback interface. +IFF_POINTOPOINT:Interface is a point-to-point link. +IFF_RUNNING:Resources allocated. +IFF_NOARP:T{ +No arp protocol, L2 destination address not set. +T} +IFF_PROMISC:Interface is in promiscuous mode. +IFF_NOTRAILERS:Avoid use of trailers. +IFF_ALLMULTI:Receive all multicast packets. +IFF_MASTER:Master of a load balancing bundle. +IFF_SLAVE:Slave of a load balancing bundle. +IFF_MULTICAST:Supports multicast +IFF_PORTSEL:Is able to select media type via ifmap. +IFF_AUTOMEDIA:Auto media selection active. +IFF_DYNAMIC:T{ +The addresses are lost when the interface goes down. +T} +IFF_LOWER_UP:Driver signals L1 up (since Linux 2.6.17) +IFF_DORMANT:Driver signals dormant (since Linux 2.6.17) +IFF_ECHO:Echo sent packets (since Linux 2.6.25) +.TE +.ad +.PP +Setting the active flag word is a privileged operation, but any +process may read it. +.TP +.BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS +Get or set extended (private) flags for the device. +.I ifr_flags +contains a bit mask of the following values: +.TS +tab(:); +c s +l l. +Private flags +IFF_802_1Q_VLAN:Interface is 802.1Q VLAN device. +IFF_EBRIDGE:Interface is Ethernet bridging device. +IFF_SLAVE_INACTIVE:Interface is inactive bonding slave. +IFF_MASTER_8023AD:Interface is 802.3ad bonding master. +IFF_MASTER_ALB:Interface is balanced-alb bonding master. +IFF_BONDING:Interface is a bonding master or slave. +IFF_SLAVE_NEEDARP:Interface needs ARPs for validation. +IFF_ISATAP:Interface is RFC4214 ISATAP interface. +.TE +.PP +Setting the extended (private) interface flags is a privileged operation. +.TP +.BR SIOCGIFADDR ", " SIOCSIFADDR ", " SIOCDIFADDR +Get, set, or delete the address of the device using +.IR ifr_addr , +or +.I ifr6_addr +with +.IR ifr6_prefixlen . +Setting or deleting the interface address is a privileged operation. +For compatibility, +.B SIOCGIFADDR +returns only +.B AF_INET +addresses, +.B SIOCSIFADDR +accepts +.B AF_INET +and +.B AF_INET6 +addresses, and +.B SIOCDIFADDR +deletes only +.B AF_INET6 +addresses. +A +.B AF_INET +address can be deleted by setting it to zero via +.BR SIOCSIFADDR . +.TP +.BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR +Get or set the destination address of a point-to-point device using +.IR ifr_dstaddr . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the destination address is a privileged operation. +.TP +.BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR +Get or set the broadcast address for a device using +.IR ifr_brdaddr . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the broadcast address is a privileged operation. +.TP +.BR SIOCGIFNETMASK ", " SIOCSIFNETMASK +Get or set the network mask for a device using +.IR ifr_netmask . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the network mask is a privileged operation. +.TP +.BR SIOCGIFMETRIC ", " SIOCSIFMETRIC +Get or set the metric of the device using +.IR ifr_metric . +This is currently not implemented; it sets +.I ifr_metric +to 0 if you attempt to read it and returns +.B EOPNOTSUPP +if you attempt to set it. +.TP +.BR SIOCGIFMTU ", " SIOCSIFMTU +Get or set the MTU (Maximum Transfer Unit) of a device using +.IR ifr_mtu . +Setting the MTU is a privileged operation. +Setting the MTU to +too small values may cause kernel crashes. +.TP +.BR SIOCGIFHWADDR ", " SIOCSIFHWADDR +Get or set the hardware address of a device using +.IR ifr_hwaddr . +The hardware address is specified in a struct +.IR sockaddr . +.I sa_family +contains the ARPHRD_* device type, +.I sa_data +the L2 hardware address starting from byte 0. +Setting the hardware address is a privileged operation. +.TP +.B SIOCSIFHWBROADCAST +Set the hardware broadcast address of a device from +.IR ifr_hwaddr . +This is a privileged operation. +.TP +.BR SIOCGIFMAP ", " SIOCSIFMAP +Get or set the interface's hardware parameters using +.IR ifr_map . +Setting the parameters is a privileged operation. +.IP +.in +4n +.EX +struct ifmap { + unsigned long mem_start; + unsigned long mem_end; + unsigned short base_addr; + unsigned char irq; + unsigned char dma; + unsigned char port; +}; +.EE +.in +.IP +The interpretation of the ifmap structure depends on the device driver +and the architecture. +.TP +.BR SIOCADDMULTI ", " SIOCDELMULTI +Add an address to or delete an address from the device's link layer +multicast filters using +.IR ifr_hwaddr . +These are privileged operations. +See also +.BR packet (7) +for an alternative. +.TP +.BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN +Get or set the transmit queue length of a device using +.IR ifr_qlen . +Setting the transmit queue length is a privileged operation. +.TP +.B SIOCSIFNAME +Changes the name of the interface specified in +.I ifr_name +to +.IR ifr_newname . +This is a privileged operation. +It is allowed only when the interface +is not up. +.TP +.B SIOCGIFCONF +Return a list of interface (network layer) addresses. +This currently +means only addresses of the +.B AF_INET +(IPv4) family for compatibility. +Unlike the others, this ioctl passes an +.I ifconf +structure: +.IP +.in +4n +.EX +struct ifconf { + int ifc_len; /* size of buffer */ + union { + char *ifc_buf; /* buffer address */ + struct ifreq *ifc_req; /* array of structures */ + }; +}; +.EE +.in +.IP +If +.I ifc_req +is NULL, +.B SIOCGIFCONF +returns the necessary buffer size in bytes +for receiving all available addresses in +.IR ifc_len . +Otherwise, +.I ifc_req +contains a pointer to an array of +.I ifreq +structures to be filled with all currently active L3 interface addresses. +.I ifc_len +contains the size of the array in bytes. +Within each +.I ifreq +structure, +.I ifr_name +will receive the interface name, and +.I ifr_addr +the address. +The actual number of bytes transferred is returned in +.IR ifc_len . +.IP +If the size specified by +.I ifc_len +is insufficient to store all the addresses, +the kernel will skip the exceeding ones and return success. +There is no reliable way of detecting this condition once it has occurred. +It is therefore recommended to either determine the necessary buffer size +beforehand by calling +.B SIOCGIFCONF +with +.I ifc_req +set to NULL, or to retry the call with a bigger buffer whenever +.I ifc_len +upon return differs by less than +.I sizeof(struct ifreq) +from its original value. +.IP +If an error occurs accessing the +.I ifconf +or +.I ifreq +structures, +.B EFAULT +will be returned. +.\" Slaving isn't supported in Linux 2.2 +.\" . +.\" .TP +.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE +.\" Get or set the slave device using +.\" .IR ifr_slave . +.\" Setting the slave device is a privileged operation. +.\" .PP +.\" FIXME . add amateur radio stuff. +.PP +Most protocols support their own ioctls to configure protocol-specific +interface options. +See the protocol man pages for a description. +For configuring IP addresses, see +.BR ip (7). +.PP +In addition, some devices support private ioctls. +These are not described here. +.SH NOTES +.B SIOCGIFCONF +and the other ioctls that accept or return only +.B AF_INET +socket addresses +are IP-specific and perhaps should rather be documented in +.BR ip (7). +.PP +The names of interfaces with no addresses or that don't have the +.B IFF_RUNNING +flag set can be found via +.IR /proc/net/dev . +.PP +.B AF_INET6 +IPv6 addresses can be read from +.I /proc/net/if_inet6 +or via +.BR rtnetlink (7). +Adding a new IPv6 address and deleting an existing IPv6 address +can be done via +.B SIOCSIFADDR +and +.B SIOCDIFADDR +or via +.BR rtnetlink (7). +Retrieving or changing destination IPv6 addresses of a point-to-point +interface is possible only via +.BR rtnetlink (7). +.SH BUGS +glibc 2.1 is missing the +.I ifr_newname +macro in +.IR <net/if.h> . +Add the following to your program as a workaround: +.PP +.in +4n +.EX +#ifndef ifr_newname +#define ifr_newname ifr_ifru.ifru_slave +#endif +.EE +.in +.SH SEE ALSO +.BR proc (5), +.BR capabilities (7), +.BR ip (7), +.BR rtnetlink (7) |