xref: /dragonfly/share/man/man9/ifnet.9 (revision 2038fb68)
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: src/share/man/man9/ifnet.9,v 1.9.2.10 2003/06/15 02:22:30 hmp Exp $
30.\" $DragonFly: src/share/man/man9/ifnet.9,v 1.10 2008/05/11 07:11:47 swildner Exp $
31.Dd May 10, 2008
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/types.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 void
50.Fn if_attach "struct ifnet *ifp"
51.Ft void
52.Fn if_down "struct ifnet *ifp"
53.Ft int
54.Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct proc *p"
55.Ft int
56.Fn ifpromisc "struct ifnet *ifp" "int pswitch"
57.Ft int
58.Fn if_allmulti "struct ifnet *ifp" "int amswitch"
59.Ft "struct ifnet *"
60.Fn ifunit "const char *name"
61.Ft void
62.Fn if_up "struct ifnet *ifp"
63.\"
64.Ss "Interface Address Functions"
65.Ft "struct ifaddr *"
66.Fn ifa_ifwithaddr "struct sockaddr *addr"
67.Ft "struct ifaddr *"
68.Fn ifa_ifwithdstaddr "struct sockaddr *addr"
69.Ft "struct ifaddr *"
70.Fn ifa_ifwithnet "struct sockaddr *addr"
71.Ft "struct ifaddr *"
72.Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
73.Fn IFAFREE "struct ifaddr *ifa"
74.\"
75.Ss "Interface Multicast Address Functions"
76.Ft int
77.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap"
78.Ft int
79.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa"
80.Ft "struct ifmultiaddr *"
81.Fn ifmaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
82.Ss "Output queue macros"
83.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m"
84.\"
85.Ss "struct ifnet Member Functions"
86.Ft int
87.Fo \*(lp*if_output\*(rp
88.Fa "struct ifnet *ifp" "struct mbuf *m"
89.Fa "struct sockaddr *dst" "struct rtentry *rt"
90.Fc
91.Ft void
92.Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m"
93.Ft void
94.Fn \*(lp*if_start\*(rp "struct ifnet *ifp"
95.Ft int
96.Fo \*(lp*if_ioctl\*(rp
97.Fa "struct ifnet *ifp" "u_long command" "caddr_t data" "struct ucred *cr"
98.Fc
99.Ft void
100.Fn \*(lp*if_watchdog\*(rp "struct ifnet *ifp"
101.Ft void
102.Fn \*(lp*if_init\*(rp "void *if_softc"
103.Ft int
104.Fo \*(lp*if_resolvemulti\*(rp
105.Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr"
106.Fc
107.Ft void
108.Fn \*(lp*if_poll\*(rp "struct ifnet *ifp" "enum poll_cmd cmd" "int count"
109.Ss "struct ifaddr member function"
110.Ft void
111.Fo \*(lp*ifa_rtrequest\*(rp
112.Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
113.Fc
114.\"
115.Ss "Global Variables"
116.Vt extern struct ifnethead ifnet ;
117.Vt extern int if_index ;
118.Vt extern int ifqmaxlen ;
119.Sh DATA STRUCTURES
120The kernel mechanisms for handling network interfaces reside primarily
121in the
122.Vt ifnet , if_data , ifaddr ,
123and
124.Vt ifmultiaddr
125structures in
126.In net/if.h
127and
128.In net/if_var.h
129and the functions named above and defined in
130.Pa /sys/net/if.c .
131Those interfaces which are intended to be used by user programs
132are defined in
133.In net/if.h ;
134these include the interface flags, the
135.Vt if_data
136structure, and the structures defining the appearance of
137interface-related messages on the
138.Xr route 4
139routing socket and in
140.Xr sysctl 3 .
141The header file
142.In net/if_var.h
143defines the kernel-internal interfaces, including the
144.Vt ifnet , ifaddr ,
145and
146.Vt ifmultiaddr
147structures and the functions which manipulate them.
148(A few user programs will need
149.In net/if_var.h
150because it is the prerequisite of some other header file like
151.In netinet/if_ether.h .
152Most references to those two files in particular can be replaced by
153.In net/ethernet.h . )
154.Pp
155The system keeps a linked list of interfaces using the
156.Li TAILQ
157macros defined in
158.Xr queue 3 ;
159this list is headed by a
160.Vt "struct ifnethead"
161called
162.Va ifnet .
163The elements of this list are of type
164.Vt "struct ifnet" ,
165and most kernel routines which manipulate interface as such accept or
166return pointers to these structures.
167Each interface structure
168contains an
169.Vt if_data
170structure, which contains statistics and identifying information used
171by management programs, and which is exported to user programs by way
172of the
173.Xr ifmib 4
174branch of the
175.Xr sysctl 3
176MIB.
177Each interface also has a
178.Li TAILQ
179of interface addresses, described by
180.Vt ifaddr
181structures; the head of the queue is always an
182.Dv AF_LINK
183address
184(see
185.Xr link_addr 3 )
186describing the link layer implemented by the interface (if any).
187(Some trivial interfaces do not provide any link layer addresses;
188this structure, while still present, serves only to identify the
189interface name and index.)
190.Pp
191Finally, those interfaces supporting reception of multicast datagrams
192have a
193.Li LIST
194of multicast group memberships, described by
195.Vt ifmultiaddr
196structures.
197These memberships are reference-counted.
198.Pp
199Interfaces are also associated with an output queue, defined as a
200.Vt "struct ifqueue" ;
201this structure is used to hold packets while the interface is in the
202process of sending another.
203.Ss The Vt ifnet Ss structure
204The fields of
205.Vt "struct ifnet"
206are as follows:
207.Bl -tag -width ".Va if_poll_slowq" -offset indent
208.It Va if_softc
209.Pq Vt "void *"
210A pointer to the driver's private state block.
211(Initialized by driver.)
212.It Va if_link
213.Pq Fn TAILQ_ENTRY ifnet
214.Xr queue 3
215macro glue.
216.It Va if_xname
217.Pq Vt "char *"
218The name of the interface,
219(e.g.,
220.Dq Li fxp0
221or
222.Dq Li lo0) .
223(Initialized by driver.)
224.It Va if_dname
225.Pq Vt "const char *"
226The name of the driver.
227(Initialized by driver.)
228.It Va if_dunit
229.Pq Vt int
230A unique number assigned to each interface managed by a particular
231driver.
232Drivers may choose to set this to
233.Dv IF_DUNIT_NONE
234if a unit number is not associated with the device.
235(Initialized by driver.)
236.\" .It Va if_vlantrunks
237.\" .Pq Vt "void *"
238.\" ...
239.It Va if_addrhead
240.Pq Vt "struct ifaddrhead"
241The head of the
242.Xr queue 3
243.Li TAILQ
244containing the list of addresses assigned to this interface.
245.It Va if_pcount
246.Pq Vt int
247A count of promiscuous listeners on this interface, used to
248reference-count the
249.Dv IFF_PROMISC
250flag.
251.It Va if_carp
252.Pq Vt "struct carp_if *"
253Per-interface data for
254.Xr carp 4 .
255.It Va if_bpf
256.Pq Vt "struct bpf_if *"
257Opaque per-interface data for the packet filter,
258.Xr bpf 4 .
259(Initialized by
260.Fn bpfattach . )
261.It Va if_index
262.Pq Vt u_short
263A unique number assigned to each interface in sequence as it is
264attached.
265This number can be used in a
266.Vt "struct sockaddr_dl"
267to refer to a particular interface by index
268(see
269.Xr link_addr 3 ) .
270.It Va if_timer
271.Pq Vt short
272Number of seconds until the watchdog timer
273.Fn if_watchdog
274is called, or zero if the timer is disabled.
275(Set by driver,
276decremented by generic watchdog code.)
277.It Va if_flags
278.Pq Vt int
279Flags describing operational parameters of this interface (see below).
280(Manipulated by both driver and generic code.)
281.It Va if_linkmib
282.Pq Vt "void *"
283A pointer to an interface-specific MIB structure exported by
284.Xr ifmib 4 .
285(Initialized by driver.)
286.It Va if_linkmiblen
287.Pq Vt size_t
288The size of said structure.
289(Initialized by driver.)
290.It Va if_data
291.Pq Vt "struct if_data"
292More statistics and information; see
293.Sx "The if_data structure" ,
294below.
295(Initialized by driver, manipulated by both driver and generic
296code.)
297.\" .It Va if_poll_cpuid
298.\" .Pq Vt int
299.\" ...
300.It Va if_snd
301.Pq Vt "struct ifaltq"
302The output queue including
303.Xr altq 4 .
304(Manipulated by driver.)
305.\" .It Va if_broadcastaddr
306.\" .Pq Vt "const uint8_t"
307.\" ...
308.\" .It Va if_bridge
309.\" .Pq Vt "void *"
310.\" ...
311.\" .It Va if_afdata
312.\" .Pq Vt "void *"
313.\" ...
314.\" .It Va if_lladdr
315.\" .Pq Vt "struct ifaddr"
316.\" ...
317.\" .It Va if_serializer
318.\" .Pq Vt "struct lwkt_serialize"
319.\" ...
320.\" .It Va if_default_serializer
321.\" .Pq Vt "struct lwkt_serialize"
322.\" ...
323.El
324.Pp
325There are in addition a number of function pointers which the driver
326must initialize to complete its interface with the generic interface
327layer:
328.Bl -ohang -offset indent
329.It Fn if_output
330Output a packet on interface
331.Fa ifp ,
332or queue it on the output queue if the interface is already active.
333.It Fn if_start
334Start queued output on an interface.
335This function is exposed in
336order to provide for some interface classes to share a
337.Fn if_output
338among all drivers.
339.Fn if_start
340may only be called when the
341.Dv IFF_OACTIVE
342flag is not set.
343(Thus,
344.Dv IFF_OACTIVE
345does not literally mean that output is active, but rather that the
346device's internal output queue is full.)
347.It Fn if_ioctl
348Process interface-related
349.Xr ioctl 2
350requests
351(defined in
352.In sys/sockio.h ) .
353Preliminary processing is done by the generic routine
354.Fn ifioctl
355to check for appropriate privileges, locate the interface being
356manipulated, and perform certain generic operations like twiddling
357flags and flushing queues.
358See the description of
359.Fn ifioctl
360below for more information.
361.It Fn if_watchdog
362Routine called by the generic code when the watchdog timer,
363.Va if_timer ,
364expires.
365Usually this will reset the interface.
366.\".It Fn if_poll
367.\" See the
368.\" .Sx POLLING
369.\" section, below.
370.It Fn if_init
371Initialize and bring up the hardware,
372e.g., reset the chip and the watchdog timer and enable the receiver unit.
373Should mark the interface running,
374but not active
375.Dv ( IFF_RUNNING , ~IFF_OACTIVE ) .
376.It Fn if_resolvemulti
377Check the requested multicast group membership,
378.Fa addr ,
379for validity, and if necessary compute a link-layer group which
380corresponds to that address which is returned in
381.Fa *retsa .
382Returns zero on success, or an error code on failure.
383.El
384.Ss "Interface Flags"
385Interface flags are used for a number of different purposes.
386Some
387flags simply indicate information about the type of interface and its
388capabilities; others are dynamically manipulated to reflect the
389current state of the interface.
390Flags of the former kind are marked
391.Aq S
392in this table; the latter are marked
393.Aq D .
394.Pp
395.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact
396.It Dv IFF_UP
397.Aq D
398The interface has been configured up by the user-level code.
399.It Dv IFF_BROADCAST
400.Aq S*
401The interface supports broadcast.
402.It Dv IFF_DEBUG
403.Aq D
404Used to enable/disable driver debugging code.
405.It Dv IFF_LOOPBACK
406.Aq S
407The interface is a loopback device.
408.It Dv IFF_POINTOPOINT
409.Aq S*
410The interface is point-to-point;
411.Dq broadcast
412address is actually the address of the other end.
413.It Dv IFF_RUNNING
414.Aq D*
415The interface has been configured and dynamic resources were
416successfully allocated.
417Probably only useful internal to the
418interface.
419.It Dv IFF_NOARP
420.Aq D
421Disable network address resolution on this interface.
422.It Dv IFF_PROMISC
423.Aq D*
424This interface is in promiscuous mode.
425.It Dv IFF_PPROMISC
426.Aq D
427This interface is in the permanently promiscuous mode (implies
428.Dv IFF_PROMISC ) .
429.It Dv IFF_ALLMULTI
430.Aq D*
431This interface is in all-multicasts mode (used by multicast routers).
432.It Dv IFF_OACTIVE
433.Aq D*
434The interface's hardware output queue (if any) is full; output packets
435are to be queued.
436.It Dv IFF_SIMPLEX
437.Aq S*
438The interface cannot hear its own transmissions.
439.It Dv IFF_LINK0
440.It Dv IFF_LINK1
441.It Dv IFF_LINK2
442.Aq D
443Control flags for the link layer.
444(Currently abused to select among
445multiple physical layers on some devices.)
446.It Dv IFF_MULTICAST
447.Aq S*
448This interface supports multicast.
449.It Dv IFF_POLLING
450The interface is in polling mode.
451.\" .It Dv IFF_MONITOR
452.\" ...
453.El
454.Pp
455The macro
456.Dv IFF_CANTCHANGE
457defines the bits which cannot be set by a user program using the
458.Dv SIOCSIFFLAGS
459command to
460.Xr ioctl 2 ;
461these are indicated by an asterisk in the listing above.
462.Ss The Vt if_data Ss Structure
463In
464.Bx 4.4 ,
465a subset of the interface information believed to be of interest to
466management stations was segregated from the
467.Vt ifnet
468structure and moved into its own
469.Vt if_data
470structure to facilitate its use by user programs.
471The following elements of the
472.Vt if_data
473structure are initialized by the interface and are not expected to change
474significantly over the course of normal operation:
475.Bl -tag -width ".Va ifi_lastchange" -offset indent
476.It Va ifi_type
477.Pq Vt u_char
478The type of the interface, as defined in
479.In net/if_types.h
480and described below in the
481.Sx "Interface Types"
482section.
483.It Va ifi_physical
484.Pq Vt u_char
485Intended to represent a selection of physical layers on devices which
486support more than one; never implemented.
487.It Va ifi_addrlen
488.Pq Vt u_char
489Length of a link-layer address on this device, or zero if there are
490none.
491Used to initialize the address length field in
492.Vt sockaddr_dl
493structures referring to this interface.
494.It Va ifi_hdrlen
495.Pq Vt u_char
496Maximum length of any link-layer header which might be prepended by
497the driver to a packet before transmission.
498The generic code computes
499the maximum over all interfaces and uses that value to influence the
500placement of data in
501.Vt mbuf Ns s
502to attempt to ensure that there is always
503sufficient space to prepend a link-layer header without allocating an
504additional
505.Vt mbuf .
506.\" (See
507.\" .Xr mbuf 9 . )
508.\" .It Va ifi_recvquota
509.\" .Pq Vt u_char
510.\" Number of packets the interface is permitted to receive at one time
511.\" when in polled mode.
512.\" .It Va ifi_xmitquota
513.\" .Pq Vt u_char
514.\" Number of packets the interface is permitted to queue for transmission
515.\" at one time when in polled mode.
516.\" There is some controversy over
517.\" whether such a restriction makes any sense at all.
518.It Va ifi_mtu
519.Pq Vt u_long
520The maximum transmission unit of the medium, exclusive of any
521link-layer overhead.
522.It Va ifi_metric
523.Pq Vt u_long
524A dimensionless metric interpreted by a user-mode routing process.
525.It Va ifi_link_state
526.Pq Vt u_long
527The link state of the interface, either
528.Dv LINK_STATE_UNKNOWN ,
529.Dv LINK_STATE_DOWN ,
530or
531.Dv LINK_STATE_UP .
532.It Va ifi_baudrate
533.Pq Vt u_long
534The line rate of the interface, in bits per second.
535.El
536.Pp
537The structure additionally contains generic statistics applicable to a
538variety of different interface types (except as noted, all members are
539of type
540.Vt u_long ) :
541.Bl -tag -width ".Va ifi_lastchange" -offset indent
542.It Va ifi_ipackets
543Number of packets received.
544.It Va ifi_ierrors
545Number of receive errors detected (e.g., FCS errors, DMA overruns,
546etc.).
547More detailed breakdowns can often be had by way of a
548link-specific MIB.
549.It Va ifi_opackets
550Number of packets transmitted.
551.It Va ifi_oerrors
552Number of output errors detected (e.g., late collisions, DMA overruns,
553etc.).
554More detailed breakdowns can often be had by way of a
555link-specific MIB.
556.It Va ifi_collisions
557Total number of collisions detected on output for CSMA interfaces.
558(This member is sometimes [ab]used by other types of interfaces for
559other output error counts.)
560.It Va ifi_ibytes
561Total traffic received, in bytes.
562.It Va ifi_obytes
563Total traffic transmitted, in bytes.
564.It Va ifi_imcasts
565Number of packets received which were sent by link-layer multicast.
566.It Va ifi_omcasts
567Number of packets sent by link-layer multicast.
568.It Va ifi_iqdrops
569Number of packets dropped on input.
570Rarely implemented.
571.It Va ifi_noproto
572Number of packets received for unknown network-layer protocol.
573.It Va ifi_lastchange
574.Pq Vt "struct timeval"
575The time of the last administrative change to the interface (as required
576for
577.Tn SNMP ) .
578.El
579.Ss Interface Types
580The header file
581.In net/if_types.h
582defines symbolic constants for a number of different types of
583interfaces.
584The most common are:
585.Pp
586.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact
587.It Dv IFT_OTHER
588none of the following
589.It Dv IFT_ETHER
590Ethernet
591.It Dv IFT_ISO88023
592ISO 8802-3 CSMA/CD
593.It Dv IFT_ISO88024
594ISO 8802-4 Token Bus
595.It Dv IFT_ISO88025
596ISO 8802-5 Token Ring
597.It Dv IFT_ISO88026
598ISO 8802-6 DQDB MAN
599.It Dv IFT_FDDI
600FDDI
601.It Dv IFT_PPP
602Internet Point-to-Point Protocol
603.Pq Xr ppp 8
604.It Dv IFT_LOOP
605The loopback
606.Pq Xr lo 4
607interface
608.It Dv IFT_SLIP
609Serial Line IP
610.It Dv IFT_PARA
611Parallel-port IP
612.Pq Dq Tn PLIP
613.It Dv IFT_ATM
614Asynchronous Transfer Mode
615.El
616.Ss The Vt ifaddr Ss Structure
617Every interface is associated with a list
618(or, rather, a
619.Li TAILQ )
620of addresses, rooted at the interface structure's
621.Va if_addrlist
622member.
623The first element in this list is always an
624.Dv AF_LINK
625address representing the interface itself; multi-access network
626drivers should complete this structure by filling in their link-layer
627addresses after calling
628.Fn if_attach .
629Other members of the structure represent network-layer addresses which
630have been configured by means of the
631.Dv SIOCAIFADDR
632command to
633.Xr ioctl 2 ,
634called on a socket of the appropriate protocol family.
635The elements of this list consist of
636.Vt ifaddr
637structures.
638Most protocols will declare their own protocol-specific
639interface address structures, but all begin with a
640.Vt "struct ifaddr"
641which provides the most-commonly-needed functionality across all
642protocols.
643Interface addresses are reference-counted.
644.Pp
645The members of
646.Vt "struct ifaddr"
647are as follows:
648.Bl -tag -width ".Va ifa_rtrequest" -offset indent
649.It Va ifa_addr
650.Pq Vt "struct sockaddr *"
651The local address of the interface.
652.It Va ifa_dstaddr
653.Pq Vt "struct sockaddr *"
654The remote address of point-to-point interfaces, and the broadcast
655address of broadcast interfaces.
656.Va ( ifa_broadaddr
657is a macro for
658.Va ifa_dstaddr . )
659.It Va ifa_netmask
660.Pq Vt "struct sockaddr *"
661The network mask for multi-access interfaces, and the confusion
662generator for point-to-point interfaces.
663.\" .It Va if_data
664.\" .Pq Vt "struct if_data"
665.\" ...
666.It Va ifa_ifp
667.Pq Vt "struct ifnet *"
668A link back to the interface structure.
669.It Va ifa_containers
670.Pq Vt "struct ifaddr_container *"
671A pointer to an array of
672.Vt ifaddr_container
673structures which hold per-CPU data.
674.It Va ifa_rtrequest
675See below.
676.It Va ifa_flags
677.Pq Vt u_short
678Some of the flags which would be used for a route representing this
679address in the route table.
680.\" .It Va ifa_cpumask
681.\" .Pq Vt cpumask_t
682.\" ...
683.It Va ifa_metric
684.Pq Vt int
685A metric associated with this interface address, for the use of some
686external routing protocol.
687.El
688.Pp
689References to
690.Vt ifaddr
691structures are gained manually, by incrementing the
692.Va ifa_refcnt
693member of the according
694.Va ifa_containers
695structure (such as by calling the
696.Fn IFAREF
697macro).
698References are released by calling the
699.Fn IFAFREE
700macro.
701.Pp
702.Fn ifa_rtrequest
703is a pointer to a function which receives callouts from the routing
704code
705.Pq Fn rtrequest
706to perform link-layer-specific actions upon requests to add, resolve,
707or delete routes.
708The
709.Fa cmd
710argument indicates the request in question:
711.Dv RTM_ADD , RTM_RESOLVE ,
712or
713.Dv RTM_DELETE .
714The
715.Fa rt
716argument is the route in question; the
717.Fa dst
718argument is the specific destination being manipulated
719for
720.Dv RTM_RESOLVE ,
721or a null pointer otherwise.
722.Sh FUNCTIONS
723The functions provided by the generic interface code can be divided
724into two groups: those which manipulate interfaces, and those which
725manipulate interface addresses.
726In addition to these functions, there
727may also be link-layer support routines which are used by a number of
728drivers implementing a specific link layer over different hardware;
729see the documentation for that link layer for more details.
730.Ss The Vt ifmultiaddr Ss Structure
731Every multicast-capable interface is associated with a list of
732multicast group memberships, which indicate at a low level which
733link-layer multicast addresses (if any) should be accepted, and at a
734high level, in which network-layer multicast groups a user process has
735expressed interest.
736.Pp
737The elements of the structure are as follows:
738.Bl -tag -width ".Va ifma_refcount" -offset indent
739.It Va ifma_link
740.Pq Fn LIST_ENTRY ifmultiaddr
741.Xr queue 3
742macro glue.
743.It Va ifma_addr
744.Pq Vt "struct sockaddr *"
745A pointer to the address which this record represents.
746The
747memberships for various address families are stored in arbitrary
748order.
749.It Va ifma_lladdr
750.Pq Vt "struct sockaddr *"
751A pointer to the link-layer multicast address, if any, to which the
752network-layer multicast address in
753.Va ifma_addr
754is mapped, else a null pointer.
755If this element is non-nil, this
756membership also holds an invisible reference to another membership for
757that link-layer address.
758.It Va ifma_refcount
759.Pq Vt u_int
760A reference count of requests for this particular membership.
761.El
762.Ss Interface Manipulation Functions
763.Bl -ohang -offset indent
764.It Fn if_attach
765Link the specified interface
766.Fa ifp
767into the list of network interfaces.
768Also initialize the list of
769addresses on that interface, and create a link-layer
770.Vt ifaddr
771structure to be the first element in that list.
772(A pointer to
773this address structure is saved in the global array
774.Va ifnet_addrs . )
775.It Fn if_down
776Mark the interface
777.Fa ifp
778as down (i.e.,
779.Dv IFF_UP
780is not set),
781flush its output queue, notify protocols of the transition,
782and generate a message from the
783.Xr route 4
784routing socket.
785.It Fn if_up
786Mark the interface
787.Fa ifp
788as up, notify protocols of the transition,
789and generate a message from the
790.Xr route 4
791routing socket.
792.It Fn ifpromisc
793Add or remove a promiscuous reference to
794.Fa ifp .
795If
796.Fa pswitch
797is true, add a reference;
798if it is false, remove a reference.
799On reference count transitions
800from zero to one and one to zero, set the
801.Dv IFF_PROMISC
802flag appropriately and call
803.Fn if_ioctl
804to set up the interface in the desired mode.
805.It Fn if_allmulti
806As
807.Fn ifpromisc ,
808but for the all-multicasts
809.Pq Dv IFF_ALLMULTI
810flag instead of the promiscuous flag.
811.It Fn ifunit
812Return an
813.Vt ifnet
814pointer for the interface named
815.Fa name .
816.It Fn ifioctl
817Process the ioctl request
818.Fa cmd ,
819issued on socket
820.Fa so
821by process
822.Fa p ,
823with data parameter
824.Fa data .
825This is the main routine for handling all interface configuration
826requests from user mode.
827It is ordinarily only called from the socket-layer
828.Xr ioctl 2
829handler, and only for commands with class
830.Sq Li i .
831Any unrecognized commands will be passed down to socket
832.Fa so Ns 's
833protocol for
834further interpretation.
835The following commands are handled by
836.Fn ifioctl :
837.Pp
838.Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact
839.It Dv SIOCGIFCONF
840.It Dv OSIOCGIFCONF
841Get interface configuration.
842(No call-down to driver.)
843.Pp
844.It Dv SIOCGIFFLAGS
845.It Dv SIOCGIFMETRIC
846.It Dv SIOCGIFMTU
847.It Dv SIOCGIFPHYS
848Get interface flags, metric, MTU, medium selection.
849(No call-down to driver.)
850.Pp
851.It Dv SIOCSIFFLAGS
852Change interface flags.
853Caller must have appropriate privilege.
854If a change to the
855.Dv IFF_UP
856flag is requested,
857.Fn if_up
858or
859.Fn if_down
860is called as appropriate.
861Flags listed in
862.Dv IFF_CANTCHANGE
863are masked off, and the driver
864.Fn if_ioctl
865routine is called to perform any setup
866requested.
867.Pp
868.It Dv SIOCSIFMETRIC
869.It Dv SIOCSIFPHYS
870Change interface metric or medium.
871Caller must have appropriate privilege.
872.Pp
873.It Dv SIOCSIFMTU
874Change interface MTU.
875Caller must have appropriate privilege.
876MTU
877values less than 72 or greater than 65535 are considered invalid.
878The driver
879.Fn if_ioctl
880routine is called to implement the change; it is responsible for any
881additional sanity checking and for actually modifying the MTU in the
882interface structure.
883.Pp
884.It Dv SIOCADDMULTI
885.It Dv SIOCDELMULTI
886Add or delete permanent multicast group memberships on the interface.
887Caller must have appropriate privilege.
888The
889.Fn if_addmulti
890or
891.Fn if_delmulti
892function is called to perform the operation; qq.v.
893.Pp
894.It Dv SIOCSIFDSTADDR
895.It Dv SIOCSIFADDR
896.It Dv SIOCSIFBRDADDR
897.It Dv SIOCSIFNETMASK
898The socket's protocol control routine is called to implement the
899requested action.
900.Pp
901.It Dv OSIOCGIFADDR
902.It Dv OSIOCGIFDSTADDR
903.It Dv OSIOCGIFBRDADDR
904.It Dv OSIOCGIFNETMASK
905The socket's protocol control routine is called to implement the
906requested action.
907On return,
908.Vt sockaddr
909structures are converted into old-style (no
910.Va sa_len
911member).
912.El
913.El
914.Pp
915.Fn if_down ,
916.Fn ifioctl ,
917.Fn ifpromisc ,
918and
919.Fn if_up
920must be called inside a critical section.
921.Ss "Interface Address Functions"
922Several functions exist to look up an interface address structure
923given an address.
924.Fn ifa_ifwithaddr
925returns an interface address with either a local address or a
926broadcast address precisely matching the parameter
927.Fa addr .
928.Fn ifa_ifwithdstaddr
929returns an interface address for a point-to-point interface whose
930remote
931.Pq Dq destination
932address is
933.Fa addr .
934.Pp
935.Fn ifa_ifwithnet
936returns the most specific interface address which matches the
937specified address,
938.Fa addr ,
939subject to its configured netmask, or a point-to-point interface
940address whose remote address is
941.Fa addr
942if one is found.
943.Pp
944.Fn ifaof_ifpforaddr
945returns the most specific address configured on interface
946.Fa ifp
947which matches address
948.Fa addr ,
949subject to its configured netmask.
950If the interface is
951point-to-point, only an interface address whose remote address is
952precisely
953.Fa addr
954will be returned.
955.Pp
956All of these functions return a null pointer if no such address can be
957found.
958.Ss "Interface Multicast Address Functions"
959The
960.Fn if_addmulti ,
961.Fn if_delmulti ,
962and
963.Fn ifmaof_ifpforaddr
964functions provide support for requesting and relinquishing multicast
965group memberships, and for querying an interface's membership list,
966respectively.
967The
968.Fn if_addmulti
969function takes a pointer to an interface,
970.Fa ifp ,
971and a generic address,
972.Fa sa .
973It also takes a pointer to a
974.Vt "struct ifmultiaddr *"
975which is filled in on successful return with the address of the
976group membership control block.
977The
978.Fn if_addmulti
979function performs the following four-step process:
980.Bl -enum -offset indent
981.It
982Call the interface's
983.Fn if_resolvemulti
984entry point to determine the link-layer address, if any, corresponding
985to this membership request, and also to give the link layer an
986opportunity to veto this membership request should it so desire.
987.It
988Check the interface's group membership list for a pre-existing
989membership for this group.
990If one is not found, allocate a new one;
991if one is, increment its reference count.
992.It
993If the
994.Fn if_resolvemulti
995routine returned a link-layer address corresponding to the group,
996repeat the previous step for that address as well.
997.It
998If the interface's multicast address filter needs to be changed
999because a new membership was added, call the interface's
1000.Fn if_ioctl
1001routine
1002(with a
1003.Fa cmd
1004argument of
1005.Dv SIOCADDMULTI )
1006to request that it do so.
1007.El
1008.Pp
1009The
1010.Fn if_delmulti
1011function, given an interface
1012.Fa ifp
1013and an address,
1014.Fa sa ,
1015reverses this process.
1016Both functions return zero on success, or a
1017standard error number on failure.
1018.Pp
1019The
1020.Fn ifmaof_ifpforaddr
1021function examines the membership list of interface
1022.Fa ifp
1023for an address matching
1024.Fa addr ,
1025and returns a pointer to that
1026.Vt "struct ifmultiaddr"
1027if one is found, else it returns a null pointer.
1028.\" .Sh POLLING
1029.\" XXX write me!
1030.Sh SEE ALSO
1031.Xr ioctl 2 ,
1032.Xr link_addr 3 ,
1033.Xr queue 3 ,
1034.Xr sysctl 3 ,
1035.Xr bpf 4 ,
1036.Xr ifmib 4 ,
1037.Xr lo 4 ,
1038.Xr netintro 4 ,
1039.Xr config 8 ,
1040.Xr ppp 8 ,
1041.\" .Xr mbuf 9 ,
1042.Xr rtentry 9
1043.Rs
1044.%A Gary R. Wright
1045.%A W. Richard Stevens
1046.%B TCP/IP Illustrated
1047.%V Vol. 2
1048.%O Addison-Wesley, ISBN 0-201-63354-X
1049.Re
1050.Sh AUTHORS
1051This manual page was written by
1052.An Garrett A. Wollman .
1053