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