lib/libc/net/sourcefilter.3

   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
  71 The
  72 .Nm
  73 functions implement the advanced, full-state multicast API
  74 defined in RFC 3678.
  75 An application may use these functions to atomically set and
  76 retrieve the multicast source address filters associated with a socket
  77 .Fa s
  78 and a multicast
  79 .Fa group .
  80 .Pp
  81 The protocol-independent functions
  82 .Fn getsourcefilter
  83 and
  84 .Fn setsourcefilter
  85 allow an application to join a multicast group on an interface by
  86 passing its index for the
  87 .Fa interface
  88 argument.
  89 The
  90 argument.
  91 .Fa grouplen
  92 argument specifies the size of the structure pointed to by
  93 .Fa group .
  94 .Pp
  95 For the
  96 .Fn setipv4sourcefilter
  97 and
  98 .Fn setsourcefilter
  99 functions.
 100 the
 101 .Fa fmode
 102 argument may be used to place the socket into inclusive or exclusive
 103 group membership modes, by using the
 104 .Dv MCAST_INCLUDE
 105 or
 106 .Dv MCAST_EXCLUDE
 107 constants respectively.
 108 The
 109 .Fa numsrc
 110 argument specifies the number of source entries in the
 111 .Fa slist
 112 array.
 113 A value of 0 will remove all source filters from the socket.
 114 The changes will be communicated to IGMPv3 and/or MLDv2 routers
 115 on the local network as appropriate.
 116 .Sh IMPLEMENTATION NOTES
 117 The IPv4 specific versions of these functions are implemented in terms
 118 of the protocol-independent functions.
 119 Application writers are encouraged to use the protocol-independent functions
 120 for efficiency, and upwards compatibility with IPv6 networks.
 121 .Sh RETURN VALUES
 122 .Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter
 123 .Sh ERRORS
 124 The
 125 .Nm
 126 functions may fail because of:
 127 .Bl -tag -width Er
 128 .It Bq Er EADDRNOTAVAIL
 129 The network interface which the
 130 .Dv interface
 131 argument refers to was not configured in the system,
 132 or the system is not a member of the
 133 .Dv group .
 134 .It Bq Er EAFNOSUPPORT
 135 The
 136 .Dv group
 137 and/or one or more of the
 138 .Dv slist
 139 arguments were of an address family unsupported by the system,
 140 or the address family of the
 141 .Dv group
 142 and
 143 .Dv slist
 144 arguments were not identical.
 145 .It Bq Er EINVAL
 146 The
 147 .Dv group
 148 argument does not contain a multicast address.
 149 The
 150 .Dv fmode
 151 argument is invalid; it must be set to either
 152 .Dv MCAST_INCLUDE
 153 or
 154 .Dv MCAST_EXCLUDE .
 155 The
 156 .Dv numsrc
 157 or
 158 .Dv slist
 159 arguments do not specify a source list.
 160 .It Bq Er ENOMEM
 161 Insufficient memory was available to carry out the requested
 162 operation.
 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
 177 The
 178 .Nm
 179 functions first appeared in
 180 .Fx 7.0 .
 181 .Sh AUTHORS
 182 Bruce M. Simpson
 183 .Aq bms@FreeBSD.org