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