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.
THIS SOFTWARE IS PROVIDED BY Bruce M. Simpson ``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 Bruce M. Simpson 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: head/lib/libc/net/sourcefilter.3 170620 2007-06-12 18:03:37Z bms $
.Dd June 12, 2007 .Dt SOURCEFILTER 3 .Os .Sh NAME .Nm sourcefilter .Nd advanced multicast group membership API .Sh SYNOPSIS n sys/socket.h n 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 .
p The protocol-independent functions .Fn getsourcefilter and .Fn setsourcefilter allow an application to join a multicast group on an interface by passing its index for the .Fa interface argument. The argument. .Fa grouplen argument specifies the size of the structure pointed to by .Fa group .
p 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. A value of 0 will remove all source filters from the socket. The changes will be communicated to IGMPv3 and/or MLDv2 routers on the local network as appropriate. .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 upwards compatibility with IPv6 networks. .Sh RETURN VALUES .Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter .Sh ERRORS The .Nm functions may fail because of: l -tag -width Er t 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 . t 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. t 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. t Bq Er ENOMEM Insufficient memory was available to carry out the requested operation. .El .Sh SEE ALSO .Xr ip 4 , .Xr ip6 4 , .Xr multicast 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