+++ /dev/null
-.\" Copyright (c) 2007-2009 Bruce Simpson.
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\" $FreeBSD: src/lib/libc/net/sourcefilter.3,v 1.2 2009/03/04 01:59:14 bms Exp $
-.\"
-.Dd February 13, 2009
-.Dt SOURCEFILTER 3
-.Os
-.Sh NAME
-.Nm sourcefilter
-.Nd advanced multicast group membership API
-.Sh SYNOPSIS
-.In sys/socket.h
-.In netinet/in.h
-.Ft int
-.Fo getipv4sourcefilter
-.Fa "int s"
-.Fa "struct in_addr interface"
-.Fa "struct in_addr group"
-.Fa "uint32_t *fmode"
-.Fa "uint32_t *numsrc"
-.Fa "struct in_addr *slist"
-.Fc
-.Ft int
-.Fo getsourcefilter
-.Fa "int s"
-.Fa "uint32_t interface"
-.Fa "struct sockaddr *group"
-.Fa "socklen_t grouplen"
-.Fa "uint32_t *fmode"
-.Fa "uint32_t *numsrc"
-.Fa "struct sockaddr_storage *slist"
-.Fc
-.Ft int
-.Fo setipv4sourcefilter
-.Fa "int s"
-.Fa "struct in_addr interface"
-.Fa "struct in_addr group"
-.Fa "uint32_t fmode"
-.Fa "uint32_t numsrc"
-.Fa "struct in_addr *slist"
-.Fc
-.Ft int
-.Fo setsourcefilter
-.Fa "int s"
-.Fa "uint32_t interface"
-.Fa "struct sockaddr *group"
-.Fa "socklen_t grouplen"
-.Fa "uint32_t fmode"
-.Fa "uint32_t numsrc"
-.Fa "struct sockaddr_storage *slist"
-.Fc
-.Sh DESCRIPTION
-The
-.Nm
-functions implement the advanced, full-state multicast API
-defined in RFC 3678.
-An application may use these functions to atomically set and
-retrieve the multicast source address filters associated with a socket
-.Fa s
-and a multicast
-.Fa group .
-.Pp
-The functions
-.Fn getipv4sourcefilter
-and
-.Fn getsourcefilter
-allow an application to discover the filter mode, and
-source filter entries,
-for an existing group membership.
-.Pp
-The kernel will always return the number of source filter
-entries on the socket for that group in
-.Fa *numsrc .
-If the
-.Fa *numsrc
-argument is non-zero, the kernel will attempt to return up to
-.Fa *numsrc
-filter entries in the array pointed to by
-.Fa slist .
-The
-.Fa *numsrc
-argument may be set to 0, in which case the
-.Fa slist
-argument will be ignored.
-.Pp
-For the
-.Fn setipv4sourcefilter
-and
-.Fn setsourcefilter
-functions,
-the
-.Fa fmode
-argument may be used to place the socket into inclusive or exclusive
-group membership modes, by using the
-.Dv MCAST_INCLUDE
-or
-.Dv MCAST_EXCLUDE
-constants respectively.
-The
-.Fa numsrc
-argument specifies the number of source entries in the
-.Fa slist
-array.
-If the
-.Fa numsrc
-argument has a value of 0,
-all source filters will be removed from the socket.
-Removing all source filters from a membership which is in the
-.Dv MCAST_INCLUDE
-filter mode will cause the group to be left on that socket.
-.Pp
-The protocol-independent function
-.Fn setsourcefilter
-allows an application to join a multicast group on an interface
-which may not have an assigned protocol address,
-by passing its index for the
-.Fa interface
-argument.
-.Pp
-Any changes made by these functions
-will be communicated to IGMPv3 and/or MLDv2 routers
-on the local network as appropriate.
-If no IGMPv3 or MLDv2 routers are present, changes in the source filter
-lists made by these functions will not cause
-state changes to be transmitted, with the exception of any
-change which causes a group to be joined or left.
-The kernel will continue to maintain the source filter state
-regardless of the IGMP or MLD version in use on the link.
-.Sh IMPLEMENTATION NOTES
-The IPv4 specific versions of these functions are implemented in terms
-of the protocol-independent functions.
-Application writers are encouraged to use the protocol-independent functions
-for efficiency, and forwards compatibility with IPv6 networks.
-.Pp
-For the protocol-independent functions
-.Fn getsourcefilter
-and
-.Fn setsourcefilter ,
-the argument
-.Fa grouplen
-argument specifies the size of the structure pointed to by
-.Fa group .
-This is required in order to differentiate between different
-address families.
-.Pp
-Currently
-.Fx
-does not support source address selection for the IPv4
-protocol family, therefore the use of multicast APIs with
-an unnumbered IPv4 interface is
-.Em not recommended.
-In all cases, the first assigned IPv4 address on the interface
-will be used as the source address of IGMP control traffic.
-If this address is removed or changed, the results are undefined.
-.Sh RETURN VALUES
-.Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter
-.Sh ERRORS
-The
-.Nm
-functions may fail because of:
-.Bl -tag -width Er
-.It Bq Er EADDRNOTAVAIL
-The network interface which the
-.Dv interface
-argument refers to was not configured in the system,
-or the system is not a member of the
-.Dv group .
-.It Bq Er EAFNOSUPPORT
-The
-.Dv group
-and/or one or more of the
-.Dv slist
-arguments were of an address family unsupported by the system,
-or the address family of the
-.Dv group
-and
-.Dv slist
-arguments were not identical.
-.It Bq Er EINVAL
-The
-.Dv group
-argument does not contain a multicast address.
-The
-.Dv fmode
-argument is invalid; it must be set to either
-.Dv MCAST_INCLUDE
-or
-.Dv MCAST_EXCLUDE .
-The
-.Dv numsrc
-or
-.Dv slist
-arguments do not specify a source list.
-.It Bq Er ENOMEM
-Insufficient memory was available to carry out the requested
-operation.
-.El
-.Sh SEE ALSO
-.Xr ip 4 ,
-.Xr ip6 4
-.Rs
-.%A D. Thaler
-.%A B. Fenner
-.%A B. Quinn
-.%T "Socket Interface Extensions for Multicast Source Filters"
-.%N RFC 3678
-.%D Jan 2004
-.Re
-.Sh HISTORY
-The
-.Nm
-functions first appeared in
-.Fx 7.0 .
-.Sh AUTHORS
-Bruce M. Simpson
-.Aq bms@FreeBSD.org
projects / apple / libc.git / blobdiff