Index: stable/4/share/man/man9/ifnet.9
===================================================================
--- stable/4/share/man/man9/ifnet.9	(revision 116366)
+++ stable/4/share/man/man9/ifnet.9	(revision 116367)
@@ -1,1062 +1,1049 @@
 .\" -*- 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/types.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 proc *p"
 .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_done\*(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_poll_slowq" -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_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_PPROMISC
 .Aq D
 This interface is in the permanently promiscuous mode (implies
 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.
 .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 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 process
 .Fa p ,
 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 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 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 .