2004-11-03 13:51:07 +00:00
|
|
|
'\" 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 $
|
2004-11-25 08:11:36 +00:00
|
|
|
.\"
|
|
|
|
.\" Modified, 2004-11-25, mtk, formatting and a few wording fixes
|
|
|
|
.\"
|
2007-05-18 10:09:18 +00:00
|
|
|
.TH NETDEVICE 7 1999-05-02 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.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.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
structure:
|
|
|
|
|
|
|
|
.nf
|
|
|
|
struct ifreq {
|
2004-11-25 08:11:36 +00:00
|
|
|
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;
|
|
|
|
};
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
struct ifconf {
|
2004-11-25 08:11:36 +00:00
|
|
|
int ifc_len; /* size of buffer */
|
2007-04-12 22:42:49 +00:00
|
|
|
union {
|
|
|
|
char * ifc_buf; /* buffer address */
|
2004-11-25 08:11:36 +00:00
|
|
|
struct ifreq * ifc_req; /* array of structures */
|
2007-04-12 22:42:49 +00:00
|
|
|
};
|
|
|
|
};
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
|
|
|
|
|
|
|
Normally, the user specifies which device to affect by setting
|
|
|
|
.B ifr_name
|
2007-04-12 22:42:49 +00:00
|
|
|
to the name of the interface.
|
|
|
|
All other members of the structure may
|
|
|
|
share memory.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SS Ioctls
|
2004-11-03 13:51:07 +00:00
|
|
|
If an ioctl is marked as privileged then using it requires an effective
|
2005-07-18 16:02:32 +00:00
|
|
|
user ID of 0 or the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B CAP_NET_ADMIN
|
2007-04-12 22:42:49 +00:00
|
|
|
capability.
|
|
|
|
If this is not the case
|
2004-11-03 13:51:07 +00:00
|
|
|
.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}
|
2007-04-12 22:42:49 +00:00
|
|
|
.TE
|
2004-11-03 13:51:07 +00:00
|
|
|
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 .
|
2007-04-12 22:42:49 +00:00
|
|
|
Setting the MTU is a privileged operation.
|
|
|
|
Setting the MTU to
|
2004-11-03 13:51:07 +00:00
|
|
|
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 .
|
2007-04-12 22:42:49 +00:00
|
|
|
.I sa_family
|
|
|
|
contains the ARPHRD_* device type,
|
2004-11-03 13:51:07 +00:00
|
|
|
.I sa_data
|
2007-04-12 22:42:49 +00:00
|
|
|
the L2 hardware address starting from byte 0.
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2006-01-03 10:58:34 +00:00
|
|
|
struct ifmap {
|
2004-11-25 08:11:36 +00:00
|
|
|
unsigned long mem_start;
|
|
|
|
unsigned long mem_end;
|
2007-04-12 22:42:49 +00:00
|
|
|
unsigned short base_addr;
|
|
|
|
unsigned char irq;
|
|
|
|
unsigned char dma;
|
|
|
|
unsigned char port;
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.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
|
2007-04-12 22:42:49 +00:00
|
|
|
Changes the name of the interface specified in
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR ifr_name
|
|
|
|
to
|
|
|
|
.BR ifr_newname .
|
2007-04-12 22:42:49 +00:00
|
|
|
This is a privileged operation.
|
|
|
|
It is only allowed when the interface
|
2004-11-03 13:51:07 +00:00
|
|
|
is not up.
|
|
|
|
.TP
|
|
|
|
.B SIOCGIFCONF
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
.B ifconf
|
2007-04-12 22:42:49 +00:00
|
|
|
structure as argument to the ioctl.
|
|
|
|
It contains a pointer to an array of
|
2004-11-03 13:51:07 +00:00
|
|
|
.I ifreq
|
2007-04-12 22:42:49 +00:00
|
|
|
structures in
|
2004-11-03 13:51:07 +00:00
|
|
|
.B ifc_req
|
2007-04-12 22:42:49 +00:00
|
|
|
and its length in bytes in
|
2005-07-19 15:36:19 +00:00
|
|
|
.BR ifc_len .
|
2004-11-03 13:51:07 +00:00
|
|
|
The kernel fills the ifreqs with all current L3 interface addresses that
|
2007-04-12 22:42:49 +00:00
|
|
|
are running:
|
|
|
|
.I ifr_name
|
|
|
|
contains the interface name (eth0:1 etc.),
|
2004-11-03 13:51:07 +00:00
|
|
|
.I ifr_addr
|
|
|
|
the address.
|
2007-04-12 22:42:49 +00:00
|
|
|
The kernel returns with the actual length in
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR ifc_len .
|
2007-04-12 22:42:49 +00:00
|
|
|
If
|
2004-11-03 13:51:07 +00:00
|
|
|
.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;
|
2007-04-12 22:42:49 +00:00
|
|
|
otherwise \-1.
|
|
|
|
Overflow is not an error.
|
2006-03-01 05:18:11 +00:00
|
|
|
.\" FIXME Slaving isn't supported in 2.2
|
2006-03-05 20:51:13 +00:00
|
|
|
.\" .
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" .TP
|
|
|
|
.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE
|
|
|
|
.\" Get or set the slave device using
|
|
|
|
.\" .BR ifr_slave .
|
|
|
|
.\" Setting the slave device is a privileged operation.
|
|
|
|
.\" .PP
|
2005-10-26 11:27:52 +00:00
|
|
|
.\" FIXME add amateur radio stuff.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR ip (7).
|
|
|
|
.PP
|
2007-04-12 22:42:49 +00:00
|
|
|
In addition some devices support private ioctls.
|
2006-01-03 10:58:34 +00:00
|
|
|
These are not described here.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
2004-11-25 08:11:36 +00:00
|
|
|
Strictly speaking,
|
2007-04-12 22:42:49 +00:00
|
|
|
.B SIOCGIFCONF
|
|
|
|
is IP specific and belongs in
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR ip (7).
|
|
|
|
.LP
|
|
|
|
The names of interfaces with no addresses or that don't have the
|
2007-04-12 22:42:49 +00:00
|
|
|
.B IFF_RUNNING
|
2004-11-03 13:51:07 +00:00
|
|
|
flag set can be found via
|
|
|
|
.IR /proc/net/dev .
|
|
|
|
.LP
|
2007-04-12 22:42:49 +00:00
|
|
|
Local IPv6 IP addresses can be found via /proc/net or via
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR rtnetlink (7).
|
|
|
|
.SH BUGS
|
2007-04-12 22:42:49 +00:00
|
|
|
glibc 2.1 is missing the
|
|
|
|
.I ifr_newname
|
|
|
|
macro in net/if.h.
|
|
|
|
Add the following to your program as a workaround:
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
#ifndef ifr_newname
|
|
|
|
#define ifr_newname ifr_ifru.ifru_slave
|
|
|
|
#endif
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.SH "SEE ALSO"
|
2007-06-01 05:24:33 +00:00
|
|
|
.BR proc (5),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR capabilities (7),
|
|
|
|
.BR ip (7),
|
|
|
|
.BR rtnetlink (7)
|