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