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.\" $FreeBSD$ 26.\" 27.Dd February 13, 2009 28.Dt SOURCEFILTER 3 29.Os 30.Sh NAME 31.Nm sourcefilter 32.Nd advanced multicast group membership API 33.Sh SYNOPSIS 34.In sys/socket.h 35.In netinet/in.h 36.Ft int 37.Fo getipv4sourcefilter 38.Fa "int s" 39.Fa "struct in_addr interface" 40.Fa "struct in_addr group" 41.Fa "uint32_t *fmode" 42.Fa "uint32_t *numsrc" 43.Fa "struct in_addr *slist" 44.Fc 45.Ft int 46.Fo getsourcefilter 47.Fa "int s" 48.Fa "uint32_t interface" 49.Fa "struct sockaddr *group" 50.Fa "socklen_t grouplen" 51.Fa "uint32_t *fmode" 52.Fa "uint32_t *numsrc" 53.Fa "struct sockaddr_storage *slist" 54.Fc 55.Ft int 56.Fo setipv4sourcefilter 57.Fa "int s" 58.Fa "struct in_addr interface" 59.Fa "struct in_addr group" 60.Fa "uint32_t fmode" 61.Fa "uint32_t numsrc" 62.Fa "struct in_addr *slist" 63.Fc 64.Ft int 65.Fo setsourcefilter 66.Fa "int s" 67.Fa "uint32_t interface" 68.Fa "struct sockaddr *group" 69.Fa "socklen_t grouplen" 70.Fa "uint32_t fmode" 71.Fa "uint32_t numsrc" 72.Fa "struct sockaddr_storage *slist" 73.Fc 74.Sh DESCRIPTION 75The 76.Nm 77functions implement the advanced, full-state multicast API 78defined in RFC 3678. 79An application may use these functions to atomically set and 80retrieve the multicast source address filters associated with a socket 81.Fa s 82and a multicast 83.Fa group . 84.Pp 85The functions 86.Fn getipv4sourcefilter 87and 88.Fn getsourcefilter 89allow an application to discover the filter mode, and 90source filter entries, 91for an existing group membership. 92.Pp 93The kernel will always return the number of source filter 94entries on the socket for that group in 95.Fa *numsrc . 96If the 97.Fa *numsrc 98argument is non-zero, the kernel will attempt to return up to 99.Fa *numsrc 100filter entries in the array pointed to by 101.Fa slist . 102The 103.Fa *numsrc 104argument may be set to 0, in which case the 105.Fa slist 106argument will be ignored. 107.Pp 108For the 109.Fn setipv4sourcefilter 110and 111.Fn setsourcefilter 112functions, 113the 114.Fa fmode 115argument may be used to place the socket into inclusive or exclusive 116group membership modes, by using the 117.Dv MCAST_INCLUDE 118or 119.Dv MCAST_EXCLUDE 120constants respectively. 121The 122.Fa numsrc 123argument specifies the number of source entries in the 124.Fa slist 125array. 126If the 127.Fa numsrc 128argument has a value of 0, 129all source filters will be removed from the socket. 130Removing all source filters from a membership which is in the 131.Dv MCAST_INCLUDE 132filter mode will cause the group to be left on that socket. 133.Pp 134The protocol-independent function 135.Fn setsourcefilter 136allows an application to join a multicast group on an interface 137which may not have an assigned protocol address, 138by passing its index for the 139.Fa interface 140argument. 141.Pp 142Any changes made by these functions 143will be communicated to IGMPv3 and/or MLDv2 routers 144on the local network as appropriate. 145If no IGMPv3 or MLDv2 routers are present, changes in the source filter 146lists made by these functions will not cause 147state changes to be transmitted, with the exception of any 148change which causes a group to be joined or left. 149The kernel will continue to maintain the source filter state 150regardless of the IGMP or MLD version in use on the link. 151.Sh IMPLEMENTATION NOTES 152The IPv4 specific versions of these functions are implemented in terms 153of the protocol-independent functions. 154Application writers are encouraged to use the protocol-independent functions 155for efficiency, and forwards compatibility with IPv6 networks. 156.Pp 157For the protocol-independent functions 158.Fn getsourcefilter 159and 160.Fn setsourcefilter , 161the argument 162.Fa grouplen 163argument specifies the size of the structure pointed to by 164.Fa group . 165This is required in order to differentiate between different 166address families. 167.Pp 168Currently 169.Fx 170does not support source address selection for the IPv4 171protocol family, therefore the use of multicast APIs with 172an unnumbered IPv4 interface is 173.Em not recommended. 174In all cases, the first assigned IPv4 address on the interface 175will be used as the source address of IGMP control traffic. 176If this address is removed or changed, the results are undefined. 177.Sh RETURN VALUES 178.Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter 179.Sh ERRORS 180The 181.Nm 182functions may fail because of: 183.Bl -tag -width Er 184.It Bq Er EADDRNOTAVAIL 185The network interface which the 186.Dv interface 187argument refers to was not configured in the system, 188or the system is not a member of the 189.Dv group . 190.It Bq Er EAFNOSUPPORT 191The 192.Dv group 193and/or one or more of the 194.Dv slist 195arguments were of an address family unsupported by the system, 196or the address family of the 197.Dv group 198and 199.Dv slist 200arguments were not identical. 201.It Bq Er EINVAL 202The 203.Dv group 204argument does not contain a multicast address. 205The 206.Dv fmode 207argument is invalid; it must be set to either 208.Dv MCAST_INCLUDE 209or 210.Dv MCAST_EXCLUDE . 211The 212.Dv numsrc 213or 214.Dv slist 215arguments do not specify a source list. 216.It Bq Er ENOMEM 217Insufficient memory was available to carry out the requested 218operation. 219.El 220.Sh SEE ALSO 221.Xr ip 4 , 222.Xr ip6 4 , 223.Xr multicast 4, 224.Xr ifmcstat 8 225.Rs 226.%A D. Thaler 227.%A B. Fenner 228.%A B. Quinn 229.%T "Socket Interface Extensions for Multicast Source Filters" 230.%N RFC 3678 231.%D Jan 2004 232.Re 233.Sh HISTORY 234The 235.Nm 236functions first appeared in 237.Fx 7.0 . 238.Sh AUTHORS 239Bruce M. Simpson 240.Aq bms@FreeBSD.org 241