diff options
Diffstat (limited to 'man7/netdevice.7')
| -rw-r--r-- | man7/netdevice.7 | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/man7/netdevice.7 b/man7/netdevice.7 new file mode 100644 index 000000000..4274136ae --- /dev/null +++ b/man7/netdevice.7 @@ -0,0 +1,264 @@ +'\" t +.\" Don't change the first line, it tells man that tbl is needed. +.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. +.\" Permission is granted to distribute possibly modified copies +.\" of this page provided the header is included verbatim, +.\" and in case of nontrivial modification author and date +.\" of the modification is added to the header. +.\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $ +.TH NETDEVICE 7 1999-05-02 "Linux Man Page" "Linux Programmer's Manual" +.SH NAME +netdevice \- Low level access to Linux network devices +.SH SYNOPSIS +.B "#include <sys/ioctl.h>" +.br +.B "#include <net/if.h>" +.SH DESCRIPTION +This man page describes the sockets interface which is used to configure +network devices. + +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. +They pass an +.B ifreq +structure: + +.nf +.ta 4 12 20 +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; + }; +}; + +struct ifconf { + int ifc_len; /* size of buffer */ + union { + char * ifc_buf; /* buffer address */ + struct ifreq *ifc_req; /* array of structures */ + }; +}; +.ta +.fi + +Normally, the user specifies which device to affect by setting +.B ifr_name +to the name of the interface. All other members of the structure may +share memory. + +.SH 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 +.BR ifr_ifindex , +return the name of the interface in +.BR ifr_name . +This is the only ioctl which returns its result in +.BR ifr_name . + +.TP +.B SIOCGIFINDEX +Retrieve the interface index of the interface into +.BR ifr_ifindex . + +.TP +.BR SIOCGIFFLAGS ", " SIOCSIFFLAGS +Get or set the active flag word of the device. +.B ifr_flags +contains a bitmask of the following values: + +.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:No arp protocol, L2 destination address not set. +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} +.TE + +Setting the active flag word is a privileged operation, but any +process may read it. +.TP +.BR SIOCGIFMETRIC ", " SIOCSIFMETRIC +Get or set the metric of the device using +.BR ifr_metric . +This is currently not implemented; it sets +.B 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 +.BR 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 +.BR 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 +.BR ifr_hwaddr . +This is a privileged operation. +.TP +.BR SIOCGIFMAP ", " SIOCSIFMAP +Get or set the interface's hardware parameters using +.BR ifr_map . +Setting the parameters is a privileged operation. + +.nf +.ta 4 20 42 +struct ifmap +{ + unsigned long mem_start; + unsigned long mem_end; + unsigned short base_addr; + unsigned char irq; + unsigned char dma; + unsigned char port; +}; +.ta +.fi + +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 +.BR 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 +.BR ifr_qlen . +Setting the transmit queue length is a privileged operation. +.TP +.B SIOCSIFNAME +Changes the name of the interface specified in +.BR ifr_name +to +.BR ifr_newname . +This is a privileged operation. It is only allowed when the interface +is not up. +.TP +.B SIOCGIFCONF +Return a list of interface (transport layer) addresses. This currently +means only addresses of the AF_INET (IPv4) family for compatibility. +The user passes a +.B ifconf +structure as argument to the ioctl. It contains a pointer to an array of +.I ifreq +structures in +.B ifc_req +and its length in bytes in +.B ifc_len. +The kernel fills the ifreqs with all current L3 interface addresses that +are running: +.I ifr_name +contains the interface name (eth0:1 etc.), +.I ifr_addr +the address. +The kernel returns with the actual length in +.IR ifc_len . +If +.I ifc_len +is equal to the original length the buffer probably has overflowed +and you should retry with a bigger buffer to get all addresses. +When no error occurs the ioctl returns 0; +otherwise \-1. Overflow is no error. +\" XXX Slaving isn't supported in 2.2 +.\" .TP +.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE +.\" Get or set the slave device using +.\" .BR ifr_slave . +.\" Setting the slave device is a privileged operation. +.\" .PP +.\" XXX 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 +Strictly seen, +.B SIOCGIFCONF +is IP specific and belongs in +.BR ip (7). +.LP +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 . +.LP +Local IPv6 IP addresses can be found via /proc/net or via +.BR rtnetlink (7). +.SH BUGS +glibc 2.1 is missing the +.I ifr_newname +macro in net/if.h. Add the following to your program as workaround: +.sp +.RS +.nf +.ta 4 20 42 +#ifndef ifr_newname +#define ifr_newname ifr_ifru.ifru_slave +#endif +.ta +.fi +.RE +.SH "SEE ALSO" +.BR capabilities (7), +.BR ip (7), +.BR proc (7), +.BR rtnetlink (7) |