From eceb838819cb07665698f5213485b338d0a79323 Mon Sep 17 00:00:00 2001 From: wollman Date: Wed, 15 Jan 1997 19:28:39 +0000 Subject: [PATCH] Document Monday's changes in the interface structure. --- share/man/man9/ifnet.9 | 180 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 169 insertions(+), 11 deletions(-) diff --git a/share/man/man9/ifnet.9 b/share/man/man9/ifnet.9 index f89633fc13c1..4cb089bbc85c 100644 --- a/share/man/man9/ifnet.9 +++ b/share/man/man9/ifnet.9 @@ -1,5 +1,5 @@ -.\" -.\" Copyright 1996 Massachusetts Institute of Technology +.\" -*- Nroff -*- +.\" Copyright 1996, 1997 Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software and .\" its documentation for any purpose and without fee is hereby @@ -26,9 +26,9 @@ .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.Dd December 16, 1996 -.Os FreeBSD 2.2 +.\" $Id: ifnet.9,v 1.3 1996/12/26 16:16:37 wosch Exp $ +.Dd January 15, 1997 +.Os FreeBSD 3.0 .Dt IFNET 9 .Sh NAME .Nm ifnet , @@ -41,6 +41,7 @@ .Fd #include .Fd #include .Fd #include +.Fd #include .Fd #include .\" .Ss "Interface manipulation functions" @@ -52,6 +53,8 @@ .Fn ifioctl "struct socket *so" "int cmd" "caddr_t data" "struct proc *p" .Ft int .Fn ifpromisc "struct ifnet *ifp" "int pswitch" +.Ft int +.Fn if_allmulti "struct ifnet *ifp" "int amswitch" .Ft "struct ifnet *" .Fn ifunit "char *name" .Ft void @@ -71,6 +74,13 @@ .Ft void \"macro .Fn IFAFREE "struct ifaddr *ifa" .\" +.Ss "Interface multicast address functions" +.Ft int +.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" +.Ft int +.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" +.Ft "struct ifmultiaddr *" +.Fn ifmaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" .Ss "Output queue macros" .Ft void \"macro .Fn IF_ENQ_DROP "struct ifqueue *ifq" "struct mbuf *m" @@ -98,6 +108,8 @@ .Fn (*if_poll_slowinput) "struct ifnet *ifp" "struct mbuf *m" .Ft void .Fn (*if_init) "void *wtf_is_this" +.Ft int +.Fn (*if_resolvemulti) "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" .Ss "struct ifaddr member function" .Ft void .Fn (*ifa_rtrequest) "int cmd" "struct rtentry *rt" "struct sockaddr *dst" @@ -111,12 +123,40 @@ The kernel mechanisms for handling network interfaces reside primarily in the .Li ifnet , .Li if_data , +.Li ifaddr , and -.Li ifaddr +.Li ifmultiaddr structures in -.Aq Pa net/if.h , +.Aq Pa net/if.h +and +.Aq Pa net/if_var.h and the functions named above and defined in .Pa /sys/net/if.c . +Those interfaces which are intended to be used by user programs +are defined in +.Aq Pa net/if.h ; +these include the interface flags, the +.Li if_data +structure, and the structures defining the appearance of +interface-related messages on the +.Xr route 4 +routing socket and in +.Xr sysctl 3 . +The header file +.Aq Pa net/if_var.h +defines the kernel-internal interfaces, including the +.Li ifnet , +.Li ifaddr , +and +.Li ifmultiaddr +structures and the functions which manipulate them. +(A few user programs will need +.Aq Pa net/if_var.h +because it is the prerequisite of some other header file like +.Aq Pa netinet/if_ether.h . +Most references to those two files in particular can be replaced by +.Aq Pa net/ethernet.h . ) +.Pp The system keeps a linked list of interfaces using the .Li TAILQ macros defined in @@ -152,6 +192,13 @@ describing the link layer implemented by the interface (if any). this structure, while still present, serves only to identify the interface name and index.) .Pp +Finally, those interfaces supporting reception of multicast datagrams +have a +.Li LIST +of multicast group memberships, described by +.Li ifmultiaddr +structures. These memberships are reference-counted. +.Pp Interfaces are also associated with an output queue, defined as a .Li "struct ifqueue" ; this structure is used to hold packets while the interface is in the @@ -315,6 +362,13 @@ expires. Usually this will reset the interface. .\" section, below. .It Fn if_init XXX fill me in +.It Fn if_resolvemulti +Check the requested multicast group membership, +.Ar addr , +for validity, and if necessary compute a link-layer group which +corresponds to that address which is returned in +.Ar \&*retsa . +Returns zero on success, or an error code on failure. .El .Ss "Interface flags" Interface flags are used for a number of different purposes. Some @@ -637,6 +691,36 @@ manipulate interface addresses. In addition to these functions, there may also be link-layer support routines which are used by a number of drivers implementing a specific link layer over different hardware; see the documentation for that link layer for more details. +.Ss The ifmultiaddr structure +Every multicast-capable interface is associated with a list of +multicast group memberships, which indicate at a low level which +link-layer multicast addresses (if any) should be accepted, and at a +high level, in which network-layer multicast groups a user process has +expressed interest. +.Pp +The elements of the structure are as follows: +.Bl -tag -width ifma_refcount -offset indent +.It Li ifma_link +.Pq Li LIST_ENTRY(ifmultiaddr) +.Xr queue 3 +macro glue. +.It Li ifma_addr +.Pq Li "struct sockaddr *" +A pointer to the address which this record represents. The +memberships for various address families are stored in arbitrary +order. +.It Li ifma_lladdr +.Pq Li "struct sockaddr *" +A pointer to the link-layer multicast address, if any, to which the +network-layter multicast address in +.Li ifma_addr +is mapped, else a null pointer. If this element is non-nil, this +membership also holds an invisible reference to another membership for +that link-layer address. +.It Li ifma_refcount +.Pq Li u_int +A reference count of requests for this particular membership. +.El .Ss Interface manipulation functions .Bl -ohang -offset indent .It Fn if_attach @@ -675,6 +759,12 @@ from zero to one and one to zero, set the flag appropriately and call .Fn if_ioctl to set up the interface in the desired mode. +.It Fn if_allmulti +As +.Fn ifpromisc , +but for the all-multicasts +.Pq Dv IFF_ALLMULTI +flag instead of the promiscuous flag. .It Fn ifunit Return an .Li ifnet @@ -739,9 +829,11 @@ interface structure. .It Dv SIOCADDMULTI .It Dv SIOCDELMULTI Add or delete permanent multicast group memberships on the interface. -Caller must have appropriate privilege. The driver -.Fn if_ioctl -routine is called to perform the requested action. +Caller must have appropriate privilege. The +.Fn if_addmulti +or +.Fn if_delmulti +function is called to perform the operation; qq.v. .It Dv SIOCSIFDSTADDR .It Dv SIOCSIFADDR .It Dv SIOCSIFBRDADDR @@ -802,6 +894,72 @@ will be returned. .Pp All of these functions return a null pointer if no such address can be found. +.Ss "Interface multicast address functions" +The +.Fn if_addmulti , +.Fn if_delmulti , +and +.Fn ifmaof_ifpforaddr +functions provide support for requesting and relinquishing multicast +group memberships, and for querying an interface's membership list, +respectively. The +.Fn if_addmulti +function takes a pointer to an interface, +.Ar ifp , +and a generic address, +.Ar sa . +It also takes a pointer to a +.Sq Li "struct ifmultiaddr *" +which is filled in on successful return with the address of the +group membership control block. The +.Fn if_addmulti +function performs the following four-step process: +.Bl -enum -offset indent +.It +Call the interface's +.Fn if_resolvemulti +entry point to determine the link-layer address, if any, corresponding +to this membership request, and also to give the link layer an +opportunity to veto this membership request should it so desire. +.It +Check the interface's group membership list for a pre-existing +membership for this group. If one is not found, allocate a new one; +if one is, increment its reference count. +.It +If the +.Fn if_resolvemulti +routine returned a link-layer address corresponding to the group, +repeat the previous step for that address as well. +.It +If the interface's multicast address filter needs to be changed +because a new membership was added, call the interface's +.Fn if_ioctl +routine +(with a +.Ar cmd +argument of +.Dv SIOCADDMULTI ) +to request that it do so. +.El +.Pp +The +.Fn if_delmulti +function, given an interface +.Ar ifp +and an address, +.Ar sa , +reverses this process. Both functions return zero on success, or a +standard error number on failure. +.Pp +The +.Fn ifmaof_ifpforaddr +function examines the membership list of interface +.Ar ifp +for an address matching +.Ar addr , +and returns a pointer to that +.Li "struct ifmultiaddr" +if one is found, else it returns a null pointer. .\" .Sh POLLING .\" XXX write me! .Sh SEE ALSO @@ -824,4 +982,4 @@ found. .%O Addison-Wesley, ISBN 0-201-63354-X .Re .Sh AUTHOR -This manual page was written by Garrett A. Wollman +This manual page was written by Garrett A. Wollman.