1getsourcefilter(3SOCKET) Sockets Library Functions getsourcefilter(3SOCKET)
2
6 getsourcefilter, setsourcefilter, getipv4sourcefilter, setipv4source‐
7 filter - retrieve and set a socket's multicast filter
8
10 cc [ flag... ] file... -lsocket [ library... ]
11 #include <netinet/in.h>
12 int getsourcefilter(int s, uint32_t interface,
14 struct sockaddr *group, socklen_t grouplen, uint32_t *fmode,
15 uint_t *numsrc, struct sockaddr_storage *slist);
16 int setsourcefilter(int s, uint32_t interface,
19 struct sockaddr *group, socklen_t grouplen, uint32_t fmode,
20 uint_t numsrc, struct sockaddr_storage *slist);
21 int getipv4sourcefilter(int s, struct in_addr interface,
24 struct in_addr group, uint32_t *fmode, uint32_t *numsrc,
25 struct in_addr *slist);
26 int setipv4sourcefilter(int s, struct in_addr interface,
29 struct in_addr group,uint32_t fmode, uint32_t numsrc,
30 struct in_addr *slist);
31
34 These functions allow applications to retrieve and modify the multicast
35 filtering state for a tuple consisting of socket, interface, and multi‐
36 cast group values.
37 A multicast filter is described by a filter mode, which is MODE_INCLUDE
40 or MODE_EXCLUDE, and a list of source addresses which are filtered. If
41 a group is simply joined with no source address restrictions, the fil‐
42 ter mode is MODE_EXCLUDE and the source list is empty.
43 The getsourcefilter() and setsourcefilter() functions are protocol-
46 independent. They can be used on either PF_INET or PF_INET6 sockets.
47 The getipv4sourcefilter() and setipv4sourcefilter() functions are
48 IPv4-specific. They must be used only on PF_INET sockets.
49 For the protocol-independent functions, the first four arguments iden‐
52 tify the socket, interface, multicast group tuple values. The argument
53 s is an open socket of type SOCK_DGRAM or SOCK_RAW. The interface argu‐
54 ment is the interface index. The interface name can be mapped to the
55 index using if_nametoindex(3SOCKET). The group points to either a sock‐
56 addr_in containing an IPv4 multicast address if the socket is PF_INET
57 or a sockaddr_in6 containing an IPv6 multicast address if the socket is
58 PF_INET6. The grouplen is the size of the structure pointed to by
59 group.
60 For the IPv4-specific functions, the first three arguments identify the
63 same socket, interface, multicast group tuple values. The argument s is
64 an open socket of type SOCK_DGRAM or SOCK_RAW and protocol family
65 PF_INET. The interface argument is the IPv4 address assigned to the
66 local interface. The group argument is the IPv4 multicast address.
67 The getsourcefilter() and getipv4sourcefilter() functions retrieve the
70 current filter for the given tuple consisting of socket, interface, and
71 multicast group values. On successful return, fmode contains either
72 MODE_INCLUDE or MODE_EXCLUDE, indicating the filter mode. On input, the
73 numsrc argument holds the number of addresses that can fit in the slist
74 array. On return, slist contains as many addresses as fit, while num‐
75 src contains the total number of source addresses in the filter. It is
76 possible that numsrc can contain a number larger than the number of
77 addresses in the slist array. An application might determine the
78 required buffer size by calling getsourcefilter() with numsrc contain‐
79 ing 0 and slist a NULL pointer. On return, numsrc contains the number
80 of elements that the slist buffer must be able to hold. Alternatively,
81 the maximum number of source addresses allowed by this implementation
82 is defined in <netinet/in.h>:
83 #define MAX_SRC_FILTER_SIZE 64
85 The setsourcefilter() and setipv4sourcefilter functions replace the
89 current filter with the filter specified in the arguments fmode, num‐
90 src, and slist. The fmode argument must be set to either MODE_INCLUDE
91 or MODE_EXCLUDE. The numsrc argument is the number of addresses in the
92 slist array. The slist argument points to the array of source addresses
93 to be included or excluded, depending on the fmode value.
94
96 If successful, all four functions return 0. Otherwise, they return −1
97 and set errno to indicate the error.
98
100 These functions will fail if:
101 EBADF The s argument is not a valid descriptor.
103 EAFNOSUPPORT The address family of the passed-in sockaddr is not
106 AF_INET or AF_INET6.
107 ENOPROTOOPT The socket s is not of type SOCK_DGRAM or SOCK_RAW.
110 ENOPROTOOPT The address family of the group parameter does not
113 match the protocol family of the socket.
114 ENOSR Insufficient STREAMS resources available for the opera‐
117 tion to complete.
118 ENXIO The interface argument, either an index or an IPv4
121 address, does not identify a valid interface.
122 The getsourcefilter() and getipv4sourcefilter() functions will fail if:
126 EADDRNOTAVAIL The tuple consisting of socket, interface, and multi‐
128 cast group values does not exist; group is not being
129 listened to on interface by socket.
130 The functions setsourcefilter()and setipv4sourcefilter() can fail in
134 the following additional case:
135 ENOBUFS The source filter list is larger than that allowed by the
137 implementation.
138
141 See attributes(5) for descriptions of the following attributes:
142 ┌─────────────────────────────┬─────────────────────────────┐
147 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
148 ├─────────────────────────────┼─────────────────────────────┤
149 │Interface Stability │Committed │
150 ├─────────────────────────────┼─────────────────────────────┤
151 │MT-Level │Safe │
152 └─────────────────────────────┴─────────────────────────────┘
153
155 if_nametoindex(3SOCKET), socket(3SOCKET), attributes(5)
156 RFC 3678
159SunOS 5.11 20 Aug 2007 getsourcefilter(3SOCKET)