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 $
30 .\" $DragonFly: src/share/man/man9/ifnet.9,v 1.3 2004/01/06 01:40:43 dillon 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"
74 .Fn ifafree "struct ifaddr *ifa"
75 .Fn IFAFREE "struct ifaddr *ifa"
77 .Ss "Interface Multicast Address Functions"
79 .Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap"
81 .Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa"
82 .Ft "struct ifmultiaddr *"
83 .Fn ifmaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
84 .Ss "Output queue macros"
85 .Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m"
87 .Ss "struct ifnet Member Functions"
89 .Fo \*(lp*if_output\*(rp
90 .Fa "struct ifnet *ifp" "struct mbuf *m"
91 .Fa "struct sockaddr *dst" "struct rtentry *rt"
94 .Fn \*(lp*if_start\*(rp "struct ifnet *ifp"
96 .Fn \*(lp*if_done\*(rp "struct ifnet *ifp"
98 .Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "int cmd" "caddr_t data"
100 .Fn \*(lp*if_watchdog\*(rp "struct ifnet *ifp"
102 .Fn \*(lp*if_poll_recv\*(rp "struct ifnet *ifp" "int *quotap"
104 .Fn \*(lp*if_poll_xmit\*(rp "struct ifnet *ifp" "int *quotap"
106 .Fn \*(lp*if_poll_inttrn\*(rp "struct ifnet *ifp"
108 .Fn \*(lp*if_poll_slowinput\*(rp "struct ifnet *ifp" "struct mbuf *m"
110 .Fn \*(lp*if_init\*(rp "void *if_softc"
112 .Fo \*(lp*if_resolvemulti\*(rp
113 .Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr"
115 .Ss "struct ifaddr member function"
117 .Fo \*(lp*ifa_rtrequest\*(rp
118 .Fa "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
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 ;
127 The kernel mechanisms for handling network interfaces reside primarily
129 .Vt ifnet , if_data , ifaddr ,
136 and the functions named above and defined in
138 Those interfaces which are intended to be used by user programs
141 these include the interface flags, the
143 structure, and the structures defining the appearance of
144 interface-related messages on the
146 routing socket and in
150 defines the kernel-internal interfaces, including the
154 structures and the functions which manipulate them.
155 (A few user programs will need
157 because it is the prerequisite of some other header file like
158 .Aq Pa netinet/if_ether.h .
159 Most references to those two files in particular can be replaced by
160 .Aq Pa net/ethernet.h . )
162 The system keeps a linked list of interfaces using the
166 this list is headed by a
167 .Vt "struct ifnethead"
170 The elements of this list are of type
172 and most kernel routines which manipulate interface as such accept or
173 return pointers to these structures.
174 Each interface structure
177 structure, which contains statistics and identifying information used
178 by management programs, and which is exported to user programs by way
184 Each interface also has a
186 of interface addresses, described by
188 structures; the head of the queue is always an
193 describing the link layer implemented by the interface (if any).
194 (Some trivial interfaces do not provide any link layer addresses;
195 this structure, while still present, serves only to identify the
196 interface name and index.)
198 Finally, those interfaces supporting reception of multicast datagrams
201 of multicast group memberships, described by
204 These memberships are reference-counted.
206 Interfaces are also associated with an output queue, defined as a
207 .Vt "struct ifqueue" ;
208 this structure is used to hold packets while the interface is in the
209 process of sending another.
211 .Ss The Vt ifnet Ss structure
215 .Bl -tag -width ".Va if_poll_slowq" -offset indent
218 A pointer to the driver's private state block.
219 (Initialized by driver.)
221 .Pq Fn TAILQ_ENTRY ifnet
226 The name of the interface,
231 (Initialized by driver.)
233 .Pq Vt "const char *"
234 The name of the driver.
235 (Initialized by driver.)
238 A unique number assigned to each interface managed by a particular
240 Drivers may choose to set this to
242 if a unit number is not associated with the device.
243 (Initialized by driver.)
245 .Pq Vt "struct ifaddrhead"
249 containing the list of addresses assigned to this interface.
252 A count of promiscuous listeners on this interface, used to
257 .Pq Vt "struct bpf_if *"
258 Opaque per-interface data for the packet filter,
264 A unique number assigned to each interface in sequence as it is
266 This number can be used in a
267 .Vt "struct sockaddr_dl"
268 to refer to a particular interface by index
273 Number of seconds until the watchdog timer
275 is called, or zero if the timer is disabled.
277 decremented by generic watchdog code.)
280 Flags describing operational parameters of this interface (see below).
281 (Manipulated by both driver and generic code.)
282 .\" .It Va if_ipending
283 .\" Interrupt-pending bits for polled operation:
285 .\" (transmit complete interrupt)
288 .\" (received packet ready interrupt).
292 .\" (Manipulated by driver.)
295 A pointer to an interface-specific MIB structure exported by
297 (Initialized by driver.)
300 The size of said structure.
301 (Initialized by driver.)
303 .Pq Vt "struct if_data"
304 More statistics and information; see
305 .Sx "The if_data structure" ,
307 (Initialized by driver, manipulated by both driver and generic
310 .Pq Vt "struct ifqueue"
312 (Manipulated by driver.)
313 .\".It Va if_poll_slowq
314 .\".Pq Vt "struct ifqueue *"
315 .\"A pointer to the input queue for devices which do not support polling
320 .\"(Initialized by driver.)
323 There are in addition a number of function pointers which the driver
324 must initialize to complete its interface with the generic interface
326 .Bl -ohang -offset indent
328 Output a packet on interface
330 or queue it on the output queue if the interface is already active.
332 Start queued output on an interface.
333 This function is exposed in
334 order to provide for some interface classes to share a
338 may only be called when the
343 does not literally mean that output is active, but rather that the
344 device's internal output queue is full.)
347 We are not even sure what it was ever for.
348 The prototype is faked.
350 Process interface-related
354 .Aq Pa sys/sockio.h ) .
355 Preliminary processing is done by the generic routine
357 to check for appropriate privileges, locate the interface being
358 manipulated, and perform certain generic operations like twiddling
359 flags and flushing queues.
360 See the description of
362 below for more information.
364 Routine called by the generic code when the watchdog timer,
367 Usually this will reset the interface.
368 .\" .It Fn if_poll_recv
369 .\" .It Fn if_poll_xmit
370 .\" .It Fn if_poll_slowinput
371 .\" .It Fn if_poll_intren
376 Initialize and bring up the hardware,
377 e.g., reset the chip and the watchdog timer and enable the receiver unit.
378 Should mark the interface running,
380 .Dv ( IFF_RUNNING , ~IIF_OACTIVE ) .
381 .It Fn if_resolvemulti
382 Check the requested multicast group membership,
384 for validity, and if necessary compute a link-layer group which
385 corresponds to that address which is returned in
387 Returns zero on success, or an error code on failure.
389 .Ss "Interface Flags"
390 Interface flags are used for a number of different purposes.
392 flags simply indicate information about the type of interface and its
393 capabilities; others are dynamically manipulated to reflect the
394 current state of the interface.
395 Flags of the former kind are marked
397 in this table; the latter are marked
400 .Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact
403 The interface has been configured up by the user-level code.
406 The interface supports broadcast.
409 Used to enable/disable driver debugging code.
412 The interface is a loopback device.
413 .It Dv IFF_POINTOPOINT
415 The interface is point-to-point;
417 address is actually the address of the other end.
420 The interface has been configured and dynamic resources were
421 successfully allocated.
422 Probably only useful internal to the
426 Disable network address resolution on this interface.
429 This interface is in promiscuous mode.
432 This interface is in the permanently promiscuous mode (implies
436 This interface is in all-multicasts mode (used by multicast routers).
439 The interface's hardware output queue (if any) is full; output packets
443 The interface cannot hear its own transmissions.
448 Control flags for the link layer.
449 (Currently abused to select among
450 multiple physical layers on some devices.)
453 This interface supports multicast.
458 defines the bits which cannot be set by a user program using the
462 these are indicated by an asterisk in the listing above.
463 .Ss The Vt if_data Ss Structure
466 a subset of the interface information believed to be of interest to
467 management stations was segregated from the
469 structure and moved into its own
471 structure to facilitate its use by user programs.
472 The following elements of the
474 structure are initialized by the interface and are not expected to change
475 significantly over the course of normal operation:
476 .Bl -tag -width ".Va ifi_lastchange" -offset indent
479 The type of the interface, as defined in
480 .Aq Pa net/if_types.h
481 and described below in the
482 .Sx "Interface Types"
486 Intended to represent a selection of physical layers on devices which
487 support more than one; never implemented.
490 Length of a link-layer address on this device, or zero if there are
492 Used to initialized the address length field in
494 structures referring to this interface.
497 Maximum length of any link-layer header which might be prepended by
498 the driver to a packet before transmission.
499 The generic code computes
500 the maximum over all interfaces and uses that value to influence the
503 to attempt to ensure that there is always
504 sufficient space to prepend a link-layer header without allocating an
509 .\" .It Va ifi_recvquota
511 .\" Number of packets the interface is permitted to receive at one time
512 .\" when in polled mode.
513 .\" .It Va ifi_xmitquota
515 .\" Number of packets the interface is permitted to queue for transmission
516 .\" at one time when in polled mode.
517 .\" There is some controversy over
518 .\" whether such a restriction makes any sense at all.
521 The maximum transmission unit of the medium, exclusive of any
525 A dimensionless metric interpreted by a user-mode routing process.
528 The line rate of the interface, in bits per second.
531 The structure additionally contains generic statistics applicable to a
532 variety of different interface types (except as noted, all members are
535 .Bl -tag -width ".Va ifi_lastchange" -offset indent
537 Number of packets received.
539 Number of receive errors detected (e.g., FCS errors, DMA overruns,
541 More detailed breakdowns can often be had by way of a
544 Number of packets transmitted.
546 Number of output errors detected (e.g., late collisions, DMA overruns,
548 More detailed breakdowns can often be had by way of a
550 .It Va ifi_collisions
551 Total number of collisions detected on output for CSMA interfaces.
552 (This member is sometimes [ab]used by other types of interfaces for
553 other output error counts.)
555 Total traffic received, in bytes.
557 Total traffic transmitted, in bytes.
559 Number of packets received which were sent by link-layer multicast.
561 Number of packets sent by link-layer multicast.
563 Number of packets dropped on input.
566 Number of packets received for unknown network-layer protocol.
567 .\" .It Va ifi_recvtiming
568 .\" Amount of time, in microseconds, spent to receive an average packet on
573 .\" .It Va ifi_xmittiming
574 .\" Amount of time, in microseconds, spent to service a transmit-complete
575 .\" interrupt on this interface.
579 .It Va ifi_lastchange
580 .Pq Vt "struct timeval"
581 The time of the last administrative change to the interface (as required
587 .Aq Pa net/if_types.h
588 defines symbolic constants for a number of different types of
592 .Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact
594 none of the following
602 ISO 8802-5 Token Ring
608 Internet Point-to-Point Protocol
620 Asynchronous Transfer Mode
622 .Ss The Vt ifaddr Ss Structure
623 Every interface is associated with a list
626 of addresses, rooted at the interface structure's
629 The first element in this list is always an
631 address representing the interface itself; multi-access network
632 drivers should complete this structure by filling in their link-layer
633 addresses after calling
635 Other members of the structure represent network-layer addresses which
636 have been configured by means of the
640 called on a socket of the appropriate protocol family.
641 The elements of this list consist of
644 Most protocols will declare their own protocol-specific
645 interface address structures, but all begin with a
647 which provides the most-commonly-needed functionality across all
649 Interface addresses are reference-counted.
654 .Bl -tag -width ".Va ifa_rtrequest" -offset indent
656 .Pq Vt "struct sockaddr *"
657 The local address of the interface.
659 .Pq Vt "struct sockaddr *"
660 The remote address of point-to-point interfaces, and the broadcast
661 address of broadcast interfaces.
666 .Pq Vt "struct sockaddr *"
667 The network mask for multi-access interfaces, and the confusion
668 generator for point-to-point interfaces.
670 .Pq Vt "struct ifnet *"
671 A link back to the interface structure.
673 .Pq Fn TAILQ_ENTRY ifaddr
675 glue for list of addresses on each interface.
680 Some of the flags which would be used for a route representing this
681 address in the route table.
687 A metric associated with this interface address, for the use of some
688 external routing protocol.
693 structures are gained manually, by incrementing the
696 References are released by calling either 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
923 .Ss "Interface Address Functions"
924 Several functions exist to look up an interface address structure
927 returns an interface address with either a local address or a
928 broadcast address precisely matching the parameter
930 .Fn ifa_ifwithdstaddr
931 returns an interface address for a point-to-point interface whose
938 returns the most specific interface address which matches the
941 subject to its configured netmask, or a point-to-point interface
942 address whose remote address is
947 returns the most specific address configured on interface
949 which matches address
951 subject to its configured netmask.
953 point-to-point, only an interface address whose remote address is
958 All of these functions return a null pointer if no such address can be
960 .Ss "Interface Multicast Address Functions"
965 .Fn ifmaof_ifpforaddr
966 functions provide support for requesting and relinquishing multicast
967 group memberships, and for querying an interface's membership list,
971 function takes a pointer to an interface,
973 and a generic address,
975 It also takes a pointer to a
976 .Vt "struct ifmultiaddr *"
977 which is filled in on successful return with the address of the
978 group membership control block.
981 function performs the following four-step process:
982 .Bl -enum -offset indent
986 entry point to determine the link-layer address, if any, corresponding
987 to this membership request, and also to give the link layer an
988 opportunity to veto this membership request should it so desire.
990 Check the interface's group membership list for a pre-existing
991 membership for this group.
992 If one is not found, allocate a new one;
993 if one is, increment its reference count.
997 routine returned a link-layer address corresponding to the group,
998 repeat the previous step for that address as well.
1000 If the interface's multicast address filter needs to be changed
1001 because a new membership was added, call the interface's
1008 to request that it do so.
1013 function, given an interface
1017 reverses this process.
1018 Both functions return zero on success, or a
1019 standard error number on failure.
1022 .Fn ifmaof_ifpforaddr
1023 function examines the membership list of interface
1025 for an address matching
1027 and returns a pointer to that
1028 .Vt "struct ifmultiaddr"
1029 if one is found, else it returns a null pointer.
1047 .%A W. Richard Stevens
1048 .%B TCP/IP Illustrated
1050 .%O Addison-Wesley, ISBN 0-201-63354-X
1053 This manual page was written by
1054 .An Garrett A. Wollman .