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