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