1.\" Copyright (c) 2007 Bruce M. Simpson. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 9.\" THIS SOFTWARE IS PROVIDED BY Bruce M. Simpson ``AS IS'' AND 10.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 11.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 12.\" ARE DISCLAIMED. IN NO EVENT SHALL Bruce M. Simpson BE LIABLE 13.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 14.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 15.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 16.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 17.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 18.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 19.\" SUCH DAMAGE. 20.\" 21.\" $FreeBSD$ 22.\" 23.Dd June 12, 2007 24.Dt SOURCEFILTER 3 25.Os 26.Sh NAME 27.Nm sourcefilter 28.Nd advanced multicast group membership API 29.Sh SYNOPSIS 30.In sys/socket.h 31.In netinet/in.h 32.Ft int 33.Fo getipv4sourcefilter 34.Fa "int s" 35.Fa "struct in_addr interface" 36.Fa "struct in_addr group" 37.Fa "uint32_t *fmode" 38.Fa "uint32_t *numsrc" 39.Fa "struct in_addr *slist" 40.Fc 41.Ft int 42.Fo getsourcefilter 43.Fa "int s" 44.Fa "uint32_t interface" 45.Fa "struct sockaddr *group" 46.Fa "socklen_t grouplen" 47.Fa "uint32_t *fmode" 48.Fa "uint32_t *numsrc" 49.Fa "struct sockaddr_storage *slist" 50.Fc 51.Ft int 52.Fo setipv4sourcefilter 53.Fa "int s" 54.Fa "struct in_addr interface" 55.Fa "struct in_addr group" 56.Fa "uint32_t fmode" 57.Fa "uint32_t numsrc" 58.Fa "struct in_addr *slist" 59.Fc 60.Ft int 61.Fo setsourcefilter 62.Fa "int s" 63.Fa "uint32_t interface" 64.Fa "struct sockaddr *group" 65.Fa "socklen_t grouplen" 66.Fa "uint32_t fmode" 67.Fa "uint32_t numsrc" 68.Fa "struct sockaddr_storage *slist" 69.Fc 70.Sh DESCRIPTION 71The 72.Nm 73functions implement the advanced, full-state multicast API 74defined in RFC 3678. 75An application may use these functions to atomically set and 76retrieve the multicast source address filters associated with a socket 77.Fa s 78and a multicast 79.Fa group . 80.Pp 81The protocol-independent functions 82.Fn getsourcefilter 83and 84.Fn setsourcefilter 85allow an application to join a multicast group on an interface by 86passing its index for the 87.Fa interface 88argument. 89The 90argument. 91.Fa grouplen 92argument specifies the size of the structure pointed to by 93.Fa group . 94.Pp 95For the 96.Fn setipv4sourcefilter 97and 98.Fn setsourcefilter 99functions. 100the 101.Fa fmode 102argument may be used to place the socket into inclusive or exclusive 103group membership modes, by using the 104.Dv MCAST_INCLUDE 105or 106.Dv MCAST_EXCLUDE 107constants respectively. 108The 109.Fa numsrc 110argument specifies the number of source entries in the 111.Fa slist 112array. 113A value of 0 will remove all source filters from the socket. 114The changes will be communicated to IGMPv3 and/or MLDv2 routers 115on the local network as appropriate. 116.Sh IMPLEMENTATION NOTES 117The IPv4 specific versions of these functions are implemented in terms 118of the protocol-independent functions. 119Application writers are encouraged to use the protocol-independent functions 120for efficiency, and upwards compatibility with IPv6 networks. 121.Sh RETURN VALUES 122.Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter 123.Sh ERRORS 124The 125.Nm 126functions may fail because of: 127.Bl -tag -width Er 128.It Bq Er EADDRNOTAVAIL 129The network interface which the 130.Dv interface 131argument refers to was not configured in the system, 132or the system is not a member of the 133.Dv group . 134.It Bq Er EAFNOSUPPORT 135The 136.Dv group 137and/or one or more of the 138.Dv slist 139arguments were of an address family unsupported by the system, 140or the address family of the 141.Dv group 142and 143.Dv slist 144arguments were not identical. 145.It Bq Er EINVAL 146The 147.Dv group 148argument does not contain a multicast address. 149The 150.Dv fmode 151argument is invalid; it must be set to either 152.Dv MCAST_INCLUDE 153or 154.Dv MCAST_EXCLUDE . 155The 156.Dv numsrc 157or 158.Dv slist 159arguments do not specify a source list. 160.It Bq Er ENOMEM 161Insufficient memory was available to carry out the requested 162operation. 163.El 164.Sh SEE ALSO 165.Xr ip 4 , 166.Xr ip6 4 , 167.Xr multicast 4 168.Rs 169.%A D. Thaler 170.%A B. Fenner 171.%A B. Quinn 172.%T "Socket Interface Extensions for Multicast Source Filters" 173.%N RFC 3678 174.%D Jan 2004 175.Re 176.Sh HISTORY 177The 178.Nm 179functions first appeared in 180.Fx 7.0 . 181.Sh AUTHORS 182Bruce M. Simpson 183.Aq bms@FreeBSD.org 184