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