diff options
Diffstat (limited to 'share/man/man9/ifnet.9')
| -rw-r--r-- | share/man/man9/ifnet.9 | 1363 |
1 files changed, 1363 insertions, 0 deletions
diff --git a/share/man/man9/ifnet.9 b/share/man/man9/ifnet.9 new file mode 100644 index 000000000000..532f6cd6e411 --- /dev/null +++ b/share/man/man9/ifnet.9 @@ -0,0 +1,1363 @@ +.\" -*- Nroff -*- +.\" Copyright 1996, 1997 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 14, 2007 +.Os +.Dt IFNET 9 +.Sh NAME +.Nm ifnet , +.Nm ifaddr , +.Nm ifqueue , +.Nm if_data +.Nd kernel interfaces for manipulating network interfaces +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/socket.h +.In net/if.h +.In net/if_var.h +.In net/if_types.h +.\" +.Ss "Interface Manipulation Functions" +.Ft "struct ifnet *" +.Fn if_alloc "u_char type" +.Ft void +.Fn if_attach "struct ifnet *ifp" +.Ft void +.Fn if_detach "struct ifnet *ifp" +.Ft void +.Fn if_free "struct ifnet *ifp" +.Ft void +.Fn if_free_type "struct ifnet *ifp" "u_char type" +.Ft void +.Fn if_down "struct ifnet *ifp" +.Ft int +.Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" +.Ft int +.Fn ifpromisc "struct ifnet *ifp" "int pswitch" +.Ft int +.Fn if_allmulti "struct ifnet *ifp" "int amswitch" +.Ft "struct ifnet *" +.Fn ifunit "const char *name" +.Ft void +.Fn if_up "struct ifnet *ifp" +.\" +.Ss "Interface Address Functions" +.Ft "struct ifaddr *" +.Fn ifa_ifwithaddr "struct sockaddr *addr" +.Ft "struct ifaddr *" +.Fn ifa_ifwithdstaddr "struct sockaddr *addr" +.Ft "struct ifaddr *" +.Fn ifa_ifwithnet "struct sockaddr *addr" +.Ft "struct ifaddr *" +.Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" +.Ft void +.Fn ifafree "struct ifaddr *ifa" +.Fn IFAFREE "struct ifaddr *ifa" +.\" +.Ss "Interface Multicast Address Functions" +.Ft int +.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" +.Ft int +.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" +.Ft "struct ifmultiaddr *" +.Fn ifmaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" +.Ss "Output queue macros" +.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" +.\" +.Ss "struct ifnet Member Functions" +.Ft void +.Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m" +.Ft int +.Fo \*(lp*if_output\*(rp +.Fa "struct ifnet *ifp" "struct mbuf *m" +.Fa "struct sockaddr *dst" "struct rtentry *rt" +.Fc +.Ft void +.Fn \*(lp*if_start\*(rp "struct ifnet *ifp" +.Ft int +.Fn \*(lp*if_transmit\*(rp "struct ifnet *ifp" "struct mbuf *m" +.Ft void +.Fn \*(lp*if_qflush\*(rp "struct ifnet *ifp" +.Ft int +.Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "int cmd" "caddr_t data" +.Ft void +.Fn \*(lp*if_watchdog\*(rp "struct ifnet *ifp" +.Ft void +.Fn \*(lp*if_init\*(rp "void *if_softc" +.Ft int +.Fo \*(lp*if_resolvemulti\*(rp +.Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" +.Fc +.Ss "struct ifaddr member function" +.Ft void +.Fo \*(lp*ifa_rtrequest\*(rp +.Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst" +.Fc +.\" +.Ss "Global Variables" +.Vt extern struct ifnethead ifnet ; +.Vt extern struct ifaddr **ifnet_addrs ; +.Vt extern int if_index ; +.Vt extern int ifqmaxlen ; +.Sh DATA STRUCTURES +The kernel mechanisms for handling network interfaces reside primarily +in the +.Vt ifnet , if_data , ifaddr , +and +.Vt ifmultiaddr +structures in +.In net/if.h +and +.In net/if_var.h +and the functions named above and defined in +.Pa /sys/net/if.c . +Those interfaces which are intended to be used by user programs +are defined in +.In net/if.h ; +these include the interface flags, the +.Vt if_data +structure, and the structures defining the appearance of +interface-related messages on the +.Xr route 4 +routing socket and in +.Xr sysctl 3 . +The header file +.In net/if_var.h +defines the kernel-internal interfaces, including the +.Vt ifnet , ifaddr , +and +.Vt ifmultiaddr +structures and the functions which manipulate them. +(A few user programs will need +.In net/if_var.h +because it is the prerequisite of some other header file like +.In netinet/if_ether.h . +Most references to those two files in particular can be replaced by +.In net/ethernet.h . ) +.Pp +The system keeps a linked list of interfaces using the +.Li TAILQ +macros defined in +.Xr queue 3 ; +this list is headed by a +.Vt "struct ifnethead" +called +.Va ifnet . +The elements of this list are of type +.Vt "struct ifnet" , +and most kernel routines which manipulate interface as such accept or +return pointers to these structures. +Each interface structure +contains an +.Vt if_data +structure, which contains statistics and identifying information used +by management programs, and which is exported to user programs by way +of the +.Xr ifmib 4 +branch of the +.Xr sysctl 3 +MIB. +Each interface also has a +.Li TAILQ +of interface addresses, described by +.Vt ifaddr +structures; the head of the queue is always an +.Dv AF_LINK +address +(see +.Xr link_addr 3 ) +describing the link layer implemented by the interface (if any). +(Some trivial interfaces do not provide any link layer addresses; +this structure, while still present, serves only to identify the +interface name and index.) +.Pp +Finally, those interfaces supporting reception of multicast datagrams +have a +.Li TAILQ +of multicast group memberships, described by +.Vt ifmultiaddr +structures. +These memberships are reference-counted. +.Pp +Interfaces are also associated with an output queue, defined as a +.Vt "struct ifqueue" ; +this structure is used to hold packets while the interface is in the +process of sending another. +.Pp +.Ss The Vt ifnet Ss structure +The fields of +.Vt "struct ifnet" +are as follows: +.Bl -tag -width ".Va if_capabilities" -offset indent +.It Va if_softc +.Pq Vt "void *" +A pointer to the driver's private state block. +(Initialized by driver.) +.It Va if_l2com +.Pq Vt "void *" +A pointer to the common data for the interface's layer 2 protocol. +(Initialized by +.Fn if_alloc . ) +.It Va if_link +.Pq Fn TAILQ_ENTRY ifnet +.Xr queue 3 +macro glue. +.It Va if_xname +.Pq Vt "char *" +The name of the interface, +(e.g., +.Dq Li fxp0 +or +.Dq Li lo0 ) . +(Initialized by driver.) +.It Va if_dname +.Pq Vt "const char *" +The name of the driver. +(Initialized by driver.) +.It Va if_dunit +.Pq Vt int +A unique number assigned to each interface managed by a particular +driver. +Drivers may choose to set this to +.Dv IF_DUNIT_NONE +if a unit number is not associated with the device. +(Initialized by driver.) +.It Va if_addrhead +.Pq Vt "struct ifaddrhead" +The head of the +.Xr queue 3 +.Li TAILQ +containing the list of addresses assigned to this interface. +.It Va if_pcount +.Pq Vt int +A count of promiscuous listeners on this interface, used to +reference-count the +.Dv IFF_PROMISC +flag. +.It Va if_bpf +.Pq Vt "struct bpf_if *" +Opaque per-interface data for the packet filter, +.Xr bpf 4 . +(Initialized by +.Fn bpf_attach . ) +.It Va if_index +.Pq Vt u_short +A unique number assigned to each interface in sequence as it is +attached. +This number can be used in a +.Vt "struct sockaddr_dl" +to refer to a particular interface by index +(see +.Xr link_addr 3 ) . +(Initialized by +.Fn if_alloc . ) +.It Va if_timer +.Pq Vt short +Number of seconds until the watchdog timer +.Fn if_watchdog +is called, or zero if the timer is disabled. +(Set by driver, +decremented by generic watchdog code.) +.It Va if_flags +.Pq Vt int +Flags describing operational parameters of this interface (see below). +(Manipulated by both driver and generic code.) +.It Va if_capabilities +.Pq Vt int +Flags describing the capabilities the interface supports (see below). +.It Va if_capenable +.Pq Vt int +Flags describing the enabled capabilities of the interface (see below). +.\" .It Va if_ipending +.\" Interrupt-pending bits for polled operation: +.\" .Dv IFI_XMIT +.\" (transmit complete interrupt) +.\" and +.\" .Dv IFI_RECV +.\" (received packet ready interrupt). +.\" See the +.\" .Sx Polling +.\" section, below. +.\" (Manipulated by driver.) +.It Va if_linkmib +.Pq Vt "void *" +A pointer to an interface-specific MIB structure exported by +.Xr ifmib 4 . +(Initialized by driver.) +.It Va if_linkmiblen +.Pq Vt size_t +The size of said structure. +(Initialized by driver.) +.It Va if_data +.Pq Vt "struct if_data" +More statistics and information; see +.Sx "The if_data structure" , +below. +(Initialized by driver, manipulated by both driver and generic +code.) +.It Va if_snd +.Pq Vt "struct ifqueue" +The output queue. +(Manipulated by driver.) +.\".It Va if_poll_slowq +.\".Pq Vt "struct ifqueue *" +.\"A pointer to the input queue for devices which do not support polling +.\"well. +.\"See the +.\".Sx Polling +.\"section, below. +.\"(Initialized by driver.) +.El +.Pp +There are in addition a number of function pointers which the driver +must initialize to complete its interface with the generic interface +layer: +.Bl -ohang -offset indent +.It Fn if_input +Pass a packet to an appropriate upper layer as determined +from the link-layer header of the packet. +This routine is to be called from an interrupt handler or +used to emulate reception of a packet on this interface. +A single function implementing +.Fn if_input +can be shared among multiple drivers utilizing the same link-layer +framing, e.g., Ethernet. +.It Fn if_output +Output a packet on interface +.Fa ifp , +or queue it on the output queue if the interface is already active. +.It Fn if_transmit +Transmit a packet on an interface or queue it if the interface is +in use. This function will return +.Dv ENOBUFS +if the devices software and hardware queues are both full. This +function must be installed after +.It Fn if_qflush +Free mbufs in internally managed queues when the interface is marked down. +This function must be installed after +.Fn if_attach +to override the default implementation. This function is exposed in order +to allow drivers to manage their own queues and to reduce the latency +caused by a frequently gratuitous enqueue / dequeue pair to ifq. The +suggested internal software queueing mechanism is buf_ring. +.It Fn if_start +Start queued output on an interface. +This function is exposed in +order to provide for some interface classes to share a +.Fn if_output +among all drivers. +.Fn if_start +may only be called when the +.Dv IFF_OACTIVE +flag is not set. +(Thus, +.Dv IFF_OACTIVE +does not literally mean that output is active, but rather that the +device's internal output queue is full.) Please note that this function +will soon be deprecated. +.It Fn if_done +Not used. +We are not even sure what it was ever for. +The prototype is faked. +.It Fn if_ioctl +Process interface-related +.Xr ioctl 2 +requests +(defined in +.In sys/sockio.h ) . +Preliminary processing is done by the generic routine +.Fn ifioctl +to check for appropriate privileges, locate the interface being +manipulated, and perform certain generic operations like twiddling +flags and flushing queues. +See the description of +.Fn ifioctl +below for more information. +.It Fn if_watchdog +Routine called by the generic code when the watchdog timer, +.Va if_timer , +expires. +Usually this will reset the interface. +.\" .It Fn if_poll_recv +.\" .It Fn if_poll_xmit +.\" .It Fn if_poll_slowinput +.\" .It Fn if_poll_intren +.\" See the +.\" .Sx Polling +.\" section, below. +.It Fn if_init +Initialize and bring up the hardware, +e.g., reset the chip and the watchdog timer and enable the receiver unit. +Should mark the interface running, +but not active +.Dv ( IFF_RUNNING , ~IIF_OACTIVE ) . +.It Fn if_resolvemulti +Check the requested multicast group membership, +.Fa addr , +for validity, and if necessary compute a link-layer group which +corresponds to that address which is returned in +.Fa *retsa . +Returns zero on success, or an error code on failure. +.El +.Ss "Interface Flags" +Interface flags are used for a number of different purposes. +Some +flags simply indicate information about the type of interface and its +capabilities; others are dynamically manipulated to reflect the +current state of the interface. +Flags of the former kind are marked +.Aq S +in this table; the latter are marked +.Aq D . +.Pp +The macro +.Dv IFF_CANTCHANGE +defines the bits which cannot be set by a user program using the +.Dv SIOCSIFFLAGS +command to +.Xr ioctl 2 ; +these are indicated by an asterisk +.Pq Ql * +in the following listing. +.Pp +.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact +.It Dv IFF_UP +.Aq D +The interface has been configured up by the user-level code. +.It Dv IFF_BROADCAST +.Aq S* +The interface supports broadcast. +.It Dv IFF_DEBUG +.Aq D +Used to enable/disable driver debugging code. +.It Dv IFF_LOOPBACK +.Aq S +The interface is a loopback device. +.It Dv IFF_POINTOPOINT +.Aq S* +The interface is point-to-point; +.Dq broadcast +address is actually the address of the other end. +.It Dv IFF_RUNNING +.Aq D* +The interface has been configured and dynamic resources were +successfully allocated. +Probably only useful internal to the +interface. +.It Dv IFF_NOARP +.Aq D +Disable network address resolution on this interface. +.It Dv IFF_PROMISC +.Aq D* +This interface is in promiscuous mode. +.It Dv IFF_PPROMISC +.Aq D +This interface is in the permanently promiscuous mode (implies +.Dv IFF_PROMISC ) . +.It Dv IFF_ALLMULTI +.Aq D* +This interface is in all-multicasts mode (used by multicast routers). +.It Dv IFF_OACTIVE +.Aq D* +The interface's hardware output queue (if any) is full; output packets +are to be queued. +.It Dv IFF_SIMPLEX +.Aq S* +The interface cannot hear its own transmissions. +.It Dv IFF_LINK0 +.It Dv IFF_LINK1 +.It Dv IFF_LINK2 +.Aq D +Control flags for the link layer. +(Currently abused to select among +multiple physical layers on some devices.) +.It Dv IFF_MULTICAST +.Aq S* +This interface supports multicast. +.It Dv IFF_POLLING +.Aq D* +The interface is in +.Xr polling 4 +mode. +See +.Sx Interface Capabilities Flags +for details. +.El +.Ss "Interface Capabilities Flags" +Interface capabilities are specialized features an interface may +or may not support. +These capabilities are very hardware-specific +and allow, when enabled, +to offload specific network processing to the interface +or to offer a particular feature for use by other kernel parts. +.Pp +It should be stressed that a capability can be completely +uncontrolled (i.e., stay always enabled with no way to disable it) +or allow limited control over itself (e.g., depend on another +capability's state.) +Such peculiarities are determined solely by the hardware and driver +of a particular interface. +Only the driver possesses +the knowledge on whether and how the interface capabilities +can be controlled. +Consequently, capabilities flags in +.Va if_capenable +should never be modified directly by kernel code other than +the interface driver. +The command +.Dv SIOCSIFCAP +to +.Fn ifioctl +is the dedicated means to attempt altering +.Va if_capenable +on an interface. +Userland code shall use +.Xr ioctl 2 . +.Pp +The following capabilities are currently supported by the system: +.Bl -tag -width ".Dv IFCAP_VLAN_HWTAGGING" -offset indent +.It Dv IFCAP_NETCONS +This interface can be a network console. +.It Dv IFCAP_POLLING +This interface supports +.Xr polling 4 . +See below for details. +.It Dv IFCAP_RXCSUM +This interface can do checksum validation on receiving data. +Some interfaces do not have sufficient buffer storage to store frames +above a certain MTU-size completely. +The driver for the interface might disable hardware checksum validation +if the MTU is set above the hardcoded limit. +.It Dv IFCAP_TXCSUM +This interface can do checksum calculation on transmitting data. +.It Dv IFCAP_HWCSUM +A shorthand for +.Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . +.It Dv IFCAP_VLAN_HWTAGGING +This interface can do VLAN tagging on output and +demultiplex frames by their VLAN tag on input. +.It Dv IFCAP_VLAN_MTU +The +.Xr vlan 4 +driver can operate over this interface in software tagging mode +without having to decrease MTU on +.Xr vlan 4 +interfaces below 1500 bytes. +This implies the ability of this interface to cope with frames somewhat +longer than permitted by the Ethernet specification. +.It Dv IFCAP_JUMBO_MTU +This Ethernet interface can transmit and receive frames up to +9000 bytes long. +.El +.Pp +The ability of advanced network interfaces to offload certain +computational tasks from the host CPU to the board is limited +mostly to TCP/IP. +Therefore a separate field associated with an interface +(see +.Va ifnet.if_data.ifi_hwassist +below) +keeps a detailed description of its enabled capabilities +specific to TCP/IP processing. +The TCP/IP module consults the field to see which tasks +can be done on an +.Em outgoing +packet by the interface. +The flags defined for that field are a superset of those for +.Va mbuf.m_pkthdr.csum_flags , +namely: +.Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent +.It Dv CSUM_IP +The interface will compute IP checksums. +.It Dv CSUM_TCP +The interface will compute TCP checksums. +.It Dv CSUM_UDP +The interface will compute UDP checksums. +.It Dv CSUM_IP_FRAGS +The interface can compute a TCP or UDP checksum for a packet +fragmented by the host CPU. +Makes sense only along with +.Dv CSUM_TCP +or +.Dv CSUM_UDP . +.It Dv CSUM_FRAGMENT +The interface will do the fragmentation of IP packets if necessary. +The host CPU does not need to care about MTU on this interface +as long as a packet to transmit through it is an IP one and it +does not exceed the size of the hardware buffer. +.El +.Pp +An interface notifies the TCP/IP module about the tasks +the former has performed on an +.Em incoming +packet by setting the corresponding flags in the field +.Va mbuf.m_pkthdr.csum_flags +of the +.Vt mbuf chain +containing the packet. +See +.Xr mbuf 9 +for details. +.Pp +The capability of a network interface to operate in +.Xr polling 4 +mode involves several flags in different +global variables and per-interface fields. +First, there is a system-wide +.Xr sysctl 8 +master switch named +.Va kern.polling.enable , +which can toggle +.Xr polling 4 +globally. +If that variable is set to non-zero, +.Xr polling 4 +will be used on those devices where it is enabled individually. +Otherwise, +.Xr polling 4 +will not be used in the system. +Second, the capability flag +.Dv IFCAP_POLLING +set in interface's +.Va if_capabilities +indicates support for +.Xr polling 4 +on the particular interface. +If set in +.Va if_capabilities , +the same flag can be marked or cleared in the interface's +.Va if_capenable , +thus initiating switch of the interface to +.Xr polling 4 +mode or interrupt +mode, respectively. +The actual mode change will occur at an implementation-specific moment +in the future, e.g., during the next interrupt or +.Xr polling 4 +cycle. +And finally, if the mode transition has been successful, the flag +.Dv IFF_POLLING +is marked or cleared in the interface's +.Va if_flags +to indicate the current mode of the interface. +.Ss The Vt if_data Ss Structure +In +.Bx 4.4 , +a subset of the interface information believed to be of interest to +management stations was segregated from the +.Vt ifnet +structure and moved into its own +.Vt if_data +structure to facilitate its use by user programs. +The following elements of the +.Vt if_data +structure are initialized by the interface and are not expected to change +significantly over the course of normal operation: +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_type +.Pq Vt u_char +The type of the interface, as defined in +.In net/if_types.h +and described below in the +.Sx "Interface Types" +section. +.It Va ifi_physical +.Pq Vt u_char +Intended to represent a selection of physical layers on devices which +support more than one; never implemented. +.It Va ifi_addrlen +.Pq Vt u_char +Length of a link-layer address on this device, or zero if there are +none. +Used to initialized the address length field in +.Vt sockaddr_dl +structures referring to this interface. +.It Va ifi_hdrlen +.Pq Vt u_char +Maximum length of any link-layer header which might be prepended by +the driver to a packet before transmission. +The generic code computes +the maximum over all interfaces and uses that value to influence the +placement of data in +.Vt mbuf Ns s +to attempt to ensure that there is always +sufficient space to prepend a link-layer header without allocating an +additional +.Vt mbuf . +.\" (See +.\" .Xr mbuf 9 . ) +.\" .It Va ifi_recvquota +.\" .Pq Vt u_char +.\" Number of packets the interface is permitted to receive at one time +.\" when in polled mode. +.\" .It Va ifi_xmitquota +.\" .Pq Vt u_char +.\" Number of packets the interface is permitted to queue for transmission +.\" at one time when in polled mode. +.\" There is some controversy over +.\" whether such a restriction makes any sense at all. +.It Va ifi_datalen +.Pq Vt u_char +Length of the +.Vt if_data +structure. +Allows some stabilization of the routing socket ABI in the face of +increases in the length of +.Vt struct ifdata . +.It Va ifi_mtu +.Pq Vt u_long +The maximum transmission unit of the medium, exclusive of any +link-layer overhead. +.It Va ifi_metric +.Pq Vt u_long +A dimensionless metric interpreted by a user-mode routing process. +.It Va ifi_baudrate +.Pq Vt u_long +The line rate of the interface, in bits per second. +.It Va ifi_hwassist +.Pq Vt u_long +A detailed interpretation of the capabilities +to offload computational tasks for +.Em outgoing +packets. +The interface driver must keep this field in accord with +the current value of +.Va if_capenable . +.It Va ifi_epoch +.Pq Vt time_t +The system uptime when interface was attached or the statistics +below were reset. +This is intended to be used to set the SNMP variable +.Va ifCounterDiscontinuityTime . +It may also be used to determine if two successive queries for an +interface of the same index have returned results for the same +interface. +.El +.Pp +The structure additionally contains generic statistics applicable to a +variety of different interface types (except as noted, all members are +of type +.Vt u_long ) : +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_link_state +.Pq Vt u_char +The current link state of Ethernet interfaces. +See the +.Sx Interface Link States +section for possible values. +.It Va ifi_ipackets +Number of packets received. +.It Va ifi_ierrors +Number of receive errors detected (e.g., FCS errors, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_opackets +Number of packets transmitted. +.It Va ifi_oerrors +Number of output errors detected (e.g., late collisions, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_collisions +Total number of collisions detected on output for CSMA interfaces. +(This member is sometimes [ab]used by other types of interfaces for +other output error counts.) +.It Va ifi_ibytes +Total traffic received, in bytes. +.It Va ifi_obytes +Total traffic transmitted, in bytes. +.It Va ifi_imcasts +Number of packets received which were sent by link-layer multicast. +.It Va ifi_omcasts +Number of packets sent by link-layer multicast. +.It Va ifi_iqdrops +Number of packets dropped on input. +Rarely implemented. +.It Va ifi_noproto +Number of packets received for unknown network-layer protocol. +.\" .It Va ifi_recvtiming +.\" Amount of time, in microseconds, spent to receive an average packet on +.\" this interface. +.\" See the +.\" .Sx Polling +.\" section, below. +.\" .It Va ifi_xmittiming +.\" Amount of time, in microseconds, spent to service a transmit-complete +.\" interrupt on this interface. +.\" See the +.\" .Sx Polling +.\" section, below. +.It Va ifi_lastchange +.Pq Vt "struct timeval" +The time of the last administrative change to the interface (as required +for +.Tn SNMP ) . +.El +.Ss Interface Types +The header file +.In net/if_types.h +defines symbolic constants for a number of different types of +interfaces. +The most common are: +.Pp +.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact +.It Dv IFT_OTHER +none of the following +.It Dv IFT_ETHER +Ethernet +.It Dv IFT_ISO88023 +ISO 8802-3 CSMA/CD +.It Dv IFT_ISO88024 +ISO 8802-4 Token Bus +.It Dv IFT_ISO88025 +ISO 8802-5 Token Ring +.It Dv IFT_ISO88026 +ISO 8802-6 DQDB MAN +.It Dv IFT_FDDI +FDDI +.It Dv IFT_PPP +Internet Point-to-Point Protocol +.Pq Xr ppp 8 +.It Dv IFT_LOOP +The loopback +.Pq Xr lo 4 +interface +.It Dv IFT_SLIP +Serial Line IP +.It Dv IFT_PARA +Parallel-port IP +.Pq Dq Tn PLIP +.It Dv IFT_ATM +Asynchronous Transfer Mode +.El +.Ss Interface Link States +The following link states are currently defined: +.Pp +.Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact +.It Dv LINK_STATE_UNKNOWN +The link is in an invalid or unknown state. +.It Dv LINK_STATE_DOWN +The link is down. +.It Dv LINK_STATE_UP +The link is up. +.El +.Ss The Vt ifaddr Ss Structure +Every interface is associated with a list +(or, rather, a +.Li TAILQ ) +of addresses, rooted at the interface structure's +.Va if_addrlist +member. +The first element in this list is always an +.Dv AF_LINK +address representing the interface itself; multi-access network +drivers should complete this structure by filling in their link-layer +addresses after calling +.Fn if_attach . +Other members of the structure represent network-layer addresses which +have been configured by means of the +.Dv SIOCAIFADDR +command to +.Xr ioctl 2 , +called on a socket of the appropriate protocol family. +The elements of this list consist of +.Vt ifaddr +structures. +Most protocols will declare their own protocol-specific +interface address structures, but all begin with a +.Vt "struct ifaddr" +which provides the most-commonly-needed functionality across all +protocols. +Interface addresses are reference-counted. +.Pp +The members of +.Vt "struct ifaddr" +are as follows: +.Bl -tag -width ".Va ifa_rtrequest" -offset indent +.It Va ifa_addr +.Pq Vt "struct sockaddr *" +The local address of the interface. +.It Va ifa_dstaddr +.Pq Vt "struct sockaddr *" +The remote address of point-to-point interfaces, and the broadcast +address of broadcast interfaces. +.Va ( ifa_broadaddr +is a macro for +.Va ifa_dstaddr . ) +.It Va ifa_netmask +.Pq Vt "struct sockaddr *" +The network mask for multi-access interfaces, and the confusion +generator for point-to-point interfaces. +.It Va ifa_ifp +.Pq Vt "struct ifnet *" +A link back to the interface structure. +.It Va ifa_link +.Pq Fn TAILQ_ENTRY ifaddr +.Xr queue 3 +glue for list of addresses on each interface. +.It Va ifa_rtrequest +See below. +.It Va ifa_flags +.Pq Vt u_short +Some of the flags which would be used for a route representing this +address in the route table. +.It Va ifa_refcnt +.Pq Vt short +The reference count. +.It Va ifa_metric +.Pq Vt int +A metric associated with this interface address, for the use of some +external routing protocol. +.El +.Pp +References to +.Vt ifaddr +structures are gained manually, by incrementing the +.Va ifa_refcnt +member. +References are released by calling either the +.Fn ifafree +function or the +.Fn IFAFREE +macro. +.Pp +.Fn ifa_rtrequest +is a pointer to a function which receives callouts from the routing +code +.Pq Fn rtrequest +to perform link-layer-specific actions upon requests to add, resolve, +or delete routes. +The +.Fa cmd +argument indicates the request in question: +.Dv RTM_ADD , RTM_RESOLVE , +or +.Dv RTM_DELETE . +The +.Fa rt +argument is the route in question; the +.Fa dst +argument is the specific destination being manipulated +for +.Dv RTM_RESOLVE , +or a null pointer otherwise. +.Sh FUNCTIONS +The functions provided by the generic interface code can be divided +into two groups: those which manipulate interfaces, and those which +manipulate interface addresses. +In addition to these functions, there +may also be link-layer support routines which are used by a number of +drivers implementing a specific link layer over different hardware; +see the documentation for that link layer for more details. +.Ss The Vt ifmultiaddr Ss Structure +Every multicast-capable interface is associated with a list of +multicast group memberships, which indicate at a low level which +link-layer multicast addresses (if any) should be accepted, and at a +high level, in which network-layer multicast groups a user process has +expressed interest. +.Pp +The elements of the structure are as follows: +.Bl -tag -width ".Va ifma_refcount" -offset indent +.It Va ifma_link +.Pq Fn LIST_ENTRY ifmultiaddr +.Xr queue 3 +macro glue. +.It Va ifma_addr +.Pq Vt "struct sockaddr *" +A pointer to the address which this record represents. +The +memberships for various address families are stored in arbitrary +order. +.It Va ifma_lladdr +.Pq Vt "struct sockaddr *" +A pointer to the link-layer multicast address, if any, to which the +network-layer multicast address in +.Va ifma_addr +is mapped, else a null pointer. +If this element is non-nil, this +membership also holds an invisible reference to another membership for +that link-layer address. +.It Va ifma_refcount +.Pq Vt u_int +A reference count of requests for this particular membership. +.El +.Ss Interface Manipulation Functions +.Bl -ohang -offset indent +.It Fn if_alloc +Allocate and initialize +.Vt "struct ifnet" . +Initialization includes the allocation of an interface index and may +include the allocation of a +.Fa type +specific structure in +.Va if_l2com . +.It Fn if_attach +Link the specified interface +.Fa ifp +into the list of network interfaces. +Also initialize the list of +addresses on that interface, and create a link-layer +.Vt ifaddr +structure to be the first element in that list. +(A pointer to +this address structure is saved in the global array +.Va ifnet_addrs . ) +The +.Fa ifp +must have been allocated by +.Fn if_alloc . +.It Fn if_detach +Shut down and unlink the specified +.Fa ifp +from the interface list. +.It Fn if_free +Free the given +.Fa ifp +back to the system. +The interface must have been previously detached if it was ever attached. +.It Fn if_free_type +Identical to +.Fn if_free +except that the given +.Fa type +is used to free +.Va if_l2com +instead of the type in +.Va if_type . +This is intended for use with drivers that change their interface type. +.It Fn if_down +Mark the interface +.Fa ifp +as down (i.e., +.Dv IFF_UP +is not set), +flush its output queue, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn if_up +Mark the interface +.Fa ifp +as up, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn ifpromisc +Add or remove a promiscuous reference to +.Fa ifp . +If +.Fa pswitch +is true, add a reference; +if it is false, remove a reference. +On reference count transitions +from zero to one and one to zero, set the +.Dv IFF_PROMISC +flag appropriately and call +.Fn if_ioctl +to set up the interface in the desired mode. +.It Fn if_allmulti +As +.Fn ifpromisc , +but for the all-multicasts +.Pq Dv IFF_ALLMULTI +flag instead of the promiscuous flag. +.It Fn ifunit +Return an +.Vt ifnet +pointer for the interface named +.Fa name . +.It Fn ifioctl +Process the ioctl request +.Fa cmd , +issued on socket +.Fa so +by thread +.Fa td , +with data parameter +.Fa data . +This is the main routine for handling all interface configuration +requests from user mode. +It is ordinarily only called from the socket-layer +.Xr ioctl 2 +handler, and only for commands with class +.Sq Li i . +Any unrecognized commands will be passed down to socket +.Fa so Ns 's +protocol for +further interpretation. +The following commands are handled by +.Fn ifioctl : +.Pp +.Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact +.It Dv SIOCGIFCONF +.It Dv OSIOCGIFCONF +Get interface configuration. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFNAME +Set the interface name. +.Dv RTM_IFANNOUNCE +departure and arrival messages are sent so that +routing code that relies on the interface name will update its interface +list. +Caller must have appropriate privilege. +(No call-down to driver.) +.It Dv SIOCGIFCAP +.It Dv SIOCGIFFLAGS +.It Dv SIOCGIFMETRIC +.It Dv SIOCGIFMTU +.It Dv SIOCGIFPHYS +Get interface capabilities, flags, metric, MTU, medium selection. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFCAP +Enable or disable interface capabilities. +Caller must have appropriate privilege. +Before a call to the driver-specific +.Fn if_ioctl +routine, the requested mask for enabled capabilities is checked +against the mask of capabilities supported by the interface, +.Va if_capabilities . +Requesting to enable an unsupported capability is invalid. +The rest is supposed to be done by the driver, +which includes updating +.Va if_capenable +and +.Va if_data.ifi_hwassist +appropriately. +.Pp +.It Dv SIOCSIFFLAGS +Change interface flags. +Caller must have appropriate privilege. +If a change to the +.Dv IFF_UP +flag is requested, +.Fn if_up +or +.Fn if_down +is called as appropriate. +Flags listed in +.Dv IFF_CANTCHANGE +are masked off, and the field +.Va if_flags +in the interface structure is updated. +Finally, the driver +.Fn if_ioctl +routine is called to perform any setup +requested. +.Pp +.It Dv SIOCSIFMETRIC +.It Dv SIOCSIFPHYS +Change interface metric or medium. +Caller must have appropriate privilege. +.Pp +.It Dv SIOCSIFMTU +Change interface MTU. +Caller must have appropriate privilege. +MTU +values less than 72 or greater than 65535 are considered invalid. +The driver +.Fn if_ioctl +routine is called to implement the change; it is responsible for any +additional sanity checking and for actually modifying the MTU in the +interface structure. +.Pp +.It Dv SIOCADDMULTI +.It Dv SIOCDELMULTI +Add or delete permanent multicast group memberships on the interface. +Caller must have appropriate privilege. +The +.Fn if_addmulti +or +.Fn if_delmulti +function is called to perform the operation; qq.v. +.Pp +.It Dv SIOCSIFDSTADDR +.It Dv SIOCSIFADDR +.It Dv SIOCSIFBRDADDR +.It Dv SIOCSIFNETMASK +The socket's protocol control routine is called to implement the +requested action. +.Pp +.It Dv OSIOGIFADDR +.It Dv OSIOCGIFDSTADDR +.It Dv OSIOCGIFBRDADDR +.It Dv OSIOCGIFNETMASK +The socket's protocol control routine is called to implement the +requested action. +On return, +.Vt sockaddr +structures are converted into old-style (no +.Va sa_len +member). +.El +.El +.Pp +.Fn if_down , +.Fn ifioctl , +.Fn ifpromisc , +and +.Fn if_up +must be called at +.Fn splnet +or higher. +.Ss "Interface Address Functions" +Several functions exist to look up an interface address structure +given an address. +.Fn ifa_ifwithaddr +returns an interface address with either a local address or a +broadcast address precisely matching the parameter +.Fa addr . +.Fn ifa_ifwithdstaddr +returns an interface address for a point-to-point interface whose +remote +.Pq Dq destination +address is +.Fa addr . +.Pp +.Fn ifa_ifwithnet +returns the most specific interface address which matches the +specified address, +.Fa addr , +subject to its configured netmask, or a point-to-point interface +address whose remote address is +.Fa addr +if one is found. +.Pp +.Fn ifaof_ifpforaddr +returns the most specific address configured on interface +.Fa ifp +which matches address +.Fa addr , +subject to its configured netmask. +If the interface is +point-to-point, only an interface address whose remote address is +precisely +.Fa addr +will be returned. +.Pp +All of these functions return a null pointer if no such address can be +found. +.Ss "Interface Multicast Address Functions" +The +.Fn if_addmulti , +.Fn if_delmulti , +and +.Fn ifmaof_ifpforaddr +functions provide support for requesting and relinquishing multicast +group memberships, and for querying an interface's membership list, +respectively. +The +.Fn if_addmulti +function takes a pointer to an interface, +.Fa ifp , +and a generic address, +.Fa sa . +It also takes a pointer to a +.Vt "struct ifmultiaddr *" +which is filled in on successful return with the address of the +group membership control block. +The +.Fn if_addmulti +function performs the following four-step process: +.Bl -enum -offset indent +.It +Call the interface's +.Fn if_resolvemulti +entry point to determine the link-layer address, if any, corresponding +to this membership request, and also to give the link layer an +opportunity to veto this membership request should it so desire. +.It +Check the interface's group membership list for a pre-existing +membership for this group. +If one is not found, allocate a new one; +if one is, increment its reference count. +.It +If the +.Fn if_resolvemulti +routine returned a link-layer address corresponding to the group, +repeat the previous step for that address as well. +.It +If the interface's multicast address filter needs to be changed +because a new membership was added, call the interface's +.Fn if_ioctl +routine +(with a +.Fa cmd +argument of +.Dv SIOCADDMULTI ) +to request that it do so. +.El +.Pp +The +.Fn if_delmulti +function, given an interface +.Fa ifp +and an address, +.Fa sa , +reverses this process. +Both functions return zero on success, or a +standard error number on failure. +.Pp +The +.Fn ifmaof_ifpforaddr +function examines the membership list of interface +.Fa ifp +for an address matching +.Fa addr , +and returns a pointer to that +.Vt "struct ifmultiaddr" +if one is found, else it returns a null pointer. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr link_addr 3 , +.Xr queue 3 , +.Xr sysctl 3 , +.Xr bpf 4 , +.Xr ifmib 4 , +.Xr lo 4 , +.Xr netintro 4 , +.Xr polling 4 , +.Xr config 8 , +.Xr ppp 8 , +.Xr mbuf 9 , +.Xr rtentry 9 +.Rs +.%A Gary R. Wright +.%A W. Richard Stevens +.%B TCP/IP Illustrated +.%V Vol. 2 +.%O Addison-Wesley, ISBN 0-201-63354-X +.Re +.Sh AUTHORS +This manual page was written by +.An Garrett A. Wollman . |