1088 lines
29 KiB
Groff
1088 lines
29 KiB
Groff
.\" -*- 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 January 15, 1997
|
|
.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 void
|
|
.Fn if_attach "struct ifnet *ifp"
|
|
.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_ENQ_DROP "struct ifqueue *ifq" "struct mbuf *m"
|
|
.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m"
|
|
.\"
|
|
.Ss "struct ifnet Member Functions"
|
|
.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_dont\*(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 int
|
|
.Fn \*(lp*if_poll_recv\*(rp "struct ifnet *ifp" "int *quotap"
|
|
.Ft int
|
|
.Fn \*(lp*if_poll_xmit\*(rp "struct ifnet *ifp" "int *quotap"
|
|
.Ft void
|
|
.Fn \*(lp*if_poll_inttrn\*(rp "struct ifnet *ifp"
|
|
.Ft void
|
|
.Fn \*(lp*if_poll_slowinput\*(rp "struct ifnet *ifp" "struct mbuf *m"
|
|
.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
|
|
.Aq Pa net/if.h
|
|
and
|
|
.Aq Pa 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
|
|
.Aq Pa 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
|
|
.Aq Pa 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
|
|
.Aq Pa net/if_var.h
|
|
because it is the prerequisite of some other header file like
|
|
.Aq Pa netinet/if_ether.h .
|
|
Most references to those two files in particular can be replaced by
|
|
.Aq Pa 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 LIST
|
|
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.
|
|
The current implementation implements a
|
|
drop-tail queuing discipline, but in the future a Random Early Drop
|
|
discipline is expected to be used.
|
|
For this reason, kernel code
|
|
should not depend on the internals of the queue structure; in
|
|
particular, only the
|
|
.Fn IF_ENQ_DROP
|
|
and
|
|
.Fn IF_DEQUEUE
|
|
macros will be supported in future implementations.
|
|
.\" The old structure will probably be retained for compatibility
|
|
.\" under a different name.
|
|
.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_name
|
|
.Pq Vt "char *"
|
|
The name of the interface, not including the unit number
|
|
(e.g.,
|
|
.Dq Li de
|
|
or
|
|
.Dq Li lo ) .
|
|
(Initialized by driver.)
|
|
.It Va if_link
|
|
.Pq Fn TAILQ_ENTRY ifnet
|
|
.Xr queue 3
|
|
macro glue.
|
|
.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 ) .
|
|
.It Va if_unit
|
|
.Pq Vt short
|
|
A unique number assigned to each interface managed by a particular
|
|
driver, usually related to the unit number of a physical device in the
|
|
kernel configuration file
|
|
(see
|
|
.Xr config 8 ) .
|
|
(Initialized by driver.)
|
|
.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 short
|
|
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_output
|
|
Output a packet on interface
|
|
.Fa ifp ,
|
|
or queue it on the output queue if the interface is already active.
|
|
.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.)
|
|
.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
|
|
.Aq Pa 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
|
|
.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_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.
|
|
.El
|
|
.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 in the listing above.
|
|
.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.
|
|
.Bl -tag -width ".Dv IFCAP_NETCONS" -offset indent
|
|
.It Dv IFCAP_NETCONS
|
|
This interface can be a network console.
|
|
.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.
|
|
.El
|
|
.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
|
|
.Aq Pa 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_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.
|
|
.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_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
|
|
.Aq Pa 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 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_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 . )
|
|
.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 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 interface capabilities.
|
|
Caller must have appropriate privilege.
|
|
.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 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 POLLING
|
|
.\" XXX write me!
|
|
.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 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 .
|