Sockets Library Functions getsourcefilter(3SOCKET)
NAME
getsourcefilter, setsourcefilter, getipv4sourcefilter,
setipv4sourcefilter - retrieve and set a socket's multicast
filter
SYNOPSIS
cc [ flag... ] file... -lsocket [ library... ]
#include
int getsourcefilter(int s, uint32t interface,
struct sockaddr *group, socklent grouplen, uint32t *fmode,
uintt *numsrc, struct sockaddrstorage *slist);
int setsourcefilter(int s, uint32t interface,
struct sockaddr *group, socklent grouplen, uint32t fmode,
uintt numsrc, struct sockaddrstorage *slist);
int getipv4sourcefilter(int s, struct inaddr interface,
struct inaddr group, uint32t *fmode, uint32t *numsrc,
struct inaddr *slist);
int setipv4sourcefilter(int s, struct inaddr interface,
struct inaddr group,uint32t fmode, uint32t numsrc,
struct inaddr *slist);
DESCRIPTION
These functions allow applications to retrieve and modify
the multicast filtering state for a tuple consisting of
socket, interface, and multicast group values.
A multicast filter is described by a filter mode, which is
MODEINCLUDE or MODEXCLUDE, and a list of source addresses
which are filtered. If a group is simply joined with no
source address restrictions, the filter mode is MODEXCLUDE
and the source list is empty.
The getsourcefilter() and setsourcefilter() functions are
protocol-independent. They can be used on either PFINET or
PFINET6 sockets. The getipv4sourcefilter() and
setipv4sourcefilter() functions are IPv4-specific. They must
be used only on PFINET sockets.
For the protocol-independent functions, the first four argu-
ments identify the socket, interface, multicast group tuple
values. The argument s is an open socket of type SOCKDGRAM
SunOS 5.11 Last change: 20 Aug 2007 1
Sockets Library Functions getsourcefilter(3SOCKET)
or SOCKRAW. The interface argument is the interface index.
The interface name can be mapped to the index using
ifnametoindex(3SOCKET). The group points to either a
sockaddrin containing an IPv4 multicast address if the
socket is PFINET or a sockaddrin6 containing an IPv6 mul-
ticast address if the socket is PFINET6. The grouplen is
the size of the structure pointed to by group.
For the IPv4-specific functions, the first three arguments
identify the same socket, interface, multicast group tuple
values. The argument s is an open socket of type SOCKDGRAM
or SOCKRAW and protocol family PFINET. The interface argu-
ment is the IPv4 address assigned to the local interface.
The group argument is the IPv4 multicast address.
The getsourcefilter() and getipv4sourcefilter() functions
retrieve the current filter for the given tuple consisting
of socket, interface, and multicast group values. On suc-
cessful return, fmode contains either MODEINCLUDE or
MODEXCLUDE, indicating the filter mode. On input, the
numsrc argument holds the number of addresses that can fit
in the slist array. On return, slist contains as many
addresses as fit, while numsrc contains the total number of
source addresses in the filter. It is possible that numsrc
can contain a number larger than the number of addresses in
the slist array. An application might determine the required
buffer size by calling getsourcefilter() with numsrc con-
taining 0 and slist a NUL pointer. On return, numsrc con-
tains the number of elements that the slist buffer must be
able to hold. Alternatively, the maximum number of source
addresses allowed by this implementation is defined in
:
#define MAXSRCFILTERSIZE 64
The setsourcefilter() and setipv4sourcefilter functions
replace the current filter with the filter specified in the
arguments fmode, numsrc, and slist. The fmode argument must
be set to either MODEINCLUDE or MODEXCLUDE. The numsrc
argument is the number of addresses in the slist array. The
slist argument points to the array of source addresses to be
included or excluded, depending on the fmode value.
RETURN VALUES
If successful, all four functions return 0. Otherwise, they
return -1 and set errno to indicate the error.
SunOS 5.11 Last change: 20 Aug 2007 2
Sockets Library Functions getsourcefilter(3SOCKET)
ERORS
These functions will fail if:
EBADF The s argument is not a valid descriptor.
EAFNOSUPORT The address family of the passed-in sockaddr
is not AFINET or AFINET6.
ENOPROTOPT The socket s is not of type SOCKDGRAM or
SOCKRAW.
ENOPROTOPT The address family of the group parameter
does not match the protocol family of the
socket.
ENOSR Insufficient STREAMS resources available for
the operation to complete.
ENXIO The interface argument, either an index or
an IPv4 address, does not identify a valid
interface.
The getsourcefilter() and getipv4sourcefilter() functions
will fail if:
EADRNOTAVAIL The tuple consisting of socket, interface,
and multicast group values does not exist;
group is not being listened to on interface
by socket.
The functions setsourcefilter()and setipv4sourcefilter() can
fail in the following additional case:
ENOBUFS The source filter list is larger than that
allowed by the implementation.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 20 Aug 2007 3
Sockets Library Functions getsourcefilter(3SOCKET)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
ifnametoindex(3SOCKET), socket(3SOCKET), attributes(5)
RFC 3678
SunOS 5.11 Last change: 20 Aug 2007 4
|
