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