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"
87 .Fo \*(lp*if_output\*(rp
88 .Fa "struct ifnet *ifp" "struct mbuf *m"
89 .Fa "struct sockaddr *dst" "struct rtentry *rt"
92 .Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m"
94 .Fn \*(lp*if_start\*(rp "struct ifnet *ifp"
96 .Fo \*(lp*if_ioctl\*(rp
97 .Fa "struct ifnet *ifp" "u_long command" "caddr_t data" "struct ucred *cr"
100 .Fn \*(lp*if_watchdog\*(rp "struct ifnet *ifp"
102 .Fn \*(lp*if_init\*(rp "void *if_softc"
104 .Fo \*(lp*if_resolvemulti\*(rp
105 .Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr"
108 .Fn \*(lp*if_poll\*(rp "struct ifnet *ifp" "enum poll_cmd cmd" "int count"
109 .Ss "struct ifaddr member function"
111 .Fo \*(lp*ifa_rtrequest\*(rp
112 .Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
115 .Ss "Global Variables"
116 .Vt extern struct ifnethead ifnet ;
117 .Vt extern int if_index ;
118 .Vt extern int ifqmaxlen ;
120 The kernel mechanisms for handling network interfaces reside primarily
122 .Vt ifnet , if_data , ifaddr ,
129 and the functions named above and defined in
131 Those interfaces which are intended to be used by user programs
134 these include the interface flags, the
136 structure, and the structures defining the appearance of
137 interface-related messages on the
139 routing socket and in
143 defines the kernel-internal interfaces, including the
147 structures and the functions which manipulate them.
148 (A few user programs will need
150 because it is the prerequisite of some other header file like
151 .In netinet/if_ether.h .
152 Most references to those two files in particular can be replaced by
153 .In net/ethernet.h . )
155 The system keeps a linked list of interfaces using the
159 this list is headed by a
160 .Vt "struct ifnethead"
163 The elements of this list are of type
165 and most kernel routines which manipulate interface as such accept or
166 return pointers to these structures.
167 Each interface structure
170 structure, which contains statistics and identifying information used
171 by management programs, and which is exported to user programs by way
177 Each interface also has a
179 of interface addresses, described by
181 structures; the head of the queue is always an
186 describing the link layer implemented by the interface (if any).
187 (Some trivial interfaces do not provide any link layer addresses;
188 this structure, while still present, serves only to identify the
189 interface name and index.)
191 Finally, those interfaces supporting reception of multicast datagrams
194 of multicast group memberships, described by
197 These memberships are reference-counted.
199 Interfaces are also associated with an output queue, defined as a
200 .Vt "struct ifqueue" ;
201 this structure is used to hold packets while the interface is in the
202 process of sending another.
203 .Ss The Vt ifnet Ss structure
207 .Bl -tag -width ".Va if_poll_slowq" -offset indent
210 A pointer to the driver's private state block.
211 (Initialized by driver.)
213 .Pq Fn TAILQ_ENTRY ifnet
218 The name of the interface,
223 (Initialized by driver.)
225 .Pq Vt "const char *"
226 The name of the driver.
227 (Initialized by driver.)
230 A unique number assigned to each interface managed by a particular
232 Drivers may choose to set this to
234 if a unit number is not associated with the device.
235 (Initialized by driver.)
236 .\" .It Va if_vlantrunks
240 .Pq Vt "struct ifaddrhead"
244 containing the list of addresses assigned to this interface.
247 A count of promiscuous listeners on this interface, used to
252 .Pq Vt "struct carp_if *"
253 Per-interface data for
256 .Pq Vt "struct bpf_if *"
257 Opaque per-interface data for the packet filter,
263 A unique number assigned to each interface in sequence as it is
265 This number can be used in a
266 .Vt "struct sockaddr_dl"
267 to refer to a particular interface by index
272 Number of seconds until the watchdog timer
274 is called, or zero if the timer is disabled.
276 decremented by generic watchdog code.)
279 Flags describing operational parameters of this interface (see below).
280 (Manipulated by both driver and generic code.)
283 A pointer to an interface-specific MIB structure exported by
285 (Initialized by driver.)
288 The size of said structure.
289 (Initialized by driver.)
291 .Pq Vt "struct if_data"
292 More statistics and information; see
293 .Sx "The if_data structure" ,
295 (Initialized by driver, manipulated by both driver and generic
297 .\" .It Va if_poll_cpuid
301 .Pq Vt "struct ifaltq"
302 The output queue including
304 (Manipulated by driver.)
305 .\" .It Va if_broadcastaddr
306 .\" .Pq Vt "const uint8_t"
315 .\" .Pq Vt "struct ifaddr"
317 .\" .It Va if_serializer
318 .\" .Pq Vt "struct lwkt_serialize"
320 .\" .It Va if_default_serializer
321 .\" .Pq Vt "struct lwkt_serialize"
325 There are in addition a number of function pointers which the driver
326 must initialize to complete its interface with the generic interface
328 .Bl -ohang -offset indent
330 Output a packet on interface
332 or queue it on the output queue if the interface is already active.
334 Start queued output on an interface.
335 This function is exposed in
336 order to provide for some interface classes to share a
340 may only be called when the
345 does not literally mean that output is active, but rather that the
346 device's internal output queue is full.)
348 Process interface-related
353 Preliminary processing is done by the generic routine
355 to check for appropriate privileges, locate the interface being
356 manipulated, and perform certain generic operations like twiddling
357 flags and flushing queues.
358 See the description of
360 below for more information.
362 Routine called by the generic code when the watchdog timer,
365 Usually this will reset the interface.
371 Initialize and bring up the hardware,
372 e.g., reset the chip and the watchdog timer and enable the receiver unit.
373 Should mark the interface running,
375 .Dv ( IFF_RUNNING , ~IFF_OACTIVE ) .
376 .It Fn if_resolvemulti
377 Check the requested multicast group membership,
379 for validity, and if necessary compute a link-layer group which
380 corresponds to that address which is returned in
382 Returns zero on success, or an error code on failure.
384 .Ss "Interface Flags"
385 Interface flags are used for a number of different purposes.
387 flags simply indicate information about the type of interface and its
388 capabilities; others are dynamically manipulated to reflect the
389 current state of the interface.
390 Flags of the former kind are marked
392 in this table; the latter are marked
395 .Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact
398 The interface has been configured up by the user-level code.
401 The interface supports broadcast.
404 Used to enable/disable driver debugging code.
407 The interface is a loopback device.
408 .It Dv IFF_POINTOPOINT
410 The interface is point-to-point;
412 address is actually the address of the other end.
415 The interface has been configured and dynamic resources were
416 successfully allocated.
417 Probably only useful internal to the
421 Disable network address resolution on this interface.
424 This interface is in promiscuous mode.
427 This interface is in the permanently promiscuous mode (implies
431 This interface is in all-multicasts mode (used by multicast routers).
434 The interface's hardware output queue (if any) is full; output packets
438 The interface cannot hear its own transmissions.
443 Control flags for the link layer.
444 (Currently abused to select among
445 multiple physical layers on some devices.)
448 This interface supports multicast.
450 The interface is in polling mode.
451 .\" .It Dv IFF_MONITOR
457 defines the bits which cannot be set by a user program using the
461 these are indicated by an asterisk in the listing above.
462 .Ss The Vt if_data Ss Structure
465 a subset of the interface information believed to be of interest to
466 management stations was segregated from the
468 structure and moved into its own
470 structure to facilitate its use by user programs.
471 The following elements of the
473 structure are initialized by the interface and are not expected to change
474 significantly over the course of normal operation:
475 .Bl -tag -width ".Va ifi_lastchange" -offset indent
478 The type of the interface, as defined in
480 and described below in the
481 .Sx "Interface Types"
485 Intended to represent a selection of physical layers on devices which
486 support more than one; never implemented.
489 Length of a link-layer address on this device, or zero if there are
491 Used to initialize the address length field in
493 structures referring to this interface.
496 Maximum length of any link-layer header which might be prepended by
497 the driver to a packet before transmission.
498 The generic code computes
499 the maximum over all interfaces and uses that value to influence the
502 to attempt to ensure that there is always
503 sufficient space to prepend a link-layer header without allocating an
508 .\" .It Va ifi_recvquota
510 .\" Number of packets the interface is permitted to receive at one time
511 .\" when in polled mode.
512 .\" .It Va ifi_xmitquota
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.
520 The maximum transmission unit of the medium, exclusive of any
524 A dimensionless metric interpreted by a user-mode routing process.
525 .It Va ifi_link_state
527 The link state of the interface, either
528 .Dv LINK_STATE_UNKNOWN ,
529 .Dv LINK_STATE_DOWN ,
534 The line rate of the interface, in bits per second.
537 The structure additionally contains generic statistics applicable to a
538 variety of different interface types (except as noted, all members are
541 .Bl -tag -width ".Va ifi_lastchange" -offset indent
543 Number of packets received.
545 Number of receive errors detected (e.g., FCS errors, DMA overruns,
547 More detailed breakdowns can often be had by way of a
550 Number of packets transmitted.
552 Number of output errors detected (e.g., late collisions, DMA overruns,
554 More detailed breakdowns can often be had by way of a
556 .It Va ifi_collisions
557 Total number of collisions detected on output for CSMA interfaces.
558 (This member is sometimes [ab]used by other types of interfaces for
559 other output error counts.)
561 Total traffic received, in bytes.
563 Total traffic transmitted, in bytes.
565 Number of packets received which were sent by link-layer multicast.
567 Number of packets sent by link-layer multicast.
569 Number of packets dropped on input.
572 Number of packets received for unknown network-layer protocol.
573 .It Va ifi_lastchange
574 .Pq Vt "struct timeval"
575 The time of the last administrative change to the interface (as required
582 defines symbolic constants for a number of different types of
586 .Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact
588 none of the following
596 ISO 8802-5 Token Ring
602 Internet Point-to-Point Protocol
614 Asynchronous Transfer Mode
616 .Ss The Vt ifaddr Ss Structure
617 Every interface is associated with a list
620 of addresses, rooted at the interface structure's
623 The first element in this list is always an
625 address representing the interface itself; multi-access network
626 drivers should complete this structure by filling in their link-layer
627 addresses after calling
629 Other members of the structure represent network-layer addresses which
630 have been configured by means of the
634 called on a socket of the appropriate protocol family.
635 The elements of this list consist of
638 Most protocols will declare their own protocol-specific
639 interface address structures, but all begin with a
641 which provides the most-commonly-needed functionality across all
643 Interface addresses are reference-counted.
648 .Bl -tag -width ".Va ifa_rtrequest" -offset indent
650 .Pq Vt "struct sockaddr *"
651 The local address of the interface.
653 .Pq Vt "struct sockaddr *"
654 The remote address of point-to-point interfaces, and the broadcast
655 address of broadcast interfaces.
660 .Pq Vt "struct sockaddr *"
661 The network mask for multi-access interfaces, and the confusion
662 generator for point-to-point interfaces.
664 .\" .Pq Vt "struct if_data"
667 .Pq Vt "struct ifnet *"
668 A link back to the interface structure.
669 .It Va ifa_containers
670 .Pq Vt "struct ifaddr_container *"
671 A pointer to an array of
673 structures which hold per-CPU data.
678 Some of the flags which would be used for a route representing this
679 address in the route table.
680 .\" .It Va ifa_cpumask
685 A metric associated with this interface address, for the use of some
686 external routing protocol.
691 structures are gained manually, by incrementing the
693 member of the according
695 structure (such as by calling the
698 References are released by calling the
703 is a pointer to a function which receives callouts from the routing
706 to perform link-layer-specific actions upon requests to add, resolve,
710 argument indicates the request in question:
711 .Dv RTM_ADD , RTM_RESOLVE ,
716 argument is the route in question; the
718 argument is the specific destination being manipulated
721 or a null pointer otherwise.
723 The functions provided by the generic interface code can be divided
724 into two groups: those which manipulate interfaces, and those which
725 manipulate interface addresses.
726 In addition to these functions, there
727 may also be link-layer support routines which are used by a number of
728 drivers implementing a specific link layer over different hardware;
729 see the documentation for that link layer for more details.
730 .Ss The Vt ifmultiaddr Ss Structure
731 Every multicast-capable interface is associated with a list of
732 multicast group memberships, which indicate at a low level which
733 link-layer multicast addresses (if any) should be accepted, and at a
734 high level, in which network-layer multicast groups a user process has
737 The elements of the structure are as follows:
738 .Bl -tag -width ".Va ifma_refcount" -offset indent
740 .Pq Fn LIST_ENTRY ifmultiaddr
744 .Pq Vt "struct sockaddr *"
745 A pointer to the address which this record represents.
747 memberships for various address families are stored in arbitrary
750 .Pq Vt "struct sockaddr *"
751 A pointer to the link-layer multicast address, if any, to which the
752 network-layer multicast address in
754 is mapped, else a null pointer.
755 If this element is non-nil, this
756 membership also holds an invisible reference to another membership for
757 that link-layer address.
760 A reference count of requests for this particular membership.
762 .Ss Interface Manipulation Functions
763 .Bl -ohang -offset indent
765 Link the specified interface
767 into the list of network interfaces.
768 Also initialize the list of
769 addresses on that interface, and create a link-layer
771 structure to be the first element in that list.
773 this address structure is saved in the global array
781 flush its output queue, notify protocols of the transition,
782 and generate a message from the
788 as up, notify protocols of the transition,
789 and generate a message from the
793 Add or remove a promiscuous reference to
797 is true, add a reference;
798 if it is false, remove a reference.
799 On reference count transitions
800 from zero to one and one to zero, set the
802 flag appropriately and call
804 to set up the interface in the desired mode.
808 but for the all-multicasts
810 flag instead of the promiscuous flag.
814 pointer for the interface named
817 Process the ioctl request
825 This is the main routine for handling all interface configuration
826 requests from user mode.
827 It is ordinarily only called from the socket-layer
829 handler, and only for commands with class
831 Any unrecognized commands will be passed down to socket
834 further interpretation.
835 The following commands are handled by
838 .Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact
841 Get interface configuration.
842 (No call-down to driver.)
848 Get interface flags, metric, MTU, medium selection.
849 (No call-down to driver.)
852 Change interface flags.
853 Caller must have appropriate privilege.
860 is called as appropriate.
863 are masked off, and the driver
865 routine is called to perform any setup
870 Change interface metric or medium.
871 Caller must have appropriate privilege.
874 Change interface MTU.
875 Caller must have appropriate privilege.
877 values less than 72 or greater than 65535 are considered invalid.
880 routine is called to implement the change; it is responsible for any
881 additional sanity checking and for actually modifying the MTU in the
886 Add or delete permanent multicast group memberships on the interface.
887 Caller must have appropriate privilege.
892 function is called to perform the operation; qq.v.
894 .It Dv SIOCSIFDSTADDR
896 .It Dv SIOCSIFBRDADDR
897 .It Dv SIOCSIFNETMASK
898 The socket's protocol control routine is called to implement the
902 .It Dv OSIOCGIFDSTADDR
903 .It Dv OSIOCGIFBRDADDR
904 .It Dv OSIOCGIFNETMASK
905 The socket's protocol control routine is called to implement the
909 structures are converted into old-style (no
920 must be called inside a critical section.
921 .Ss "Interface Address Functions"
922 Several functions exist to look up an interface address structure
925 returns an interface address with either a local address or a
926 broadcast address precisely matching the parameter
928 .Fn ifa_ifwithdstaddr
929 returns an interface address for a point-to-point interface whose
936 returns the most specific interface address which matches the
939 subject to its configured netmask, or a point-to-point interface
940 address whose remote address is
945 returns the most specific address configured on interface
947 which matches address
949 subject to its configured netmask.
951 point-to-point, only an interface address whose remote address is
956 All of these functions return a null pointer if no such address can be
958 .Ss "Interface Multicast Address Functions"
963 .Fn ifmaof_ifpforaddr
964 functions provide support for requesting and relinquishing multicast
965 group memberships, and for querying an interface's membership list,
969 function takes a pointer to an interface,
971 and a generic address,
973 It also takes a pointer to a
974 .Vt "struct ifmultiaddr *"
975 which is filled in on successful return with the address of the
976 group membership control block.
979 function performs the following four-step process:
980 .Bl -enum -offset indent
984 entry point to determine the link-layer address, if any, corresponding
985 to this membership request, and also to give the link layer an
986 opportunity to veto this membership request should it so desire.
988 Check the interface's group membership list for a pre-existing
989 membership for this group.
990 If one is not found, allocate a new one;
991 if one is, increment its reference count.
995 routine returned a link-layer address corresponding to the group,
996 repeat the previous step for that address as well.
998 If the interface's multicast address filter needs to be changed
999 because a new membership was added, call the interface's
1006 to request that it do so.
1011 function, given an interface
1015 reverses this process.
1016 Both functions return zero on success, or a
1017 standard error number on failure.
1020 .Fn ifmaof_ifpforaddr
1021 function examines the membership list of interface
1023 for an address matching
1025 and returns a pointer to that
1026 .Vt "struct ifmultiaddr"
1027 if one is found, else it returns a null pointer.
1045 .%A W. Richard Stevens
1046 .%B TCP/IP Illustrated
1048 .%O Addison-Wesley, ISBN 0-201-63354-X
1051 This manual page was written by
1052 .An Garrett A. Wollman .