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