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