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