share/man/man3socket/getsourcefilter.3socket

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GETSOURCEFILTER 3SOCKET "Aug 20, 2007"
   7 .SH NAME
   8 getsourcefilter, setsourcefilter, getipv4sourcefilter, setipv4sourcefilter \-
   9 retrieve and set a socket's multicast filter
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  14 #include <netinet/in.h>
  15
  16 \fBint\fR \fBgetsourcefilter\fR(\fBint\fR \fIs\fR, \fBuint32_t\fR \fIinterface\fR,
  17      \fBstruct sockaddr *\fR\fIgroup\fR, \fBsocklen_t\fR \fIgrouplen\fR, \fBuint32_t *\fR\fIfmode\fR,
  18      \fBuint_t *\fR\fInumsrc\fR, \fBstruct sockaddr_storage *\fR\fIslist\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBsetsourcefilter\fR(\fBint\fR \fIs\fR, \fBuint32_t\fR \fIinterface\fR,
  24      \fBstruct sockaddr *\fR\fIgroup\fR, \fBsocklen_t\fR \fIgrouplen\fR, \fBuint32_t\fR \fIfmode\fR,
  25      \fBuint_t\fR \fInumsrc\fR, \fBstruct sockaddr_storage *\fR\fIslist\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBgetipv4sourcefilter\fR(\fBint\fR \fIs\fR, \fBstruct in_addr\fR \fIinterface\fR,
  31      \fBstruct in_addr\fR \fIgroup\fR, \fBuint32_t *\fR\fIfmode\fR, \fBuint32_t *\fR\fInumsrc\fR,
  32      \fBstruct in_addr *\fR\fIslist\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBint\fR \fBsetipv4sourcefilter\fR(\fBint\fR \fIs\fR, \fBstruct in_addr\fR \fIinterface\fR,
  38      \fBstruct in_addr\fR \fIgroup\fR,\fBuint32_t\fR \fIfmode\fR, \fBuint32_t\fR \fInumsrc\fR,
  39      \fBstruct in_addr *\fR\fIslist\fR);
  40 .fi
  41
  42 .SH DESCRIPTION
  43 .LP
  44 These functions allow applications to retrieve and modify the multicast
  45 filtering state for a tuple consisting of socket, interface, and multicast
  46 group values.
  47 .sp
  48 .LP
  49 A multicast filter is described by a filter mode, which is \fBMODE_INCLUDE\fR
  50 or \fBMODE_EXCLUDE\fR, and a list of source addresses which are filtered. If a
  51 group is simply joined with no source address restrictions, the filter mode is
  52 \fBMODE_EXCLUDE\fR and the source list is empty.
  53 .sp
  54 .LP
  55 The \fBgetsourcefilter()\fR and \fBsetsourcefilter()\fR functions are
  56 protocol-independent. They can be used on either \fBPF_INET\fR or
  57 \fBPF_INET6\fR sockets. The \fBgetipv4sourcefilter()\fR and
  58 \fBsetipv4sourcefilter()\fR functions are IPv4-specific. They must be used only
  59 on \fBPF_INET\fR sockets.
  60 .sp
  61 .LP
  62 For the protocol-independent functions, the first four arguments identify the
  63 socket, interface, multicast group tuple values. The argument \fIs\fR is an
  64 open socket of type \fBSOCK_DGRAM\fR or \fBSOCK_RAW\fR. The \fIinterface\fR
  65 argument is the interface index. The interface name can be mapped to the index
  66 using \fBif_nametoindex\fR(3SOCKET). The \fIgroup\fR points to either a
  67 \fBsockaddr_in\fR containing an IPv4 multicast address if the socket is
  68 \fBPF_INET\fR or a \fBsockaddr_in6\fR containing an IPv6 multicast address if
  69 the socket is \fBPF_INET6\fR. The \fIgrouplen\fR is the size of the structure
  70 pointed to by \fIgroup\fR.
  71 .sp
  72 .LP
  73 For the IPv4-specific functions, the first three arguments identify the same
  74 socket, interface, multicast group tuple values. The argument \fIs\fR is an
  75 open socket of type \fBSOCK_DGRAM\fR or \fBSOCK_RAW\fR and protocol family
  76 \fBPF_INET\fR. The \fIinterface\fR argument is the IPv4 address assigned to the
  77 local interface. The \fIgroup\fR argument is the IPv4 multicast address.
  78 .sp
  79 .LP
  80 The \fBgetsourcefilter()\fR and \fBgetipv4sourcefilter()\fR functions retrieve
  81 the current filter for the given tuple consisting of socket, interface, and
  82 multicast group values. On successful return, \fIfmode\fR contains either
  83 \fBMODE_INCLUDE\fR or \fBMODE_EXCLUDE\fR, indicating the filter mode. On input,
  84 the \fInumsrc\fR argument holds the number of addresses that can fit in the
  85 \fIslist\fR array.  On return, \fIslist\fR contains as many addresses as fit,
  86 while \fInumsrc\fR contains the total number of source addresses in the filter.
  87 It is possible that \fInumsrc\fR can contain a number larger than the number of
  88 addresses in the \fIslist\fR array. An application might determine the required
  89 buffer size by calling \fBgetsourcefilter()\fR with \fInumsrc\fR containing
  90 \fB0\fR and \fIslist\fR a \fBNULL\fR pointer. On return, \fInumsrc\fR contains
  91 the number of elements that the \fIslist\fR buffer must be able to hold.
  92 Alternatively, the maximum number of source addresses allowed by this
  93 implementation is defined in \fB<netinet/in.h>\fR:
  94 .sp
  95 .in +2
  96 .nf
  97 #define MAX_SRC_FILTER_SIZE     64
  98 .fi
  99 .in -2
 100
 101 .sp
 102 .LP
 103 The \fBsetsourcefilter()\fR and \fBsetipv4sourcefilter\fR functions replace the
 104 current filter with the filter specified in the arguments \fIfmode\fR,
 105 \fInumsrc\fR, and \fIslist\fR. The \fIfmode\fR argument must be set to either
 106 \fBMODE_INCLUDE\fR or \fBMODE_EXCLUDE\fR. The \fInumsrc\fR argument is the
 107 number of addresses in the \fIslist\fR array. The \fIslist\fR argument points
 108 to the array of source addresses to be included or excluded, depending on the
 109 \fIfmode\fR value.
 110 .SH RETURN VALUES
 111 .LP
 112 If successful, all four functions return \fB0\fR. Otherwise, they return
 113 \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
 114 .SH ERRORS
 115 .LP
 116 These functions will fail if:
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEBADF\fR\fR
 121 .ad
 122 .RS 16n
 123 The \fIs\fR argument is not a valid descriptor.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBEAFNOSUPPORT\fR\fR
 130 .ad
 131 .RS 16n
 132 The address family of the passed-in \fIsockaddr\fR is not \fBAF_INET\fR or
 133 \fBAF_INET6\fR.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBENOPROTOOPT\fR\fR
 140 .ad
 141 .RS 16n
 142 The socket \fIs\fR is not of type \fBSOCK_DGRAM\fR or \fBSOCK_RAW\fR.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBENOPROTOOPT\fR\fR
 149 .ad
 150 .RS 16n
 151 The address family of the group parameter does not match the protocol family of
 152 the socket.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBENOSR\fR\fR
 159 .ad
 160 .RS 16n
 161 Insufficient \fBSTREAMS\fR resources available for the operation to complete.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBENXIO\fR\fR
 168 .ad
 169 .RS 16n
 170 The \fIinterface\fR argument, either an index or an IPv4 address, does not
 171 identify a valid interface.
 172 .RE
 173
 174 .sp
 175 .LP
 176 The \fBgetsourcefilter()\fR and \fBgetipv4sourcefilter()\fR functions will fail
 177 if:
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBEADDRNOTAVAIL\fR\fR
 182 .ad
 183 .RS 17n
 184 The tuple consisting of socket, interface, and multicast group values does not
 185 exist; \fIgroup\fR is not being listened to on \fIinterface\fR by \fIsocket\fR.
 186 .RE
 187
 188 .sp
 189 .LP
 190 The functions \fBsetsourcefilter()\fRand \fBsetipv4sourcefilter()\fR can fail
 191 in the following additional case:
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fBENOBUFS\fR\fR
 196 .ad
 197 .RS 11n
 198 The source filter list is larger than that allowed by the implementation.
 199 .RE
 200
 201 .SH ATTRIBUTES
 202 .LP
 203 See \fBattributes\fR(5) for descriptions of the following attributes:
 204 .sp
 205
 206 .sp
 207 .TS
 208 box;
 209 c | c
 210 l | l .
 211 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 212 _
 213 Interface Stability     Committed
 214 _
 215 MT-Level        Safe
 216 .TE
 217
 218 .SH SEE ALSO
 219 .LP
 220 \fBif_nametoindex\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsockaddr\fR(3SOCKET),
 221 \fBattributes\fR(5)
 222 .sp
 223 .LP
 224 RFC 3678