1.\" Copyright (c) 2007-2009 Bruce Simpson. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd February 13, 2009 26.Dt SOURCEFILTER 3 27.Os 28.Sh NAME 29.Nm sourcefilter 30.Nd advanced multicast group membership API 31.Sh SYNOPSIS 32.In sys/socket.h 33.In netinet/in.h 34.Ft int 35.Fo getipv4sourcefilter 36.Fa "int s" 37.Fa "struct in_addr interface" 38.Fa "struct in_addr group" 39.Fa "uint32_t *fmode" 40.Fa "uint32_t *numsrc" 41.Fa "struct in_addr *slist" 42.Fc 43.Ft int 44.Fo getsourcefilter 45.Fa "int s" 46.Fa "uint32_t interface" 47.Fa "struct sockaddr *group" 48.Fa "socklen_t grouplen" 49.Fa "uint32_t *fmode" 50.Fa "uint32_t *numsrc" 51.Fa "struct sockaddr_storage *slist" 52.Fc 53.Ft int 54.Fo setipv4sourcefilter 55.Fa "int s" 56.Fa "struct in_addr interface" 57.Fa "struct in_addr group" 58.Fa "uint32_t fmode" 59.Fa "uint32_t numsrc" 60.Fa "struct in_addr *slist" 61.Fc 62.Ft int 63.Fo setsourcefilter 64.Fa "int s" 65.Fa "uint32_t interface" 66.Fa "struct sockaddr *group" 67.Fa "socklen_t grouplen" 68.Fa "uint32_t fmode" 69.Fa "uint32_t numsrc" 70.Fa "struct sockaddr_storage *slist" 71.Fc 72.Sh DESCRIPTION 73The 74.Nm 75functions implement the advanced, full-state multicast API 76defined in RFC 3678. 77An application may use these functions to atomically set and 78retrieve the multicast source address filters associated with a socket 79.Fa s 80and a multicast 81.Fa group . 82.Pp 83The functions 84.Fn getipv4sourcefilter 85and 86.Fn getsourcefilter 87allow an application to discover the filter mode, and 88source filter entries, 89for an existing group membership. 90.Pp 91The kernel will always return the number of source filter 92entries on the socket for that group in 93.Fa *numsrc . 94If the 95.Fa *numsrc 96argument is non-zero, the kernel will attempt to return up to 97.Fa *numsrc 98filter entries in the array pointed to by 99.Fa slist . 100The 101.Fa *numsrc 102argument may be set to 0, in which case the 103.Fa slist 104argument will be ignored. 105.Pp 106For the 107.Fn setipv4sourcefilter 108and 109.Fn setsourcefilter 110functions, 111the 112.Fa fmode 113argument may be used to place the socket into inclusive or exclusive 114group membership modes, by using the 115.Dv MCAST_INCLUDE 116or 117.Dv MCAST_EXCLUDE 118constants respectively. 119The 120.Fa numsrc 121argument specifies the number of source entries in the 122.Fa slist 123array. 124If the 125.Fa numsrc 126argument has a value of 0, 127all source filters will be removed from the socket. 128Removing all source filters from a membership which is in the 129.Dv MCAST_INCLUDE 130filter mode will cause the group to be left on that socket. 131.Pp 132The protocol-independent function 133.Fn setsourcefilter 134allows an application to join a multicast group on an interface 135which may not have an assigned protocol address, 136by passing its index for the 137.Fa interface 138argument. 139.Pp 140Any changes made by these functions 141will be communicated to IGMPv3 and/or MLDv2 routers 142on the local network as appropriate. 143If no IGMPv3 or MLDv2 routers are present, changes in the source filter 144lists made by these functions will not cause 145state changes to be transmitted, with the exception of any 146change which causes a group to be joined or left. 147The kernel will continue to maintain the source filter state 148regardless of the IGMP or MLD version in use on the link. 149.Sh IMPLEMENTATION NOTES 150The IPv4 specific versions of these functions are implemented in terms 151of the protocol-independent functions. 152Application writers are encouraged to use the protocol-independent functions 153for efficiency, and forwards compatibility with IPv6 networks. 154.Pp 155For the protocol-independent functions 156.Fn getsourcefilter 157and 158.Fn setsourcefilter , 159the 160.Fa grouplen 161argument specifies the size of the structure pointed to by 162.Fa group . 163This is required in order to differentiate between different 164address families. 165.Pp 166Currently 167.Fx 168does not support source address selection for the IPv4 169protocol family, therefore the use of multicast APIs with 170an unnumbered IPv4 interface is 171.Em not recommended. 172In all cases, the first assigned IPv4 address on the interface 173will be used as the source address of IGMP control traffic. 174If this address is removed or changed, the results are undefined. 175.Sh RETURN VALUES 176.Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter 177.Sh ERRORS 178The 179.Nm 180functions may fail because of: 181.Bl -tag -width Er 182.It Bq Er EADDRNOTAVAIL 183The network interface which the 184.Dv interface 185argument refers to was not configured in the system, 186or the system is not a member of the 187.Dv group . 188.It Bq Er EAFNOSUPPORT 189The 190.Dv group 191and/or one or more of the 192.Dv slist 193arguments were of an address family unsupported by the system, 194or the address family of the 195.Dv group 196and 197.Dv slist 198arguments were not identical. 199.It Bq Er EINVAL 200The 201.Dv group 202argument does not contain a multicast address. 203The 204.Dv fmode 205argument is invalid; it must be set to either 206.Dv MCAST_INCLUDE 207or 208.Dv MCAST_EXCLUDE . 209The 210.Dv numsrc 211or 212.Dv slist 213arguments do not specify a source list. 214.It Bq Er ENOMEM 215Insufficient memory was available to carry out the requested 216operation. 217.El 218.Sh SEE ALSO 219.Xr ip 4 , 220.Xr ip6 4 , 221.Xr multicast 4 , 222.Xr ifmcstat 8 223.Rs 224.%A D. Thaler 225.%A B. Fenner 226.%A B. Quinn 227.%T "Socket Interface Extensions for Multicast Source Filters" 228.%N RFC 3678 229.%D Jan 2004 230.Re 231.Sh HISTORY 232The 233.Nm 234functions first appeared in 235.Fx 7.0 . 236.Sh AUTHORS 237.An Bruce M. Simpson Aq Mt bms@FreeBSD.org 238