NAME

netdevice - 底層訪問 Linux 網絡設備.

總覽 (SYNOPSIS)

#include <sys/ioctl.h>
#include <net/if.h>

描述 (DESCRIPTION)

本手冊 描述 用于 配置 網絡設備 的 套接字(socket) 接口.

Linux 支持 一些 配置 網絡設備 的 標準 ioctl. 他們 用于 任意的 套接字 描述符, 而 無須 了解 其 類型 或 系列. 他們 傳遞 一個 ifreq 結構:

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 */
    };  
};     

一般說來, ioctl 通過 把 ifr_name 設置為 接口 的 名字 來 指定 將要 操作 的 設備. 結構的 其他成員 可以 分享 內存.

IOCTLS

如果 某個 ioctl 標記為 特權操作, 那么 操作時 需要 有效uid 為 0, 或者 擁有 CAP_NET_ADMIN 能力. 否則 將 返回 EPERM .

SIOCGIFNAME

給定 ifr_ifindex, 返回 ifr_name 中 的 接口名字. 這是 唯一 返回 ifr_name 內容 的 ioctl.

SIOCGIFINDEX

把 接口 的 索引 存入 ifr_ifindex.

SIOCGIFFLAGS, SIOCSIFFLAGS

讀取 或 設置 設備的 活動標志字. ifr_flags 包含 下列值 的 屏蔽位:

設備標志
IFF_UP	接口正在運行.
IFF_BROADCAST	有效的廣播地址集.
IFF_DEBUG	內部調試標志.
IFF_LOOPBACK	這是自環接口.
IFF_POINTOPOINT	這是點到點的鏈路接口.
IFF_RUNNING	資源已分配.
IFF_NOARP	無arp協議, 沒有設置第二層目的地址.
IFF_PROMISC	接口為雜湊(promiscuous)模式.
IFF_NOTRAILERS	避免使用trailer .
IFF_ALLMULTI	接收所有組播(multicast)報文.
IFF_MASTER	主負載平衡群(bundle).
IFF_SLAVE	從負載平衡群(bundle).
IFF_MULTICAST	支持組播(multicast).
IFF_PORTSEL	可以通過ifmap選擇介質(media)類型.
IFF_AUTOMEDIA	自動選擇介質.
IFF_DYNAMIC	接口關閉時丟棄地址.

設置 活動標志字 是 特權操作, 但是 任何進程 都可以 讀取 標志字.

SIOCGIFMETRIC, SIOCSIFMETRIC

使用 ifr_metric 讀取 或 設置 設備的 metric 值. 該功能 目前 還沒有 實現. 讀取操作 使 ifr_metric 置 0, 而 設置操作 則 返回 EOPNOTSUPP.

SIOCGIFMTU, SIOCSIFMTU

使用 ifr_mtu 讀取 或 設置 設備的 MTU(最大傳輸單元). 設置 MTU 是 特權操作. 過小的 MTU 可能 導致 內核 崩潰.

SIOCGIFHWADDR, SIOCSIFHWADDR

使用 ifr_hwaddr 讀取 或 設置 設備的 硬件地址. 設置 硬件地址 是 特權操作.

SIOCSIFHWBROADCAST

使用 ifr_hwaddr 讀取 或 設置 設備的 硬件廣播地址. 這是個 特權操作.

SIOCGIFMAP, SIOCSIFMAP

使用 ifr_map 讀取 或 設置 接口的 硬件參數. 設置 這個參數 是 特權操作.

struct ifmap 
{
    unsigned long   mem_start;
    unsigned long   mem_end;
    unsigned short  base_addr; 
    unsigned char   irq;                  
    unsigned char   dma; 
    unsigned char   port; 
};

對 ifmap 結構 的 解釋 取決于 設備驅動程序 和 體系結構.

SIOCADDMULTI, SIOCDELMULTI

使用 ifr_hwaddr 在 設備的 鏈路層 組播過濾器 (multicase filter) 中 添加 或 刪除 地址. 這些是 特權操作. 參看 packet(7).

SIOCGIFTXQLEN, SIOCSIFTXQLEN

使用 ifr_qlen 讀取 或 設置 設備的 傳輸隊列長度. 設置 傳輸隊列長度 是 特權操作.

SIOCSIFNAME

把 ifr_ifindex 中 指定的 接口名字 改成 ifr_newname. 這是個 特權操作.

SIOCGIFCONF

返回 接口地址(傳輸層) 列表. 出于 兼容性, 目前 只代表 AF_INET 地址. 用戶 傳送 一個 ifconf 結構 作為 ioctl 的 參數. 其中 ifc_req 包含 一個 指針 指向 ifreq 結構數組, 他的 長度 以字節 為單位 存放在 ifc_len 中. 內核 用 所有 當前的 L3(第三層?) 接口地址 填充 ifreqs, 這些 接口 正在 運行: ifr_name 存放 接口名字 (eth0:1等), ifr_addr 存放 地址. 內核 在 ifc_len 中 返回 實際長度; 如果 他 等于 初始長度, 表示 溢出了, 用戶 應該 換一個 大些的 緩沖區 重試 一下. 沒有 發生 錯誤時 ioctl 返回 0, 否則 返回 -1, 溢出 不算 錯誤.

大多數 協議 使用 自己的 ioctl 配置 協議 特定的 接口 操作. 具體 情況參看 協議的 幫助手冊. 要配置 IP 地址 可以 參看 ip(7).

另外, 某些 設備 有 專用的 ioctl, 這里 不做 敘述.

注意 (NOTE)

嚴格說來 SIOCGIFCONF 是 專門 針對 IP 的, 它 屬于 ip(7).

注意 (NOTE)

可以 通過 /proc/net/dev 看到 沒有 地址 或 沒有 IFF_RUNNING 標志 的 接口名字.

另見 (SEE ALSO)

ip(7), proc(7)

#p#

NAME

netdevice - Low level access to Linux network devices  

SYNOPSIS

#include <sys/ioctl.h>
#include <net/if.h>  

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 ifreq structure:

struct ifreq {
    char    ifr_name[IFNAMSIZ];/* Interface name */
    union {
            struct sockaddrifr_addr;
            struct sockaddrifr_dstaddr;
            struct sockaddrifr_broadaddr;
            struct sockaddrifr_netmask;
            struct sockaddrifr_hwaddr;
            short   ifr_flags;
            int     ifr_ifindex;
            int     ifr_metric;
            int     ifr_mtu;
            struct ifmapifr_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 */
    };  
};     

Normally, the user specifies which device to affect by setting ifr_name to the name of the interface. All other members of the structure may share memory.

IOCTLS

If an ioctl is marked as privileged then using it requires an effective user id of 0 or the CAP_NET_ADMIN capability. If this is not the case EPERM will be returned.

SIOCGIFNAME

Given the ifr_ifindex, return the name of the interface in ifr_name. This is the only ioctl which returns its result in ifr_name.

SIOCGIFINDEX

Retrieve the interface index of the interface into ifr_ifindex.

SIOCGIFFLAGS, SIOCSIFFLAGS

Get or set the active flag word of the device. ifr_flags contains a bitmask of the following values:

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	The addresses are lost when the interface goes down.

Setting the active flag word is a privileged operation, but any process may read it.

SIOCGIFMETRIC, SIOCSIFMETRIC

Get or set the metric of the device using ifr_metric. This is currently not implemented; it sets ifr_metric to 0 if you attempt to read it and returns EOPNOTSUPP if you attempt to set it.

SIOCGIFMTU, SIOCSIFMTU

Get or set the MTU (Maximum Transfer Unit) of a device using ifr_mtu. Setting the MTU is a privileged operation. Setting the MTU to too small values may cause kernel crashes.

SIOCGIFHWADDR, SIOCSIFHWADDR

Get or set the hardware address of a device using ifr_hwaddr. The hardware address is specified in a struct sockaddr. sa_family contains the ARPHRD_* device type, sa_data the L2 hardware address starting from byte 0. Setting the hardware address is a privileged operation.

SIOCSIFHWBROADCAST

Set the hardware broadcast address of a device from ifr_hwaddr. This is a privileged operation.

SIOCGIFMAP, SIOCSIFMAP

Get or set the interface's hardware parameters using ifr_map. Setting the parameters is a privileged operation.

struct ifmap 
{
    unsigned long   mem_start;
    unsigned long   mem_end;
    unsigned short  base_addr; 
    unsigned char   irq;                  
    unsigned char   dma; 
    unsigned char   port; 
};

The interpretation of the ifmap structure depends on the device driver and the architecture.

SIOCADDMULTI, SIOCDELMULTI

Add an address to or delete an address from the device's link layer multicast filters using ifr_hwaddr. These are privileged operations. See also packet(7) for an alternative.

SIOCGIFTXQLEN, SIOCSIFTXQLEN

Get or set the transmit queue length of a device using ifr_qlen. Setting the transmit queue length is a privileged operation.

SIOCSIFNAME

Changes the name of the interface specified in ifr_name to ifr_newname. This is a privileged operation. It is only allowed when the interface is not up.

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 ifconf structure as argument to the ioctl. It contains a pointer to an array of ifreq structures in ifc_req and its length in bytes in ifc_len. The kernel fills the ifreqs with all current L3 interface addresses that are running: ifr_name contains the interface name (eth0:1 etc.), ifr_addr the address. The kernel returns with the actual length in ifc_len. If 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.

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 ip(7).

In addition some devices support private ioctls. These are not described here.  

NOTES

Strictly seen, SIOCGIFCONF is IP specific and belongs in ip(7).

The names of interfaces with no addresses or that don't have the IFF_RUNNING flag set can be found via /proc/net/dev.

Local IPv6 IP addresses can be found via /proc/net or via rtnetlink(7).  

BUGS

glibc 2.1 is missing the ifr_newname macro in net/if.h. Add the following to your program as workaround:

#ifndef ifr_newname
#define ifr_newname     ifr_ifru.ifru_slave
#endif

SEE ALSO

ip(7), proc(7), rtnetlink(7)