2 .\" Copyright 1996, 1997 Massachusetts Institute of Technology
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
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
29 .\" $FreeBSD: src/share/man/man9/ifnet.9,v 1.9.2.10 2003/06/15 02:22:30 hmp Exp $
39 .Nd kernel interfaces for manipulating network interfaces
48 .Ss "Interface Manipulation Functions"
50 .Fn if_attach "struct ifnet *ifp"
52 .Fn if_down "struct ifnet *ifp"
54 .Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct proc *p"
56 .Fn ifpromisc "struct ifnet *ifp" "int pswitch"
58 .Fn if_allmulti "struct ifnet *ifp" "int amswitch"
60 .Fn ifunit "const char *name"
62 .Fn if_up "struct ifnet *ifp"
64 .Ss "Interface Address Functions"
66 .Fn ifa_ifwithaddr "struct sockaddr *addr"
68 .Fn ifa_ifwithdstaddr "struct sockaddr *addr"
70 .Fn ifa_ifwithnet "struct sockaddr *addr"
72 .Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
73 .Fn IFAFREE "struct ifaddr *ifa"
75 .Ss "Interface Multicast Address Functions"
77 .Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap"
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"
85 .Ss "struct ifnet Member Functions"
88 .Fa "struct ifnet *ifp" "struct mbuf *m"
89 .Fa "struct sockaddr *dst" "struct rtentry *rt"
93 .Fa "struct ifnet *ifp" "struct mbuf *m"
94 .Fa "const struct pktinfo *pi" "int cpuid"
97 .Fn (*if_start) "struct ifnet *ifp"
100 .Fa "struct ifnet *ifp" "u_long command" "caddr_t data" "struct ucred *cr"
103 .Fn (*if_watchdog) "struct ifnet *ifp"
105 .Fn (*if_init) "void *if_softc"
107 .Fo (*if_resolvemulti)
108 .Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr"
111 .Fn (*if_poll) "struct ifnet *ifp" "enum poll_cmd cmd" "int count"
112 .Ss "struct ifaddr member function"
115 .Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
118 .Ss "Global Variables"
119 .Vt extern struct ifnethead ifnet ;
120 .Vt extern int if_index ;
121 .Vt extern int ifqmaxlen ;
123 The kernel mechanisms for handling network interfaces reside primarily
125 .Vt ifnet , if_data , ifaddr ,
132 and the functions named above and defined in
134 Those interfaces which are intended to be used by user programs
137 these include the interface flags, the
139 structure, and the structures defining the appearance of
140 interface-related messages on the
142 routing socket and in
146 defines the kernel-internal interfaces, including the
150 structures and the functions which manipulate them.
151 (A few user programs will need
153 because it is the prerequisite of some other header file like
154 .In netinet/if_ether.h .
155 Most references to those two files in particular can be replaced by
156 .In net/ethernet.h . )
158 The system keeps a linked list of interfaces using the
162 this list is headed by a
163 .Vt "struct ifnethead"
166 The elements of this list are of type
168 and most kernel routines which manipulate interface as such accept or
169 return pointers to these structures.
170 Each interface structure
173 structure, which contains statistics and identifying information used
174 by management programs, and which is exported to user programs by way
180 Each interface also has a
182 of interface addresses, described by
184 structures; the head of the queue is always an
189 describing the link layer implemented by the interface (if any).
190 (Some trivial interfaces do not provide any link layer addresses;
191 this structure, while still present, serves only to identify the
192 interface name and index.)
194 Finally, those interfaces supporting reception of multicast datagrams
197 of multicast group memberships, described by
200 These memberships are reference-counted.
202 Interfaces are also associated with an output queue, defined as a
203 .Vt "struct ifqueue" ;
204 this structure is used to hold packets while the interface is in the
205 process of sending another.
206 .Ss The Vt ifnet Ss structure
210 .Bl -tag -width ".Va if_poll_slowq" -offset indent
213 A pointer to the driver's private state block.
214 (Initialized by driver.)
216 .Pq Fn TAILQ_ENTRY ifnet
221 The name of the interface,
226 (Initialized by driver.)
228 .Pq Vt "const char *"
229 The name of the driver.
230 (Initialized by driver.)
233 A unique number assigned to each interface managed by a particular
235 Drivers may choose to set this to
237 if a unit number is not associated with the device.
238 (Initialized by driver.)
239 .\" .It Va if_vlantrunks
243 .Pq Vt "struct ifaddrhead"
247 containing the list of addresses assigned to this interface.
250 A count of promiscuous listeners on this interface, used to
255 .Pq Vt "struct carp_if *"
256 Per-interface data for
259 .Pq Vt "struct bpf_if *"
260 Opaque per-interface data for the packet filter,
266 A unique number assigned to each interface in sequence as it is
268 This number can be used in a
269 .Vt "struct sockaddr_dl"
270 to refer to a particular interface by index
275 Number of seconds until the watchdog timer
277 is called, or zero if the timer is disabled.
279 decremented by generic watchdog code.)
282 Flags describing operational parameters of this interface (see below).
283 (Manipulated by both driver and generic code.)
286 A pointer to an interface-specific MIB structure exported by
288 (Initialized by driver.)
291 The size of said structure.
292 (Initialized by driver.)
294 .Pq Vt "struct if_data"
295 More statistics and information; see
296 .Sx "The if_data structure" ,
298 (Initialized by driver, manipulated by both driver and generic
300 .\" .It Va if_poll_cpuid
304 .Pq Vt "struct ifaltq"
305 The output queue including
307 (Manipulated by driver.)
308 .\" .It Va if_broadcastaddr
309 .\" .Pq Vt "const uint8_t"
318 .\" .Pq Vt "struct ifaddr"
320 .\" .It Va if_serializer
321 .\" .Pq Vt "struct lwkt_serialize"
323 .\" .It Va if_default_serializer
324 .\" .Pq Vt "struct lwkt_serialize"
328 There are in addition a number of function pointers which the driver
329 must initialize to complete its interface with the generic interface
331 .Bl -ohang -offset indent
333 Output a packet on interface
335 or queue it on the output queue if the interface is already active.
337 Start queued output on an interface.
338 This function is exposed in
339 order to provide for some interface classes to share a
343 may only be called when the
348 does not literally mean that output is active, but rather that the
349 device's internal output queue is full.)
351 Process interface-related
356 Preliminary processing is done by the generic routine
358 to check for appropriate privileges, locate the interface being
359 manipulated, and perform certain generic operations like twiddling
360 flags and flushing queues.
361 See the description of
363 below for more information.
365 Routine called by the generic code when the watchdog timer,
368 Usually this will reset the interface.
374 Initialize and bring up the hardware,
375 e.g., reset the chip and the watchdog timer and enable the receiver unit.
376 Should mark the interface running,
378 .Dv ( IFF_RUNNING , ~IFF_OACTIVE ) .
379 .It Fn if_resolvemulti
380 Check the requested multicast group membership,
382 for validity, and if necessary compute a link-layer group which
383 corresponds to that address which is returned in
385 Returns zero on success, or an error code on failure.
387 .Ss "Interface Flags"
388 Interface flags are used for a number of different purposes.
390 flags simply indicate information about the type of interface and its
391 capabilities; others are dynamically manipulated to reflect the
392 current state of the interface.
393 Flags of the former kind are marked
395 in this table; the latter are marked
398 .Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact
401 The interface has been configured up by the user-level code.
404 The interface supports broadcast.
407 Used to enable/disable driver debugging code.
410 The interface is a loopback device.
411 .It Dv IFF_POINTOPOINT
413 The interface is point-to-point;
415 address is actually the address of the other end.
418 The interface has been configured and dynamic resources were
419 successfully allocated.
420 Probably only useful internal to the
424 Disable network address resolution on this interface.
427 This interface is in promiscuous mode.
430 This interface is in the permanently promiscuous mode (implies
434 This interface is in all-multicasts mode (used by multicast routers).
437 The interface's hardware output queue (if any) is full; output packets
441 The interface cannot hear its own transmissions.
446 Control flags for the link layer.
447 (Currently abused to select among
448 multiple physical layers on some devices.)
451 This interface supports multicast.
453 The interface is in polling mode.
454 .\" .It Dv IFF_MONITOR
460 defines the bits which cannot be set by a user program using the
464 these are indicated by an asterisk in the listing above.
465 .Ss The Vt if_data Ss Structure
468 a subset of the interface information believed to be of interest to
469 management stations was segregated from the
471 structure and moved into its own
473 structure to facilitate its use by user programs.
474 The following elements of the
476 structure are initialized by the interface and are not expected to change
477 significantly over the course of normal operation:
478 .Bl -tag -width ".Va ifi_lastchange" -offset indent
481 The type of the interface, as defined in
483 and described below in the
484 .Sx "Interface Types"
488 Intended to represent a selection of physical layers on devices which
489 support more than one; never implemented.
492 Length of a link-layer address on this device, or zero if there are
494 Used to initialize the address length field in
496 structures referring to this interface.
499 Maximum length of any link-layer header which might be prepended by
500 the driver to a packet before transmission.
501 The generic code computes
502 the maximum over all interfaces and uses that value to influence the
505 to attempt to ensure that there is always
506 sufficient space to prepend a link-layer header without allocating an
511 .\" .It Va ifi_recvquota
513 .\" Number of packets the interface is permitted to receive at one time
514 .\" when in polled mode.
515 .\" .It Va ifi_xmitquota
517 .\" Number of packets the interface is permitted to queue for transmission
518 .\" at one time when in polled mode.
519 .\" There is some controversy over
520 .\" whether such a restriction makes any sense at all.
523 The maximum transmission unit of the medium, exclusive of any
527 A dimensionless metric interpreted by a user-mode routing process.
528 .It Va ifi_link_state
530 The link state of the interface, either
531 .Dv LINK_STATE_UNKNOWN ,
532 .Dv LINK_STATE_DOWN ,
537 The line rate of the interface, in bits per second.
540 The structure additionally contains generic statistics applicable to a
541 variety of different interface types (except as noted, all members are
544 .Bl -tag -width ".Va ifi_lastchange" -offset indent
546 Number of packets received.
548 Number of receive errors detected (e.g., FCS errors, DMA overruns,
550 More detailed breakdowns can often be had by way of a
553 Number of packets transmitted.
555 Number of output errors detected (e.g., late collisions, DMA overruns,
557 More detailed breakdowns can often be had by way of a
559 .It Va ifi_collisions
560 Total number of collisions detected on output for CSMA interfaces.
561 (This member is sometimes [ab]used by other types of interfaces for
562 other output error counts.)
564 Total traffic received, in bytes.
566 Total traffic transmitted, in bytes.
568 Number of packets received which were sent by link-layer multicast.
570 Number of packets sent by link-layer multicast.
572 Number of packets dropped on input.
575 Number of packets received for unknown network-layer protocol.
576 .It Va ifi_lastchange
577 .Pq Vt "struct timeval"
578 The time of the last administrative change to the interface (as required
585 defines symbolic constants for a number of different types of
589 .Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact
591 none of the following
599 ISO 8802-5 Token Ring
605 Internet Point-to-Point Protocol
617 Asynchronous Transfer Mode
619 .Ss The Vt ifaddr Ss Structure
620 Every interface is associated with a list
623 of addresses, rooted at the interface structure's
626 The first element in this list is always an
628 address representing the interface itself; multi-access network
629 drivers should complete this structure by filling in their link-layer
630 addresses after calling
632 Other members of the structure represent network-layer addresses which
633 have been configured by means of the
637 called on a socket of the appropriate protocol family.
638 The elements of this list consist of
641 Most protocols will declare their own protocol-specific
642 interface address structures, but all begin with a
644 which provides the most-commonly-needed functionality across all
646 Interface addresses are reference-counted.
651 .Bl -tag -width ".Va ifa_rtrequest" -offset indent
653 .Pq Vt "struct sockaddr *"
654 The local address of the interface.
656 .Pq Vt "struct sockaddr *"
657 The remote address of point-to-point interfaces, and the broadcast
658 address of broadcast interfaces.
663 .Pq Vt "struct sockaddr *"
664 The network mask for multi-access interfaces, and the confusion
665 generator for point-to-point interfaces.
667 .\" .Pq Vt "struct if_data"
670 .Pq Vt "struct ifnet *"
671 A link back to the interface structure.
672 .It Va ifa_containers
673 .Pq Vt "struct ifaddr_container *"
674 A pointer to an array of
676 structures which hold per-CPU data.
681 Some of the flags which would be used for a route representing this
682 address in the route table.
683 .\" .It Va ifa_cpumask
688 A metric associated with this interface address, for the use of some
689 external routing protocol.
694 structures are gained manually, by incrementing the
696 member of the according
698 structure (such as by calling the
701 References are released by calling the
706 is a pointer to a function which receives callouts from the routing
709 to perform link-layer-specific actions upon requests to add, resolve,
713 argument indicates the request in question:
714 .Dv RTM_ADD , RTM_RESOLVE ,
719 argument is the route in question; the
721 argument is the specific destination being manipulated
724 or a null pointer otherwise.
726 The functions provided by the generic interface code can be divided
727 into two groups: those which manipulate interfaces, and those which
728 manipulate interface addresses.
729 In addition to these functions, there
730 may also be link-layer support routines which are used by a number of
731 drivers implementing a specific link layer over different hardware;
732 see the documentation for that link layer for more details.
733 .Ss The Vt ifmultiaddr Ss Structure
734 Every multicast-capable interface is associated with a list of
735 multicast group memberships, which indicate at a low level which
736 link-layer multicast addresses (if any) should be accepted, and at a
737 high level, in which network-layer multicast groups a user process has
740 The elements of the structure are as follows:
741 .Bl -tag -width ".Va ifma_refcount" -offset indent
743 .Pq Fn LIST_ENTRY ifmultiaddr
747 .Pq Vt "struct sockaddr *"
748 A pointer to the address which this record represents.
750 memberships for various address families are stored in arbitrary
753 .Pq Vt "struct sockaddr *"
754 A pointer to the link-layer multicast address, if any, to which the
755 network-layer multicast address in
757 is mapped, else a null pointer.
758 If this element is non-nil, this
759 membership also holds an invisible reference to another membership for
760 that link-layer address.
763 A reference count of requests for this particular membership.
765 .Ss Interface Manipulation Functions
766 .Bl -ohang -offset indent
768 Link the specified interface
770 into the list of network interfaces.
771 Also initialize the list of
772 addresses on that interface, and create a link-layer
774 structure to be the first element in that list.
776 this address structure is saved in the global array
784 flush its output queue, notify protocols of the transition,
785 and generate a message from the
791 as up, notify protocols of the transition,
792 and generate a message from the
796 Add or remove a promiscuous reference to
800 is true, add a reference;
801 if it is false, remove a reference.
802 On reference count transitions
803 from zero to one and one to zero, set the
805 flag appropriately and call
807 to set up the interface in the desired mode.
811 but for the all-multicasts
813 flag instead of the promiscuous flag.
817 pointer for the interface named
820 Process the ioctl request
828 This is the main routine for handling all interface configuration
829 requests from user mode.
830 It is ordinarily only called from the socket-layer
832 handler, and only for commands with class
834 Any unrecognized commands will be passed down to socket
837 further interpretation.
838 The following commands are handled by
841 .Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact
844 Get interface configuration.
845 (No call-down to driver.)
851 Get interface flags, metric, MTU, medium selection.
852 (No call-down to driver.)
855 Change interface flags.
856 Caller must have appropriate privilege.
863 is called as appropriate.
866 are masked off, and the driver
868 routine is called to perform any setup
873 Change interface metric or medium.
874 Caller must have appropriate privilege.
877 Change interface MTU.
878 Caller must have appropriate privilege.
880 values less than 72 or greater than 65535 are considered invalid.
883 routine is called to implement the change; it is responsible for any
884 additional sanity checking and for actually modifying the MTU in the
889 Add or delete permanent multicast group memberships on the interface.
890 Caller must have appropriate privilege.
895 function is called to perform the operation; qq.v.
897 .It Dv SIOCSIFDSTADDR
899 .It Dv SIOCSIFBRDADDR
900 .It Dv SIOCSIFNETMASK
901 The socket's protocol control routine is called to implement the
905 .It Dv OSIOCGIFDSTADDR
906 .It Dv OSIOCGIFBRDADDR
907 .It Dv OSIOCGIFNETMASK
908 The socket's protocol control routine is called to implement the
912 structures are converted into old-style (no
923 must be called inside a critical section.
924 .Ss "Interface Address Functions"
925 Several functions exist to look up an interface address structure
928 returns an interface address with either a local address or a
929 broadcast address precisely matching the parameter
931 .Fn ifa_ifwithdstaddr
932 returns an interface address for a point-to-point interface whose
939 returns the most specific interface address which matches the
942 subject to its configured netmask, or a point-to-point interface
943 address whose remote address is
948 returns the most specific address configured on interface
950 which matches address
952 subject to its configured netmask.
954 point-to-point, only an interface address whose remote address is
959 All of these functions return a null pointer if no such address can be
961 .Ss "Interface Multicast Address Functions"
966 .Fn ifmaof_ifpforaddr
967 functions provide support for requesting and relinquishing multicast
968 group memberships, and for querying an interface's membership list,
972 function takes a pointer to an interface,
974 and a generic address,
976 It also takes a pointer to a
977 .Vt "struct ifmultiaddr *"
978 which is filled in on successful return with the address of the
979 group membership control block.
982 function performs the following four-step process:
983 .Bl -enum -offset indent
987 entry point to determine the link-layer address, if any, corresponding
988 to this membership request, and also to give the link layer an
989 opportunity to veto this membership request should it so desire.
991 Check the interface's group membership list for a pre-existing
992 membership for this group.
993 If one is not found, allocate a new one;
994 if one is, increment its reference count.
998 routine returned a link-layer address corresponding to the group,
999 repeat the previous step for that address as well.
1001 If the interface's multicast address filter needs to be changed
1002 because a new membership was added, call the interface's
1009 to request that it do so.
1014 function, given an interface
1018 reverses this process.
1019 Both functions return zero on success, or a
1020 standard error number on failure.
1023 .Fn ifmaof_ifpforaddr
1024 function examines the membership list of interface
1026 for an address matching
1028 and returns a pointer to that
1029 .Vt "struct ifmultiaddr"
1030 if one is found, else it returns a null pointer.
1048 .%A W. Richard Stevens
1049 .%B TCP/IP Illustrated
1051 .%O Addison-Wesley, ISBN 0-201-63354-X
1054 This manual page was written by
1055 .An Garrett A. Wollman .