Create a new manual page describing how network interfaces and
addresses are glued together with the generic networking code.
This commit is contained in:
Garrett Wollman
parent
558ad0694d
commit
3cb60f1a48
@ -1,7 +1,7 @@
|
||||
# $Id: Makefile,v 1.10 1996/10/08 18:45:03 wollman Exp $
|
||||
# $Id: Makefile,v 1.11 1996/10/08 20:25:36 wollman Exp $
|
||||
|
||||
MAN9= at_shutdown.9 at_fork.9 at_exit.9 copy.9 devfs_add_devswf.9 \
|
||||
devfs_link.9 fetch.9 intro.9 rtalloc.9 rtentry.9 sleep.9 spl.9 \
|
||||
devfs_link.9 fetch.9 ifnet.9 intro.9 rtalloc.9 rtentry.9 sleep.9 spl.9 \
|
||||
store.9 style.9 timeout.9
|
||||
|
||||
MLINKS+= copy.9 copyin.9 copy.9 copyout.9 copy.9 copystr.9 copy.9 copyinstr.9
|
||||
@ -9,6 +9,7 @@ MLINKS+= fetch.9 fubyte.9 fetch.9 fusword.9 fetch.9 fuswintr.9 fetch.9 fuword.9
|
||||
MLINKS+= at_shutdown.9 rm_at_shutdown.9
|
||||
MLINKS+= at_exit.9 rm_at_exit.9
|
||||
MLINKS+= at_fork.9 rm_at_fork.9
|
||||
MLINKS+= ifnet.9 ifaddr.9 ifnet.9 ifqueue.9 ifnet.9 if_data.9
|
||||
MLINKS+= rtalloc.9 rtalloc_ign.9 rtalloc.9 rtalloc1.9
|
||||
MLINKS+= sleep.9 tsleep.9 sleep.9 wakeup.9
|
||||
MLINKS+= spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 spl.9 splimp.9
|
||||
|
||||
827
share/man/man9/ifnet.9
Normal file
827
share/man/man9/ifnet.9
Normal file
@ -0,0 +1,827 @@
|
||||
.\"
|
||||
.\" Copyright 1996 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.
|
||||
.\"
|
||||
.\" $Id: rtalloc.9,v 1.3 1996/12/01 00:25:05 mpp Exp $
|
||||
.Dd December 16, 1996
|
||||
.Os FreeBSD 2.2
|
||||
.Dt IFNET 9
|
||||
.Sh NAME
|
||||
.Nm ifnet ,
|
||||
.Nm ifaddr ,
|
||||
.Nm ifqueue ,
|
||||
.Nm if_data
|
||||
.Nd kernel interfaces for manipulating network interfaces
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/types.h>
|
||||
.Fd #include <sys/time.h>
|
||||
.Fd #include <sys/socket.h>
|
||||
.Fd #include <net/if.h>
|
||||
.Fd #include <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" "int cmd" "caddr_t data" "struct proc *p"
|
||||
.Ft int
|
||||
.Fn ifpromisc "struct ifnet *ifp" "int pswitch"
|
||||
.Ft "struct ifnet *"
|
||||
.Fn ifunit "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"
|
||||
.Ft void \"macro
|
||||
.Fn IFAFREE "struct ifaddr *ifa"
|
||||
.\"
|
||||
.Ss "Output queue macros"
|
||||
.Ft void \"macro
|
||||
.Fn IF_ENQ_DROP "struct ifqueue *ifq" "struct mbuf *m"
|
||||
.Ft void \"macro
|
||||
.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m"
|
||||
.\"
|
||||
.Ss "struct ifnet member functions"
|
||||
.Ft int
|
||||
.Fn (*if_output) "struct ifnet *ifp" "struct mbuf *m" "struct sockaddr *dst" "struct rtentry *rt"
|
||||
.Ft void
|
||||
.Fn (*if_start) "struct ifnet *ifp"
|
||||
.Ft int
|
||||
.Fn (*if_dont) "struct ifnet *ifp"
|
||||
.Ft int
|
||||
.Fn (*if_ioctl) "struct ifnet *ifp" "int cmd" "caddr_t data"
|
||||
.Ft void
|
||||
.Fn (*if_watchdog) "struct ifnet *ifp"
|
||||
.Ft int
|
||||
.Fn (*if_poll_recv) "struct ifnet *ifp" "int *quotap"
|
||||
.Ft int
|
||||
.Fn (*if_poll_xmit) "struct ifnet *ifp" "int *quotap"
|
||||
.Ft void
|
||||
.Fn (*if_poll_inttrn) "struct ifnet *ifp"
|
||||
.Ft void
|
||||
.Fn (*if_poll_slowinput) "struct ifnet *ifp" "struct mbuf *m"
|
||||
.Ft void
|
||||
.Fn (*if_init) "void *wtf_is_this"
|
||||
.Ss "struct ifaddr member function"
|
||||
.Ft void
|
||||
.Fn (*ifa_rtrequest) "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
|
||||
.Ss "Global variables"
|
||||
.Fd extern struct ifnethead ifnet;
|
||||
.Fd extern struct ifaddr \&**ifnet_addrs;
|
||||
.Fd extern int if_index;
|
||||
.Fd extern int ifqmaxlen;
|
||||
.Sh DATA STRUCTURES
|
||||
The kernel mechanisms for handling network interfaces reside primarily
|
||||
in the
|
||||
.Li ifnet ,
|
||||
.Li if_data ,
|
||||
and
|
||||
.Li ifaddr
|
||||
structures in
|
||||
.Aq Pa net/if.h ,
|
||||
and the functions named above and defined in
|
||||
.Pa /sys/net/if.c .
|
||||
The system keeps a linked list of interfaces using the
|
||||
.Li TAILQ
|
||||
macros defined in
|
||||
.Xr queue 3 ;
|
||||
this list is headed by a
|
||||
.Li "struct ifnethead"
|
||||
called
|
||||
.Li ifnet .
|
||||
The elements of this list are of type
|
||||
.Li "struct ifnet" ,
|
||||
and most kernel routines which manipulate interface as such accept or
|
||||
return pointers to these structures. Each interface structure
|
||||
contains an
|
||||
.Li 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
|
||||
.Li 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
|
||||
Interfaces are also associated with an output queue, defined as a
|
||||
.Li "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 queueing 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 ifnet structure
|
||||
The fields of
|
||||
.Li "struct ifnet"
|
||||
are as follows:
|
||||
.Pp
|
||||
.Bl -tag -width "if_poll_slowq" -offset indent
|
||||
.It Li "if_softc"
|
||||
.Pq Li "void *"
|
||||
A pointer to the driver's private state block. (Initialized by
|
||||
driver.)
|
||||
.It Li if_name
|
||||
.Pq Li "char *"
|
||||
The name of the interface, not including the unit number
|
||||
(e.g.,
|
||||
.Dq Li de
|
||||
or
|
||||
.Dq Li lo ) .
|
||||
(Initialized by driver.)
|
||||
.It Li if_link
|
||||
.Pq Li "TAILQ_ENTRY(ifnet)"
|
||||
.Xr queue 3
|
||||
macro glue.
|
||||
.It Li if_addrhead
|
||||
.Pq Li "struct ifaddrhead"
|
||||
The head of the
|
||||
.Xr queue 3
|
||||
.Li TAILQ
|
||||
containing the list of addresses assigned to this interface.
|
||||
.It Li if_pcount
|
||||
.Pq Li "int"
|
||||
A count of promiscuous listeners on this interface, used to
|
||||
reference-count the
|
||||
.Dv IFF_PROMISC
|
||||
flag.
|
||||
.It Li "if_bpf"
|
||||
.Pq Li "struct bpf_if *"
|
||||
Opaque per-interface data for the packet filter,
|
||||
.Xr bpf 4 .
|
||||
(Initialized by
|
||||
.Fn bpf_attach . )
|
||||
.It Li "if_index"
|
||||
.Pq Li "u_short"
|
||||
A unique number assigned to each interface in sequence as it is
|
||||
attached. This number can be used in a
|
||||
.Li "struct sockaddr_dl"
|
||||
to refer to a particular interface by index
|
||||
(see
|
||||
.Xr link_addr 3 ) .
|
||||
.It Li "if_unit"
|
||||
.Pq Li "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 Li "if_timer"
|
||||
.Pq Li "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 Li "if_flags"
|
||||
.Pq Li "short"
|
||||
Flags describing operational parameters of this interface (see below).
|
||||
(Manipulated by both driver and generic code.)
|
||||
.\" .It Li "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 Li "if_linkmib"
|
||||
.Pq Li "void *"
|
||||
A pointer to an interface-specific MIB structure exported by
|
||||
.Xr ifmib 4 .
|
||||
(Initialized by driver.)
|
||||
.It Li "if_linkmiblen"
|
||||
.Pq Li "size_t"
|
||||
The size of said structure. (Initialized by driver.)
|
||||
.It Li "if_data"
|
||||
.Pq Li "struct if_data"
|
||||
More statistics and information; see
|
||||
.Dq Sx "The if_data structure" ,
|
||||
below. (Initialized by driver, manipulated by both driver and generic
|
||||
code.)
|
||||
.It Li "if_snd"
|
||||
.Pq Li "struct ifqueue"
|
||||
The output queue. (Manipulated by driver.)
|
||||
.\".It Li "if_poll_slowq"
|
||||
.\".Pq Li "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
|
||||
.Ar 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're not even sure what it was ever for.
|
||||
.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,
|
||||
.Li 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
|
||||
XXX fill me in
|
||||
.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 "IFF_POINTOPOINT" -compact -offset indent
|
||||
.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
|
||||
addresses are 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 The if_data structure
|
||||
In
|
||||
.Bx 4.4 ,
|
||||
a subset of the interface information believed to be of interest to
|
||||
management stations was segregated from the
|
||||
.Li ifnet
|
||||
structure and moved into its own
|
||||
.Li if_data
|
||||
structure to facilitate its use by user programs. The following
|
||||
elements of the
|
||||
.Li if_data
|
||||
structure are initialized by the interface and are not expected to change
|
||||
significantly over the course of normal operation:
|
||||
.Bl -tag -width "ifi_lastchange" -offset indent
|
||||
.It Li ifi_type
|
||||
.Pq Li u_char
|
||||
The type of the interface, as defined in
|
||||
.Aq Pa net/if_types.h
|
||||
and described below in the
|
||||
.Dq Sx "Interface types"
|
||||
section.
|
||||
.It Li ifi_physical
|
||||
.Pq Li u_char
|
||||
Intended to represent a selection of physical layers on devices which
|
||||
support more than one; never implemented.
|
||||
.It Li ifi_addrlen
|
||||
.Pq Li 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
|
||||
.Li "sockaddr_dl"
|
||||
structures referring to this interface.
|
||||
.It Li ifi_hdrlen
|
||||
.Pq Li 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
|
||||
.Li mbuf Ns s
|
||||
to attempt to ensure that there is always
|
||||
sufficient space to prepend a link-layer header without allocating an
|
||||
additional
|
||||
.Li mbuf .
|
||||
.\" (See
|
||||
.\" .Xr mbuf 9 . )
|
||||
.\" .It Li ifi_recvquota
|
||||
.\" .Pq Li u_char
|
||||
.\" Number of packets the interface is permitted to receive at one time
|
||||
.\" when in polled mode.
|
||||
.\" .It Li ifi_xmitquota
|
||||
.\" .Pq Li 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 Li ifi_mtu
|
||||
.Pq Li u_long
|
||||
The maximum transmission unit of the medium, exclusive of any
|
||||
link-layer overhead.
|
||||
.It Li ifi_metric
|
||||
.Pq Li u_long
|
||||
A dimensionless metric interpreted by a user-mode routing process.
|
||||
.It Li ifi_baudrate
|
||||
.Pq Li 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
|
||||
.Li u_long ) :
|
||||
.Bl -tag -width "ifi_lastchange" -offset indent
|
||||
.It Li ifi_ipackets
|
||||
Number of packets received.
|
||||
.It Li 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 Li ifi_opackets
|
||||
Number of packets transmitted.
|
||||
.It Li 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 Li 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 Li ifi_ibytes
|
||||
Total traffic received, in bytes.
|
||||
.It Li ifi_obytes
|
||||
Total traffic transmitted, in bytes.
|
||||
.It Li ifi_imcasts
|
||||
Number of packets received which were sent by link-layer multicast.
|
||||
.It Li ifi_omcasts
|
||||
Number of packets sent by link-layer multicast.
|
||||
.It Li ifi_iqdrops
|
||||
Number of packets dropped on input. Rarely implemented.
|
||||
.It Li ifi_noproto
|
||||
Number of packets received for unknown network-layer protocol.
|
||||
.\" .It Li ifi_recvtiming
|
||||
.\" Amount of time, in microseconds, spent to receive an average packet on
|
||||
.\" this interface. See the
|
||||
.\" .Sx Polling
|
||||
.\" section, below.
|
||||
.\" .It Li ifi_xmittiming
|
||||
.\" Amount of time, in microseconds, spent to service a transmit-complete
|
||||
.\" interrupt on this interface. See the
|
||||
.\" .Sx Polling
|
||||
.\" section, below.
|
||||
.It Li ifi_lastchange
|
||||
.Pq Li "struct timeval"
|
||||
The time of the last administative 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 -compact -offset indent -width IFT_PROPVIRTUAL
|
||||
.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 ifaddr structure
|
||||
Every interface is associated with a list
|
||||
(or, rather, a
|
||||
.Dv TAILQ )
|
||||
of addresses, rooted at the interface structure's
|
||||
.Li 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
|
||||
.Li ifaddr
|
||||
structures. Most protocols will declare their own protocol-specific
|
||||
interface address structures, but all begin with a
|
||||
.Li "struct ifaddr"
|
||||
which provides the most-commonly-needed functionality across all
|
||||
protocols. Interface addresses are reference-counted.
|
||||
.Pp
|
||||
The members of
|
||||
.Li "struct ifaddr"
|
||||
are as follows:
|
||||
.Bl -tag -width ifa_rtrequest -offset indent
|
||||
.It Li ifa_addr
|
||||
.Pq Li "struct sockaddr *"
|
||||
The local address of the interface.
|
||||
.It Li ifa_dstaddr
|
||||
.Pq Li "struct sockaddr *"
|
||||
The remote address of point-to-point interfaces, and the broadcast
|
||||
address of broadcast interfaces.
|
||||
.Po
|
||||
.Li ifa_broadaddr
|
||||
is a macro for
|
||||
.Li ifa_dstaddr .
|
||||
.Pc
|
||||
.It Li ifa_netmask
|
||||
.Pq Li "struct sockaddr *"
|
||||
The network mask for multi-access interfaces, and the confusion
|
||||
generator for point-to-point interfaces.
|
||||
.It Li ifa_ifp
|
||||
.Pq Li "struct ifnet *"
|
||||
A link back to the interface structure.
|
||||
.It Li ifa_link
|
||||
.Pq Li TAILQ_ENTRY(ifaddr)
|
||||
.Xr queue 3
|
||||
glue for list of addresses on each interface.
|
||||
.It Li ifa_rtrequest
|
||||
See below.
|
||||
.It Li ifa_flags
|
||||
.Pq Li u_short
|
||||
Some of the flags which would be used for a route representing this
|
||||
address in the route table.
|
||||
.It Li ifa_refcnt
|
||||
.Pq Li short
|
||||
The reference count.
|
||||
.It Li ifa_metric
|
||||
.Pq Li int
|
||||
A metric associated with this interface address, for the use of some
|
||||
external routing protocol.
|
||||
.El
|
||||
.Pp
|
||||
References to
|
||||
.Li ifaddr
|
||||
structures are gained manually, by incrementing the
|
||||
.Li 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
|
||||
.Ar cmd
|
||||
argument indicates the request in question:
|
||||
.Dv RTM_ADD ,
|
||||
.Dv RTM_RESOLVE ,
|
||||
or
|
||||
.Dv RTM_DELETE .
|
||||
The
|
||||
.Ar rt
|
||||
argument is the route in question; the
|
||||
.Ar sa
|
||||
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 Interface manipulation functions
|
||||
.Bl -ohang -offset indent
|
||||
.It Fn if_attach
|
||||
Link the specified interface
|
||||
.Ar ifp
|
||||
into the list of network interfaces. Also initialize the list of
|
||||
addresses on that interface, and create a link-layer
|
||||
.Li ifaddr
|
||||
structure to be the first element in that list. (A pointer to
|
||||
this address structure is saved in the global array
|
||||
.Li ifnet_addrs . )
|
||||
.It Fn if_down
|
||||
Mark the interface
|
||||
.Ar ifp
|
||||
as down (i.e.,
|
||||
.Dv IFF_UP
|
||||
is not set),
|
||||
flush its output queue, and call the interface's
|
||||
.Fn if_ioctl
|
||||
routine to notify the driver of the shutdown request.
|
||||
.It Fn if_up
|
||||
Mark the interface
|
||||
.Ar ifp
|
||||
as up, and call the interface's
|
||||
.Fn if_ioctl
|
||||
routine to (re-)initialize the driver.
|
||||
.It Fn ifpromisc
|
||||
Add or remove a promiscuous reference to
|
||||
.Ar ifp .
|
||||
If
|
||||
.Ar 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 ifunit
|
||||
Return an
|
||||
.Li ifnet
|
||||
pointer for the interface named
|
||||
.Ar name .
|
||||
.It Fn ifioctl
|
||||
Process the ioctl request
|
||||
.Ar cmd ,
|
||||
issued on socket
|
||||
.Ar so
|
||||
by process
|
||||
.Ar p ,
|
||||
with data parameter
|
||||
.Ar 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
|
||||
.Ar so Ns 's
|
||||
protocol for
|
||||
further interpretation. The following commands are handled by
|
||||
.Fn ifioctl :
|
||||
.Pp
|
||||
.Bl -tag -width OSIOCGIFNETMASK -compact -offset indent
|
||||
.It Dv SIOCGIFCONF
|
||||
.It Dv OSIOCGIFCONF
|
||||
Get interface configuration. (No call-down to driver.)
|
||||
.It Dv SIOCGIFFLAGS
|
||||
.It Dv SIOCGIFMETRIC
|
||||
.It Dv SIOCGIFMTU
|
||||
.It Dv SIOCGIFPHYS
|
||||
Get interface flags, metric, MTU, medium selection. (No call-down to
|
||||
driver.)
|
||||
.Pp
|
||||
.It Dv SIOCSIFFLAGS
|
||||
Change interface flags. Caller must have appropriate privilege. If
|
||||
requested a change to the 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.
|
||||
.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.
|
||||
.It Dv SIOCADDMULTI
|
||||
.It Dv SIOCDELMULTI
|
||||
Add or delete permanent multicast group memberships on the interface.
|
||||
Caller must have appropriate privilege. The driver
|
||||
.Fn if_ioctl
|
||||
routine is called to perform the requested action.
|
||||
.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.
|
||||
.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,
|
||||
.Li sockaddr
|
||||
structures are converted into old-style (no
|
||||
.Li sa_len
|
||||
member).
|
||||
.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
|
||||
.Ar addr .
|
||||
.Fn ifa_ifwithdstaddr
|
||||
returns an interface address for a point-to-point interface whose
|
||||
remote (``destination'') address is
|
||||
.Ar addr .
|
||||
.Pp
|
||||
.Fn ifa_ifwithnet
|
||||
returns the most specific interface address which matches the
|
||||
specified address,
|
||||
.Ar addr ,
|
||||
subject to its configured netmask, or a point-to-point interface
|
||||
address whose remote address is
|
||||
.Ar addr
|
||||
if one is found.
|
||||
.Pp
|
||||
.Fn ifaof_ifpforaddr
|
||||
returns the most specific address configured on interface
|
||||
.Ar ifp
|
||||
which matches address
|
||||
.Ar addr ,
|
||||
subject to its configured netmask. If the interface is
|
||||
point-to-point, only an interface address whose remote address is
|
||||
precisely
|
||||
.Ar addr
|
||||
will be returned.
|
||||
.Pp
|
||||
All of these functions return a null pointer if no such address can be
|
||||
found.
|
||||
.\" .Sh POLLING
|
||||
.\" XXX write me!
|
||||
.Sh SEE ALSO
|
||||
.Xr bpf 4 ,
|
||||
.Xr config 8 ,
|
||||
.Xr ifmib 4 ,
|
||||
.Xr ioctl 2 ,
|
||||
.Xr link_addr 3 ,
|
||||
.Xr lo 4 ,
|
||||
.\" .Xr mbuf 9 ,
|
||||
.Xr netintro 4 ,
|
||||
.Xr ppp 8 ,
|
||||
.Xr queue 3 ,
|
||||
.Xr rtentry 9 ,
|
||||
.Xr sysctl 3
|
||||
.Rs
|
||||
.%A Gary R. Wright and W. Richard Stevens
|
||||
.%B TCP/IP Illustrated
|
||||
.%V vol. 2
|
||||
.%O Addison-Wesley, ISBN 0-201-63354-X
|
||||
.Re
|
||||
.Sh AUTHOR
|
||||
This manual page was written by Garrett A. Wollman
|
||||
Loading…
Reference in New Issue
Block a user