.\" Copyright (c) 2007 Bruce M. 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.
.\"
.\" 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$
.\"
.Dd June 12, 2007
.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 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 .
.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.
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:
.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 ,
.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