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$ 30.\" 31.Dd April 26, 2013 32.Dt IFNET 9 33.Os 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/param.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 "struct ifnet *" 50.Fn if_alloc "u_char type" 51.Ft void 52.Fn if_attach "struct ifnet *ifp" 53.Ft void 54.Fn if_detach "struct ifnet *ifp" 55.Ft void 56.Fn if_free "struct ifnet *ifp" 57.Ft void 58.Fn if_free_type "struct ifnet *ifp" "u_char type" 59.Ft void 60.Fn if_down "struct ifnet *ifp" 61.Ft int 62.Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" 63.Ft int 64.Fn ifpromisc "struct ifnet *ifp" "int pswitch" 65.Ft int 66.Fn if_allmulti "struct ifnet *ifp" "int amswitch" 67.Ft "struct ifnet *" 68.Fn ifunit "const char *name" 69.Ft "struct ifnet *" 70.Fn ifunit_ref "const char *name" 71.Ft void 72.Fn if_up "struct ifnet *ifp" 73.\" 74.Ss "Interface Address Functions" 75.Ft "struct ifaddr *" 76.Fn ifaddr_byindex "u_short idx" 77.Ft "struct ifaddr *" 78.Fn ifa_ifwithaddr "struct sockaddr *addr" 79.Ft "struct ifaddr *" 80.Fn ifa_ifwithdstaddr "struct sockaddr *addr" 81.Ft "struct ifaddr *" 82.Fn ifa_ifwithnet "struct sockaddr *addr" "int ignore_ptp" 83.Ft "struct ifaddr *" 84.Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" 85.Ft void 86.Fn ifa_ref "struct ifaddr *ifa" 87.Ft void 88.Fn ifa_free "struct ifaddr *ifa" 89.\" 90.Ss "Interface Multicast Address Functions" 91.Ft int 92.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" 93.Ft int 94.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" 95.Ft "struct ifmultiaddr *" 96.Fn if_findmulti "struct ifnet *ifp" "struct sockaddr *sa" 97.Ss "Output queue macros" 98.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" 99.\" 100.Ss "struct ifnet Member Functions" 101.Ft void 102.Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m" 103.Ft int 104.Fo \*(lp*if_output\*(rp 105.Fa "struct ifnet *ifp" "struct mbuf *m" 106.Fa "const struct sockaddr *dst" "struct route *ro" 107.Fc 108.Ft void 109.Fn \*(lp*if_start\*(rp "struct ifnet *ifp" 110.Ft int 111.Fn \*(lp*if_transmit\*(rp "struct ifnet *ifp" "struct mbuf *m" 112.Ft void 113.Fn \*(lp*if_qflush\*(rp "struct ifnet *ifp" 114.Ft int 115.Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "u_long cmd" "caddr_t data" 116.Ft void 117.Fn \*(lp*if_init\*(rp "void *if_softc" 118.Ft int 119.Fo \*(lp*if_resolvemulti\*(rp 120.Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" 121.Fc 122.Ss "struct ifaddr member function" 123.Ft void 124.Fo \*(lp*ifa_rtrequest\*(rp 125.Fa "int cmd" "struct rtentry *rt" "struct rt_addrinfo *info" 126.Fc 127.\" 128.Ss "Global Variables" 129.Vt extern struct ifnethead ifnet ; 130.\" extern struct ifindex_entry *ifindex_table ; 131.Vt extern int if_index ; 132.Vt extern int ifqmaxlen ; 133.Sh DATA STRUCTURES 134The kernel mechanisms for handling network interfaces reside primarily 135in the 136.Vt ifnet , if_data , ifaddr , 137and 138.Vt ifmultiaddr 139structures in 140.In net/if.h 141and 142.In net/if_var.h 143and the functions named above and defined in 144.Pa /sys/net/if.c . 145Those interfaces which are intended to be used by user programs 146are defined in 147.In net/if.h ; 148these include the interface flags, the 149.Vt if_data 150structure, and the structures defining the appearance of 151interface-related messages on the 152.Xr route 4 153routing socket and in 154.Xr sysctl 3 . 155The header file 156.In net/if_var.h 157defines the kernel-internal interfaces, including the 158.Vt ifnet , ifaddr , 159and 160.Vt ifmultiaddr 161structures and the functions which manipulate them. 162(A few user programs will need 163.In net/if_var.h 164because it is the prerequisite of some other header file like 165.In netinet/if_ether.h . 166Most references to those two files in particular can be replaced by 167.In net/ethernet.h . ) 168.Pp 169The system keeps a linked list of interfaces using the 170.Li TAILQ 171macros defined in 172.Xr queue 3 ; 173this list is headed by a 174.Vt "struct ifnethead" 175called 176.Va ifnet . 177The elements of this list are of type 178.Vt "struct ifnet" , 179and most kernel routines which manipulate interface as such accept or 180return pointers to these structures. 181Each interface structure 182contains an 183.Vt if_data 184structure used for statistics and information. 185Each interface also has a 186.Li TAILQ 187of interface addresses, described by 188.Vt ifaddr 189structures. 190An 191.Dv AF_LINK 192address 193(see 194.Xr link_addr 3 ) 195describing the link layer implemented by the interface (if any) 196is accessed by the 197.Fn ifaddr_byindex 198function or 199.Va if_addr 200structure. 201(Some trivial interfaces do not provide any link layer addresses; 202this structure, while still present, serves only to identify the 203interface name and index.) 204.Pp 205Finally, those interfaces supporting reception of multicast datagrams 206have a 207.Li TAILQ 208of multicast group memberships, described by 209.Vt ifmultiaddr 210structures. 211These memberships are reference-counted. 212.Pp 213Interfaces are also associated with an output queue, defined as a 214.Vt "struct ifqueue" ; 215this structure is used to hold packets while the interface is in the 216process of sending another. 217.Pp 218.Ss The Vt ifnet Ss structure 219The fields of 220.Vt "struct ifnet" 221are as follows: 222.Bl -tag -width ".Va if_capabilities" -offset indent 223.It Va if_softc 224.Pq Vt "void *" 225A pointer to the driver's private state block. 226(Initialized by driver.) 227.It Va if_l2com 228.Pq Vt "void *" 229A pointer to the common data for the interface's layer 2 protocol. 230(Initialized by 231.Fn if_alloc . ) 232.It Va if_vnet 233.Pq Vt "struct vnet *" 234A pointer to the virtual network stack instance. 235(Initialized by 236.Fn if_attach . ) 237.It Va if_home_vnet 238.Pq Vt "struct vnet *" 239A pointer to the parent virtual network stack, where this 240.Vt "struct ifnet" 241originates from. 242(Initialized by 243.Fn if_attach . ) 244.It Va if_link 245.Pq Fn TAILQ_ENTRY ifnet 246.Xr queue 3 247macro glue. 248.It Va if_xname 249.Pq Vt "char *" 250The name of the interface, 251(e.g., 252.Dq Li fxp0 253or 254.Dq Li lo0 ) . 255(Initialized by driver 256(usually via 257.Fn if_initname ) . ) 258.It Va if_dname 259.Pq Vt "const char *" 260The name of the driver. 261(Initialized by driver 262(usually via 263.Fn if_initname ) . ) 264.It Va if_dunit 265.Pq Vt int 266A unique number assigned to each interface managed by a particular 267driver. 268Drivers may choose to set this to 269.Dv IF_DUNIT_NONE 270if a unit number is not associated with the device. 271(Initialized by driver 272(usually via 273.Fn if_initname ) . ) 274.It Va if_refcount 275.Pq Vt u_int 276The reference count. 277(Initialized by 278.Fn if_alloc . ) 279.It Va if_addrhead 280.Pq Vt "struct ifaddrhead" 281The head of the 282.Xr queue 3 283.Li TAILQ 284containing the list of addresses assigned to this interface. 285.It Va if_pcount 286.Pq Vt int 287A count of promiscuous listeners on this interface, used to 288reference-count the 289.Dv IFF_PROMISC 290flag. 291.It Va if_carp 292.Pq Vt "struct carp_if *" 293A pointer to the CARP interface structure, 294.Xr carp 4 . 295(Initialized by the driver-specific 296.Fn if_ioctl 297routine.) 298.It Va if_bpf 299.Pq Vt "struct bpf_if *" 300Opaque per-interface data for the packet filter, 301.Xr bpf 4 . 302(Initialized by 303.Fn bpf_attach . ) 304.It Va if_index 305.Pq Vt u_short 306A unique number assigned to each interface in sequence as it is 307attached. 308This number can be used in a 309.Vt "struct sockaddr_dl" 310to refer to a particular interface by index 311(see 312.Xr link_addr 3 ) . 313(Initialized by 314.Fn if_alloc . ) 315.It Va if_vlantrunk 316.Pq Vt struct ifvlantrunk * 317A pointer to 802.1Q trunk structure, 318.Xr vlan 4 . 319(Initialized by the driver-specific 320.Fn if_ioctl 321routine.) 322.It Va if_flags 323.Pq Vt int 324Flags describing operational parameters of this interface (see below). 325(Manipulated by generic code.) 326.It Va if_drv_flags 327.Pq Vt int 328Flags describing operational status of this interface (see below). 329(Manipulated by driver.) 330.It Va if_capabilities 331.Pq Vt int 332Flags describing the capabilities the interface supports (see below). 333.It Va if_capenable 334.Pq Vt int 335Flags describing the enabled capabilities of the interface (see below). 336.It Va if_linkmib 337.Pq Vt "void *" 338A pointer to an interface-specific MIB structure exported by 339.Xr ifmib 4 . 340(Initialized by driver.) 341.It Va if_linkmiblen 342.Pq Vt size_t 343The size of said structure. 344(Initialized by driver.) 345.It Va if_data 346.Pq Vt "struct if_data" 347More statistics and information; see 348.Sx "The if_data structure" , 349below. 350(Initialized by driver, manipulated by both driver and generic 351code.) 352.It Va if_multiaddrs 353.Pq Vt struct ifmultihead 354The head of the 355.Xr queue 3 356.Li TAILQ 357containing the list of multicast addresses assigned to this interface. 358.It Va if_amcount 359.Pq Vt int 360A number of multicast requests on this interface, used to 361reference-count the 362.Dv IFF_ALLMULTI 363flag. 364.It Va if_addr 365.Pq Vt "struct ifaddr *" 366A pointer to the link-level interface address. 367(Initialized by 368.Fn if_alloc . ) 369.\" .It Va if_llsoftc 370.\" .Pq Vt "void *" 371.\" The purpose of the field is unclear. 372.It Va if_snd 373.Pq Vt "struct ifaltq" 374The output queue. 375(Manipulated by driver.) 376.It Va if_broadcastaddr 377.Pq Vt "const u_int8_t *" 378A link-level broadcast bytestring for protocols with variable address 379length. 380.It Va if_bridge 381.Pq Vt "void *" 382A pointer to the bridge interface structure, 383.Xr if_bridge 4 . 384(Initialized by the driver-specific 385.Fn if_ioctl 386routine.) 387.It Va if_label 388.Pq Vt "struct label *" 389A pointer to the MAC Framework label structure, 390.Xr mac 4 . 391(Initialized by 392.Fn if_alloc . ) 393.It Va if_afdata 394.Pq Vt "void *" 395An address family dependent data region. 396.It Va if_afdata_initialized 397.Pq Vt int 398Used to track the current state of address family initialization. 399.It Va if_afdata_lock 400.Pq Vt "struct rwlock" 401An 402.Xr rwlock 9 403lock used to protect 404.Va if_afdata 405internals. 406.It Va if_linktask 407.Pq Vt "struct task" 408A 409.Xr taskqueue 9 410task scheduled for link state change events of the interface. 411.It Va if_addr_lock 412.Pq Vt "struct rwlock" 413An 414.Xr rwlock 9 415lock used to protect interface-related address lists. 416.It Va if_clones 417.Pq Fn LIST_ENTRY ifnet 418.Xr queue 3 419macro glue for the list of clonable network interfaces. 420.It Va if_groups 421.Pq Fn TAILQ_HEAD ", ifg_list" 422The head of the 423.Xr queue 3 424.Li TAILQ 425containing the list of groups per interface. 426.It Va if_pf_kif 427.Pq Vt "void *" 428A pointer to the structure used for interface abstraction by 429.Xr pf 4 . 430.It Va if_lagg 431.Pq Vt "void *" 432A pointer to the 433.Xr lagg 4 434interface structure. 435.It Va if_alloctype 436.Pq Vt u_char 437The type of the interface as it was at the time of its allocation. 438It is used to cache the type passed to 439.Fn if_alloc , 440but unlike 441.Va if_type , 442it would not be changed by drivers. 443.El 444.Pp 445References to 446.Vt ifnet 447structures are gained by calling the 448.Fn if_ref 449function and released by calling the 450.Fn if_rele 451function. 452They are used to allow kernel code walking global interface lists 453to release the 454.Vt ifnet 455lock yet keep the 456.Vt ifnet 457structure stable. 458.Pp 459There are in addition a number of function pointers which the driver 460must initialize to complete its interface with the generic interface 461layer: 462.Bl -ohang -offset indent 463.It Fn if_input 464Pass a packet to an appropriate upper layer as determined 465from the link-layer header of the packet. 466This routine is to be called from an interrupt handler or 467used to emulate reception of a packet on this interface. 468A single function implementing 469.Fn if_input 470can be shared among multiple drivers utilizing the same link-layer 471framing, e.g., Ethernet. 472.It Fn if_output 473Output a packet on interface 474.Fa ifp , 475or queue it on the output queue if the interface is already active. 476.It Fn if_transmit 477Transmit a packet on an interface or queue it if the interface is 478in use. 479This function will return 480.Dv ENOBUFS 481if the devices software and hardware queues are both full. 482This function must be installed after 483.Fn if_attach 484to override the default implementation. 485This function is exposed in order to allow drivers to manage their own queues 486and to reduce the latency caused by a frequently gratuitous enqueue / dequeue 487pair to ifq. 488The suggested internal software queueing mechanism is buf_ring. 489.It Fn if_qflush 490Free mbufs in internally managed queues when the interface is marked down. 491This function must be installed after 492.Fn if_attach 493to override the default implementation. 494This function is exposed in order to allow drivers to manage their own queues 495and to reduce the latency caused by a frequently gratuitous enqueue / dequeue 496pair to ifq. 497The suggested internal software queueing mechanism is buf_ring. 498.It Fn if_start 499Start queued output on an interface. 500This function is exposed in 501order to provide for some interface classes to share a 502.Fn if_output 503among all drivers. 504.Fn if_start 505may only be called when the 506.Dv IFF_DRV_OACTIVE 507flag is not set. 508(Thus, 509.Dv IFF_DRV_OACTIVE 510does not literally mean that output is active, but rather that the 511device's internal output queue is full.) Please note that this function 512will soon be deprecated. 513.It Fn if_ioctl 514Process interface-related 515.Xr ioctl 2 516requests 517(defined in 518.In sys/sockio.h ) . 519Preliminary processing is done by the generic routine 520.Fn ifioctl 521to check for appropriate privileges, locate the interface being 522manipulated, and perform certain generic operations like twiddling 523flags and flushing queues. 524See the description of 525.Fn ifioctl 526below for more information. 527.It Fn if_init 528Initialize and bring up the hardware, 529e.g., reset the chip and enable the receiver unit. 530Should mark the interface running, 531but not active 532.Dv ( IFF_DRV_RUNNING , ~IIF_DRV_OACTIVE ) . 533.It Fn if_resolvemulti 534Check the requested multicast group membership, 535.Fa addr , 536for validity, and if necessary compute a link-layer group which 537corresponds to that address which is returned in 538.Fa *retsa . 539Returns zero on success, or an error code on failure. 540.El 541.Ss "Interface Flags" 542Interface flags are used for a number of different purposes. 543Some 544flags simply indicate information about the type of interface and its 545capabilities; others are dynamically manipulated to reflect the 546current state of the interface. 547Flags of the former kind are marked 548.Aq S 549in this table; the latter are marked 550.Aq D . 551Flags which begin with 552.Dq IFF_DRV_ 553are stored in 554.Va if_drv_flags ; 555all other flags are stored in 556.Va if_flags . 557.Pp 558The macro 559.Dv IFF_CANTCHANGE 560defines the bits which cannot be set by a user program using the 561.Dv SIOCSIFFLAGS 562command to 563.Xr ioctl 2 ; 564these are indicated by an asterisk 565.Pq Ql * 566in the following listing. 567.Pp 568.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact 569.It Dv IFF_UP 570.Aq D 571The interface has been configured up by the user-level code. 572.It Dv IFF_BROADCAST 573.Aq S* 574The interface supports broadcast. 575.It Dv IFF_DEBUG 576.Aq D 577Used to enable/disable driver debugging code. 578.It Dv IFF_LOOPBACK 579.Aq S 580The interface is a loopback device. 581.It Dv IFF_POINTOPOINT 582.Aq S* 583The interface is point-to-point; 584.Dq broadcast 585address is actually the address of the other end. 586.It Dv IFF_SMART 587.Aq S* 588The interface manages its own routes, rather than using the generic 589code in 590.Fn if_up 591and 592.Fn if_down . 593This is probably useful for serial lines. 594.It Dv IFF_DRV_RUNNING 595.Aq D* 596The interface has been configured and dynamic resources were 597successfully allocated. 598Probably only useful internal to the 599interface. 600.It Dv IFF_NOARP 601.Aq D 602Disable network address resolution on this interface. 603.It Dv IFF_PROMISC 604.Aq D* 605This interface is in promiscuous mode. 606.It Dv IFF_PPROMISC 607.Aq D 608This interface is in the permanently promiscuous mode (implies 609.Dv IFF_PROMISC ) . 610.It Dv IFF_ALLMULTI 611.Aq D* 612This interface is in all-multicasts mode (used by multicast routers). 613.It Dv IFF_DRV_OACTIVE 614.Aq D* 615The interface's hardware output queue (if any) is full; output packets 616are to be queued. 617.It Dv IFF_SIMPLEX 618.Aq S* 619The interface cannot hear its own transmissions. 620.It Dv IFF_LINK0 621.It Dv IFF_LINK1 622.It Dv IFF_LINK2 623.Aq D 624Control flags for the link layer. 625(Currently abused to select among 626multiple physical layers on some devices.) 627.It Dv IFF_MULTICAST 628.Aq S* 629This interface supports multicast. 630.It Dv IFF_CANTCONFIG 631.Aq S* 632The interface is not configurable in a meaningful way. 633Primarily useful for 634.Dv IFT_USB 635interfaces registered at the interface list. 636.It Dv IFF_MONITOR 637.Aq D 638This interface blocks transmission of packets and discards incoming 639packets after BPF processing. 640Used to monitor network traffic but not interact 641with the network in question. 642.It Dv IFF_STATICARP 643.Aq D 644Used to enable/disable ARP requests on this interface. 645.It Dv IFF_DYING 646.Aq D* 647Set when the 648.Vt ifnet 649structure of this interface is being released and still has 650.Va if_refcount 651references. 652.It Dv IFF_RENAMING 653.Aq D* 654Set when this interface is being renamed. 655.El 656.Ss "Interface Capabilities Flags" 657Interface capabilities are specialized features an interface may 658or may not support. 659These capabilities are very hardware-specific 660and allow, when enabled, 661to offload specific network processing to the interface 662or to offer a particular feature for use by other kernel parts. 663.Pp 664It should be stressed that a capability can be completely 665uncontrolled (i.e., stay always enabled with no way to disable it) 666or allow limited control over itself (e.g., depend on another 667capability's state.) 668Such peculiarities are determined solely by the hardware and driver 669of a particular interface. 670Only the driver possesses 671the knowledge on whether and how the interface capabilities 672can be controlled. 673Consequently, capabilities flags in 674.Va if_capenable 675should never be modified directly by kernel code other than 676the interface driver. 677The command 678.Dv SIOCSIFCAP 679to 680.Fn ifioctl 681is the dedicated means to attempt altering 682.Va if_capenable 683on an interface. 684Userland code shall use 685.Xr ioctl 2 . 686.Pp 687The following capabilities are currently supported by the system: 688.Bl -tag -width ".Dv IFCAP_POLLING_NOCOUNT" -offset indent 689.It Dv IFCAP_RXCSUM 690This interface can do checksum validation on receiving data. 691Some interfaces do not have sufficient buffer storage to store frames 692above a certain MTU-size completely. 693The driver for the interface might disable hardware checksum validation 694if the MTU is set above the hardcoded limit. 695.It Dv IFCAP_TXCSUM 696This interface can do checksum calculation on transmitting data. 697.It Dv IFCAP_HWCSUM 698A shorthand for 699.Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . 700.It Dv IFCAP_NETCONS 701This interface can be a network console. 702.It Dv IFCAP_VLAN_MTU 703The 704.Xr vlan 4 705driver can operate over this interface in software tagging mode 706without having to decrease MTU on 707.Xr vlan 4 708interfaces below 1500 bytes. 709This implies the ability of this interface to cope with frames somewhat 710longer than permitted by the Ethernet specification. 711.It Dv IFCAP_VLAN_HWTAGGING 712This interface can do VLAN tagging on output and 713demultiplex frames by their VLAN tag on input. 714.It Dv IFCAP_JUMBO_MTU 715This Ethernet interface can transmit and receive frames up to 7169000 bytes long. 717.It Dv IFCAP_POLLING 718This interface supports 719.Xr polling 4 . 720See below for details. 721.It Dv IFCAP_VLAN_HWCSUM 722This interface can do checksum calculation on both transmitting 723and receiving data on 724.Xr vlan 4 725interfaces (implies 726.Dv IFCAP_HWCSUM ) . 727.It Dv IFCAP_TSO4 728This Ethernet interface supports TCP4 Segmentation offloading. 729.It Dv IFCAP_TSO6 730This Ethernet interface supports TCP6 Segmentation offloading. 731.It Dv IFCAP_TSO 732A shorthand for 733.Pq Dv IFCAP_TSO4 | IFCAP_TSO6 . 734.It Dv IFCAP_TOE4 735This Ethernet interface supports TCP offloading. 736.It Dv IFCAP_TOE6 737This Ethernet interface supports TCP6 offloading. 738.It Dv IFCAP_TOE 739A shorthand for 740.Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . 741.It Dv IFCAP_WOL_UCAST 742This Ethernet interface supports waking up on any Unicast packet. 743.It Dv IFCAP_WOL_MCAST 744This Ethernet interface supports waking up on any Multicast packet. 745.It Dv IFCAP_WOL_MAGIC 746This Ethernet interface supports waking up on any Magic packet such 747as those sent by 748.Xr wake 8 . 749.It Dv IFCAP_WOL 750A shorthand for 751.Pq Dv IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC . 752.It Dv IFCAP_TOE4 753This Ethernet interface supports TCP4 Offload Engine. 754.It Dv IFCAP_TOE6 755This Ethernet interface supports TCP6 Offload Engine. 756.It Dv IFCAP_TOE 757A shorthand for 758.Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . 759.It Dv IFCAP_VLAN_HWFILTER 760This interface supports frame filtering in hardware on 761.Xr vlan 4 762interfaces. 763.It Dv IFCAP_POLLING_NOCOUNT 764The return value for the number of processed packets should be 765skipped for this interface. 766.It Dv IFCAP_VLAN_HWTSO 767This interface supports TCP Segmentation offloading on 768.Xr vlan 4 769interfaces (implies 770.Dv IFCAP_TSO ) . 771.It Dv IFCAP_LINKSTATE 772This Ethernet interface supports dynamic link state changes. 773.El 774.Pp 775The ability of advanced network interfaces to offload certain 776computational tasks from the host CPU to the board is limited 777mostly to TCP/IP. 778Therefore a separate field associated with an interface 779(see 780.Va ifnet.if_data.ifi_hwassist 781below) 782keeps a detailed description of its enabled capabilities 783specific to TCP/IP processing. 784The TCP/IP module consults the field to see which tasks 785can be done on an 786.Em outgoing 787packet by the interface. 788The flags defined for that field are a superset of those for 789.Va mbuf.m_pkthdr.csum_flags , 790namely: 791.Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent 792.It Dv CSUM_IP 793The interface will compute IP checksums. 794.It Dv CSUM_TCP 795The interface will compute TCP checksums. 796.It Dv CSUM_UDP 797The interface will compute UDP checksums. 798.It Dv CSUM_IP_FRAGS 799The interface can compute a TCP or UDP checksum for a packet 800fragmented by the host CPU. 801Makes sense only along with 802.Dv CSUM_TCP 803or 804.Dv CSUM_UDP . 805.It Dv CSUM_FRAGMENT 806The interface will do the fragmentation of IP packets if necessary. 807The host CPU does not need to care about MTU on this interface 808as long as a packet to transmit through it is an IP one and it 809does not exceed the size of the hardware buffer. 810.El 811.Pp 812An interface notifies the TCP/IP module about the tasks 813the former has performed on an 814.Em incoming 815packet by setting the corresponding flags in the field 816.Va mbuf.m_pkthdr.csum_flags 817of the 818.Vt mbuf chain 819containing the packet. 820See 821.Xr mbuf 9 822for details. 823.Pp 824The capability of a network interface to operate in 825.Xr polling 4 826mode involves several flags in different 827global variables and per-interface fields. 828The capability flag 829.Dv IFCAP_POLLING 830set in interface's 831.Va if_capabilities 832indicates support for 833.Xr polling 4 834on the particular interface. 835If set in 836.Va if_capabilities , 837the same flag can be marked or cleared in the interface's 838.Va if_capenable 839within 840.Fn ifioctl , 841thus initiating switch of the interface to 842.Xr polling 4 843mode or interrupt 844mode, respectively. 845The actual mode change is managed by the driver-specific 846.Fn if_ioctl 847routine. 848The 849.Xr polling 850handler returns the number of packets processed. 851.Ss The Vt if_data Ss Structure 852The 853.Vt if_data 854structure contains statistics and identifying information used 855by management programs, and which is exported to user programs by way 856of the 857.Xr ifmib 4 858branch of the 859.Xr sysctl 3 860MIB. 861The following elements of the 862.Vt if_data 863structure are initialized by the interface and are not expected to change 864significantly over the course of normal operation: 865.Bl -tag -width ".Va ifi_lastchange" -offset indent 866.It Va ifi_type 867.Pq Vt u_char 868The type of the interface, as defined in 869.In net/if_types.h 870and described below in the 871.Sx "Interface Types" 872section. 873.It Va ifi_physical 874.Pq Vt u_char 875Intended to represent a selection of physical layers on devices which 876support more than one; never implemented. 877.It Va ifi_addrlen 878.Pq Vt u_char 879Length of a link-layer address on this device, or zero if there are 880none. 881Used to initialized the address length field in 882.Vt sockaddr_dl 883structures referring to this interface. 884.It Va ifi_hdrlen 885.Pq Vt u_char 886Maximum length of any link-layer header which might be prepended by 887the driver to a packet before transmission. 888The generic code computes 889the maximum over all interfaces and uses that value to influence the 890placement of data in 891.Vt mbuf Ns s 892to attempt to ensure that there is always 893sufficient space to prepend a link-layer header without allocating an 894additional 895.Vt mbuf . 896.It Va ifi_datalen 897.Pq Vt u_char 898Length of the 899.Vt if_data 900structure. 901Allows some stabilization of the routing socket ABI in the face of 902increases in the length of 903.Vt struct ifdata . 904.It Va ifi_mtu 905.Pq Vt u_long 906The maximum transmission unit of the medium, exclusive of any 907link-layer overhead. 908.It Va ifi_metric 909.Pq Vt u_long 910A dimensionless metric interpreted by a user-mode routing process. 911.It Va ifi_baudrate 912.Pq Vt u_long 913The line rate of the interface, in bits per second. 914.It Va ifi_hwassist 915.Pq Vt u_long 916A detailed interpretation of the capabilities 917to offload computational tasks for 918.Em outgoing 919packets. 920The interface driver must keep this field in accord with 921the current value of 922.Va if_capenable . 923.It Va ifi_epoch 924.Pq Vt time_t 925The system uptime when interface was attached or the statistics 926below were reset. 927This is intended to be used to set the SNMP variable 928.Va ifCounterDiscontinuityTime . 929It may also be used to determine if two successive queries for an 930interface of the same index have returned results for the same 931interface. 932.El 933.Pp 934The structure additionally contains generic statistics applicable to a 935variety of different interface types (except as noted, all members are 936of type 937.Vt u_long ) : 938.Bl -tag -width ".Va ifi_lastchange" -offset indent 939.It Va ifi_link_state 940.Pq Vt u_char 941The current link state of Ethernet interfaces. 942See the 943.Sx Interface Link States 944section for possible values. 945.It Va ifi_ipackets 946Number of packets received. 947.It Va ifi_ierrors 948Number of receive errors detected (e.g., FCS errors, DMA overruns, 949etc.). 950More detailed breakdowns can often be had by way of a 951link-specific MIB. 952.It Va ifi_opackets 953Number of packets transmitted. 954.It Va ifi_oerrors 955Number of output errors detected (e.g., late collisions, DMA overruns, 956etc.). 957More detailed breakdowns can often be had by way of a 958link-specific MIB. 959.It Va ifi_collisions 960Total number of collisions detected on output for CSMA interfaces. 961(This member is sometimes [ab]used by other types of interfaces for 962other output error counts.) 963.It Va ifi_ibytes 964Total traffic received, in bytes. 965.It Va ifi_obytes 966Total traffic transmitted, in bytes. 967.It Va ifi_imcasts 968Number of packets received which were sent by link-layer multicast. 969.It Va ifi_omcasts 970Number of packets sent by link-layer multicast. 971.It Va ifi_iqdrops 972Number of packets dropped on input. 973Rarely implemented. 974.It Va ifi_noproto 975Number of packets received for unknown network-layer protocol. 976.It Va ifi_lastchange 977.Pq Vt "struct timeval" 978The time of the last administrative change to the interface (as required 979for 980.Tn SNMP ) . 981.El 982.Ss Interface Types 983The header file 984.In net/if_types.h 985defines symbolic constants for a number of different types of 986interfaces. 987The most common are: 988.Pp 989.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact 990.It Dv IFT_OTHER 991none of the following 992.It Dv IFT_ETHER 993Ethernet 994.It Dv IFT_ISO88023 995ISO 8802-3 CSMA/CD 996.It Dv IFT_ISO88024 997ISO 8802-4 Token Bus 998.It Dv IFT_ISO88025 999ISO 8802-5 Token Ring 1000.It Dv IFT_ISO88026 1001ISO 8802-6 DQDB MAN 1002.It Dv IFT_FDDI 1003FDDI 1004.It Dv IFT_PPP 1005Internet Point-to-Point Protocol 1006.Pq Xr ppp 8 1007.It Dv IFT_LOOP 1008The loopback 1009.Pq Xr lo 4 1010interface 1011.It Dv IFT_SLIP 1012Serial Line IP 1013.It Dv IFT_PARA 1014Parallel-port IP 1015.Pq Dq Tn PLIP 1016.It Dv IFT_ATM 1017Asynchronous Transfer Mode 1018.It Dv IFT_USB 1019USB Interface 1020.El 1021.Ss Interface Link States 1022The following link states are currently defined: 1023.Pp 1024.Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact 1025.It Dv LINK_STATE_UNKNOWN 1026The link is in an invalid or unknown state. 1027.It Dv LINK_STATE_DOWN 1028The link is down. 1029.It Dv LINK_STATE_UP 1030The link is up. 1031.El 1032.Ss The Vt ifaddr Ss Structure 1033Every interface is associated with a list 1034(or, rather, a 1035.Li TAILQ ) 1036of addresses, rooted at the interface structure's 1037.Va if_addrlist 1038member. 1039The first element in this list is always an 1040.Dv AF_LINK 1041address representing the interface itself; multi-access network 1042drivers should complete this structure by filling in their link-layer 1043addresses after calling 1044.Fn if_attach . 1045Other members of the structure represent network-layer addresses which 1046have been configured by means of the 1047.Dv SIOCAIFADDR 1048command to 1049.Xr ioctl 2 , 1050called on a socket of the appropriate protocol family. 1051The elements of this list consist of 1052.Vt ifaddr 1053structures. 1054Most protocols will declare their own protocol-specific 1055interface address structures, but all begin with a 1056.Vt "struct ifaddr" 1057which provides the most-commonly-needed functionality across all 1058protocols. 1059Interface addresses are reference-counted. 1060.Pp 1061The members of 1062.Vt "struct ifaddr" 1063are as follows: 1064.Bl -tag -width ".Va ifa_rtrequest" -offset indent 1065.It Va ifa_addr 1066.Pq Vt "struct sockaddr *" 1067The local address of the interface. 1068.It Va ifa_dstaddr 1069.Pq Vt "struct sockaddr *" 1070The remote address of point-to-point interfaces, and the broadcast 1071address of broadcast interfaces. 1072.Va ( ifa_broadaddr 1073is a macro for 1074.Va ifa_dstaddr . ) 1075.It Va ifa_netmask 1076.Pq Vt "struct sockaddr *" 1077The network mask for multi-access interfaces, and the confusion 1078generator for point-to-point interfaces. 1079.It Va ifa_ifp 1080.Pq Vt "struct ifnet *" 1081A link back to the interface structure. 1082.It Va ifa_link 1083.Pq Fn TAILQ_ENTRY ifaddr 1084.Xr queue 3 1085glue for list of addresses on each interface. 1086.It Va ifa_rtrequest 1087See below. 1088.It Va ifa_flags 1089.Pq Vt u_short 1090Some of the flags which would be used for a route representing this 1091address in the route table. 1092.It Va ifa_refcnt 1093.Pq Vt short 1094The reference count. 1095.It Va ifa_metric 1096.Pq Vt int 1097A metric associated with this interface address, for the use of some 1098external routing protocol. 1099.El 1100.Pp 1101References to 1102.Vt ifaddr 1103structures are gained by calling the 1104.Fn ifa_ref 1105function and released by calling the 1106.Fn ifa_free 1107function. 1108.Pp 1109.Fn ifa_rtrequest 1110is a pointer to a function which receives callouts from the routing 1111code 1112.Pq Fn rtrequest 1113to perform link-layer-specific actions upon requests to add, 1114or delete routes. 1115The 1116.Fa cmd 1117argument indicates the request in question: 1118.Dv RTM_ADD , 1119or 1120.Dv RTM_DELETE . 1121The 1122.Fa rt 1123argument is the route in question; the 1124.Fa info 1125argument contains the specific destination being manipulated. 1126.Sh FUNCTIONS 1127The functions provided by the generic interface code can be divided 1128into two groups: those which manipulate interfaces, and those which 1129manipulate interface addresses. 1130In addition to these functions, there 1131may also be link-layer support routines which are used by a number of 1132drivers implementing a specific link layer over different hardware; 1133see the documentation for that link layer for more details. 1134.Ss The Vt ifmultiaddr Ss Structure 1135Every multicast-capable interface is associated with a list of 1136multicast group memberships, which indicate at a low level which 1137link-layer multicast addresses (if any) should be accepted, and at a 1138high level, in which network-layer multicast groups a user process has 1139expressed interest. 1140.Pp 1141The elements of the structure are as follows: 1142.Bl -tag -width ".Va ifma_refcount" -offset indent 1143.It Va ifma_link 1144.Pq Fn LIST_ENTRY ifmultiaddr 1145.Xr queue 3 1146macro glue. 1147.It Va ifma_addr 1148.Pq Vt "struct sockaddr *" 1149A pointer to the address which this record represents. 1150The 1151memberships for various address families are stored in arbitrary 1152order. 1153.It Va ifma_lladdr 1154.Pq Vt "struct sockaddr *" 1155A pointer to the link-layer multicast address, if any, to which the 1156network-layer multicast address in 1157.Va ifma_addr 1158is mapped, else a null pointer. 1159If this element is non-nil, this 1160membership also holds an invisible reference to another membership for 1161that link-layer address. 1162.It Va ifma_refcount 1163.Pq Vt u_int 1164A reference count of requests for this particular membership. 1165.El 1166.Ss Interface Manipulation Functions 1167.Bl -ohang -offset indent 1168.It Fn if_alloc 1169Allocate and initialize 1170.Vt "struct ifnet" . 1171Initialization includes the allocation of an interface index and may 1172include the allocation of a 1173.Fa type 1174specific structure in 1175.Va if_l2com . 1176.It Fn if_attach 1177Link the specified interface 1178.Fa ifp 1179into the list of network interfaces. 1180Also initialize the list of 1181addresses on that interface, and create a link-layer 1182.Vt ifaddr 1183structure to be the first element in that list. 1184(A pointer to 1185this address structure is saved in the 1186.Vt ifnet 1187structure and shall be accessed by the 1188.Fn ifaddr_byindex 1189function.) 1190The 1191.Fa ifp 1192must have been allocated by 1193.Fn if_alloc . 1194.It Fn if_detach 1195Shut down and unlink the specified 1196.Fa ifp 1197from the interface list. 1198.It Fn if_free 1199Free the given 1200.Fa ifp 1201back to the system. 1202The interface must have been previously detached if it was ever attached. 1203.It Fn if_free_type 1204Identical to 1205.Fn if_free 1206except that the given 1207.Fa type 1208is used to free 1209.Va if_l2com 1210instead of the type in 1211.Va if_type . 1212This is intended for use with drivers that change their interface type. 1213.It Fn if_down 1214Mark the interface 1215.Fa ifp 1216as down (i.e., 1217.Dv IFF_UP 1218is not set), 1219flush its output queue, notify protocols of the transition, 1220and generate a message from the 1221.Xr route 4 1222routing socket. 1223.It Fn if_up 1224Mark the interface 1225.Fa ifp 1226as up, notify protocols of the transition, 1227and generate a message from the 1228.Xr route 4 1229routing socket. 1230.It Fn ifpromisc 1231Add or remove a promiscuous reference to 1232.Fa ifp . 1233If 1234.Fa pswitch 1235is true, add a reference; 1236if it is false, remove a reference. 1237On reference count transitions 1238from zero to one and one to zero, set the 1239.Dv IFF_PROMISC 1240flag appropriately and call 1241.Fn if_ioctl 1242to set up the interface in the desired mode. 1243.It Fn if_allmulti 1244As 1245.Fn ifpromisc , 1246but for the all-multicasts 1247.Pq Dv IFF_ALLMULTI 1248flag instead of the promiscuous flag. 1249.It Fn ifunit 1250Return an 1251.Vt ifnet 1252pointer for the interface named 1253.Fa name . 1254.It Fn ifunit_ref 1255Return a reference-counted (via 1256.Fn ifa_ref ) 1257.Vt ifnet 1258pointer for the interface named 1259.Fa name . 1260This is the preferred function over 1261.Fn ifunit . 1262The caller is responsible for releasing the reference with 1263.Fn if_rele 1264when it is finished with the ifnet. 1265.It Fn ifioctl 1266Process the ioctl request 1267.Fa cmd , 1268issued on socket 1269.Fa so 1270by thread 1271.Fa td , 1272with data parameter 1273.Fa data . 1274This is the main routine for handling all interface configuration 1275requests from user mode. 1276It is ordinarily only called from the socket-layer 1277.Xr ioctl 2 1278handler, and only for commands with class 1279.Sq Li i . 1280Any unrecognized commands will be passed down to socket 1281.Fa so Ns 's 1282protocol for 1283further interpretation. 1284The following commands are handled by 1285.Fn ifioctl : 1286.Pp 1287.Bl -tag -width ".Dv OSIOCGIFNETMASK" -offset indent -compact 1288.It Dv SIOCGIFCONF 1289.It Dv OSIOCGIFCONF 1290Get interface configuration. 1291(No call-down to driver.) 1292.Pp 1293.It Dv SIOCSIFNAME 1294Set the interface name. 1295.Dv RTM_IFANNOUNCE 1296departure and arrival messages are sent so that 1297routing code that relies on the interface name will update its interface 1298list. 1299Caller must have appropriate privilege. 1300(No call-down to driver.) 1301.It Dv SIOCGIFCAP 1302.It Dv SIOCGIFFIB 1303.It Dv SIOCGIFFLAGS 1304.It Dv SIOCGIFMETRIC 1305.It Dv SIOCGIFMTU 1306.It Dv SIOCGIFPHYS 1307Get interface capabilities, FIB, flags, metric, MTU, medium selection. 1308(No call-down to driver.) 1309.Pp 1310.It Dv SIOCSIFCAP 1311Enable or disable interface capabilities. 1312Caller must have appropriate privilege. 1313Before a call to the driver-specific 1314.Fn if_ioctl 1315routine, the requested mask for enabled capabilities is checked 1316against the mask of capabilities supported by the interface, 1317.Va if_capabilities . 1318Requesting to enable an unsupported capability is invalid. 1319The rest is supposed to be done by the driver, 1320which includes updating 1321.Va if_capenable 1322and 1323.Va if_data.ifi_hwassist 1324appropriately. 1325.Pp 1326.It Dv SIOCSIFFIB 1327Sets interface FIB. 1328Caller must have appropriate privilege. 1329FIB values start at 0 and values greater or equals than 1330.Va net.fibs 1331are considered invalid. 1332.It Dv SIOCSIFFLAGS 1333Change interface flags. 1334Caller must have appropriate privilege. 1335If a change to the 1336.Dv IFF_UP 1337flag is requested, 1338.Fn if_up 1339or 1340.Fn if_down 1341is called as appropriate. 1342Flags listed in 1343.Dv IFF_CANTCHANGE 1344are masked off, and the field 1345.Va if_flags 1346in the interface structure is updated. 1347Finally, the driver 1348.Fn if_ioctl 1349routine is called to perform any setup 1350requested. 1351.Pp 1352.It Dv SIOCSIFMETRIC 1353.It Dv SIOCSIFPHYS 1354Change interface metric or medium. 1355Caller must have appropriate privilege. 1356.Pp 1357.It Dv SIOCSIFMTU 1358Change interface MTU. 1359Caller must have appropriate privilege. 1360MTU 1361values less than 72 or greater than 65535 are considered invalid. 1362The driver 1363.Fn if_ioctl 1364routine is called to implement the change; it is responsible for any 1365additional sanity checking and for actually modifying the MTU in the 1366interface structure. 1367.Pp 1368.It Dv SIOCADDMULTI 1369.It Dv SIOCDELMULTI 1370Add or delete permanent multicast group memberships on the interface. 1371Caller must have appropriate privilege. 1372The 1373.Fn if_addmulti 1374or 1375.Fn if_delmulti 1376function is called to perform the operation; qq.v. 1377.Pp 1378.It Dv SIOCAIFADDR 1379.It Dv SIOCDIFADDR 1380The socket's protocol control routine is called to implement the 1381requested action. 1382.Pp 1383.It Dv OSIOCGIFADDR 1384.It Dv OSIOCGIFDSTADDR 1385.It Dv OSIOCGIFBRDADDR 1386.It Dv OSIOCGIFNETMASK 1387The socket's protocol control routine is called to implement the 1388requested action. 1389On return, 1390.Vt sockaddr 1391structures are converted into old-style (no 1392.Va sa_len 1393member). 1394.El 1395.El 1396.Pp 1397.Fn if_down , 1398.Fn ifioctl , 1399.Fn ifpromisc , 1400and 1401.Fn if_up 1402must be called at 1403.Fn splnet 1404or higher. 1405.Ss "Interface Address Functions" 1406Several functions exist to look up an interface address structure 1407given an address. 1408.Fn ifa_ifwithaddr 1409returns an interface address with either a local address or a 1410broadcast address precisely matching the parameter 1411.Fa addr . 1412.Fn ifa_ifwithdstaddr 1413returns an interface address for a point-to-point interface whose 1414remote 1415.Pq Dq destination 1416address is 1417.Fa addr . 1418.Pp 1419.Fn ifa_ifwithnet 1420returns the most specific interface address which matches the 1421specified address, 1422.Fa addr , 1423subject to its configured netmask, or a point-to-point interface 1424address whose remote address is 1425.Fa addr 1426if one is found. 1427If 1428.Fa ignore_ptp 1429is true, skip point-to-point interface addresses. 1430.Pp 1431.Fn ifaof_ifpforaddr 1432returns the most specific address configured on interface 1433.Fa ifp 1434which matches address 1435.Fa addr , 1436subject to its configured netmask. 1437If the interface is 1438point-to-point, only an interface address whose remote address is 1439precisely 1440.Fa addr 1441will be returned. 1442.Pp 1443.Fn ifaddr_byindex 1444returns the link-level address of the interface with the given index 1445.Fa idx . 1446.Pp 1447All of these functions return a null pointer if no such address can be 1448found. 1449.Ss "Interface Multicast Address Functions" 1450The 1451.Fn if_addmulti , 1452.Fn if_delmulti , 1453and 1454.Fn if_findmulti 1455functions provide support for requesting and relinquishing multicast 1456group memberships, and for querying an interface's membership list, 1457respectively. 1458The 1459.Fn if_addmulti 1460function takes a pointer to an interface, 1461.Fa ifp , 1462and a generic address, 1463.Fa sa . 1464It also takes a pointer to a 1465.Vt "struct ifmultiaddr *" 1466which is filled in on successful return with the address of the 1467group membership control block. 1468The 1469.Fn if_addmulti 1470function performs the following four-step process: 1471.Bl -enum -offset indent 1472.It 1473Call the interface's 1474.Fn if_resolvemulti 1475entry point to determine the link-layer address, if any, corresponding 1476to this membership request, and also to give the link layer an 1477opportunity to veto this membership request should it so desire. 1478.It 1479Check the interface's group membership list for a pre-existing 1480membership for this group. 1481If one is not found, allocate a new one; 1482if one is, increment its reference count. 1483.It 1484If the 1485.Fn if_resolvemulti 1486routine returned a link-layer address corresponding to the group, 1487repeat the previous step for that address as well. 1488.It 1489If the interface's multicast address filter needs to be changed 1490because a new membership was added, call the interface's 1491.Fn if_ioctl 1492routine 1493(with a 1494.Fa cmd 1495argument of 1496.Dv SIOCADDMULTI ) 1497to request that it do so. 1498.El 1499.Pp 1500The 1501.Fn if_delmulti 1502function, given an interface 1503.Fa ifp 1504and an address, 1505.Fa sa , 1506reverses this process. 1507Both functions return zero on success, or a 1508standard error number on failure. 1509.Pp 1510The 1511.Fn if_findmulti 1512function examines the membership list of interface 1513.Fa ifp 1514for an address matching 1515.Fa sa , 1516and returns a pointer to that 1517.Vt "struct ifmultiaddr" 1518if one is found, else it returns a null pointer. 1519.Sh SEE ALSO 1520.Xr ioctl 2 , 1521.Xr link_addr 3 , 1522.Xr queue 3 , 1523.Xr sysctl 3 , 1524.Xr bpf 4 , 1525.Xr ifmib 4 , 1526.Xr lo 4 , 1527.Xr netintro 4 , 1528.Xr polling 4 , 1529.Xr config 8 , 1530.Xr ppp 8 , 1531.Xr mbuf 9 , 1532.Xr rtentry 9 1533.Rs 1534.%A Gary R. Wright 1535.%A W. Richard Stevens 1536.%B TCP/IP Illustrated 1537.%V Vol. 2 1538.%O Addison-Wesley, ISBN 0-201-63354-X 1539.Re 1540.Sh AUTHORS 1541This manual page was written by 1542.An Garrett A. Wollman . 1543