diff options
Diffstat (limited to 'static/freebsd/man9/ifnet.9')
| -rw-r--r-- | static/freebsd/man9/ifnet.9 | 1692 |
1 files changed, 1692 insertions, 0 deletions
diff --git a/static/freebsd/man9/ifnet.9 b/static/freebsd/man9/ifnet.9 new file mode 100644 index 00000000..e0a4dae9 --- /dev/null +++ b/static/freebsd/man9/ifnet.9 @@ -0,0 +1,1692 @@ +.\" -*- 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. +.\" +.Dd December 10, 2024 +.Dt IFNET 9 +.Os +.Sh NAME +.Nm if_t , +.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 "if_t" +.Fn if_alloc "u_char type" +.Ft "if_t" +.Fn if_alloc_dev "u_char type" "device_t dev" +.Ft "if_t" +.Fn if_alloc_domain "u_char type" "int numa_domain" +.Ft void +.Fn if_attach "if_t ifp" +.Ft void +.Fn if_detach "if_t ifp" +.Ft void +.Fn if_free "if_t ifp" +.Ft void +.Fn if_free_type "if_t ifp" "u_char type" +.Ft void +.Fn if_down "if_t ifp" +.Ft int +.Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" +.Ft int +.Fn ifpromisc "if_t ifp" "int pswitch" +.Ft int +.Fn if_allmulti "if_t ifp" "int amswitch" +.Ft "if_t" +.Fn ifunit "const char *name" +.Ft "if_t" +.Fn ifunit_ref "const char *name" +.Ft void +.Fn if_up "if_t ifp" +.\" +.Ss "Interface Address Functions" +.Ft "struct ifaddr *" +.Fn ifa_ifwithaddr "struct sockaddr *addr" +.Ft "struct ifaddr *" +.Fn ifa_ifwithdstaddr "struct sockaddr *addr" "int fib" +.Ft "struct ifaddr *" +.Fn ifa_ifwithnet "struct sockaddr *addr" "int ignore_ptp" "int fib" +.Ft "struct ifaddr *" +.Fn ifaof_ifpforaddr "struct sockaddr *addr" "if_t ifp" +.Ft void +.Fn ifa_ref "struct ifaddr *ifa" +.Ft void +.Fn ifa_free "struct ifaddr *ifa" +.\" +.Ss "Interface Multicast Address Functions" +.Ft int +.Fn if_addmulti "if_t ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" +.Ft int +.Fn if_delmulti "if_t ifp" "struct sockaddr *sa" +.Ft "struct ifmultiaddr *" +.Fn if_findmulti "if_t ifp" "struct sockaddr *sa" +.Ss "Output queue accessors" +.Fn if_dequeue "if_t ifp" "struct mbuf *m" +.Ss "Output queue macros" +.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" +.\" +.Ss "if_t accesors" +.Ft uint64_t +.Fn if_setbaudrate "if_t ifp" "uint64_t baudrate" +.Ft uint64_t +.Fn if_getbaudrate "const if_t ifp" +.Ft int +.Fn if_setcapabilities "if_t ifp" "int capabilities" +.Ft int +.Fn if_setcapabilitiesbit "if_t ifp" "int setbit" "int clearbit" +.Ft int +.Fn if_getcapabilities "const if_t ifp" +.Ft int +.Fn if_togglecapenable "if_t ifp" "int togglecap" +.Ft int +.Fn if_setcapenable "if_t ifp" "int capenable" +.Ft int +.Fn if_setcapenablebit "if_t ifp" "int setcap" "int clearcap" +.Ft int +.Fn if_getcapenable "const if_t ifp" +.Ft int +.Fn if_setcapabilities2 "if_t ifp" "int capabilities" +.Ft int +.Fn if_setcapabilities2bit "if_t ifp" "int setbit" "int clearbit" +.Ft int +.Fn if_getcapabilities2 "const if_t ifp" +.Ft int +.Fn if_togglecapenable2 "if_t ifp" "int togglecap" +.Ft int +.Fn if_setcapenable2 "if_t ifp" "int capenable" +.Ft int +.Fn if_setcapenable2bit "if_t ifp" "int setcap" "int clearcap" +.Ft int +.Fn if_getcapenable2 "const if_t ifp" +.Ft int +.Fn if_getdunit "const if_t ifp" +.Ft int +.Fn if_getindex "const if_t ifp" +.Ft int +.Fn if_getidxgen "const if_t ifp" +.Ft const char * +.Fn if_getdname "const if_t ifp" +.Ft void +.Fn if_setdname "if_t ifp" "const char *name" +.Ft const char * +.Fn if_name "if_t ifp" +.Ft int +.Fn if_setname "if_t ifp" "const char *name" +.Ft void +.Fn if_setdescr "if_t ifp" "char *descrbuf" +.Ft char * +.Fn if_allocdescr "size_t sz" "int malloc_flag" +.Ft void +.Fn if_freedescr "char *descrbuf" +.Ft int +.Fn if_getalloctype "const if_t ifp" +.Ft int +.Fn if_gettype "const if_t ifp" +.Ft int +.Fn if_setdev "if_t ifp" "void *dev" +.Ft int +.Fn if_setdrvflagbits "if_t ifp" "int if_setflags" "int clear_flags" +.Ft int +.Fn if_getdrvflags "const if_t ifp" +.Ft int +.Fn if_setdrvflags "if_t ifp" "int flags" +.Ft int +.Fn if_getlinkstate "if_t ifp" +.Ft int +.Fn if_clearhwassist "if_t ifp" +.Ft int +.Fn if_sethwassistbits "if_t ifp" "int toset" "int toclear" +.Ft int +.Fn if_sethwassist "if_t ifp" "int hwassist_bit" +.Ft int +.Fn if_gethwassist "const if_t ifp" +.Ft int +.Fn if_togglehwassist "if_t ifp" "int toggle_bits" +.Ft int +.Fn if_setsoftc "if_t ifp" "void *softc" +.Ft void * +.Fn if_getsoftc "if_t ifp" +.Ft void +.Fn if_setllsoftc "if_t ifp" "void *softc" +.Ft void * +.Fn if_getllsoftc "if_t ifp" +.Ft u_int +.Fn if_getfib "if_t ifp" +.Ft uint8_t +.Fn if_getaddrlen "if_t ifp" +.Ft int +.Fn if_gethwaddr "const if_t ifp" "struct ifreq *" +.Ft const uint8_t * +.Fn if_getbroadcastaddr "const if_t ifp" +.Ft void +.Fn if_setbroadcastaddr "if_t ifp" "const uint8_t *" +.Ft int +.Fn if_setmtu "if_t ifp" "int mtu" +.Ft int +.Fn if_getmtu "const if_t ifp" +.Ft int +.Fn if_getmtu_family "const if_t ifp" "int family" +.Ft void +.Fn if_notifymtu "if_t ifp" +.Ft int +.Fn if_setflagbits "if_t ifp" "int set" "int clear" +.Ft int +.Fn if_setflags "if_t ifp" "int flags" +.Ft int +.Fn if_getflags "const if_t ifp" +.Ft int +.Fn if_getnumadomain "if_t ifp" +.Ft int +.Fn if_sendq_empty "if_t ifp" +.Ft int +.Fn if_setsendqready "if_t ifp" +.Ft int +.Fn if_setsendqlen "if_t ifp" "int tx_desc_count" +.Ft int +.Fn if_sethwtsomax "if_t ifp" "u_int if_hw_tsomax" +.Ft int +.Fn if_sethwtsomaxsegcount "if_t ifp" "u_int if_hw_tsomaxsegcount" +.Ft int +.Fn if_sethwtsomaxsegsize "if_t ifp" "u_int if_hw_tsomaxsegsize" +.Ft u_int +.Fn if_gethwtsomax "const if_t ifp" +.Ft u_int +.Fn if_gethwtsomaxsegcount "const if_t ifp" +.Ft u_int +.Fn if_gethwtsomaxsegsize "const if_t ifp" +.Ft void +.Fn if_setnetmapadapter "if_t ifp" "struct netmap_adapter *na" +.Ft struct netmap_adapter * +.Fn if_getnetmapadapter "if_t ifp" +.Ft void +.Fn if_input "if_t ifp" "struct mbuf* sendmp" +.Ft int +.Fn if_sendq_prepend "if_t ifp" "struct mbuf *m" +.Ft struct mbuf * +.Fn if_dequeue "if_t ifp" +.Ft int +.Fn if_setifheaderlen "if_t ifp" "int len" +.Ft void +.Fn if_setrcvif "struct mbuf *m" "if_t ifp" +.Ft void +.Fn if_setvtag "struct mbuf *m" "u_int16_t tag" +.Ft u_int16_t +.Fn if_getvtag "struct mbuf *m" +.Ft int +.Fn if_vlantrunkinuse "if_t ifp" +.Ft caddr_t +.Fn if_getlladdr "const if_t ifp" +.Ft struct vnet * +.Fn if_getvnet "const if_t ifp" +.Ft void * +.Fn if_gethandle "u_char" +.Ft void +.Fn if_bpfmtap "if_t ifp" "struct mbuf *m" +.Ft void +.Fn if_etherbpfmtap "if_t ifp" "struct mbuf *m" +.Ft void +.Fn if_vlancap "if_t ifp" +.Ft int +.Fn if_transmit "if_t ifp" "struct mbuf *m" +.Ft void +.Fn if_init "if_t ifp" "void *ctx" +.Ft int +.Fn if_resolvemulti "if_t ifp" "struct sockaddr **" "struct sockaddr *" +.Ft uint64_t +.Fn if_getcounter "if_t ifp" "ift_counter counter" +.Ft struct label * +.Fn if_getmaclabel "if_t ifp" +.Ft void +.Fn if_setmaclabel "if_t ifp" "struct label *label" +.Ft struct bpf_if * +.Fn if_getbpf "if_t ifp" +.Ft uint8_t +.Fn if_getpcp "if_t ifp" +.Ft void * +.Fn if_getl2com "if_t ifp" +.Ft struct ifvlantrunk * +.Fn if_getvlantrunk "if_t ifp" +.Ft bool +.Fn if_altq_is_enabled "if_t ifp" +.\" +.Ss "struct ifnet Member Functions" +.Ft void +.Fn \*(lp*if_input\*(rp "if_t ifp" "struct mbuf *m" +.Ft int +.Fo \*(lp*if_output\*(rp +.Fa "if_t ifp" "struct mbuf *m" +.Fa "const struct sockaddr *dst" "struct route *ro" +.Fc +.Ft void +.Fn \*(lp*if_start\*(rp "if_t ifp" +.Ft int +.Fn \*(lp*if_transmit\*(rp "if_t ifp" "struct mbuf *m" +.Ft void +.Fn \*(lp*if_qflush\*(rp "if_t ifp" +.Ft int +.Fn \*(lp*if_ioctl\*(rp "if_t ifp" "u_long cmd" "caddr_t data" +.Ft void +.Fn \*(lp*if_init\*(rp "void *if_softc" +.Ft int +.Fo \*(lp*if_resolvemulti\*(rp +.Fa "if_t 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 rt_addrinfo *info" +.Fc +.\" +.Ss "Global Variables" +.Vt extern struct ifnethead ifnet ; +.\" extern struct ifindex_entry *ifindex_table ; +.Vt extern int if_index ; +.Vt extern int ifqmaxlen ; +.Sh DATA STRUCTURES +The kernel mechanisms for handling network interfaces reside primarily +in the +.Vt ifnet , if_data , ifaddr , +and +.Vt ifmultiaddr +structures in +.In net/if.h +and +.In net/if_var.h +and the functions named above and defined in +.Pa /sys/net/if.c . +Those interfaces which are intended to be used by user programs +are defined in +.In net/if.h ; +these include the interface flags, the +.Vt if_data +structure, and the structures defining the appearance of +interface-related messages on the +.Xr route 4 +routing socket and in +.Xr sysctl 3 . +The header file +.In net/if_var.h +defines the kernel-internal interfaces, including the +.Vt ifnet , ifaddr , +and +.Vt ifmultiaddr +structures and the functions which manipulate them. +(A few user programs will need +.In net/if_var.h +because it is the prerequisite of some other header file like +.In netinet/if_ether.h . +Most references to those two files in particular can be replaced by +.In net/ethernet.h . ) +.Pp +The system keeps a linked list of interfaces using the +.Li TAILQ +macros defined in +.Xr queue 3 ; +this list is headed by a +.Vt "struct ifnethead" +called +.Va ifnet . +The elements of this list are of type +.Vt "struct ifnet" , +and most kernel routines which manipulate interface as such accept or +return pointers to these structures. +Each interface structure +contains an +.Vt if_data +structure used for statistics and information. +Each interface also has a +.Li TAILQ +of interface addresses, described by +.Vt ifaddr +structures. +An +.Dv AF_LINK +address +(see +.Xr link_addr 3 ) +describing the link layer implemented by the interface (if any) +is accessed by the +.Va if_addr +structure. +(Some trivial interfaces do not provide any link layer addresses; +this structure, while still present, serves only to identify the +interface name and index.) +.Pp +Finally, those interfaces supporting reception of multicast datagrams +have a +.Li TAILQ +of multicast group memberships, described by +.Vt ifmultiaddr +structures. +These memberships are reference-counted. +.Pp +Interfaces are also associated with an output queue, defined as a +.Vt "struct ifqueue" ; +this structure is used to hold packets while the interface is in the +process of sending another. +.Ss The ifnet accessors +The accessors for +.Vt "if_t" +are as follows: +.Bl -tag -width indent -offset indent +.It Fn if_getbaudrate Fn if_setbaudrate +.Pq Vt u_long +The line rate of the interface, in bits per second. +.It Fn if_setcapabilities Fn if_setcapabilitiesbit Fn if_getcapabilities +.Pq Vt int +Flags describing the capabilities the interface supports (see below). +.It Fn if_getcapenable Fn if_setcapenable Fn if_setcapenablebit Fn if_togglecapenable +.Pq Vt int +Flags describing the enabled capabilities of the interface (see below). +.It Fn if_getcapabilities2 Fn if_setcapabilities2 Fn if_setcapabilities2bit +.It Fn if_getcapenable2 Fn if_setcapenable2 Fn if_setcapenable2bit Fn if_togglecapenable2 +.It Fn if_getdunit +.Pq Vt int +A unique number assigned to each interface managed by a particular +driver. +Drivers may choose to set this to +.Dv IF_DUNIT_NONE +if a unit number is not associated with the device. +(Initialized by driver, usually via +.Fn if_initname . ) +.It Fn if_getindex +.Pq Vt u_short +Return the unique number assigned to the device when 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 ) . +This is initialized by +.Fn if_alloc . +.It Fn if_getidxgen +.It Fn if_getdname Fn if_setdname +.Pq Ft "const char *" +The name of the driver. +This is initialized by driver +(usually via +.Fn if_initname ) . +.It Fn if_name Fn if_setname +.Pq Vt "char *" +The name of the interface, +(e.g., +.Ql fxp0 +or +.Dq Li lo0 ) . +This is initialized by driver, usually via +.Fn if_initname . +.It Fn if_getalloctype +.Pq Ft u_char +The type of the interface as it was at the time of its allocation. +It is used to cache the type passed to +.Fn if_alloc , +but unlike +.Va if_type , +it would not be changed by drivers. +.It Fn if_gettype +.It Fn if_setdev +.It Fn if_getdrvflags Fn if_setdrvflags Fn if_setdrvflagbits +.It Fn if_getlinkstate +.It Fn if_clearhwassist Fn if_sethwassistbits +.Fn if_gethwassist Fn if_sethwassist Fn if_togglehwassist +.Pq Vt u_long +A detailed interpretation of the capabilities +to offload computational tasks for +.Em outgoing +packets. +The interface driver must keep this field in accord with +the current value of +.Va if_capenable . +.It Fn if_getsoftc Fn if_setsoftc +.Pq Ft "void *" +A pointer to the driver's private state block. +This is initialized by driver at attach. +.It Fn if_setllsoftc +.It Fn if_getllsoftc +.It Fn if_getfib +.It Fn if_getaddrlen +.It Fn if_gethwaddr +.It Fn if_getbroadcastaddr Fn if_setbroadcastaddr +Access the interface broadcast address. +.It Fn if_setmtu +.It Fn if_getmtu +Access the interface MTU. +.It Fn if_setflags Fn if_getflags Fn if_setflagbits +.Pq Vt int +Flags describing operational parameters of this interface (see below). +These flags are manipulated by generic code. +.It Fn if_getnumadomain +.Pq Vt uint8_t +The NUMA domain of the hardware device associated with the interface. +This is filled in with a wildcard value unless the kernel is NUMA +aware, the system is a NUMA system, and the ifnet is allocated +using +.Fn if_alloc_dev +or +.Fn if_alloc_domain . +.It Fn if_sendq_empty +.It Fn if_setsendqready +.It Fn if_setsendqlen +.It Fn if_sethwtsomax Fn if_gethwtsomax +.It Fn if_sethwtsomaxsegcount Fn if_gethwtsomaxsegcount +.It Fn if_sethwtsomaxsegsize Fn if_gethwtsomaxsegsize +.It Fn if_setnetmapadapter Fn if_getnetmapadapter +.It Fn if_setifheaderlen +.It Fn if_setrcvif +.It Fn if_setvtag Fn if_getvtag +.It Fn if_vlantrunkinuse +.It Fn if_getlladdr +.It Fn if_getvnet +.Pq Vt "struct vnet *" +A pointer to the virtual network stack instance. +This is initialized by +.Fn if_attach . +.It Fn if_gethandle +.It Fn if_vlancap +.It Fn if_getcounter +.It Fn if_getmaclabel Fn if_setmaclabel +.It Fn if_getbpf +.Pq Ft "struct bpf_if *" +Opaque per-interface data for the packet filter, +.Xr bpf 4 . +This is initialized by +.Fn bpf_attach . +.It Fn if_getpcp +.It Fn if_getl2com +A pointer to the common data for the interface's layer 2 protocol. +This is initialized by +.Fn if_alloc . +.Fn if_getvlantrunk "if_t ifp" +.Pq Ft struct ifvlantrunk * +A pointer to 802.1Q trunk structure, +.Xr vlan 4 . +This is initialized by the driver-specific +.Fn if_ioctl +routine. +.It Fn if_getdrvflags Fn if_setdrvflags Fn if_setdrvflagbits +.Pq Ft int +Flags describing operational status of this interface (see below). +These flags are manipulated by driver. +.It Fn if_addmulti Fn if_delmulti Fn if_findmulti +Add, remove, and find multicast addresses assigned to this interface. +.It Fn if_getifaddr +.Pq Vt "struct ifaddr *" +Get a pointer to the interface's link-level address. +.It Fn if_getbroadcastaddr Fn if_setbroadcastaddr +.Pq Ft "const u_int8_t *" +A link-level broadcast bytestring for protocols with variable address +length. +.It Fn if_getafdata +.Pq Ft "void *" +An address family dependent data region. +.It Fn if_addgroup Fn if_delgroup +Add and delete groups from the interface. +.El +.Pp +References to +.Vt ifnet +structures are gained by calling the +.Fn if_ref +function and released by calling the +.Fn if_rele +function. +They are used to allow kernel code walking global interface lists +to release the +.Vt ifnet +lock yet keep the +.Vt ifnet +structure stable. +.Pp +There are in addition a number of function pointers which the driver +must initialize to complete its interface with the generic interface +layer: +.Bl -ohang -offset indent +.It Fn if_input +Pass a packet to an appropriate upper layer as determined +from the link-layer header of the packet. +This routine is to be called from an interrupt handler or +used to emulate reception of a packet on this interface. +A single function implementing +.Fn if_input +can be shared among multiple drivers utilizing the same link-layer +framing, e.g., Ethernet. +.It Fn if_output +Output a packet on interface +.Fa ifp , +or queue it on the output queue if the interface is already active. +.It Fn if_transmit +Transmit a packet on an interface or queue it if the interface is +in use. +This function will return +.Dv ENOBUFS +if the devices software and hardware queues are both full. +This function must be installed after +.Fn if_attach +to override the default implementation. +This function is exposed in order to allow drivers to manage their own queues +and to reduce the latency caused by a frequently gratuitous enqueue / dequeue +pair to ifq. +The suggested internal software queuing mechanism is buf_ring. +.It Fn if_qflush +Free mbufs in internally managed queues when the interface is marked down. +This function must be installed after +.Fn if_attach +to override the default implementation. +This function is exposed in order to allow drivers to manage their own queues +and to reduce the latency caused by a frequently gratuitous enqueue / dequeue +pair to ifq. +The suggested internal software queuing mechanism is buf_ring. +.It Fn if_start +Start queued output on an interface. +This function is exposed in +order to provide for some interface classes to share a +.Fn if_output +among all drivers. +.Fn if_start +may only be called when the +.Dv IFF_DRV_OACTIVE +flag is not set. +(Thus, +.Dv IFF_DRV_OACTIVE +does not literally mean that output is active, but rather that the +device's internal output queue is full.) Please note that this function +will soon be deprecated. +.It Fn if_ioctl +Process interface-related +.Xr ioctl 2 +requests +(defined in +.In sys/sockio.h ) . +Preliminary processing is done by the generic routine +.Fn ifioctl +to check for appropriate privileges, locate the interface being +manipulated, and perform certain generic operations like twiddling +flags and flushing queues. +See the description of +.Fn ifioctl +below for more information. +.It Fn if_init +Initialize and bring up the hardware, +e.g., reset the chip and enable the receiver unit. +Should mark the interface running, +but not active +.Dv ( IFF_DRV_RUNNING , ~IIF_DRV_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 . +Flags which begin with +.Dq IFF_DRV_ +are stored in +.Va if_drv_flags ; +all other flags are stored in +.Va if_flags . +.Pp +The macro +.Dv IFF_CANTCHANGE +defines the bits which cannot be set by a user program using the +.Dv SIOCSIFFLAGS +command to +.Xr ioctl 2 ; +these are indicated by an asterisk +.Pq Ql * +in the following listing. +.Pp +.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact +.It Dv IFF_UP +.Aq D +The interface has been configured up by the user-level code. +.It Dv IFF_BROADCAST +.Aq S* +The interface supports broadcast. +.It Dv IFF_DEBUG +.Aq D +Used to enable/disable driver debugging code. +.It Dv IFF_LOOPBACK +.Aq S +The interface is a loopback device. +.It Dv IFF_POINTOPOINT +.Aq S* +The interface is point-to-point; +.Dq broadcast +address is actually the address of the other end. +.It Dv IFF_DRV_RUNNING +.Aq D* +The interface has been configured and dynamic resources were +successfully allocated. +Probably only useful internal to the +interface. +.It Dv IFF_NOARP +.Aq D +Disable network address resolution on this interface. +.It Dv IFF_PROMISC +.Aq D* +This interface is in promiscuous mode. +.It Dv IFF_PPROMISC +.Aq D +This interface is in the permanently promiscuous mode (implies +.Dv IFF_PROMISC ) . +.It Dv IFF_ALLMULTI +.Aq D* +This interface is in all-multicasts mode (used by multicast routers). +.It Dv IFF_PALLMULTI +.Aq D +This interface is in the permanently all-multicasts mode (implies +.Dv IFF_ALLMULTI ) . +.It Dv IFF_DRV_OACTIVE +.Aq D* +The interface's hardware output queue (if any) is full; output packets +are to be queued. +.It Dv IFF_SIMPLEX +.Aq S* +The interface cannot hear its own transmissions. +.It Dv IFF_LINK0 +.It Dv IFF_LINK1 +.It Dv IFF_LINK2 +.Aq D +Control flags for the link layer. +(Currently abused to select among +multiple physical layers on some devices.) +.It Dv IFF_MULTICAST +.Aq S* +This interface supports multicast. +.It Dv IFF_CANTCONFIG +.Aq S* +The interface is not configurable in a meaningful way. +Primarily useful for +.Dv IFT_USB +interfaces registered at the interface list. +.It Dv IFF_MONITOR +.Aq D +This interface blocks transmission of packets and discards incoming +packets after BPF processing. +Used to monitor network traffic but not interact +with the network in question. +.It Dv IFF_STATICARP +.Aq D +Used to enable/disable ARP requests on this interface. +.It Dv IFF_DYING +.Aq D* +Set when the +.Vt ifnet +structure of this interface is being released and still has +.Va if_refcount +references. +.El +.Ss "Interface Capabilities Flags" +Interface capabilities are specialized features an interface may +or may not support. +These capabilities are very hardware-specific +and allow, when enabled, +to offload specific network processing to the interface +or to offer a particular feature for use by other kernel parts. +.Pp +It should be stressed that a capability can be completely +uncontrolled (i.e., stay always enabled with no way to disable it) +or allow limited control over itself (e.g., depend on another +capability's state.) +Such peculiarities are determined solely by the hardware and driver +of a particular interface. +Only the driver possesses +the knowledge on whether and how the interface capabilities +can be controlled. +Consequently, capabilities flags in +.Va if_capenable +should never be modified directly by kernel code other than +the interface driver. +The command +.Dv SIOCSIFCAP +to +.Fn ifioctl +is the dedicated means to attempt altering +.Va if_capenable +on an interface. +Userland code shall use +.Xr ioctl 2 . +.Pp +The following capabilities are currently supported by the system: +.Bl -tag -width ".Dv IFCAP_VLAN_HWTAGGING" -offset indent +.It Dv IFCAP_RXCSUM +This interface can do checksum validation on receiving data. +Some interfaces do not have sufficient buffer storage to store frames +above a certain MTU-size completely. +The driver for the interface might disable hardware checksum validation +if the MTU is set above the hardcoded limit. +.It Dv IFCAP_TXCSUM +This interface can do checksum calculation on transmitting data. +.It Dv IFCAP_HWCSUM +A shorthand for +.Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . +.It Dv IFCAP_NETCONS +This interface can be a network console. +.It Dv IFCAP_VLAN_MTU +The +.Xr vlan 4 +driver can operate over this interface in software tagging mode +without having to decrease MTU on +.Xr vlan 4 +interfaces below 1500 bytes. +This implies the ability of this interface to cope with frames somewhat +longer than permitted by the Ethernet specification. +.It Dv IFCAP_VLAN_HWTAGGING +This interface can do VLAN tagging on output and +demultiplex frames by their VLAN tag on input. +.It Dv IFCAP_JUMBO_MTU +This Ethernet interface can transmit and receive frames up to +9000 bytes long. +.It Dv IFCAP_POLLING +This interface supports +.Xr polling 4 . +See below for details. +.It Dv IFCAP_VLAN_HWCSUM +This interface can do checksum calculation on both transmitting +and receiving data on +.Xr vlan 4 +interfaces (implies +.Dv IFCAP_HWCSUM ) . +.It Dv IFCAP_TSO4 +This Ethernet interface supports TCP4 Segmentation offloading. +.It Dv IFCAP_TSO6 +This Ethernet interface supports TCP6 Segmentation offloading. +.It Dv IFCAP_TSO +A shorthand for +.Pq Dv IFCAP_TSO4 | IFCAP_TSO6 . +.It Dv IFCAP_TOE4 +This Ethernet interface supports TCP4 Offload Engine. +.It Dv IFCAP_TOE6 +This Ethernet interface supports TCP6 Offload Engine. +.It Dv IFCAP_TOE +A shorthand for +.Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . +.It Dv IFCAP_WOL_UCAST +This Ethernet interface supports waking up on any Unicast packet. +.It Dv IFCAP_WOL_MCAST +This Ethernet interface supports waking up on any Multicast packet. +.It Dv IFCAP_WOL_MAGIC +This Ethernet interface supports waking up on any Magic packet such +as those sent by +.Xr wake 8 . +.It Dv IFCAP_WOL +A shorthand for +.Pq Dv IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC . +.It Dv IFCAP_VLAN_HWFILTER +This interface supports frame filtering in hardware on +.Xr vlan 4 +interfaces. +.It Dv IFCAP_VLAN_HWTSO +This interface supports TCP Segmentation offloading on +.Xr vlan 4 +interfaces (implies +.Dv IFCAP_TSO ) . +.It Dv IFCAP_LINKSTATE +This Ethernet interface supports dynamic link state changes. +.It Dv IFCAP_NETMAP +This Ethernet interface supports +.Xr netmap 4 . +.El +.Pp +The ability of advanced network interfaces to offload certain +computational tasks from the host CPU to the board is limited +mostly to TCP/IP. +Therefore a separate field associated with an interface +(see +.Va ifnet.if_data.ifi_hwassist +below) +keeps a detailed description of its enabled capabilities +specific to TCP/IP processing. +The TCP/IP module consults the field to see which tasks +can be done on an +.Em outgoing +packet by the interface. +The flags defined for that field are a superset of those for +.Va mbuf.m_pkthdr.csum_flags , +namely: +.Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent +.It Dv CSUM_IP +The interface will compute IP checksums. +.It Dv CSUM_TCP +The interface will compute TCP checksums. +.It Dv CSUM_UDP +The interface will compute UDP checksums. +.El +.Pp +An interface notifies the TCP/IP module about the tasks +the former has performed on an +.Em incoming +packet by setting the corresponding flags in the field +.Va mbuf.m_pkthdr.csum_flags +of the +.Vt mbuf chain +containing the packet. +See +.Xr mbuf 9 +for details. +.Pp +The capability of a network interface to operate in +.Xr polling 4 +mode involves several flags in different +global variables and per-interface fields. +The capability flag +.Dv IFCAP_POLLING +set in interface's +.Va if_capabilities +indicates support for +.Xr polling 4 +on the particular interface. +If set in +.Va if_capabilities , +the same flag can be marked or cleared in the interface's +.Va if_capenable +within +.Fn ifioctl , +thus initiating switch of the interface to +.Xr polling 4 +mode or interrupt +mode, respectively. +The actual mode change is managed by the driver-specific +.Fn if_ioctl +routine. +The +.Xr polling 4 +handler returns the number of packets processed. +.Ss The if_data Structure +The +.Vt if_data +structure 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. +The following elements of the +.Vt if_data +structure are initialized by the interface and are not expected to change +significantly over the course of normal operation: +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_type +.Pq Vt u_char +The type of the interface, as defined in +.In net/if_types.h +and described below in the +.Sx "Interface Types" +section. +.It Va ifi_physical +.Pq Vt u_char +Intended to represent a selection of physical layers on devices which +support more than one; never implemented. +.It Va ifi_addrlen +.Pq Vt u_char +Length of a link-layer address on this device, or zero if there are +none. +Used to initialized the address length field in +.Vt sockaddr_dl +structures referring to this interface. +.It Va ifi_hdrlen +.Pq Vt u_char +Maximum length of any link-layer header which might be prepended by +the driver to a packet before transmission. +The generic code computes +the maximum over all interfaces and uses that value to influence the +placement of data in +.Vt mbuf Ns s +to attempt to ensure that there is always +sufficient space to prepend a link-layer header without allocating an +additional +.Vt mbuf . +.It Va ifi_datalen +.Pq Vt u_char +Length of the +.Vt if_data +structure. +Allows some stabilization of the routing socket ABI in the face of +increases in the length of +.Vt struct ifdata . +.It Va ifi_mtu +.Pq Vt u_long +The maximum transmission unit of the medium, exclusive of any +link-layer overhead. +.It Va ifi_metric +.Pq Vt u_long +A dimensionless metric interpreted by a user-mode routing process. +.It Va ifi_epoch +.Pq Vt time_t +The system uptime when interface was attached or the statistics +below were reset. +This is intended to be used to set the SNMP variable +.Va ifCounterDiscontinuityTime . +It may also be used to determine if two successive queries for an +interface of the same index have returned results for the same +interface. +.El +.Pp +The structure additionally contains generic statistics applicable to a +variety of different interface types (except as noted, all members are +of type +.Vt u_long ) : +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_link_state +.Pq Vt u_char +The current link state of Ethernet interfaces. +See the +.Sx Interface Link States +section for possible values. +.It Va ifi_ipackets +Number of packets received. +.It Va ifi_ierrors +Number of receive errors detected (e.g., FCS errors, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_opackets +Number of packets transmitted. +.It Va ifi_oerrors +Number of output errors detected (e.g., late collisions, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_collisions +Total number of collisions detected on output for CSMA interfaces. +(This member is sometimes [ab]used by other types of interfaces for +other output error counts.) +.It Va ifi_ibytes +Total traffic received, in bytes. +.It Va ifi_obytes +Total traffic transmitted, in bytes. +.It Va ifi_imcasts +Number of packets received which were sent by link-layer multicast. +.It Va ifi_omcasts +Number of packets sent by link-layer multicast. +.It Va ifi_iqdrops +Number of packets dropped on input. +Rarely implemented. +.It Va ifi_oqdrops +Number of packets dropped on output. +.It Va ifi_noproto +Number of packets received for unknown network-layer protocol. +.It Va ifi_lastchange +.Pq Vt "struct timeval" +The time of the last administrative change to the interface (as required +for SNMP ) . +.El +.Ss Interface Types +The header file +.In net/if_types.h +defines symbolic constants for a number of different types of +interfaces. +The most common are: +.Pp +.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact +.It Dv IFT_OTHER +none of the following +.It Dv IFT_ETHER +Ethernet +.It Dv IFT_ISO88023 +ISO 8802-3 CSMA/CD +.It Dv IFT_ISO88024 +ISO 8802-4 Token Bus +.It Dv IFT_ISO88025 +ISO 8802-5 Token Ring +.It Dv IFT_ISO88026 +ISO 8802-6 DQDB MAN +.It Dv IFT_FDDI +FDDI +.It Dv IFT_PPP +Internet Point-to-Point Protocol +.Pq Xr ppp 8 +.It Dv IFT_LOOP +The loopback +.Pq Xr lo 4 +interface +.It Dv IFT_SLIP +Serial Line IP +.It Dv IFT_PARA +Parallel-port IP +.Pq Dq PLIP +.It Dv IFT_ATM +Asynchronous Transfer Mode +.It Dv IFT_USB +USB Interface +.El +.Ss Interface Link States +The following link states are currently defined: +.Pp +.Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact +.It Dv LINK_STATE_UNKNOWN +The link is in an invalid or unknown state. +.It Dv LINK_STATE_DOWN +The link is down. +.It Dv LINK_STATE_UP +The link is up. +.El +.Ss The ifaddr Structure +Every interface is associated with a list +(or, rather, a +.Li TAILQ ) +of addresses, rooted at the interface structure's +.Va if_addrhead +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 "if_t" +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. +.El +.Pp +References to +.Vt ifaddr +structures are gained by calling the +.Fn ifa_ref +function and released by calling the +.Fn ifa_free +function. +.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, +or delete routes. +The +.Fa cmd +argument indicates the request in question: +.Dv RTM_ADD , +or +.Dv RTM_DELETE . +The +.Fa rt +argument is the route in question; the +.Fa info +argument contains the specific destination being manipulated. +.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 ifmultiaddr Structure +Every multicast-capable interface is associated with a list of +multicast group memberships, which indicate at a low level which +link-layer multicast addresses (if any) should be accepted, and at a +high level, in which network-layer multicast groups a user process has +expressed interest. +.Pp +The elements of the structure are as follows: +.Bl -tag -width ".Va ifma_refcount" -offset indent +.It Va ifma_link +.Pq Fn LIST_ENTRY ifmultiaddr +.Xr queue 3 +macro glue. +.It Va ifma_addr +.Pq Vt "struct sockaddr *" +A pointer to the address which this record represents. +The +memberships for various address families are stored in arbitrary +order. +.It Va ifma_lladdr +.Pq Vt "struct sockaddr *" +A pointer to the link-layer multicast address, if any, to which the +network-layer multicast address in +.Va ifma_addr +is mapped, else a null pointer. +If this element is non-nil, this +membership also holds an invisible reference to another membership for +that link-layer address. +.It Va ifma_refcount +.Pq Vt u_int +A reference count of requests for this particular membership. +.El +.Ss Interface Manipulation Functions +.Bl -ohang -offset indent +.It Fn if_alloc +Allocate and initialize +.Vt "struct ifnet" . +Initialization includes the allocation of an interface index and may +include the allocation of a +.Fa type +specific structure in +.Va if_l2com . +.It Fn if_alloc_dev +Allocate and initialize +.Vt "struct ifnet" +as +.Fn if_alloc +does, with the addition that the ifnet can be tagged with the +appropriate NUMA domain derived from the +.Fa dev +argument passed by the caller. +.It Fn if_alloc_domain +Allocate and initialize +.Vt "struct ifnet" +as +.Fn if_alloc +does, with the addition that the ifnet will be tagged with the NUMA +domain via the +.Fa numa_domain +argument passed by the caller. +.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 +.Vt ifnet +structure.) +The +.Fa ifp +must have been allocated by +.Fn if_alloc , +.Fn if_alloc_dev +or +.Fn if_alloc_domain . +.It Fn if_detach +Shut down and unlink the specified +.Fa ifp +from the interface list. +.It Fn if_free +Free the given +.Fa ifp +back to the system. +The interface must have been previously detached if it was ever attached. +.It Fn if_free_type +Identical to +.Fn if_free +except that the given +.Fa type +is used to free +.Va if_l2com +instead of the type in +.Va if_type . +This is intended for use with drivers that change their interface type. +.It Fn if_down +Mark the interface +.Fa ifp +as down (i.e., +.Dv IFF_UP +is not set), +flush its output queue, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn if_up +Mark the interface +.Fa ifp +as up, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn ifpromisc +Add or remove a promiscuous reference to +.Fa ifp . +If +.Fa pswitch +is true, add a reference; +if it is false, remove a reference. +On reference count transitions +from zero to one and one to zero, set the +.Dv IFF_PROMISC +flag appropriately and call +.Fn if_ioctl +to set up the interface in the desired mode. +.It Fn if_allmulti +As +.Fn ifpromisc , +but for the all-multicasts +.Pq Dv IFF_ALLMULTI +flag instead of the promiscuous flag. +.It Fn ifunit +Return an +.Vt ifnet +pointer for the interface named +.Fa name . +.It Fn ifunit_ref +Return a reference-counted (via +.Fn ifa_ref ) +.Vt ifnet +pointer for the interface named +.Fa name . +This is the preferred function over +.Fn ifunit . +The caller is responsible for releasing the reference with +.Fn if_rele +when it is finished with the ifnet. +.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 SIOCGIFNETMASK" -offset indent -compact +.It Dv SIOCGIFCONF +Get interface configuration. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFNAME +Set the interface name. +.Dv RTM_IFANNOUNCE +departure and arrival messages are sent so that +routing code that relies on the interface name will update its interface +list. +Caller must have appropriate privilege. +(No call-down to driver.) +.It Dv SIOCGIFCAP +.It Dv SIOCGIFDATA +.It Dv SIOCGIFFIB +.It Dv SIOCGIFFLAGS +.It Dv SIOCGIFMETRIC +.It Dv SIOCGIFMTU +.It Dv SIOCGIFPHYS +Get interface capabilities, data, FIB, flags, metric, MTU, medium selection. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFCAP +Enable or disable interface capabilities. +Caller must have appropriate privilege. +Before a call to the driver-specific +.Fn if_ioctl +routine, the requested mask for enabled capabilities is checked +against the mask of capabilities supported by the interface, +.Va if_capabilities . +Requesting to enable an unsupported capability is invalid. +The rest is supposed to be done by the driver, +which includes updating +.Va if_capenable +and +.Va if_data.ifi_hwassist +appropriately. +.Pp +.It Dv SIOCGIFCAPNV +.Xr nv 9 +version of the +.Dv SIOCGIFCAP +ioctl. +Caller must provide a pointer to +.Vt struct ifreq_cap_nv +as +.Fa data , +where the member +.Dv buffer +points to some buffer containing +.Dv buf_length +bytes. +The serialized nvlist with description of the device capabilities +is written to the buffer. +If buffer is too short, the structure is updated with +.Dv buffer +member set to +.Dv NULL , +.Dv length +set to the minimal required length, and error +.Er EFBIG +is returned. +.Pp +Elements of the returned nvlist for simple capabilities are boolean, +identified by names. +Presence of the boolean element means that corresponding capability is +supported by the interface. +Element's value describes the current configured state: +.Dv true +means that the capability is enabled, and +.Dv false +that it is disabled. +.Pp +Driver indicates support for both +.Dv SIOCGIFCAPNV +and +.Dv SIOCSIFCAPNV +requests by setting +.Dv IFCAP_NV +non-modifiable capability bit in +.Dv if_capabilities . +.Pp +.It Dv SIOCSIFCAPNV +.Xr nv 9 +version of the +.Dv SIOCSIFCAP +ioctl. +Caller must provide the pointer to +.Vt struct ifreq_cap_nv +as +.Fa data , +where the member +.Dv buffer +points to serialized nvlist of +.Dv length +bytes. +Each element of nvlist describes a requested update of one capability, +identified by the element name. +For simple capabilities, the element must be boolean. +Its +.Dv true +value means that the caller asks to enable the capability, and +.Dv false +value to disable. +Only capabilities listed in the nvlist are affected by the call. +.Pp +.It Dv SIOCSIFFIB +Sets interface FIB. +Caller must have appropriate privilege. +FIB values start at 0 and values greater or equals than +.Va net.fibs +are considered invalid. +.It Dv SIOCSIFFLAGS +Change interface flags. +Caller must have appropriate privilege. +If a change to the +.Dv IFF_UP +flag is requested, +.Fn if_up +or +.Fn if_down +is called as appropriate. +Flags listed in +.Dv IFF_CANTCHANGE +are masked off, and the field +.Va if_flags +in the interface structure is updated. +Finally, the driver +.Fn if_ioctl +routine is called to perform any setup +requested. +.Pp +.It Dv SIOCSIFMETRIC +.It Dv SIOCSIFPHYS +Change interface metric or medium. +Caller must have appropriate privilege. +.Pp +.It Dv SIOCSIFMTU +Change interface MTU. +Caller must have appropriate privilege. +MTU +values less than 72 or greater than 65535 are considered invalid. +The driver +.Fn if_ioctl +routine is called to implement the change; it is responsible for any +additional sanity checking and for actually modifying the MTU in the +interface structure. +.Pp +.It Dv SIOCADDMULTI +.It Dv SIOCDELMULTI +Add or delete permanent multicast group memberships on the interface. +Caller must have appropriate privilege. +The +.Fn if_addmulti +or +.Fn if_delmulti +function is called to perform the operation; qq.v. +.Pp +.It Dv SIOCAIFADDR +.It Dv SIOCDIFADDR +The socket's protocol control routine is called to implement the +requested action. +.El +.El +.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 +and a fib is +.Fa fib . +If +.Fa fib +is +.Dv RT_ALL_FIBS , +then the first interface address matching +.Fa addr +will be returned. +.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. +If +.Fa ignore_ptp +is true, skip point-to-point interface addresses. +The +.Fa fib +parameter is handled the same way as by +.Fn ifa_ifwithdstaddr . +.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 if_findmulti +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 if_findmulti +function examines the membership list of interface +.Fa ifp +for an address matching +.Fa sa , +and returns a pointer to that +.Vt "struct ifmultiaddr" +if one is found, else it returns a null pointer. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr link_addr 3 , +.Xr queue 3 , +.Xr sysctl 3 , +.Xr bpf 4 , +.Xr ifmib 4 , +.Xr lo 4 , +.Xr netintro 4 , +.Xr polling 4 , +.Xr config 8 , +.Xr ppp 8 , +.Xr mbuf 9 , +.Xr rtentry 9 +.Rs +.%A Gary R. Wright +.%A W. Richard Stevens +.%B TCP/IP Illustrated +.%V Vol. 2 +.%O Addison-Wesley, ISBN 0-201-63354-X +.Re +.Sh AUTHORS +This manual page was written by +.An Garrett A. Wollman . |