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