1.\" -*- Nroff -*-
2.\" Copyright 1996, 1997 Massachusetts Institute of Technology
3.\"
4.\" Permission to use, copy, modify, and distribute this software and
5.\" its documentation for any purpose and without fee is hereby
6.\" granted, provided that both the above copyright notice and this
7.\" permission notice appear in all copies, that both the above
8.\" copyright notice and this permission notice appear in all
9.\" supporting documentation, and that the name of M.I.T. not be used
10.\" in advertising or publicity pertaining to distribution of the
11.\" software without specific, written prior permission. M.I.T. makes
12.\" no representations about the suitability of this software for any
13.\" purpose. It is provided "as is" without express or implied
14.\" warranty.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
17.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
18.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
19.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
20.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
23.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
26.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
| 1.\" -*- Nroff -*-
2.\" Copyright 1996, 1997 Massachusetts Institute of Technology
3.\"
4.\" Permission to use, copy, modify, and distribute this software and
5.\" its documentation for any purpose and without fee is hereby
6.\" granted, provided that both the above copyright notice and this
7.\" permission notice appear in all copies, that both the above
8.\" copyright notice and this permission notice appear in all
9.\" supporting documentation, and that the name of M.I.T. not be used
10.\" in advertising or publicity pertaining to distribution of the
11.\" software without specific, written prior permission. M.I.T. makes
12.\" no representations about the suitability of this software for any
13.\" purpose. It is provided "as is" without express or implied
14.\" warranty.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
17.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
18.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
19.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
20.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
23.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
26.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
|
32.Os
33.Dt IFNET 9
34.Sh NAME
35.Nm ifnet ,
36.Nm ifaddr ,
37.Nm ifqueue ,
38.Nm if_data
39.Nd kernel interfaces for manipulating network interfaces
40.Sh SYNOPSIS
41.In sys/param.h
42.In sys/time.h
43.In sys/socket.h
44.In net/if.h
45.In net/if_var.h
46.In net/if_types.h
47.\"
48.Ss "Interface Manipulation Functions"
49.Ft "struct ifnet *"
50.Fn if_alloc "u_char type"
51.Ft void
52.Fn if_attach "struct ifnet *ifp"
53.Ft void
54.Fn if_detach "struct ifnet *ifp"
55.Ft void
56.Fn if_free "struct ifnet *ifp"
57.Ft void
58.Fn if_free_type "struct ifnet *ifp" "u_char type"
59.Ft void
60.Fn if_down "struct ifnet *ifp"
61.Ft int
62.Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td"
63.Ft int
64.Fn ifpromisc "struct ifnet *ifp" "int pswitch"
65.Ft int
66.Fn if_allmulti "struct ifnet *ifp" "int amswitch"
67.Ft "struct ifnet *"
68.Fn ifunit "const char *name"
69.Ft void
70.Fn if_up "struct ifnet *ifp"
71.\"
72.Ss "Interface Address Functions"
73.Ft "struct ifaddr *"
74.Fn ifa_ifwithaddr "struct sockaddr *addr"
75.Ft "struct ifaddr *"
76.Fn ifa_ifwithdstaddr "struct sockaddr *addr"
77.Ft "struct ifaddr *"
78.Fn ifa_ifwithnet "struct sockaddr *addr"
79.Ft "struct ifaddr *"
80.Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
81.Ft void
82.Fn ifafree "struct ifaddr *ifa"
83.Fn IFAFREE "struct ifaddr *ifa"
84.\"
85.Ss "Interface Multicast Address Functions"
86.Ft int
87.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap"
88.Ft int
89.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa"
90.Ft "struct ifmultiaddr *"
91.Fn ifmaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
92.Ss "Output queue macros"
93.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m"
94.\"
95.Ss "struct ifnet Member Functions"
96.Ft void
97.Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m"
98.Ft int
99.Fo \*(lp*if_output\*(rp
100.Fa "struct ifnet *ifp" "struct mbuf *m"
101.Fa "struct sockaddr *dst" "struct rtentry *rt"
102.Fc
103.Ft void
104.Fn \*(lp*if_start\*(rp "struct ifnet *ifp"
105.Ft int
106.Fn \*(lp*if_done\*(rp "struct ifnet *ifp"
107.Ft int
108.Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "int cmd" "caddr_t data"
109.Ft void
110.Fn \*(lp*if_watchdog\*(rp "struct ifnet *ifp"
111.Ft int
112.Fn \*(lp*if_poll_recv\*(rp "struct ifnet *ifp" "int *quotap"
113.Ft int
114.Fn \*(lp*if_poll_xmit\*(rp "struct ifnet *ifp" "int *quotap"
115.Ft void
116.Fn \*(lp*if_poll_inttrn\*(rp "struct ifnet *ifp"
117.Ft void
118.Fn \*(lp*if_poll_slowinput\*(rp "struct ifnet *ifp" "struct mbuf *m"
119.Ft void
120.Fn \*(lp*if_init\*(rp "void *if_softc"
121.Ft int
122.Fo \*(lp*if_resolvemulti\*(rp
123.Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr"
124.Fc
125.Ss "struct ifaddr member function"
126.Ft void
127.Fo \*(lp*ifa_rtrequest\*(rp
128.Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
129.Fc
130.\"
131.Ss "Global Variables"
132.Vt extern struct ifnethead ifnet ;
133.Vt extern struct ifaddr **ifnet_addrs ;
134.Vt extern int if_index ;
135.Vt extern int ifqmaxlen ;
136.Sh DATA STRUCTURES
137The kernel mechanisms for handling network interfaces reside primarily
138in the
139.Vt ifnet , if_data , ifaddr ,
140and
141.Vt ifmultiaddr
142structures in
143.In net/if.h
144and
145.In net/if_var.h
146and the functions named above and defined in
147.Pa /sys/net/if.c .
148Those interfaces which are intended to be used by user programs
149are defined in
150.In net/if.h ;
151these include the interface flags, the
152.Vt if_data
153structure, and the structures defining the appearance of
154interface-related messages on the
155.Xr route 4
156routing socket and in
157.Xr sysctl 3 .
158The header file
159.In net/if_var.h
160defines the kernel-internal interfaces, including the
161.Vt ifnet , ifaddr ,
162and
163.Vt ifmultiaddr
164structures and the functions which manipulate them.
165(A few user programs will need
166.In net/if_var.h
167because it is the prerequisite of some other header file like
168.In netinet/if_ether.h .
169Most references to those two files in particular can be replaced by
170.In net/ethernet.h . )
171.Pp
172The system keeps a linked list of interfaces using the
173.Li TAILQ
174macros defined in
175.Xr queue 3 ;
176this list is headed by a
177.Vt "struct ifnethead"
178called
179.Va ifnet .
180The elements of this list are of type
181.Vt "struct ifnet" ,
182and most kernel routines which manipulate interface as such accept or
183return pointers to these structures.
184Each interface structure
185contains an
186.Vt if_data
187structure, which contains statistics and identifying information used
188by management programs, and which is exported to user programs by way
189of the
190.Xr ifmib 4
191branch of the
192.Xr sysctl 3
193MIB.
194Each interface also has a
195.Li TAILQ
196of interface addresses, described by
197.Vt ifaddr
198structures; the head of the queue is always an
199.Dv AF_LINK
200address
201(see
202.Xr link_addr 3 )
203describing the link layer implemented by the interface (if any).
204(Some trivial interfaces do not provide any link layer addresses;
205this structure, while still present, serves only to identify the
206interface name and index.)
207.Pp
208Finally, those interfaces supporting reception of multicast datagrams
209have a
210.Li TAILQ
211of multicast group memberships, described by
212.Vt ifmultiaddr
213structures.
214These memberships are reference-counted.
215.Pp
216Interfaces are also associated with an output queue, defined as a
217.Vt "struct ifqueue" ;
218this structure is used to hold packets while the interface is in the
219process of sending another.
220.Pp
221.Ss The Vt ifnet Ss structure
222The fields of
223.Vt "struct ifnet"
224are as follows:
225.Bl -tag -width ".Va if_capabilities" -offset indent
226.It Va if_softc
227.Pq Vt "void *"
228A pointer to the driver's private state block.
229(Initialized by driver.)
230.It Va if_l2com
231.Pq Vt "void *"
232A pointer to the common data for the interface's layer 2 protocol.
233(Initialized by
234.Fn if_alloc . )
235.It Va if_link
236.Pq Fn TAILQ_ENTRY ifnet
237.Xr queue 3
238macro glue.
239.It Va if_xname
240.Pq Vt "char *"
241The name of the interface,
242(e.g.,
243.Dq Li fxp0
244or
245.Dq Li lo0 ) .
246(Initialized by driver.)
247.It Va if_dname
248.Pq Vt "const char *"
249The name of the driver.
250(Initialized by driver.)
251.It Va if_dunit
252.Pq Vt int
253A unique number assigned to each interface managed by a particular
254driver.
255Drivers may choose to set this to
256.Dv IF_DUNIT_NONE
257if a unit number is not associated with the device.
258(Initialized by driver.)
259.It Va if_addrhead
260.Pq Vt "struct ifaddrhead"
261The head of the
262.Xr queue 3
263.Li TAILQ
264containing the list of addresses assigned to this interface.
265.It Va if_pcount
266.Pq Vt int
267A count of promiscuous listeners on this interface, used to
268reference-count the
269.Dv IFF_PROMISC
270flag.
271.It Va if_bpf
272.Pq Vt "struct bpf_if *"
273Opaque per-interface data for the packet filter,
274.Xr bpf 4 .
275(Initialized by
276.Fn bpf_attach . )
277.It Va if_index
278.Pq Vt u_short
279A unique number assigned to each interface in sequence as it is
280attached.
281This number can be used in a
282.Vt "struct sockaddr_dl"
283to refer to a particular interface by index
284(see
285.Xr link_addr 3 ) .
286(Initialized by
287.Fn if_alloc . )
288.It Va if_timer
289.Pq Vt short
290Number of seconds until the watchdog timer
291.Fn if_watchdog
292is called, or zero if the timer is disabled.
293(Set by driver,
294decremented by generic watchdog code.)
295.It Va if_flags
296.Pq Vt int
297Flags describing operational parameters of this interface (see below).
298(Manipulated by both driver and generic code.)
299.It Va if_capabilities
300.Pq Vt int
301Flags describing the capabilities the interface supports (see below).
302.It Va if_capenable
303.Pq Vt int
304Flags describing the enabled capabilities of the interface (see below).
305.\" .It Va if_ipending
306.\" Interrupt-pending bits for polled operation:
307.\" .Dv IFI_XMIT
308.\" (transmit complete interrupt)
309.\" and
310.\" .Dv IFI_RECV
311.\" (received packet ready interrupt).
312.\" See the
313.\" .Sx Polling
314.\" section, below.
315.\" (Manipulated by driver.)
316.It Va if_linkmib
317.Pq Vt "void *"
318A pointer to an interface-specific MIB structure exported by
319.Xr ifmib 4 .
320(Initialized by driver.)
321.It Va if_linkmiblen
322.Pq Vt size_t
323The size of said structure.
324(Initialized by driver.)
325.It Va if_data
326.Pq Vt "struct if_data"
327More statistics and information; see
328.Sx "The if_data structure" ,
329below.
330(Initialized by driver, manipulated by both driver and generic
331code.)
332.It Va if_snd
333.Pq Vt "struct ifqueue"
334The output queue.
335(Manipulated by driver.)
336.\".It Va if_poll_slowq
337.\".Pq Vt "struct ifqueue *"
338.\"A pointer to the input queue for devices which do not support polling
339.\"well.
340.\"See the
341.\".Sx Polling
342.\"section, below.
343.\"(Initialized by driver.)
344.El
345.Pp
346There are in addition a number of function pointers which the driver
347must initialize to complete its interface with the generic interface
348layer:
349.Bl -ohang -offset indent
350.It Fn if_input
351Pass a packet to an appropriate upper layer as determined
352from the link-layer header of the packet.
353This routine is to be called from an interrupt handler or
354used to emulate reception of a packet on this interface.
355A single function implementing
356.Fn if_input
357can be shared among multiple drivers utilizing the same link-layer
358framing, e.g., Ethernet.
359.It Fn if_output
360Output a packet on interface
361.Fa ifp ,
362or queue it on the output queue if the interface is already active.
363.It Fn if_start
364Start queued output on an interface.
365This function is exposed in
366order to provide for some interface classes to share a
367.Fn if_output
368among all drivers.
369.Fn if_start
370may only be called when the
371.Dv IFF_OACTIVE
372flag is not set.
373(Thus,
374.Dv IFF_OACTIVE
375does not literally mean that output is active, but rather that the
376device's internal output queue is full.)
377.It Fn if_done
378Not used.
379We are not even sure what it was ever for.
380The prototype is faked.
381.It Fn if_ioctl
382Process interface-related
383.Xr ioctl 2
384requests
385(defined in
386.In sys/sockio.h ) .
387Preliminary processing is done by the generic routine
388.Fn ifioctl
389to check for appropriate privileges, locate the interface being
390manipulated, and perform certain generic operations like twiddling
391flags and flushing queues.
392See the description of
393.Fn ifioctl
394below for more information.
395.It Fn if_watchdog
396Routine called by the generic code when the watchdog timer,
397.Va if_timer ,
398expires.
399Usually this will reset the interface.
400.\" .It Fn if_poll_recv
401.\" .It Fn if_poll_xmit
402.\" .It Fn if_poll_slowinput
403.\" .It Fn if_poll_intren
404.\" See the
405.\" .Sx Polling
406.\" section, below.
407.It Fn if_init
408Initialize and bring up the hardware,
409e.g., reset the chip and the watchdog timer and enable the receiver unit.
410Should mark the interface running,
411but not active
412.Dv ( IFF_RUNNING , ~IIF_OACTIVE ) .
413.It Fn if_resolvemulti
414Check the requested multicast group membership,
415.Fa addr ,
416for validity, and if necessary compute a link-layer group which
417corresponds to that address which is returned in
418.Fa *retsa .
419Returns zero on success, or an error code on failure.
420.El
421.Ss "Interface Flags"
422Interface flags are used for a number of different purposes.
423Some
424flags simply indicate information about the type of interface and its
425capabilities; others are dynamically manipulated to reflect the
426current state of the interface.
427Flags of the former kind are marked
428.Aq S
429in this table; the latter are marked
430.Aq D .
431.Pp
432The macro
433.Dv IFF_CANTCHANGE
434defines the bits which cannot be set by a user program using the
435.Dv SIOCSIFFLAGS
436command to
437.Xr ioctl 2 ;
438these are indicated by an asterisk
439.Pq Ql *
440in the following listing.
441.Pp
442.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact
443.It Dv IFF_UP
444.Aq D
445The interface has been configured up by the user-level code.
446.It Dv IFF_BROADCAST
447.Aq S*
448The interface supports broadcast.
449.It Dv IFF_DEBUG
450.Aq D
451Used to enable/disable driver debugging code.
452.It Dv IFF_LOOPBACK
453.Aq S
454The interface is a loopback device.
455.It Dv IFF_POINTOPOINT
456.Aq S*
457The interface is point-to-point;
458.Dq broadcast
459address is actually the address of the other end.
460.It Dv IFF_RUNNING
461.Aq D*
462The interface has been configured and dynamic resources were
463successfully allocated.
464Probably only useful internal to the
465interface.
466.It Dv IFF_NOARP
467.Aq D
468Disable network address resolution on this interface.
469.It Dv IFF_PROMISC
470.Aq D*
471This interface is in promiscuous mode.
472.It Dv IFF_PPROMISC
473.Aq D
474This interface is in the permanently promiscuous mode (implies
475.Dv IFF_PROMISC ) .
476.It Dv IFF_ALLMULTI
477.Aq D*
478This interface is in all-multicasts mode (used by multicast routers).
479.It Dv IFF_OACTIVE
480.Aq D*
481The interface's hardware output queue (if any) is full; output packets
482are to be queued.
483.It Dv IFF_SIMPLEX
484.Aq S*
485The interface cannot hear its own transmissions.
486.It Dv IFF_LINK0
487.It Dv IFF_LINK1
488.It Dv IFF_LINK2
489.Aq D
490Control flags for the link layer.
491(Currently abused to select among
492multiple physical layers on some devices.)
493.It Dv IFF_MULTICAST
494.Aq S*
495This interface supports multicast.
496.It Dv IFF_POLLING
497.Aq D*
498The interface is in
499.Xr polling 4
500mode.
501See
502.Sx Interface Capabilities Flags
503for details.
504.El
505.Ss "Interface Capabilities Flags"
506Interface capabilities are specialized features an interface may
507or may not support.
508These capabilities are very hardware-specific
509and allow, when enabled,
510to offload specific network processing to the interface
511or to offer a particular feature for use by other kernel parts.
512.Pp
513It should be stressed that a capability can be completely
514uncontrolled (i.e., stay always enabled with no way to disable it)
515or allow limited control over itself (e.g., depend on another
516capability's state.)
517Such peculiarities are determined solely by the hardware and driver
518of a particular interface.
519Only the driver possesses
520the knowledge on whether and how the interface capabilities
521can be controlled.
522Consequently, capabilities flags in
523.Va if_capenable
524should never be modified directly by kernel code other than
525the interface driver.
526The command
527.Dv SIOCSIFCAP
528to
529.Fn ifioctl
530is the dedicated means to attempt altering
531.Va if_capenable
532on an interface.
533Userland code shall use
534.Xr ioctl 2 .
535.Pp
536The following capabilities are currently supported by the system:
537.Bl -tag -width ".Dv IFCAP_VLAN_HWTAGGING" -offset indent
538.It Dv IFCAP_NETCONS
539This interface can be a network console.
540.It Dv IFCAP_POLLING
541This interface supports
542.Xr polling 4 .
543See below for details.
544.It Dv IFCAP_RXCSUM
545This interface can do checksum validation on receiving data.
546Some interfaces do not have sufficient buffer storage to store frames
547above a certain MTU-size completely.
548The driver for the interface might disable hardware checksum validation
549if the MTU is set above the hardcoded limit.
550.It Dv IFCAP_TXCSUM
551This interface can do checksum calculation on transmitting data.
552.It Dv IFCAP_HWCSUM
553A shorthand for
554.Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM .
555.It Dv IFCAP_VLAN_HWTAGGING
556This interface can do VLAN tagging on output and
557demultiplex frames by their VLAN tag on input.
558.It Dv IFCAP_VLAN_MTU
559The
560.Xr vlan 4
561driver can operate over this interface in software tagging mode
562without having to decrease MTU on
563.Xr vlan 4
564interfaces below 1500 bytes.
565This implies the ability of this interface to cope with frames somewhat
566longer than permitted by the Ethernet specification.
567.It Dv IFCAP_JUMBO_MTU
568This Ethernet interface can transmit and receive frames up to
5699000 bytes long.
570.El
571.Pp
572The ability of advanced network interfaces to offload certain
573computational tasks from the host CPU to the board is limited
574mostly to TCP/IP.
575Therefore a separate field associated with an interface
576(see
577.Va ifnet.if_data.ifi_hwassist
578below)
579keeps a detailed description of its enabled capabilities
580specific to TCP/IP processing.
581The TCP/IP module consults the field to see which tasks
582can be done on an
583.Em outgoing
584packet by the interface.
585The flags defined for that field are a superset of those for
586.Va mbuf.m_pkthdr.csum_flags ,
587namely:
588.Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent
589.It Dv CSUM_IP
590The interface will compute IP checksums.
591.It Dv CSUM_TCP
592The interface will compute TCP checksums.
593.It Dv CSUM_UDP
594The interface will compute UDP checksums.
595.It Dv CSUM_IP_FRAGS
596The interface can compute a TCP or UDP checksum for a packet
597fragmented by the host CPU.
598Makes sense only along with
599.Dv CSUM_TCP
600or
601.Dv CSUM_UDP .
602.It Dv CSUM_FRAGMENT
603The interface will do the fragmentation of IP packets if necessary.
604The host CPU does not need to care about MTU on this interface
605as long as a packet to transmit through it is an IP one and it
606does not exceed the size of the hardware buffer.
607.El
608.Pp
609An interface notifies the TCP/IP module about the tasks
610the former has performed on an
611.Em incoming
612packet by setting the corresponding flags in the field
613.Va mbuf.m_pkthdr.csum_flags
614of the
615.Vt mbuf chain
616containing the packet.
617See
618.Xr mbuf 9
619for details.
620.Pp
621The capability of a network interface to operate in
622.Xr polling 4
623mode involves several flags in different
624global variables and per-interface fields.
625First, there is a system-wide
626.Xr sysctl 8
627master switch named
628.Va kern.polling.enable ,
629which can toggle
630.Xr polling 4
631globally.
632If that variable is set to non-zero,
633.Xr polling 4
634will be used on those devices where it is enabled individually.
635Otherwise,
636.Xr polling 4
637will not be used in the system.
638Second, the capability flag
639.Dv IFCAP_POLLING
640set in interface's
641.Va if_capabilities
642indicates support for
643.Xr polling 4
644on the particular interface.
645If set in
646.Va if_capabilities ,
647the same flag can be marked or cleared in the interface's
648.Va if_capenable ,
649thus initiating switch of the interface to
650.Xr polling 4
651mode or interrupt
652mode, respectively.
653The actual mode change will occur at an implementation-specific moment
654in the future, e.g., during the next interrupt or
655.Xr polling 4
656cycle.
657And finally, if the mode transition has been successful, the flag
658.Dv IFF_POLLING
659is marked or cleared in the interface's
660.Va if_flags
661to indicate the current mode of the interface.
662.Ss The Vt if_data Ss Structure
663In
664.Bx 4.4 ,
665a subset of the interface information believed to be of interest to
666management stations was segregated from the
667.Vt ifnet
668structure and moved into its own
669.Vt if_data
670structure to facilitate its use by user programs.
671The following elements of the
672.Vt if_data
673structure are initialized by the interface and are not expected to change
674significantly over the course of normal operation:
675.Bl -tag -width ".Va ifi_lastchange" -offset indent
676.It Va ifi_type
677.Pq Vt u_char
678The type of the interface, as defined in
679.In net/if_types.h
680and described below in the
681.Sx "Interface Types"
682section.
683.It Va ifi_physical
684.Pq Vt u_char
685Intended to represent a selection of physical layers on devices which
686support more than one; never implemented.
687.It Va ifi_addrlen
688.Pq Vt u_char
689Length of a link-layer address on this device, or zero if there are
690none.
691Used to initialized the address length field in
692.Vt sockaddr_dl
693structures referring to this interface.
694.It Va ifi_hdrlen
695.Pq Vt u_char
696Maximum length of any link-layer header which might be prepended by
697the driver to a packet before transmission.
698The generic code computes
699the maximum over all interfaces and uses that value to influence the
700placement of data in
701.Vt mbuf Ns s
702to attempt to ensure that there is always
703sufficient space to prepend a link-layer header without allocating an
704additional
705.Vt mbuf .
706.\" (See
707.\" .Xr mbuf 9 . )
708.\" .It Va ifi_recvquota
709.\" .Pq Vt u_char
710.\" Number of packets the interface is permitted to receive at one time
711.\" when in polled mode.
712.\" .It Va ifi_xmitquota
713.\" .Pq Vt u_char
714.\" Number of packets the interface is permitted to queue for transmission
715.\" at one time when in polled mode.
716.\" There is some controversy over
717.\" whether such a restriction makes any sense at all.
718.It Va ifi_datalen
719.Pq Vt u_char
720Length of the
721.Vt if_data
722structure.
723Allows some stabilization of the routing socket ABI in the face of
724increases in the length of
725.Vt struct ifdata .
726.It Va ifi_mtu
727.Pq Vt u_long
728The maximum transmission unit of the medium, exclusive of any
729link-layer overhead.
730.It Va ifi_metric
731.Pq Vt u_long
732A dimensionless metric interpreted by a user-mode routing process.
733.It Va ifi_baudrate
734.Pq Vt u_long
735The line rate of the interface, in bits per second.
736.It Va ifi_hwassist
737.Pq Vt u_long
738A detailed interpretation of the capabilities
739to offload computational tasks for
740.Em outgoing
741packets.
742The interface driver must keep this field in accord with
743the current value of
744.Va if_capenable .
745.It Va ifi_epoch
746.Pq Vt time_t
747The system uptime when interface was attached or the statistics
748below were reset.
749This is intended to be used to set the SNMP variable
750.Va ifCounterDiscontinuityTime .
751It may also be used to determine if two successive queries for an
752interface of the same index have returned results for the same
753interface.
754.El
755.Pp
756The structure additionally contains generic statistics applicable to a
757variety of different interface types (except as noted, all members are
758of type
759.Vt u_long ) :
760.Bl -tag -width ".Va ifi_lastchange" -offset indent
761.It Va ifi_link_state
762.Pq Vt u_char
763The current link state of Ethernet interfaces.
764See the
765.Sx Interface Link States
766section for possible values.
767.It Va ifi_ipackets
768Number of packets received.
769.It Va ifi_ierrors
770Number of receive errors detected (e.g., FCS errors, DMA overruns,
771etc.).
772More detailed breakdowns can often be had by way of a
773link-specific MIB.
774.It Va ifi_opackets
775Number of packets transmitted.
776.It Va ifi_oerrors
777Number of output errors detected (e.g., late collisions, DMA overruns,
778etc.).
779More detailed breakdowns can often be had by way of a
780link-specific MIB.
781.It Va ifi_collisions
782Total number of collisions detected on output for CSMA interfaces.
783(This member is sometimes [ab]used by other types of interfaces for
784other output error counts.)
785.It Va ifi_ibytes
786Total traffic received, in bytes.
787.It Va ifi_obytes
788Total traffic transmitted, in bytes.
789.It Va ifi_imcasts
790Number of packets received which were sent by link-layer multicast.
791.It Va ifi_omcasts
792Number of packets sent by link-layer multicast.
793.It Va ifi_iqdrops
794Number of packets dropped on input.
795Rarely implemented.
796.It Va ifi_noproto
797Number of packets received for unknown network-layer protocol.
798.\" .It Va ifi_recvtiming
799.\" Amount of time, in microseconds, spent to receive an average packet on
800.\" this interface.
801.\" See the
802.\" .Sx Polling
803.\" section, below.
804.\" .It Va ifi_xmittiming
805.\" Amount of time, in microseconds, spent to service a transmit-complete
806.\" interrupt on this interface.
807.\" See the
808.\" .Sx Polling
809.\" section, below.
810.It Va ifi_lastchange
811.Pq Vt "struct timeval"
812The time of the last administrative change to the interface (as required
813for
814.Tn SNMP ) .
815.El
816.Ss Interface Types
817The header file
818.In net/if_types.h
819defines symbolic constants for a number of different types of
820interfaces.
821The most common are:
822.Pp
823.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact
824.It Dv IFT_OTHER
825none of the following
826.It Dv IFT_ETHER
827Ethernet
828.It Dv IFT_ISO88023
829ISO 8802-3 CSMA/CD
830.It Dv IFT_ISO88024
831ISO 8802-4 Token Bus
832.It Dv IFT_ISO88025
833ISO 8802-5 Token Ring
834.It Dv IFT_ISO88026
835ISO 8802-6 DQDB MAN
836.It Dv IFT_FDDI
837FDDI
838.It Dv IFT_PPP
839Internet Point-to-Point Protocol
840.Pq Xr ppp 8
841.It Dv IFT_LOOP
842The loopback
843.Pq Xr lo 4
844interface
845.It Dv IFT_SLIP
846Serial Line IP
847.It Dv IFT_PARA
848Parallel-port IP
849.Pq Dq Tn PLIP
850.It Dv IFT_ATM
851Asynchronous Transfer Mode
852.El
853.Ss Interface Link States
854The following link states are currently defined:
855.Pp
856.Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact
857.It Dv LINK_STATE_UNKNOWN
858The link is in an invalid or unknown state.
859.It Dv LINK_STATE_DOWN
860The link is down.
861.It Dv LINK_STATE_UP
862The link is up.
863.El
864.Ss The Vt ifaddr Ss Structure
865Every interface is associated with a list
866(or, rather, a
867.Li TAILQ )
868of addresses, rooted at the interface structure's
869.Va if_addrlist
870member.
871The first element in this list is always an
872.Dv AF_LINK
873address representing the interface itself; multi-access network
874drivers should complete this structure by filling in their link-layer
875addresses after calling
876.Fn if_attach .
877Other members of the structure represent network-layer addresses which
878have been configured by means of the
879.Dv SIOCAIFADDR
880command to
881.Xr ioctl 2 ,
882called on a socket of the appropriate protocol family.
883The elements of this list consist of
884.Vt ifaddr
885structures.
886Most protocols will declare their own protocol-specific
887interface address structures, but all begin with a
888.Vt "struct ifaddr"
889which provides the most-commonly-needed functionality across all
890protocols.
891Interface addresses are reference-counted.
892.Pp
893The members of
894.Vt "struct ifaddr"
895are as follows:
896.Bl -tag -width ".Va ifa_rtrequest" -offset indent
897.It Va ifa_addr
898.Pq Vt "struct sockaddr *"
899The local address of the interface.
900.It Va ifa_dstaddr
901.Pq Vt "struct sockaddr *"
902The remote address of point-to-point interfaces, and the broadcast
903address of broadcast interfaces.
904.Va ( ifa_broadaddr
905is a macro for
906.Va ifa_dstaddr . )
907.It Va ifa_netmask
908.Pq Vt "struct sockaddr *"
909The network mask for multi-access interfaces, and the confusion
910generator for point-to-point interfaces.
911.It Va ifa_ifp
912.Pq Vt "struct ifnet *"
913A link back to the interface structure.
914.It Va ifa_link
915.Pq Fn TAILQ_ENTRY ifaddr
916.Xr queue 3
917glue for list of addresses on each interface.
918.It Va ifa_rtrequest
919See below.
920.It Va ifa_flags
921.Pq Vt u_short
922Some of the flags which would be used for a route representing this
923address in the route table.
924.It Va ifa_refcnt
925.Pq Vt short
926The reference count.
927.It Va ifa_metric
928.Pq Vt int
929A metric associated with this interface address, for the use of some
930external routing protocol.
931.El
932.Pp
933References to
934.Vt ifaddr
935structures are gained manually, by incrementing the
936.Va ifa_refcnt
937member.
938References are released by calling either the
939.Fn ifafree
940function or the
941.Fn IFAFREE
942macro.
943.Pp
944.Fn ifa_rtrequest
945is a pointer to a function which receives callouts from the routing
946code
947.Pq Fn rtrequest
948to perform link-layer-specific actions upon requests to add, resolve,
949or delete routes.
950The
951.Fa cmd
952argument indicates the request in question:
953.Dv RTM_ADD , RTM_RESOLVE ,
954or
955.Dv RTM_DELETE .
956The
957.Fa rt
958argument is the route in question; the
959.Fa dst
960argument is the specific destination being manipulated
961for
962.Dv RTM_RESOLVE ,
963or a null pointer otherwise.
964.Sh FUNCTIONS
965The functions provided by the generic interface code can be divided
966into two groups: those which manipulate interfaces, and those which
967manipulate interface addresses.
968In addition to these functions, there
969may also be link-layer support routines which are used by a number of
970drivers implementing a specific link layer over different hardware;
971see the documentation for that link layer for more details.
972.Ss The Vt ifmultiaddr Ss Structure
973Every multicast-capable interface is associated with a list of
974multicast group memberships, which indicate at a low level which
975link-layer multicast addresses (if any) should be accepted, and at a
976high level, in which network-layer multicast groups a user process has
977expressed interest.
978.Pp
979The elements of the structure are as follows:
980.Bl -tag -width ".Va ifma_refcount" -offset indent
981.It Va ifma_link
982.Pq Fn LIST_ENTRY ifmultiaddr
983.Xr queue 3
984macro glue.
985.It Va ifma_addr
986.Pq Vt "struct sockaddr *"
987A pointer to the address which this record represents.
988The
989memberships for various address families are stored in arbitrary
990order.
991.It Va ifma_lladdr
992.Pq Vt "struct sockaddr *"
993A pointer to the link-layer multicast address, if any, to which the
994network-layer multicast address in
995.Va ifma_addr
996is mapped, else a null pointer.
997If this element is non-nil, this
998membership also holds an invisible reference to another membership for
999that link-layer address.
1000.It Va ifma_refcount
1001.Pq Vt u_int
1002A reference count of requests for this particular membership.
1003.El
1004.Ss Interface Manipulation Functions
1005.Bl -ohang -offset indent
1006.It Fn if_alloc
| 32.Os
33.Dt IFNET 9
34.Sh NAME
35.Nm ifnet ,
36.Nm ifaddr ,
37.Nm ifqueue ,
38.Nm if_data
39.Nd kernel interfaces for manipulating network interfaces
40.Sh SYNOPSIS
41.In sys/param.h
42.In sys/time.h
43.In sys/socket.h
44.In net/if.h
45.In net/if_var.h
46.In net/if_types.h
47.\"
48.Ss "Interface Manipulation Functions"
49.Ft "struct ifnet *"
50.Fn if_alloc "u_char type"
51.Ft void
52.Fn if_attach "struct ifnet *ifp"
53.Ft void
54.Fn if_detach "struct ifnet *ifp"
55.Ft void
56.Fn if_free "struct ifnet *ifp"
57.Ft void
58.Fn if_free_type "struct ifnet *ifp" "u_char type"
59.Ft void
60.Fn if_down "struct ifnet *ifp"
61.Ft int
62.Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td"
63.Ft int
64.Fn ifpromisc "struct ifnet *ifp" "int pswitch"
65.Ft int
66.Fn if_allmulti "struct ifnet *ifp" "int amswitch"
67.Ft "struct ifnet *"
68.Fn ifunit "const char *name"
69.Ft void
70.Fn if_up "struct ifnet *ifp"
71.\"
72.Ss "Interface Address Functions"
73.Ft "struct ifaddr *"
74.Fn ifa_ifwithaddr "struct sockaddr *addr"
75.Ft "struct ifaddr *"
76.Fn ifa_ifwithdstaddr "struct sockaddr *addr"
77.Ft "struct ifaddr *"
78.Fn ifa_ifwithnet "struct sockaddr *addr"
79.Ft "struct ifaddr *"
80.Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
81.Ft void
82.Fn ifafree "struct ifaddr *ifa"
83.Fn IFAFREE "struct ifaddr *ifa"
84.\"
85.Ss "Interface Multicast Address Functions"
86.Ft int
87.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap"
88.Ft int
89.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa"
90.Ft "struct ifmultiaddr *"
91.Fn ifmaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
92.Ss "Output queue macros"
93.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m"
94.\"
95.Ss "struct ifnet Member Functions"
96.Ft void
97.Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m"
98.Ft int
99.Fo \*(lp*if_output\*(rp
100.Fa "struct ifnet *ifp" "struct mbuf *m"
101.Fa "struct sockaddr *dst" "struct rtentry *rt"
102.Fc
103.Ft void
104.Fn \*(lp*if_start\*(rp "struct ifnet *ifp"
105.Ft int
106.Fn \*(lp*if_done\*(rp "struct ifnet *ifp"
107.Ft int
108.Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "int cmd" "caddr_t data"
109.Ft void
110.Fn \*(lp*if_watchdog\*(rp "struct ifnet *ifp"
111.Ft int
112.Fn \*(lp*if_poll_recv\*(rp "struct ifnet *ifp" "int *quotap"
113.Ft int
114.Fn \*(lp*if_poll_xmit\*(rp "struct ifnet *ifp" "int *quotap"
115.Ft void
116.Fn \*(lp*if_poll_inttrn\*(rp "struct ifnet *ifp"
117.Ft void
118.Fn \*(lp*if_poll_slowinput\*(rp "struct ifnet *ifp" "struct mbuf *m"
119.Ft void
120.Fn \*(lp*if_init\*(rp "void *if_softc"
121.Ft int
122.Fo \*(lp*if_resolvemulti\*(rp
123.Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr"
124.Fc
125.Ss "struct ifaddr member function"
126.Ft void
127.Fo \*(lp*ifa_rtrequest\*(rp
128.Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
129.Fc
130.\"
131.Ss "Global Variables"
132.Vt extern struct ifnethead ifnet ;
133.Vt extern struct ifaddr **ifnet_addrs ;
134.Vt extern int if_index ;
135.Vt extern int ifqmaxlen ;
136.Sh DATA STRUCTURES
137The kernel mechanisms for handling network interfaces reside primarily
138in the
139.Vt ifnet , if_data , ifaddr ,
140and
141.Vt ifmultiaddr
142structures in
143.In net/if.h
144and
145.In net/if_var.h
146and the functions named above and defined in
147.Pa /sys/net/if.c .
148Those interfaces which are intended to be used by user programs
149are defined in
150.In net/if.h ;
151these include the interface flags, the
152.Vt if_data
153structure, and the structures defining the appearance of
154interface-related messages on the
155.Xr route 4
156routing socket and in
157.Xr sysctl 3 .
158The header file
159.In net/if_var.h
160defines the kernel-internal interfaces, including the
161.Vt ifnet , ifaddr ,
162and
163.Vt ifmultiaddr
164structures and the functions which manipulate them.
165(A few user programs will need
166.In net/if_var.h
167because it is the prerequisite of some other header file like
168.In netinet/if_ether.h .
169Most references to those two files in particular can be replaced by
170.In net/ethernet.h . )
171.Pp
172The system keeps a linked list of interfaces using the
173.Li TAILQ
174macros defined in
175.Xr queue 3 ;
176this list is headed by a
177.Vt "struct ifnethead"
178called
179.Va ifnet .
180The elements of this list are of type
181.Vt "struct ifnet" ,
182and most kernel routines which manipulate interface as such accept or
183return pointers to these structures.
184Each interface structure
185contains an
186.Vt if_data
187structure, which contains statistics and identifying information used
188by management programs, and which is exported to user programs by way
189of the
190.Xr ifmib 4
191branch of the
192.Xr sysctl 3
193MIB.
194Each interface also has a
195.Li TAILQ
196of interface addresses, described by
197.Vt ifaddr
198structures; the head of the queue is always an
199.Dv AF_LINK
200address
201(see
202.Xr link_addr 3 )
203describing the link layer implemented by the interface (if any).
204(Some trivial interfaces do not provide any link layer addresses;
205this structure, while still present, serves only to identify the
206interface name and index.)
207.Pp
208Finally, those interfaces supporting reception of multicast datagrams
209have a
210.Li TAILQ
211of multicast group memberships, described by
212.Vt ifmultiaddr
213structures.
214These memberships are reference-counted.
215.Pp
216Interfaces are also associated with an output queue, defined as a
217.Vt "struct ifqueue" ;
218this structure is used to hold packets while the interface is in the
219process of sending another.
220.Pp
221.Ss The Vt ifnet Ss structure
222The fields of
223.Vt "struct ifnet"
224are as follows:
225.Bl -tag -width ".Va if_capabilities" -offset indent
226.It Va if_softc
227.Pq Vt "void *"
228A pointer to the driver's private state block.
229(Initialized by driver.)
230.It Va if_l2com
231.Pq Vt "void *"
232A pointer to the common data for the interface's layer 2 protocol.
233(Initialized by
234.Fn if_alloc . )
235.It Va if_link
236.Pq Fn TAILQ_ENTRY ifnet
237.Xr queue 3
238macro glue.
239.It Va if_xname
240.Pq Vt "char *"
241The name of the interface,
242(e.g.,
243.Dq Li fxp0
244or
245.Dq Li lo0 ) .
246(Initialized by driver.)
247.It Va if_dname
248.Pq Vt "const char *"
249The name of the driver.
250(Initialized by driver.)
251.It Va if_dunit
252.Pq Vt int
253A unique number assigned to each interface managed by a particular
254driver.
255Drivers may choose to set this to
256.Dv IF_DUNIT_NONE
257if a unit number is not associated with the device.
258(Initialized by driver.)
259.It Va if_addrhead
260.Pq Vt "struct ifaddrhead"
261The head of the
262.Xr queue 3
263.Li TAILQ
264containing the list of addresses assigned to this interface.
265.It Va if_pcount
266.Pq Vt int
267A count of promiscuous listeners on this interface, used to
268reference-count the
269.Dv IFF_PROMISC
270flag.
271.It Va if_bpf
272.Pq Vt "struct bpf_if *"
273Opaque per-interface data for the packet filter,
274.Xr bpf 4 .
275(Initialized by
276.Fn bpf_attach . )
277.It Va if_index
278.Pq Vt u_short
279A unique number assigned to each interface in sequence as it is
280attached.
281This number can be used in a
282.Vt "struct sockaddr_dl"
283to refer to a particular interface by index
284(see
285.Xr link_addr 3 ) .
286(Initialized by
287.Fn if_alloc . )
288.It Va if_timer
289.Pq Vt short
290Number of seconds until the watchdog timer
291.Fn if_watchdog
292is called, or zero if the timer is disabled.
293(Set by driver,
294decremented by generic watchdog code.)
295.It Va if_flags
296.Pq Vt int
297Flags describing operational parameters of this interface (see below).
298(Manipulated by both driver and generic code.)
299.It Va if_capabilities
300.Pq Vt int
301Flags describing the capabilities the interface supports (see below).
302.It Va if_capenable
303.Pq Vt int
304Flags describing the enabled capabilities of the interface (see below).
305.\" .It Va if_ipending
306.\" Interrupt-pending bits for polled operation:
307.\" .Dv IFI_XMIT
308.\" (transmit complete interrupt)
309.\" and
310.\" .Dv IFI_RECV
311.\" (received packet ready interrupt).
312.\" See the
313.\" .Sx Polling
314.\" section, below.
315.\" (Manipulated by driver.)
316.It Va if_linkmib
317.Pq Vt "void *"
318A pointer to an interface-specific MIB structure exported by
319.Xr ifmib 4 .
320(Initialized by driver.)
321.It Va if_linkmiblen
322.Pq Vt size_t
323The size of said structure.
324(Initialized by driver.)
325.It Va if_data
326.Pq Vt "struct if_data"
327More statistics and information; see
328.Sx "The if_data structure" ,
329below.
330(Initialized by driver, manipulated by both driver and generic
331code.)
332.It Va if_snd
333.Pq Vt "struct ifqueue"
334The output queue.
335(Manipulated by driver.)
336.\".It Va if_poll_slowq
337.\".Pq Vt "struct ifqueue *"
338.\"A pointer to the input queue for devices which do not support polling
339.\"well.
340.\"See the
341.\".Sx Polling
342.\"section, below.
343.\"(Initialized by driver.)
344.El
345.Pp
346There are in addition a number of function pointers which the driver
347must initialize to complete its interface with the generic interface
348layer:
349.Bl -ohang -offset indent
350.It Fn if_input
351Pass a packet to an appropriate upper layer as determined
352from the link-layer header of the packet.
353This routine is to be called from an interrupt handler or
354used to emulate reception of a packet on this interface.
355A single function implementing
356.Fn if_input
357can be shared among multiple drivers utilizing the same link-layer
358framing, e.g., Ethernet.
359.It Fn if_output
360Output a packet on interface
361.Fa ifp ,
362or queue it on the output queue if the interface is already active.
363.It Fn if_start
364Start queued output on an interface.
365This function is exposed in
366order to provide for some interface classes to share a
367.Fn if_output
368among all drivers.
369.Fn if_start
370may only be called when the
371.Dv IFF_OACTIVE
372flag is not set.
373(Thus,
374.Dv IFF_OACTIVE
375does not literally mean that output is active, but rather that the
376device's internal output queue is full.)
377.It Fn if_done
378Not used.
379We are not even sure what it was ever for.
380The prototype is faked.
381.It Fn if_ioctl
382Process interface-related
383.Xr ioctl 2
384requests
385(defined in
386.In sys/sockio.h ) .
387Preliminary processing is done by the generic routine
388.Fn ifioctl
389to check for appropriate privileges, locate the interface being
390manipulated, and perform certain generic operations like twiddling
391flags and flushing queues.
392See the description of
393.Fn ifioctl
394below for more information.
395.It Fn if_watchdog
396Routine called by the generic code when the watchdog timer,
397.Va if_timer ,
398expires.
399Usually this will reset the interface.
400.\" .It Fn if_poll_recv
401.\" .It Fn if_poll_xmit
402.\" .It Fn if_poll_slowinput
403.\" .It Fn if_poll_intren
404.\" See the
405.\" .Sx Polling
406.\" section, below.
407.It Fn if_init
408Initialize and bring up the hardware,
409e.g., reset the chip and the watchdog timer and enable the receiver unit.
410Should mark the interface running,
411but not active
412.Dv ( IFF_RUNNING , ~IIF_OACTIVE ) .
413.It Fn if_resolvemulti
414Check the requested multicast group membership,
415.Fa addr ,
416for validity, and if necessary compute a link-layer group which
417corresponds to that address which is returned in
418.Fa *retsa .
419Returns zero on success, or an error code on failure.
420.El
421.Ss "Interface Flags"
422Interface flags are used for a number of different purposes.
423Some
424flags simply indicate information about the type of interface and its
425capabilities; others are dynamically manipulated to reflect the
426current state of the interface.
427Flags of the former kind are marked
428.Aq S
429in this table; the latter are marked
430.Aq D .
431.Pp
432The macro
433.Dv IFF_CANTCHANGE
434defines the bits which cannot be set by a user program using the
435.Dv SIOCSIFFLAGS
436command to
437.Xr ioctl 2 ;
438these are indicated by an asterisk
439.Pq Ql *
440in the following listing.
441.Pp
442.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact
443.It Dv IFF_UP
444.Aq D
445The interface has been configured up by the user-level code.
446.It Dv IFF_BROADCAST
447.Aq S*
448The interface supports broadcast.
449.It Dv IFF_DEBUG
450.Aq D
451Used to enable/disable driver debugging code.
452.It Dv IFF_LOOPBACK
453.Aq S
454The interface is a loopback device.
455.It Dv IFF_POINTOPOINT
456.Aq S*
457The interface is point-to-point;
458.Dq broadcast
459address is actually the address of the other end.
460.It Dv IFF_RUNNING
461.Aq D*
462The interface has been configured and dynamic resources were
463successfully allocated.
464Probably only useful internal to the
465interface.
466.It Dv IFF_NOARP
467.Aq D
468Disable network address resolution on this interface.
469.It Dv IFF_PROMISC
470.Aq D*
471This interface is in promiscuous mode.
472.It Dv IFF_PPROMISC
473.Aq D
474This interface is in the permanently promiscuous mode (implies
475.Dv IFF_PROMISC ) .
476.It Dv IFF_ALLMULTI
477.Aq D*
478This interface is in all-multicasts mode (used by multicast routers).
479.It Dv IFF_OACTIVE
480.Aq D*
481The interface's hardware output queue (if any) is full; output packets
482are to be queued.
483.It Dv IFF_SIMPLEX
484.Aq S*
485The interface cannot hear its own transmissions.
486.It Dv IFF_LINK0
487.It Dv IFF_LINK1
488.It Dv IFF_LINK2
489.Aq D
490Control flags for the link layer.
491(Currently abused to select among
492multiple physical layers on some devices.)
493.It Dv IFF_MULTICAST
494.Aq S*
495This interface supports multicast.
496.It Dv IFF_POLLING
497.Aq D*
498The interface is in
499.Xr polling 4
500mode.
501See
502.Sx Interface Capabilities Flags
503for details.
504.El
505.Ss "Interface Capabilities Flags"
506Interface capabilities are specialized features an interface may
507or may not support.
508These capabilities are very hardware-specific
509and allow, when enabled,
510to offload specific network processing to the interface
511or to offer a particular feature for use by other kernel parts.
512.Pp
513It should be stressed that a capability can be completely
514uncontrolled (i.e., stay always enabled with no way to disable it)
515or allow limited control over itself (e.g., depend on another
516capability's state.)
517Such peculiarities are determined solely by the hardware and driver
518of a particular interface.
519Only the driver possesses
520the knowledge on whether and how the interface capabilities
521can be controlled.
522Consequently, capabilities flags in
523.Va if_capenable
524should never be modified directly by kernel code other than
525the interface driver.
526The command
527.Dv SIOCSIFCAP
528to
529.Fn ifioctl
530is the dedicated means to attempt altering
531.Va if_capenable
532on an interface.
533Userland code shall use
534.Xr ioctl 2 .
535.Pp
536The following capabilities are currently supported by the system:
537.Bl -tag -width ".Dv IFCAP_VLAN_HWTAGGING" -offset indent
538.It Dv IFCAP_NETCONS
539This interface can be a network console.
540.It Dv IFCAP_POLLING
541This interface supports
542.Xr polling 4 .
543See below for details.
544.It Dv IFCAP_RXCSUM
545This interface can do checksum validation on receiving data.
546Some interfaces do not have sufficient buffer storage to store frames
547above a certain MTU-size completely.
548The driver for the interface might disable hardware checksum validation
549if the MTU is set above the hardcoded limit.
550.It Dv IFCAP_TXCSUM
551This interface can do checksum calculation on transmitting data.
552.It Dv IFCAP_HWCSUM
553A shorthand for
554.Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM .
555.It Dv IFCAP_VLAN_HWTAGGING
556This interface can do VLAN tagging on output and
557demultiplex frames by their VLAN tag on input.
558.It Dv IFCAP_VLAN_MTU
559The
560.Xr vlan 4
561driver can operate over this interface in software tagging mode
562without having to decrease MTU on
563.Xr vlan 4
564interfaces below 1500 bytes.
565This implies the ability of this interface to cope with frames somewhat
566longer than permitted by the Ethernet specification.
567.It Dv IFCAP_JUMBO_MTU
568This Ethernet interface can transmit and receive frames up to
5699000 bytes long.
570.El
571.Pp
572The ability of advanced network interfaces to offload certain
573computational tasks from the host CPU to the board is limited
574mostly to TCP/IP.
575Therefore a separate field associated with an interface
576(see
577.Va ifnet.if_data.ifi_hwassist
578below)
579keeps a detailed description of its enabled capabilities
580specific to TCP/IP processing.
581The TCP/IP module consults the field to see which tasks
582can be done on an
583.Em outgoing
584packet by the interface.
585The flags defined for that field are a superset of those for
586.Va mbuf.m_pkthdr.csum_flags ,
587namely:
588.Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent
589.It Dv CSUM_IP
590The interface will compute IP checksums.
591.It Dv CSUM_TCP
592The interface will compute TCP checksums.
593.It Dv CSUM_UDP
594The interface will compute UDP checksums.
595.It Dv CSUM_IP_FRAGS
596The interface can compute a TCP or UDP checksum for a packet
597fragmented by the host CPU.
598Makes sense only along with
599.Dv CSUM_TCP
600or
601.Dv CSUM_UDP .
602.It Dv CSUM_FRAGMENT
603The interface will do the fragmentation of IP packets if necessary.
604The host CPU does not need to care about MTU on this interface
605as long as a packet to transmit through it is an IP one and it
606does not exceed the size of the hardware buffer.
607.El
608.Pp
609An interface notifies the TCP/IP module about the tasks
610the former has performed on an
611.Em incoming
612packet by setting the corresponding flags in the field
613.Va mbuf.m_pkthdr.csum_flags
614of the
615.Vt mbuf chain
616containing the packet.
617See
618.Xr mbuf 9
619for details.
620.Pp
621The capability of a network interface to operate in
622.Xr polling 4
623mode involves several flags in different
624global variables and per-interface fields.
625First, there is a system-wide
626.Xr sysctl 8
627master switch named
628.Va kern.polling.enable ,
629which can toggle
630.Xr polling 4
631globally.
632If that variable is set to non-zero,
633.Xr polling 4
634will be used on those devices where it is enabled individually.
635Otherwise,
636.Xr polling 4
637will not be used in the system.
638Second, the capability flag
639.Dv IFCAP_POLLING
640set in interface's
641.Va if_capabilities
642indicates support for
643.Xr polling 4
644on the particular interface.
645If set in
646.Va if_capabilities ,
647the same flag can be marked or cleared in the interface's
648.Va if_capenable ,
649thus initiating switch of the interface to
650.Xr polling 4
651mode or interrupt
652mode, respectively.
653The actual mode change will occur at an implementation-specific moment
654in the future, e.g., during the next interrupt or
655.Xr polling 4
656cycle.
657And finally, if the mode transition has been successful, the flag
658.Dv IFF_POLLING
659is marked or cleared in the interface's
660.Va if_flags
661to indicate the current mode of the interface.
662.Ss The Vt if_data Ss Structure
663In
664.Bx 4.4 ,
665a subset of the interface information believed to be of interest to
666management stations was segregated from the
667.Vt ifnet
668structure and moved into its own
669.Vt if_data
670structure to facilitate its use by user programs.
671The following elements of the
672.Vt if_data
673structure are initialized by the interface and are not expected to change
674significantly over the course of normal operation:
675.Bl -tag -width ".Va ifi_lastchange" -offset indent
676.It Va ifi_type
677.Pq Vt u_char
678The type of the interface, as defined in
679.In net/if_types.h
680and described below in the
681.Sx "Interface Types"
682section.
683.It Va ifi_physical
684.Pq Vt u_char
685Intended to represent a selection of physical layers on devices which
686support more than one; never implemented.
687.It Va ifi_addrlen
688.Pq Vt u_char
689Length of a link-layer address on this device, or zero if there are
690none.
691Used to initialized the address length field in
692.Vt sockaddr_dl
693structures referring to this interface.
694.It Va ifi_hdrlen
695.Pq Vt u_char
696Maximum length of any link-layer header which might be prepended by
697the driver to a packet before transmission.
698The generic code computes
699the maximum over all interfaces and uses that value to influence the
700placement of data in
701.Vt mbuf Ns s
702to attempt to ensure that there is always
703sufficient space to prepend a link-layer header without allocating an
704additional
705.Vt mbuf .
706.\" (See
707.\" .Xr mbuf 9 . )
708.\" .It Va ifi_recvquota
709.\" .Pq Vt u_char
710.\" Number of packets the interface is permitted to receive at one time
711.\" when in polled mode.
712.\" .It Va ifi_xmitquota
713.\" .Pq Vt u_char
714.\" Number of packets the interface is permitted to queue for transmission
715.\" at one time when in polled mode.
716.\" There is some controversy over
717.\" whether such a restriction makes any sense at all.
718.It Va ifi_datalen
719.Pq Vt u_char
720Length of the
721.Vt if_data
722structure.
723Allows some stabilization of the routing socket ABI in the face of
724increases in the length of
725.Vt struct ifdata .
726.It Va ifi_mtu
727.Pq Vt u_long
728The maximum transmission unit of the medium, exclusive of any
729link-layer overhead.
730.It Va ifi_metric
731.Pq Vt u_long
732A dimensionless metric interpreted by a user-mode routing process.
733.It Va ifi_baudrate
734.Pq Vt u_long
735The line rate of the interface, in bits per second.
736.It Va ifi_hwassist
737.Pq Vt u_long
738A detailed interpretation of the capabilities
739to offload computational tasks for
740.Em outgoing
741packets.
742The interface driver must keep this field in accord with
743the current value of
744.Va if_capenable .
745.It Va ifi_epoch
746.Pq Vt time_t
747The system uptime when interface was attached or the statistics
748below were reset.
749This is intended to be used to set the SNMP variable
750.Va ifCounterDiscontinuityTime .
751It may also be used to determine if two successive queries for an
752interface of the same index have returned results for the same
753interface.
754.El
755.Pp
756The structure additionally contains generic statistics applicable to a
757variety of different interface types (except as noted, all members are
758of type
759.Vt u_long ) :
760.Bl -tag -width ".Va ifi_lastchange" -offset indent
761.It Va ifi_link_state
762.Pq Vt u_char
763The current link state of Ethernet interfaces.
764See the
765.Sx Interface Link States
766section for possible values.
767.It Va ifi_ipackets
768Number of packets received.
769.It Va ifi_ierrors
770Number of receive errors detected (e.g., FCS errors, DMA overruns,
771etc.).
772More detailed breakdowns can often be had by way of a
773link-specific MIB.
774.It Va ifi_opackets
775Number of packets transmitted.
776.It Va ifi_oerrors
777Number of output errors detected (e.g., late collisions, DMA overruns,
778etc.).
779More detailed breakdowns can often be had by way of a
780link-specific MIB.
781.It Va ifi_collisions
782Total number of collisions detected on output for CSMA interfaces.
783(This member is sometimes [ab]used by other types of interfaces for
784other output error counts.)
785.It Va ifi_ibytes
786Total traffic received, in bytes.
787.It Va ifi_obytes
788Total traffic transmitted, in bytes.
789.It Va ifi_imcasts
790Number of packets received which were sent by link-layer multicast.
791.It Va ifi_omcasts
792Number of packets sent by link-layer multicast.
793.It Va ifi_iqdrops
794Number of packets dropped on input.
795Rarely implemented.
796.It Va ifi_noproto
797Number of packets received for unknown network-layer protocol.
798.\" .It Va ifi_recvtiming
799.\" Amount of time, in microseconds, spent to receive an average packet on
800.\" this interface.
801.\" See the
802.\" .Sx Polling
803.\" section, below.
804.\" .It Va ifi_xmittiming
805.\" Amount of time, in microseconds, spent to service a transmit-complete
806.\" interrupt on this interface.
807.\" See the
808.\" .Sx Polling
809.\" section, below.
810.It Va ifi_lastchange
811.Pq Vt "struct timeval"
812The time of the last administrative change to the interface (as required
813for
814.Tn SNMP ) .
815.El
816.Ss Interface Types
817The header file
818.In net/if_types.h
819defines symbolic constants for a number of different types of
820interfaces.
821The most common are:
822.Pp
823.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact
824.It Dv IFT_OTHER
825none of the following
826.It Dv IFT_ETHER
827Ethernet
828.It Dv IFT_ISO88023
829ISO 8802-3 CSMA/CD
830.It Dv IFT_ISO88024
831ISO 8802-4 Token Bus
832.It Dv IFT_ISO88025
833ISO 8802-5 Token Ring
834.It Dv IFT_ISO88026
835ISO 8802-6 DQDB MAN
836.It Dv IFT_FDDI
837FDDI
838.It Dv IFT_PPP
839Internet Point-to-Point Protocol
840.Pq Xr ppp 8
841.It Dv IFT_LOOP
842The loopback
843.Pq Xr lo 4
844interface
845.It Dv IFT_SLIP
846Serial Line IP
847.It Dv IFT_PARA
848Parallel-port IP
849.Pq Dq Tn PLIP
850.It Dv IFT_ATM
851Asynchronous Transfer Mode
852.El
853.Ss Interface Link States
854The following link states are currently defined:
855.Pp
856.Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact
857.It Dv LINK_STATE_UNKNOWN
858The link is in an invalid or unknown state.
859.It Dv LINK_STATE_DOWN
860The link is down.
861.It Dv LINK_STATE_UP
862The link is up.
863.El
864.Ss The Vt ifaddr Ss Structure
865Every interface is associated with a list
866(or, rather, a
867.Li TAILQ )
868of addresses, rooted at the interface structure's
869.Va if_addrlist
870member.
871The first element in this list is always an
872.Dv AF_LINK
873address representing the interface itself; multi-access network
874drivers should complete this structure by filling in their link-layer
875addresses after calling
876.Fn if_attach .
877Other members of the structure represent network-layer addresses which
878have been configured by means of the
879.Dv SIOCAIFADDR
880command to
881.Xr ioctl 2 ,
882called on a socket of the appropriate protocol family.
883The elements of this list consist of
884.Vt ifaddr
885structures.
886Most protocols will declare their own protocol-specific
887interface address structures, but all begin with a
888.Vt "struct ifaddr"
889which provides the most-commonly-needed functionality across all
890protocols.
891Interface addresses are reference-counted.
892.Pp
893The members of
894.Vt "struct ifaddr"
895are as follows:
896.Bl -tag -width ".Va ifa_rtrequest" -offset indent
897.It Va ifa_addr
898.Pq Vt "struct sockaddr *"
899The local address of the interface.
900.It Va ifa_dstaddr
901.Pq Vt "struct sockaddr *"
902The remote address of point-to-point interfaces, and the broadcast
903address of broadcast interfaces.
904.Va ( ifa_broadaddr
905is a macro for
906.Va ifa_dstaddr . )
907.It Va ifa_netmask
908.Pq Vt "struct sockaddr *"
909The network mask for multi-access interfaces, and the confusion
910generator for point-to-point interfaces.
911.It Va ifa_ifp
912.Pq Vt "struct ifnet *"
913A link back to the interface structure.
914.It Va ifa_link
915.Pq Fn TAILQ_ENTRY ifaddr
916.Xr queue 3
917glue for list of addresses on each interface.
918.It Va ifa_rtrequest
919See below.
920.It Va ifa_flags
921.Pq Vt u_short
922Some of the flags which would be used for a route representing this
923address in the route table.
924.It Va ifa_refcnt
925.Pq Vt short
926The reference count.
927.It Va ifa_metric
928.Pq Vt int
929A metric associated with this interface address, for the use of some
930external routing protocol.
931.El
932.Pp
933References to
934.Vt ifaddr
935structures are gained manually, by incrementing the
936.Va ifa_refcnt
937member.
938References are released by calling either the
939.Fn ifafree
940function or the
941.Fn IFAFREE
942macro.
943.Pp
944.Fn ifa_rtrequest
945is a pointer to a function which receives callouts from the routing
946code
947.Pq Fn rtrequest
948to perform link-layer-specific actions upon requests to add, resolve,
949or delete routes.
950The
951.Fa cmd
952argument indicates the request in question:
953.Dv RTM_ADD , RTM_RESOLVE ,
954or
955.Dv RTM_DELETE .
956The
957.Fa rt
958argument is the route in question; the
959.Fa dst
960argument is the specific destination being manipulated
961for
962.Dv RTM_RESOLVE ,
963or a null pointer otherwise.
964.Sh FUNCTIONS
965The functions provided by the generic interface code can be divided
966into two groups: those which manipulate interfaces, and those which
967manipulate interface addresses.
968In addition to these functions, there
969may also be link-layer support routines which are used by a number of
970drivers implementing a specific link layer over different hardware;
971see the documentation for that link layer for more details.
972.Ss The Vt ifmultiaddr Ss Structure
973Every multicast-capable interface is associated with a list of
974multicast group memberships, which indicate at a low level which
975link-layer multicast addresses (if any) should be accepted, and at a
976high level, in which network-layer multicast groups a user process has
977expressed interest.
978.Pp
979The elements of the structure are as follows:
980.Bl -tag -width ".Va ifma_refcount" -offset indent
981.It Va ifma_link
982.Pq Fn LIST_ENTRY ifmultiaddr
983.Xr queue 3
984macro glue.
985.It Va ifma_addr
986.Pq Vt "struct sockaddr *"
987A pointer to the address which this record represents.
988The
989memberships for various address families are stored in arbitrary
990order.
991.It Va ifma_lladdr
992.Pq Vt "struct sockaddr *"
993A pointer to the link-layer multicast address, if any, to which the
994network-layer multicast address in
995.Va ifma_addr
996is mapped, else a null pointer.
997If this element is non-nil, this
998membership also holds an invisible reference to another membership for
999that link-layer address.
1000.It Va ifma_refcount
1001.Pq Vt u_int
1002A reference count of requests for this particular membership.
1003.El
1004.Ss Interface Manipulation Functions
1005.Bl -ohang -offset indent
1006.It Fn if_alloc
|
1044.Va if_l2com
1045instead of the type in
1046.Va if_type .
1047This is intended for use with drivers that change their interface type.
1048.It Fn if_down
1049Mark the interface
1050.Fa ifp
1051as down (i.e.,
1052.Dv IFF_UP
1053is not set),
1054flush its output queue, notify protocols of the transition,
1055and generate a message from the
1056.Xr route 4
1057routing socket.
1058.It Fn if_up
1059Mark the interface
1060.Fa ifp
1061as up, notify protocols of the transition,
1062and generate a message from the
1063.Xr route 4
1064routing socket.
1065.It Fn ifpromisc
1066Add or remove a promiscuous reference to
1067.Fa ifp .
1068If
1069.Fa pswitch
1070is true, add a reference;
1071if it is false, remove a reference.
1072On reference count transitions
1073from zero to one and one to zero, set the
1074.Dv IFF_PROMISC
1075flag appropriately and call
1076.Fn if_ioctl
1077to set up the interface in the desired mode.
1078.It Fn if_allmulti
1079As
1080.Fn ifpromisc ,
1081but for the all-multicasts
1082.Pq Dv IFF_ALLMULTI
1083flag instead of the promiscuous flag.
1084.It Fn ifunit
1085Return an
1086.Vt ifnet
1087pointer for the interface named
1088.Fa name .
1089.It Fn ifioctl
1090Process the ioctl request
1091.Fa cmd ,
1092issued on socket
1093.Fa so
1094by thread
1095.Fa td ,
1096with data parameter
1097.Fa data .
1098This is the main routine for handling all interface configuration
1099requests from user mode.
1100It is ordinarily only called from the socket-layer
1101.Xr ioctl 2
1102handler, and only for commands with class
1103.Sq Li i .
1104Any unrecognized commands will be passed down to socket
1105.Fa so Ns 's
1106protocol for
1107further interpretation.
1108The following commands are handled by
1109.Fn ifioctl :
1110.Pp
1111.Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact
1112.It Dv SIOCGIFCONF
1113.It Dv OSIOCGIFCONF
1114Get interface configuration.
1115(No call-down to driver.)
1116.Pp
1117.It Dv SIOCSIFNAME
1118Set the interface name.
1119.Dv RTM_IFANNOUNCE
1120departure and arrival messages are sent so that
1121routing code that relies on the interface name will update its interface
1122list.
1123Caller must have appropriate privilege.
1124(No call-down to driver.)
1125.It Dv SIOCGIFCAP
1126.It Dv SIOCGIFFLAGS
1127.It Dv SIOCGIFMETRIC
1128.It Dv SIOCGIFMTU
1129.It Dv SIOCGIFPHYS
1130Get interface capabilities, flags, metric, MTU, medium selection.
1131(No call-down to driver.)
1132.Pp
1133.It Dv SIOCSIFCAP
1134Enable or disable interface capabilities.
1135Caller must have appropriate privilege.
1136Before a call to the driver-specific
1137.Fn if_ioctl
1138routine, the requested mask for enabled capabilities is checked
1139against the mask of capabilities supported by the interface,
1140.Va if_capabilities .
1141Requesting to enable an unsupported capability is invalid.
1142The rest is supposed to be done by the driver,
1143which includes updating
1144.Va if_capenable
1145and
1146.Va if_data.ifi_hwassist
1147appropriately.
1148.Pp
1149.It Dv SIOCSIFFLAGS
1150Change interface flags.
1151Caller must have appropriate privilege.
1152If a change to the
1153.Dv IFF_UP
1154flag is requested,
1155.Fn if_up
1156or
1157.Fn if_down
1158is called as appropriate.
1159Flags listed in
1160.Dv IFF_CANTCHANGE
1161are masked off, and the field
1162.Va if_flags
1163in the interface structure is updated.
1164Finally, the driver
1165.Fn if_ioctl
1166routine is called to perform any setup
1167requested.
1168.Pp
1169.It Dv SIOCSIFMETRIC
1170.It Dv SIOCSIFPHYS
1171Change interface metric or medium.
1172Caller must have appropriate privilege.
1173.Pp
1174.It Dv SIOCSIFMTU
1175Change interface MTU.
1176Caller must have appropriate privilege.
1177MTU
1178values less than 72 or greater than 65535 are considered invalid.
1179The driver
1180.Fn if_ioctl
1181routine is called to implement the change; it is responsible for any
1182additional sanity checking and for actually modifying the MTU in the
1183interface structure.
1184.Pp
1185.It Dv SIOCADDMULTI
1186.It Dv SIOCDELMULTI
1187Add or delete permanent multicast group memberships on the interface.
1188Caller must have appropriate privilege.
1189The
1190.Fn if_addmulti
1191or
1192.Fn if_delmulti
1193function is called to perform the operation; qq.v.
1194.Pp
1195.It Dv SIOCSIFDSTADDR
1196.It Dv SIOCSIFADDR
1197.It Dv SIOCSIFBRDADDR
1198.It Dv SIOCSIFNETMASK
1199The socket's protocol control routine is called to implement the
1200requested action.
1201.Pp
1202.It Dv OSIOGIFADDR
1203.It Dv OSIOCGIFDSTADDR
1204.It Dv OSIOCGIFBRDADDR
1205.It Dv OSIOCGIFNETMASK
1206The socket's protocol control routine is called to implement the
1207requested action.
1208On return,
1209.Vt sockaddr
1210structures are converted into old-style (no
1211.Va sa_len
1212member).
1213.El
1214.El
1215.Pp
1216.Fn if_down ,
1217.Fn ifioctl ,
1218.Fn ifpromisc ,
1219and
1220.Fn if_up
1221must be called at
1222.Fn splnet
1223or higher.
1224.Ss "Interface Address Functions"
1225Several functions exist to look up an interface address structure
1226given an address.
1227.Fn ifa_ifwithaddr
1228returns an interface address with either a local address or a
1229broadcast address precisely matching the parameter
1230.Fa addr .
1231.Fn ifa_ifwithdstaddr
1232returns an interface address for a point-to-point interface whose
1233remote
1234.Pq Dq destination
1235address is
1236.Fa addr .
1237.Pp
1238.Fn ifa_ifwithnet
1239returns the most specific interface address which matches the
1240specified address,
1241.Fa addr ,
1242subject to its configured netmask, or a point-to-point interface
1243address whose remote address is
1244.Fa addr
1245if one is found.
1246.Pp
1247.Fn ifaof_ifpforaddr
1248returns the most specific address configured on interface
1249.Fa ifp
1250which matches address
1251.Fa addr ,
1252subject to its configured netmask.
1253If the interface is
1254point-to-point, only an interface address whose remote address is
1255precisely
1256.Fa addr
1257will be returned.
1258.Pp
1259All of these functions return a null pointer if no such address can be
1260found.
1261.Ss "Interface Multicast Address Functions"
1262The
1263.Fn if_addmulti ,
1264.Fn if_delmulti ,
1265and
1266.Fn ifmaof_ifpforaddr
1267functions provide support for requesting and relinquishing multicast
1268group memberships, and for querying an interface's membership list,
1269respectively.
1270The
1271.Fn if_addmulti
1272function takes a pointer to an interface,
1273.Fa ifp ,
1274and a generic address,
1275.Fa sa .
1276It also takes a pointer to a
1277.Vt "struct ifmultiaddr *"
1278which is filled in on successful return with the address of the
1279group membership control block.
1280The
1281.Fn if_addmulti
1282function performs the following four-step process:
1283.Bl -enum -offset indent
1284.It
1285Call the interface's
1286.Fn if_resolvemulti
1287entry point to determine the link-layer address, if any, corresponding
1288to this membership request, and also to give the link layer an
1289opportunity to veto this membership request should it so desire.
1290.It
1291Check the interface's group membership list for a pre-existing
1292membership for this group.
1293If one is not found, allocate a new one;
1294if one is, increment its reference count.
1295.It
1296If the
1297.Fn if_resolvemulti
1298routine returned a link-layer address corresponding to the group,
1299repeat the previous step for that address as well.
1300.It
1301If the interface's multicast address filter needs to be changed
1302because a new membership was added, call the interface's
1303.Fn if_ioctl
1304routine
1305(with a
1306.Fa cmd
1307argument of
1308.Dv SIOCADDMULTI )
1309to request that it do so.
1310.El
1311.Pp
1312The
1313.Fn if_delmulti
1314function, given an interface
1315.Fa ifp
1316and an address,
1317.Fa sa ,
1318reverses this process.
1319Both functions return zero on success, or a
1320standard error number on failure.
1321.Pp
1322The
1323.Fn ifmaof_ifpforaddr
1324function examines the membership list of interface
1325.Fa ifp
1326for an address matching
1327.Fa addr ,
1328and returns a pointer to that
1329.Vt "struct ifmultiaddr"
1330if one is found, else it returns a null pointer.
1331.Sh SEE ALSO
1332.Xr ioctl 2 ,
1333.Xr link_addr 3 ,
1334.Xr queue 3 ,
1335.Xr sysctl 3 ,
1336.Xr bpf 4 ,
1337.Xr ifmib 4 ,
1338.Xr lo 4 ,
1339.Xr netintro 4 ,
1340.Xr polling 4 ,
1341.Xr config 8 ,
1342.Xr ppp 8 ,
1343.Xr mbuf 9 ,
1344.Xr rtentry 9
1345.Rs
1346.%A Gary R. Wright
1347.%A W. Richard Stevens
1348.%B TCP/IP Illustrated
1349.%V Vol. 2
1350.%O Addison-Wesley, ISBN 0-201-63354-X
1351.Re
1352.Sh AUTHORS
1353This manual page was written by
1354.An Garrett A. Wollman .
| 1044.Va if_l2com
1045instead of the type in
1046.Va if_type .
1047This is intended for use with drivers that change their interface type.
1048.It Fn if_down
1049Mark the interface
1050.Fa ifp
1051as down (i.e.,
1052.Dv IFF_UP
1053is not set),
1054flush its output queue, notify protocols of the transition,
1055and generate a message from the
1056.Xr route 4
1057routing socket.
1058.It Fn if_up
1059Mark the interface
1060.Fa ifp
1061as up, notify protocols of the transition,
1062and generate a message from the
1063.Xr route 4
1064routing socket.
1065.It Fn ifpromisc
1066Add or remove a promiscuous reference to
1067.Fa ifp .
1068If
1069.Fa pswitch
1070is true, add a reference;
1071if it is false, remove a reference.
1072On reference count transitions
1073from zero to one and one to zero, set the
1074.Dv IFF_PROMISC
1075flag appropriately and call
1076.Fn if_ioctl
1077to set up the interface in the desired mode.
1078.It Fn if_allmulti
1079As
1080.Fn ifpromisc ,
1081but for the all-multicasts
1082.Pq Dv IFF_ALLMULTI
1083flag instead of the promiscuous flag.
1084.It Fn ifunit
1085Return an
1086.Vt ifnet
1087pointer for the interface named
1088.Fa name .
1089.It Fn ifioctl
1090Process the ioctl request
1091.Fa cmd ,
1092issued on socket
1093.Fa so
1094by thread
1095.Fa td ,
1096with data parameter
1097.Fa data .
1098This is the main routine for handling all interface configuration
1099requests from user mode.
1100It is ordinarily only called from the socket-layer
1101.Xr ioctl 2
1102handler, and only for commands with class
1103.Sq Li i .
1104Any unrecognized commands will be passed down to socket
1105.Fa so Ns 's
1106protocol for
1107further interpretation.
1108The following commands are handled by
1109.Fn ifioctl :
1110.Pp
1111.Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact
1112.It Dv SIOCGIFCONF
1113.It Dv OSIOCGIFCONF
1114Get interface configuration.
1115(No call-down to driver.)
1116.Pp
1117.It Dv SIOCSIFNAME
1118Set the interface name.
1119.Dv RTM_IFANNOUNCE
1120departure and arrival messages are sent so that
1121routing code that relies on the interface name will update its interface
1122list.
1123Caller must have appropriate privilege.
1124(No call-down to driver.)
1125.It Dv SIOCGIFCAP
1126.It Dv SIOCGIFFLAGS
1127.It Dv SIOCGIFMETRIC
1128.It Dv SIOCGIFMTU
1129.It Dv SIOCGIFPHYS
1130Get interface capabilities, flags, metric, MTU, medium selection.
1131(No call-down to driver.)
1132.Pp
1133.It Dv SIOCSIFCAP
1134Enable or disable interface capabilities.
1135Caller must have appropriate privilege.
1136Before a call to the driver-specific
1137.Fn if_ioctl
1138routine, the requested mask for enabled capabilities is checked
1139against the mask of capabilities supported by the interface,
1140.Va if_capabilities .
1141Requesting to enable an unsupported capability is invalid.
1142The rest is supposed to be done by the driver,
1143which includes updating
1144.Va if_capenable
1145and
1146.Va if_data.ifi_hwassist
1147appropriately.
1148.Pp
1149.It Dv SIOCSIFFLAGS
1150Change interface flags.
1151Caller must have appropriate privilege.
1152If a change to the
1153.Dv IFF_UP
1154flag is requested,
1155.Fn if_up
1156or
1157.Fn if_down
1158is called as appropriate.
1159Flags listed in
1160.Dv IFF_CANTCHANGE
1161are masked off, and the field
1162.Va if_flags
1163in the interface structure is updated.
1164Finally, the driver
1165.Fn if_ioctl
1166routine is called to perform any setup
1167requested.
1168.Pp
1169.It Dv SIOCSIFMETRIC
1170.It Dv SIOCSIFPHYS
1171Change interface metric or medium.
1172Caller must have appropriate privilege.
1173.Pp
1174.It Dv SIOCSIFMTU
1175Change interface MTU.
1176Caller must have appropriate privilege.
1177MTU
1178values less than 72 or greater than 65535 are considered invalid.
1179The driver
1180.Fn if_ioctl
1181routine is called to implement the change; it is responsible for any
1182additional sanity checking and for actually modifying the MTU in the
1183interface structure.
1184.Pp
1185.It Dv SIOCADDMULTI
1186.It Dv SIOCDELMULTI
1187Add or delete permanent multicast group memberships on the interface.
1188Caller must have appropriate privilege.
1189The
1190.Fn if_addmulti
1191or
1192.Fn if_delmulti
1193function is called to perform the operation; qq.v.
1194.Pp
1195.It Dv SIOCSIFDSTADDR
1196.It Dv SIOCSIFADDR
1197.It Dv SIOCSIFBRDADDR
1198.It Dv SIOCSIFNETMASK
1199The socket's protocol control routine is called to implement the
1200requested action.
1201.Pp
1202.It Dv OSIOGIFADDR
1203.It Dv OSIOCGIFDSTADDR
1204.It Dv OSIOCGIFBRDADDR
1205.It Dv OSIOCGIFNETMASK
1206The socket's protocol control routine is called to implement the
1207requested action.
1208On return,
1209.Vt sockaddr
1210structures are converted into old-style (no
1211.Va sa_len
1212member).
1213.El
1214.El
1215.Pp
1216.Fn if_down ,
1217.Fn ifioctl ,
1218.Fn ifpromisc ,
1219and
1220.Fn if_up
1221must be called at
1222.Fn splnet
1223or higher.
1224.Ss "Interface Address Functions"
1225Several functions exist to look up an interface address structure
1226given an address.
1227.Fn ifa_ifwithaddr
1228returns an interface address with either a local address or a
1229broadcast address precisely matching the parameter
1230.Fa addr .
1231.Fn ifa_ifwithdstaddr
1232returns an interface address for a point-to-point interface whose
1233remote
1234.Pq Dq destination
1235address is
1236.Fa addr .
1237.Pp
1238.Fn ifa_ifwithnet
1239returns the most specific interface address which matches the
1240specified address,
1241.Fa addr ,
1242subject to its configured netmask, or a point-to-point interface
1243address whose remote address is
1244.Fa addr
1245if one is found.
1246.Pp
1247.Fn ifaof_ifpforaddr
1248returns the most specific address configured on interface
1249.Fa ifp
1250which matches address
1251.Fa addr ,
1252subject to its configured netmask.
1253If the interface is
1254point-to-point, only an interface address whose remote address is
1255precisely
1256.Fa addr
1257will be returned.
1258.Pp
1259All of these functions return a null pointer if no such address can be
1260found.
1261.Ss "Interface Multicast Address Functions"
1262The
1263.Fn if_addmulti ,
1264.Fn if_delmulti ,
1265and
1266.Fn ifmaof_ifpforaddr
1267functions provide support for requesting and relinquishing multicast
1268group memberships, and for querying an interface's membership list,
1269respectively.
1270The
1271.Fn if_addmulti
1272function takes a pointer to an interface,
1273.Fa ifp ,
1274and a generic address,
1275.Fa sa .
1276It also takes a pointer to a
1277.Vt "struct ifmultiaddr *"
1278which is filled in on successful return with the address of the
1279group membership control block.
1280The
1281.Fn if_addmulti
1282function performs the following four-step process:
1283.Bl -enum -offset indent
1284.It
1285Call the interface's
1286.Fn if_resolvemulti
1287entry point to determine the link-layer address, if any, corresponding
1288to this membership request, and also to give the link layer an
1289opportunity to veto this membership request should it so desire.
1290.It
1291Check the interface's group membership list for a pre-existing
1292membership for this group.
1293If one is not found, allocate a new one;
1294if one is, increment its reference count.
1295.It
1296If the
1297.Fn if_resolvemulti
1298routine returned a link-layer address corresponding to the group,
1299repeat the previous step for that address as well.
1300.It
1301If the interface's multicast address filter needs to be changed
1302because a new membership was added, call the interface's
1303.Fn if_ioctl
1304routine
1305(with a
1306.Fa cmd
1307argument of
1308.Dv SIOCADDMULTI )
1309to request that it do so.
1310.El
1311.Pp
1312The
1313.Fn if_delmulti
1314function, given an interface
1315.Fa ifp
1316and an address,
1317.Fa sa ,
1318reverses this process.
1319Both functions return zero on success, or a
1320standard error number on failure.
1321.Pp
1322The
1323.Fn ifmaof_ifpforaddr
1324function examines the membership list of interface
1325.Fa ifp
1326for an address matching
1327.Fa addr ,
1328and returns a pointer to that
1329.Vt "struct ifmultiaddr"
1330if one is found, else it returns a null pointer.
1331.Sh SEE ALSO
1332.Xr ioctl 2 ,
1333.Xr link_addr 3 ,
1334.Xr queue 3 ,
1335.Xr sysctl 3 ,
1336.Xr bpf 4 ,
1337.Xr ifmib 4 ,
1338.Xr lo 4 ,
1339.Xr netintro 4 ,
1340.Xr polling 4 ,
1341.Xr config 8 ,
1342.Xr ppp 8 ,
1343.Xr mbuf 9 ,
1344.Xr rtentry 9
1345.Rs
1346.%A Gary R. Wright
1347.%A W. Richard Stevens
1348.%B TCP/IP Illustrated
1349.%V Vol. 2
1350.%O Addison-Wesley, ISBN 0-201-63354-X
1351.Re
1352.Sh AUTHORS
1353This manual page was written by
1354.An Garrett A. Wollman .
|