share/man/man9/ifnet.9

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