net/sourcefilter.3

   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: src/lib/libc/net/sourcefilter.3,v 1.2 2009/03/04 01:59:14 bms Exp $
  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
  75 The
  76 .Nm
  77 functions implement the advanced, full-state multicast API
  78 defined in RFC 3678.
  79 An application may use these functions to atomically set and
  80 retrieve the multicast source address filters associated with a socket
  81 .Fa s
  82 and a multicast
  83 .Fa group .
  84 .Pp
  85 The functions
  86 .Fn getipv4sourcefilter
  87 and
  88 .Fn getsourcefilter
  89 allow an application to discover the filter mode, and
  90 source filter entries,
  91 for an existing group membership.
  92 .Pp
  93 The kernel will always return the number of source filter
  94 entries on the socket for that group in
  95 .Fa *numsrc .
  96 If the
  97 .Fa *numsrc
  98 argument is non-zero, the kernel will attempt to return up to
  99 .Fa *numsrc
 100 filter entries in the array pointed to by
 101 .Fa slist .
 102 The
 103 .Fa *numsrc
 104 argument may be set to 0, in which case the
 105 .Fa slist
 106 argument will be ignored.
 107 .Pp
 108 For the
 109 .Fn setipv4sourcefilter
 110 and
 111 .Fn setsourcefilter
 112 functions,
 113 the
 114 .Fa fmode
 115 argument may be used to place the socket into inclusive or exclusive
 116 group membership modes, by using the
 117 .Dv MCAST_INCLUDE
 118 or
 119 .Dv MCAST_EXCLUDE
 120 constants respectively.
 121 The
 122 .Fa numsrc
 123 argument specifies the number of source entries in the
 124 .Fa slist
 125 array.
 126 If the
 127 .Fa numsrc
 128 argument has a value of 0,
 129 all source filters will be removed from the socket.
 130 Removing all source filters from a membership which is in the
 131 .Dv MCAST_INCLUDE
 132 filter mode will cause the group to be left on that socket.
 133 .Pp
 134 The protocol-independent function
 135 .Fn setsourcefilter
 136 allows an application to join a multicast group on an interface
 137 which may not have an assigned protocol address,
 138 by passing its index for the
 139 .Fa interface
 140 argument.
 141 .Pp
 142 Any changes made by these functions
 143 will be communicated to IGMPv3 and/or MLDv2 routers
 144 on the local network as appropriate.
 145 If no IGMPv3 or MLDv2 routers are present, changes in the source filter
 146 lists made by these functions will not cause
 147 state changes to be transmitted, with the exception of any
 148 change which causes a group to be joined or left.
 149 The kernel will continue to maintain the source filter state
 150 regardless of the IGMP or MLD version in use on the link.
 151 .Sh IMPLEMENTATION NOTES
 152 The IPv4 specific versions of these functions are implemented in terms
 153 of the protocol-independent functions.
 154 Application writers are encouraged to use the protocol-independent functions
 155 for efficiency, and forwards compatibility with IPv6 networks.
 156 .Pp
 157 For the protocol-independent functions
 158 .Fn getsourcefilter
 159 and
 160 .Fn setsourcefilter ,
 161 the argument
 162 .Fa grouplen
 163 argument specifies the size of the structure pointed to by
 164 .Fa group .
 165 This is required in order to differentiate between different
 166 address families.
 167 .Pp
 168 Currently
 169 .Fx
 170 does not support source address selection for the IPv4
 171 protocol family, therefore the use of multicast APIs with
 172 an unnumbered IPv4 interface is
 173 .Em not recommended.
 174 In all cases, the first assigned IPv4 address on the interface
 175 will be used as the source address of IGMP control traffic.
 176 If this address is removed or changed, the results are undefined.
 177 .Sh RETURN VALUES
 178 .Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter
 179 .Sh ERRORS
 180 The
 181 .Nm
 182 functions may fail because of:
 183 .Bl -tag -width Er
 184 .It Bq Er EADDRNOTAVAIL
 185 The network interface which the
 186 .Dv interface
 187 argument refers to was not configured in the system,
 188 or the system is not a member of the
 189 .Dv group .
 190 .It Bq Er EAFNOSUPPORT
 191 The
 192 .Dv group
 193 and/or one or more of the
 194 .Dv slist
 195 arguments were of an address family unsupported by the system,
 196 or the address family of the
 197 .Dv group
 198 and
 199 .Dv slist
 200 arguments were not identical.
 201 .It Bq Er EINVAL
 202 The
 203 .Dv group
 204 argument does not contain a multicast address.
 205 The
 206 .Dv fmode
 207 argument is invalid; it must be set to either
 208 .Dv MCAST_INCLUDE
 209 or
 210 .Dv MCAST_EXCLUDE .
 211 The
 212 .Dv numsrc
 213 or
 214 .Dv slist
 215 arguments do not specify a source list.
 216 .It Bq Er ENOMEM
 217 Insufficient memory was available to carry out the requested
 218 operation.
 219 .El
 220 .Sh SEE ALSO
 221 .Xr ip 4 ,
 222 .Xr ip6 4
 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
 232 The
 233 .Nm
 234 functions first appeared in
 235 .Fx 7.0 .
 236 .Sh AUTHORS
 237 Bruce M. Simpson
 238 .Aq bms@FreeBSD.org