setsourcefilter(3n) [hpux man page]
setsourcefilter(3N) setsourcefilter(3N) NAME
setsourcefilter() - set IP multicast source filter state SYNOPSIS
DESCRIPTION
This function sets the multicast source filter state for an IPv4 or IPv6 multicast group on a given socket. This function can be used to join a multicast group by specifying a filter mode of (with or without a source list), or by specifying a filter mode of with a non-empty source list. If the multicast group is already joined, this function replaces the existing filter mode and source list with the ones pro- vided. This function can be used to leave a multicast group by specifying a filter mode of and an empty source list. Parameters s Specifies the descriptor identifying the socket. The socket address family must be or and the socket type must be interface Holds the interface index of a local interface, or zero. If set to zero, the system chooses a multicast group by matching the multicast address only; or when joining a group, the system chooses the interface that datagrams for the group would be sent from, based on the routing configuration. group Points to either a sockaddr_in structure (for IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP multicast address of the group. grouplen Holds the size of the structure pointed to by the group argument. fmode Identifies the filter mode. The value of this field must be either or which are defined in numsrc Holds the number of source addresses in the slist array. slist Points to an array of sockaddr_storage structures containing the IP addresses to include or exclude depending on the filter mode. The sockaddr_storage structures will contain either a sockaddr_in structure (for IPv4 addresses) or a sockaddr_in6 structure (for IPv6 addresses, including IPv4-mapped IPv6 addresses); the address family must match that of the group argument. RETURN VALUES
returns the following values: Successful completion. Failure. is set to indicate the error. ERRORS
If fails, is set to one of the following values: The argument s is not a valid descriptor. This function is not supported by the socket type. Insufficient memory is available for internal system data structures. numsrc exceeds the maximum number of sources allowed, as determined by the ndd tunable parameters and (for IPv4), or and (for IPv6). The address family of the group argument is not supported. Trying to leave an unjoined group. group does not hold an IP multicast address; or slist contains an invalid source address; or the specified filter mode is not valid; or interface contains an invalid interface index; or grouplen is not valid; or the address family of a source address in the slist argument does not match the address family of the group argument. AUTHOR
was developed by HP and the IETF. SEE ALSO
ndd(1M), socket(2), getipv4sourcefilter(3N), getsourcefilter(3N), if_nameindex(3N), setipv4sourcefilter(3N), ip(7P), ip6(7P). STANDARDS CONFORMANCE
RFC 3678 setsourcefilter(3N)
Check Out this Related Man Page
getsourcefilter(3SOCKET) 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 <netinet/in.h> int getsourcefilter(int s, uint32_t interface, struct sockaddr *group, socklen_t grouplen, uint32_t *fmode, uint_t *numsrc, struct sockaddr_storage *slist); int setsourcefilter(int s, uint32_t interface, struct sockaddr *group, socklen_t grouplen, uint32_t fmode, uint_t numsrc, struct sockaddr_storage *slist); int getipv4sourcefilter(int s, struct in_addr interface, struct in_addr group, uint32_t *fmode, uint32_t *numsrc, struct in_addr *slist); int setipv4sourcefilter(int s, struct in_addr interface, struct in_addr group,uint32_t fmode, uint32_t numsrc, struct in_addr *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 MODE_INCLUDE or MODE_EXCLUDE, and a list of source addresses which are filtered. If a group is simply joined with no source address restrictions, the filter mode is MODE_EXCLUDE and the source list is empty. The getsourcefilter() and setsourcefilter() functions are protocol-independent. They can be used on either PF_INET or PF_INET6 sockets. The getipv4sourcefilter() and setipv4sourcefilter() functions are IPv4-specific. They must be used only on PF_INET sockets. For the protocol-independent functions, the first four arguments identify the socket, interface, multicast group tuple values. The argument s is an open socket of type SOCK_DGRAM or SOCK_RAW. The interface argument is the interface index. The interface name can be mapped to the index using if_nametoindex(3SOCKET). The group points to either a sockaddr_in containing an IPv4 multicast address if the socket is PF_INET or a sockaddr_in6 containing an IPv6 multicast address if the socket is PF_INET6. 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 SOCK_DGRAM or SOCK_RAW and protocol family PF_INET. The interface argument 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 successful return, fmode contains either MODE_INCLUDE or MODE_EXCLUDE, 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 containing 0 and slist a NULL pointer. On return, numsrc contains the number of elements that the slist buffer must be able to hold. Alter- natively, the maximum number of source addresses allowed by this implementation is defined in <netinet/in.h>: #define MAX_SRC_FILTER_SIZE 64 The setsourcefilter() and setipv4sourcefilter functions replace the current filter with the filter specified in the arguments fmode, num- src, and slist. The fmode argument must be set to either MODE_INCLUDE or MODE_EXCLUDE. 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. ERRORS
These functions will fail if: EBADF The s argument is not a valid descriptor. EAFNOSUPPORT The address family of the passed-in sockaddr is not AF_INET or AF_INET6. ENOPROTOOPT The socket s is not of type SOCK_DGRAM or SOCK_RAW. ENOPROTOOPT 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: EADDRNOTAVAIL 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. ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Interface Stability |Committed | +-----------------------------+-----------------------------+ |MT-Level |Safe | +-----------------------------+-----------------------------+ SEE ALSO
if_nametoindex(3SOCKET), socket(3SOCKET), attributes(5) RFC 3678 SunOS 5.11 20 Aug 2007 getsourcefilter(3SOCKET)