Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SOURCEFILTER(3)	       FreeBSD Library Functions Manual	       SOURCEFILTER(3)

NAME
     sourcefilter -- advanced multicast	group membership API

SYNOPSIS
     #include <sys/socket.h>
     #include <netinet/in.h>

     int
     getipv4sourcefilter(int s,	struct in_addr interface,
	 struct	in_addr	group, uint32_t	*fmode,	uint32_t *numsrc,
	 struct	in_addr	*slist);

     int
     getsourcefilter(int s, uint32_t interface,	struct sockaddr	*group,
	 socklen_t grouplen, uint32_t *fmode, uint32_t *numsrc,
	 struct	sockaddr_storage *slist);

     int
     setipv4sourcefilter(int s,	struct in_addr interface,
	 struct	in_addr	group, uint32_t	fmode, uint32_t	numsrc,
	 struct	in_addr	*slist);

     int
     setsourcefilter(int s, uint32_t interface,	struct sockaddr	*group,
	 socklen_t grouplen, uint32_t fmode, uint32_t numsrc,
	 struct	sockaddr_storage *slist);

DESCRIPTION
     The sourcefilter functions	implement the advanced,	full-state multicast
     API defined in RFC	3678.  An application may use these functions to atom-
     ically set	and retrieve the multicast source address filters associated
     with a socket s and a multicast group.

     The functions getipv4sourcefilter() and getsourcefilter() allow an	appli-
     cation to discover	the filter mode, and source filter entries, for	an
     existing group membership.

     The kernel	will always return the number of source	filter entries on the
     socket for	that group in *numsrc.	If the *numsrc argument	is non-zero,
     the kernel	will attempt to	return up to *numsrc filter entries in the
     array pointed to by slist.	 The *numsrc argument may be set to 0, in
     which case	the slist argument will	be ignored.

     For the setipv4sourcefilter() and setsourcefilter() functions, the	fmode
     argument may be used to place the socket into inclusive or	exclusive
     group membership modes, by	using the MCAST_INCLUDE	or MCAST_EXCLUDE con-
     stants respectively.  The numsrc argument specifies the number of source
     entries in	the slist array.  If the numsrc	argument has a value of	0, all
     source filters will be removed from the socket.  Removing all source fil-
     ters from a membership which is in	the MCAST_INCLUDE filter mode will
     cause the group to	be left	on that	socket.

     The protocol-independent function 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 interface argument.

     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	excep-
     tion 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.

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.

     For the protocol-independent functions getsourcefilter() and
     setsourcefilter(),	the argument grouplen argument specifies the size of
     the structure pointed to by group.	 This is required in order to differ-
     entiate between different address families.

     Currently FreeBSD does not	support	source address selection for the IPv4
     protocol family, therefore	the use	of multicast APIs with an unnumbered
     IPv4 interface is not recommended.	In all cases, the first	assigned IPv4
     address on	the interface will be used as the source address of IGMP con-
     trol traffic.  If this address is removed or changed, the results are
     undefined.

RETURN VALUES
     The getsourcefilter(), getipv4sourcefilter(), setsourcefilter(), and
     setipv4sourcefilter() functions return the	value 0	if successful; other-
     wise the value -1 is returned and the global variable errno is set	to
     indicate the error.

ERRORS
     The sourcefilter functions	may fail because of:

     [EADDRNOTAVAIL]	The network interface which the	interface argument
			refers to was not configured in	the system, or the
			system is not a	member of the group.

     [EAFNOSUPPORT]	The group and/or one or	more of	the slist arguments
			were of	an address family unsupported by the system,
			or the address family of the group and slist arguments
			were not identical.

     [EINVAL]		The group argument does	not contain a multicast
			address.  The fmode argument is	invalid; it must be
			set to either MCAST_INCLUDE or MCAST_EXCLUDE.  The
			numsrc or slist	arguments do not specify a source
			list.

     [ENOMEM]		Insufficient memory was	available to carry out the
			requested operation.

SEE ALSO
     ip(4), ip6(4), multicast(4,) ifmcstat(8)

     D.	Thaler,	B. Fenner, and B. Quinn, Socket	Interface Extensions for
     Multicast Source Filters, RFC 3678, Jan 2004.

HISTORY
     The sourcefilter functions	first appeared in FreeBSD 7.0.

AUTHORS
     Bruce M. Simpson <bms@FreeBSD.org>

FreeBSD	9.2		       February	13, 2009		   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=sourcefilter&sektion=3&manpath=FreeBSD+9.2-RELEASE>

home | help