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
38 .Nd kernel interfaces for manipulating network interfaces
40 .Fd #include <sys/types.h>
41 .Fd #include <sys/time.h>
42 .Fd #include <sys/socket.h>
43 .Fd #include <net/if.h>
44 .Fd #include <net/if_var.h>
45 .Fd #include <net/if_types.h>
47 .Ss "Interface manipulation functions"
49 .Fn if_attach "struct ifnet *ifp"
51 .Fn if_down "struct ifnet *ifp"
53 .Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct proc *p"
55 .Fn ifpromisc "struct ifnet *ifp" "int pswitch"
57 .Fn if_allmulti "struct ifnet *ifp" "int amswitch"
59 .Fn ifunit "char *name"
61 .Fn if_up "struct ifnet *ifp"
63 .Ss "Interface address functions"
65 .Fn ifa_ifwithaddr "struct sockaddr *addr"
67 .Fn ifa_ifwithdstaddr "struct sockaddr *addr"
69 .Fn ifa_ifwithnet "struct sockaddr *addr"
71 .Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp"
73 .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"
86 .Fn IF_ENQ_DROP "struct ifqueue *ifq" "struct mbuf *m"
88 .Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m"
90 .Ss "struct ifnet member functions"
92 .Fn \*(lp*if_output\*(rp "struct ifnet *ifp" "struct mbuf *m" "struct sockaddr *dst" "struct rtentry *rt"
94 .Fn \*(lp*if_start\*(rp "struct ifnet *ifp"
96 .Fn \*(lp*if_dont\*(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 .Fn \*(lp*if_resolvemulti\*(rp "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr"
113 .Ss "struct ifaddr member function"
115 .Fn \*(lp*ifa_rtrequest\*(rp "int cmd" "struct rtentry *rt" "struct sockaddr *dst"
116 .Ss "Global variables"
117 .Vt extern struct ifnethead ifnet ;
118 .Vt extern struct ifaddr \&**ifnet_addrs ;
119 .Vt extern int if_index ;
120 .Vt extern int ifqmaxlen ;
122 The kernel mechanisms for handling network interfaces reside primarily
133 and the functions named above and defined in
135 Those interfaces which are intended to be used by user programs
138 these include the interface flags, the
140 structure, and the structures defining the appearance of
141 interface-related messages on the
143 routing socket and in
147 defines the kernel-internal interfaces, including the
152 structures and the functions which manipulate them.
153 (A few user programs will need
155 because it is the prerequisite of some other header file like
156 .Aq Pa netinet/if_ether.h .
157 Most references to those two files in particular can be replaced by
158 .Aq Pa net/ethernet.h . )
160 The system keeps a linked list of interfaces using the
164 this list is headed by a
165 .Li "struct ifnethead"
168 The elements of this list are of type
170 and most kernel routines which manipulate interface as such accept or
171 return pointers to these structures. Each interface structure
174 structure, which contains statistics and identifying information used
175 by management programs, and which is exported to user programs by way
181 Each interface also has a
183 of interface addresses, described by
185 structures; the head of the queue is always an
190 describing the link layer implemented by the interface (if any).
191 (Some trivial interfaces do not provide any link layer addresses;
192 this structure, while still present, serves only to identify the
193 interface name and index.)
195 Finally, those interfaces supporting reception of multicast datagrams
198 of multicast group memberships, described by
200 structures. These memberships are reference-counted.
202 Interfaces are also associated with an output queue, defined as a
203 .Li "struct ifqueue" ;
204 this structure is used to hold packets while the interface is in the
205 process of sending another. The current implementation implements a
206 drop-tail queuing discipline, but in the future a Random Early Drop
207 discipline is expected to be used. For this reason, kernel code
208 should not depend on the internals of the queue structure; in
213 macros will be supported in future implementations.
214 .\" The old structure will probably be retained for compatibility
215 .\" under a different name.
217 .Ss The ifnet structure
222 .Bl -tag -width "if_poll_slowq" -offset indent
225 A pointer to the driver's private state block. (Initialized by
229 The name of the interface, not including the unit number
234 (Initialized by driver.)
236 .Pq Li "TAILQ_ENTRY(ifnet)"
240 .Pq Li "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 Li "struct bpf_if *"
253 Opaque per-interface data for the packet filter,
259 A unique number assigned to each interface in sequence as it is
260 attached. This number can be used in a
261 .Li "struct sockaddr_dl"
262 to refer to a particular interface by index
267 A unique number assigned to each interface managed by a particular
268 driver, usually related to the unit number of a physical device in the
269 kernel configuration file
272 (Initialized by driver.)
275 Number of seconds until the watchdog timer
277 is called, or zero if the timer is disabled. (Set by driver,
278 decremented by generic watchdog code.)
281 Flags describing operational parameters of this interface (see below).
282 (Manipulated by both driver and generic code.)
283 .\" .It Li "if_ipending"
284 .\" Interrupt-pending bits for polled operation:
286 .\" (transmit complete interrupt)
289 .\" (received packet ready interrupt). See the
291 .\" section, below. (Manipulated by driver.)
294 A pointer to an interface-specific MIB structure exported by
296 (Initialized by driver.)
297 .It Li "if_linkmiblen"
299 The size of said structure. (Initialized by driver.)
301 .Pq Li "struct if_data"
302 More statistics and information; see
303 .Dq Sx "The if_data structure" ,
304 below. (Initialized by driver, manipulated by both driver and generic
307 .Pq Li "struct ifqueue"
308 The output queue. (Manipulated by driver.)
309 .\".It Li "if_poll_slowq"
310 .\".Pq Li "struct ifqueue *"
311 .\"A pointer to the input queue for devices which do not support polling
314 .\"section, below. (Initialized by driver.)
317 There are in addition a number of function pointers which the driver
318 must initialize to complete its interface with the generic interface
320 .Bl -ohang -offset indent
322 Output a packet on interface
324 or queue it on the output queue if the interface is already active.
326 Start queued output on an interface. This function is exposed in
327 order to provide for some interface classes to share a
331 may only be called when the
333 flag is not set. (Thus,
335 does not literally mean that output is active, but rather that the
336 device's internal output queue is full.)
338 Not used. We're not even sure what it was ever for.
339 The prototype is faked.
341 Process interface-related
345 .Aq Pa sys/sockio.h ) .
346 Preliminary processing is done by the generic routine
348 to check for appropriate privileges, locate the interface being
349 manipulated, and perform certain generic operations like twiddling
350 flags and flushing queues. See the description of
352 below for more information.
354 Routine called by the generic code when the watchdog timer,
356 expires. Usually this will reset the interface.
357 .\" .It Fn if_poll_recv
358 .\" .It Fn if_poll_xmit
359 .\" .It Fn if_poll_slowinput
360 .\" .It Fn if_poll_intren
365 Initialize and bring up the hardware,
366 e.g. reset the chip and the watchdog timer and enable the receiver unit.
367 Should mark the interface running,
369 .Dv ( IFF_RUNNING , ~IIF_OACTIVE ) .
370 .It Fn if_resolvemulti
371 Check the requested multicast group membership,
373 for validity, and if necessary compute a link-layer group which
374 corresponds to that address which is returned in
376 Returns zero on success, or an error code on failure.
378 .Ss "Interface flags"
379 Interface flags are used for a number of different purposes. Some
380 flags simply indicate information about the type of interface and its
381 capabilities; others are dynamically manipulated to reflect the
382 current state of the interface. Flags of the former kind are marked
384 in this table; the latter are marked
387 .Bl -tag -width "IFF_POINTOPOINT" -compact -offset indent
390 The interface has been configured up by the user-level code.
393 The interface supports broadcast.
396 Used to enable/disable driver debugging code.
399 The interface is a loopback device.
400 .It Dv IFF_POINTOPOINT
402 The interface is point-to-point;
404 addresses are actually the address of the other end.
407 The interface has been configured and dynamic resources were
408 successfully allocated. Probably only useful internal to the
412 Disable network address resolution on this interface.
415 This interface is in promiscuous mode.
418 This interface is in all-multicasts mode (used by multicast routers).
421 The interface's hardware output queue (if any) is full; output packets
425 The interface cannot hear its own transmissions.
430 Control flags for the link layer. (Currently abused to select among
431 multiple physical layers on some devices.)
434 This interface supports multicast.
439 defines the bits which cannot be set by a user program using the
443 these are indicated by an asterisk in the listing above.
444 .Ss The if_data structure
447 a subset of the interface information believed to be of interest to
448 management stations was segregated from the
450 structure and moved into its own
452 structure to facilitate its use by user programs. The following
455 structure are initialized by the interface and are not expected to change
456 significantly over the course of normal operation:
457 .Bl -tag -width "ifi_lastchange" -offset indent
460 The type of the interface, as defined in
461 .Aq Pa net/if_types.h
462 and described below in the
463 .Dq Sx "Interface types"
467 Intended to represent a selection of physical layers on devices which
468 support more than one; never implemented.
471 Length of a link-layer address on this device, or zero if there are
472 none. Used to initialized the address length field in
474 structures referring to this interface.
477 Maximum length of any link-layer header which might be prepended by
478 the driver to a packet before transmission. The generic code computes
479 the maximum over all interfaces and uses that value to influence the
482 to attempt to ensure that there is always
483 sufficient space to prepend a link-layer header without allocating an
488 .\" .It Li ifi_recvquota
490 .\" Number of packets the interface is permitted to receive at one time
491 .\" when in polled mode.
492 .\" .It Li ifi_xmitquota
494 .\" Number of packets the interface is permitted to queue for transmission
495 .\" at one time when in polled mode. There is some controversy over
496 .\" whether such a restriction makes any sense at all.
499 The maximum transmission unit of the medium, exclusive of any
503 A dimensionless metric interpreted by a user-mode routing process.
506 The line rate of the interface, in bits per second.
509 The structure additionally contains generic statistics applicable to a
510 variety of different interface types (except as noted, all members are
513 .Bl -tag -width "ifi_lastchange" -offset indent
515 Number of packets received.
517 Number of receive errors detected (e.g., FCS errors, DMA overruns,
518 etc.). More detailed breakdowns can often be had by way of a
521 Number of packets transmitted.
523 Number of output errors detected (e.g., late collisions, DMA overruns,
524 etc.). More detailed breakdowns can often be had by way of a
526 .It Li ifi_collisions
527 Total number of collisions detected on output for CSMA interfaces.
528 (This member is sometimes [ab]used by other types of interfaces for
529 other output error counts.)
531 Total traffic received, in bytes.
533 Total traffic transmitted, in bytes.
535 Number of packets received which were sent by link-layer multicast.
537 Number of packets sent by link-layer multicast.
539 Number of packets dropped on input. Rarely implemented.
541 Number of packets received for unknown network-layer protocol.
542 .\" .It Li ifi_recvtiming
543 .\" Amount of time, in microseconds, spent to receive an average packet on
544 .\" this interface. See the
547 .\" .It Li ifi_xmittiming
548 .\" Amount of time, in microseconds, spent to service a transmit-complete
549 .\" interrupt on this interface. See the
552 .It Li ifi_lastchange
553 .Pq Li "struct timeval"
554 The time of the last administrative change to the interface (as required
560 .Aq Pa net/if_types.h
561 defines symbolic constants for a number of different types of
562 interfaces. The most common are:
564 .Bl -tag -compact -offset indent -width IFT_PROPVIRTUAL
566 none of the following
574 ISO 8802-5 Token Ring
580 Internet Point-to-Point Protocol
592 Asynchronous Transfer Mode
594 .Ss The ifaddr structure
595 Every interface is associated with a list
598 of addresses, rooted at the interface structure's
600 member. The first element in this list is always an
602 address representing the interface itself; multi-access network
603 drivers should complete this structure by filling in their link-layer
604 addresses after calling
606 Other members of the structure represent network-layer addresses which
607 have been configured by means of the
611 called on a socket of the appropriate protocol family.
612 The elements of this list consist of
614 structures. Most protocols will declare their own protocol-specific
615 interface address structures, but all begin with a
617 which provides the most-commonly-needed functionality across all
618 protocols. Interface addresses are reference-counted.
623 .Bl -tag -width ifa_rtrequest -offset indent
625 .Pq Li "struct sockaddr *"
626 The local address of the interface.
628 .Pq Li "struct sockaddr *"
629 The remote address of point-to-point interfaces, and the broadcast
630 address of broadcast interfaces.
635 .Pq Li "struct sockaddr *"
636 The network mask for multi-access interfaces, and the confusion
637 generator for point-to-point interfaces.
639 .Pq Li "struct ifnet *"
640 A link back to the interface structure.
642 .Pq Li TAILQ_ENTRY(ifaddr)
644 glue for list of addresses on each interface.
649 Some of the flags which would be used for a route representing this
650 address in the route table.
656 A metric associated with this interface address, for the use of some
657 external routing protocol.
662 structures are gained manually, by incrementing the
664 member. References are released by calling either the
671 is a pointer to a function which receives callouts from the routing
674 to perform link-layer-specific actions upon requests to add, resolve,
675 or delete routes. The
677 argument indicates the request in question:
684 argument is the route in question; the
686 argument is the specific destination being manipulated
689 or a null pointer otherwise.
691 The functions provided by the generic interface code can be divided
692 into two groups: those which manipulate interfaces, and those which
693 manipulate interface addresses. In addition to these functions, there
694 may also be link-layer support routines which are used by a number of
695 drivers implementing a specific link layer over different hardware;
696 see the documentation for that link layer for more details.
697 .Ss The ifmultiaddr structure
698 Every multicast-capable interface is associated with a list of
699 multicast group memberships, which indicate at a low level which
700 link-layer multicast addresses (if any) should be accepted, and at a
701 high level, in which network-layer multicast groups a user process has
704 The elements of the structure are as follows:
705 .Bl -tag -width ifma_refcount -offset indent
707 .Pq Li LIST_ENTRY(ifmultiaddr)
711 .Pq Li "struct sockaddr *"
712 A pointer to the address which this record represents. The
713 memberships for various address families are stored in arbitrary
716 .Pq Li "struct sockaddr *"
717 A pointer to the link-layer multicast address, if any, to which the
718 network-layer multicast address in
720 is mapped, else a null pointer. If this element is non-nil, this
721 membership also holds an invisible reference to another membership for
722 that link-layer address.
725 A reference count of requests for this particular membership.
727 .Ss Interface manipulation functions
728 .Bl -ohang -offset indent
730 Link the specified interface
732 into the list of network interfaces. Also initialize the list of
733 addresses on that interface, and create a link-layer
735 structure to be the first element in that list. (A pointer to
736 this address structure is saved in the global array
744 flush its output queue, notify protocols of the transition,
745 and generate a message from the
751 as up, notify protocols of the transition,
752 and generate a message from the
756 Add or remove a promiscuous reference to
760 is true, add a reference;
761 if it is false, remove a reference. On reference count transitions
762 from zero to one and one to zero, set the
764 flag appropriately and call
766 to set up the interface in the desired mode.
770 but for the all-multicasts
772 flag instead of the promiscuous flag.
776 pointer for the interface named
779 Process the ioctl request
787 This is the main routine for handling all interface configuration
788 requests from user mode.
789 It is ordinarily only called from the socket-layer
791 handler, and only for commands with class
793 Any unrecognized commands will be passed down to socket
796 further interpretation. The following commands are handled by
799 .Bl -tag -width OSIOCGIFNETMASK -compact -offset indent
802 Get interface configuration. (No call-down to driver.)
807 Get interface flags, metric, MTU, medium selection. (No call-down to
811 Change interface flags. Caller must have appropriate privilege. If
812 requested a change to the IFF_UP flag is requested,
816 is called as appropriate. Flags listed in
818 are masked off, and the driver
820 routine is called to perform any setup
824 Change interface metric or medium. Caller must have appropriate privilege.
827 Change interface MTU. Caller must have appropriate privilege. MTU
828 values less than 72 or greater than 65535 are considered invalid. The
831 routine is called to implement the change; it is responsible for any
832 additional sanity checking and for actually modifying the MTU in the
836 Add or delete permanent multicast group memberships on the interface.
837 Caller must have appropriate privilege. The
841 function is called to perform the operation; qq.v.
842 .It Dv SIOCSIFDSTADDR
844 .It Dv SIOCSIFBRDADDR
845 .It Dv SIOCSIFNETMASK
846 The socket's protocol control routine is called to implement the
849 .It Dv OSIOCGIFDSTADDR
850 .It Dv OSIOCGIFBRDADDR
851 .It Dv OSIOCGIFNETMASK
852 The socket's protocol control routine is called to implement the
853 requested action. On return,
855 structures are converted into old-style (no
869 .Ss "Interface address functions"
870 Several functions exist to look up an interface address structure
873 returns an interface address with either a local address or a
874 broadcast address precisely matching the parameter
876 .Fn ifa_ifwithdstaddr
877 returns an interface address for a point-to-point interface whose
878 remote (``destination'') address is
882 returns the most specific interface address which matches the
885 subject to its configured netmask, or a point-to-point interface
886 address whose remote address is
891 returns the most specific address configured on interface
893 which matches address
895 subject to its configured netmask. If the interface is
896 point-to-point, only an interface address whose remote address is
901 All of these functions return a null pointer if no such address can be
903 .Ss "Interface multicast address functions"
908 .Fn ifmaof_ifpforaddr
909 functions provide support for requesting and relinquishing multicast
910 group memberships, and for querying an interface's membership list,
913 function takes a pointer to an interface,
915 and a generic address,
917 It also takes a pointer to a
918 .Sq Li "struct ifmultiaddr *"
919 which is filled in on successful return with the address of the
920 group membership control block. The
922 function performs the following four-step process:
923 .Bl -enum -offset indent
927 entry point to determine the link-layer address, if any, corresponding
928 to this membership request, and also to give the link layer an
929 opportunity to veto this membership request should it so desire.
931 Check the interface's group membership list for a pre-existing
932 membership for this group. If one is not found, allocate a new one;
933 if one is, increment its reference count.
937 routine returned a link-layer address corresponding to the group,
938 repeat the previous step for that address as well.
940 If the interface's multicast address filter needs to be changed
941 because a new membership was added, call the interface's
948 to request that it do so.
953 function, given an interface
957 reverses this process. Both functions return zero on success, or a
958 standard error number on failure.
961 .Fn ifmaof_ifpforaddr
962 function examines the membership list of interface
964 for an address matching
966 and returns a pointer to that
967 .Li "struct ifmultiaddr"
968 if one is found, else it returns a null pointer.
986 .%A W. Richard Stevens
987 .%B TCP/IP Illustrated
989 .%O Addison-Wesley, ISBN 0-201-63354-X
992 This manual page was written by
993 .An Garrett A. Wollman .