tfIoctl

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int tfIoctl (
int socketDescriptor,
unsigned long request,
int * argumentPtr
);


Function Description

This function is used to set/clear non-blocking I/O, to get the number of bytes to read, or to check whether the specified socket's read pointer is currently at the out of band mark. This function also provides access to the Treck IGMPv3 and MLDv2 Multicast Source Filtering packages. The function is not called ioctl to avoid confusion with an embedded kernel file system call.


Parameters

  • socketDescriptor
    The socket descriptor to perform the ioctl request on.
  • request
    See the table below.
  • argumentPtr
    A pointer to an integer in which to store the request parameter or request result. If the request parameter is an IGMPv3 command, see the table below for this parameter's meaning.


Request Description
FIONBIO Set/clear non-blocking I/O: if the integer pointed to by argumentPtr contains a non-zero value, then the specified socket non-blocking flag is turned on. If it contains a zero value, then the specified socket non-blocking flag is turned off. See also tfBlockingState().
FIONREAD Stores in the integer cell pointed to by argumentPtr the number of bytes available to read from the socket descriptor. See also tfGetWaitingBytes().
SIOCATMARK Stores in the integer cell pointed to by argumentPtr a non-zero value if the specified socket's read pointer is currently at the out-of-band mark, zero otherwise. See recv() for a description of out-of-band data. See also tfGetOobDataOffset().
SIOCSIPMSFILTER Sets or modifies the IPv4 source filter content (e.g., unicast source address list) or mode (exclude or include) for a given multicast group. See details below.
SIOCGIPMSFILTER Retrieves the list of IPv4 source addresses that comprise the source filter along with the current filter mode for a given multicast group. See details below.
SIOCSMSFILTER Sets or modifies the IPv4 or IPv6 source filter content (e.g., unicast source address list) or mode (exclude or include) for a given multicast group. See details below.
SIOCGMSFILTER Retrieves the list of IPv4 or IPv6 source addresses that comprise the source filter along with the current filter mode for a given multicast group. See details below.


SIOCSIPMSFILTER and SIOCGIPMSFILTER Notes

These tfIoctl() options are provided for backward compatibility.


These options utilize the ip_msfilter structure, as well as some new macros that are located in <trsocket.h>.


#include <trsocket.h>
 
/*
 * Structure pointed to by the 3rd parameter of tfIoctl() when
 * the second parameter is either SIOCGIPMSFILTER, or SIOCSIPMSFILTER.
 */
struct ip_msfilter
{
   struct in_addr imsf_multiaddr;  /* IP multicast address of group */
   struct in_addr imsf_interface;  /* local IP address of interface */
   ttUser32Bit    imsf_fmode;      /* filter mode (either MCAST_INCLUDE
                                      or MCAST_EXCLUDE) */
   ttUser32Bit    imsf_numsrc;     /* number of sources in src_list */
   struct in_addr imsf_slist[1];   /* start of source list */
};


The <trsocket.h> macros are:

Macro Name Usage Comments
MCAST_INCLUDE imsf_fmode Initialize imsf_fmode with MCAST_INCLUDE when the mode is inclusive.
MCAST_EXCLUDE imsf_fmode Initialize imsf_fmode with MCAST_EXCLUDE when the mode is exclusive.
IP_MSFILTER_SIZE(x) Allocation size of the ip_msfilter structure. When x is the number of sources as set in imsf_numsrc, this macro gives the allocation size of the ip_msfilter structure.


When the request parameter is an IGMPv3 command, the meaning of the argumentPtr parameter is as follows:

request Value argumentPtr Meaning
SIOCSIPMSFILTER In this case, the third parameter of the tfIoctl() API points to an ip_msfilter structure. This allocated structure length must be at least IP_MSFILTER_SIZE(0) bytes long, and the imsf_numsrc parameter should be set so that IP_MSFILTER_SIZE(imsf_numsrc) indicates the buffer length. The imsf_fmode should be set to MCAST_INCLUDE or MCAST_EXCLUDE. Calling this API in include mode with imsf_numsrc set to zero is the same as dropping the multicast membership.
SIOCGIPMSFILTER If the application does not know the size of the source list beforehand, it can make a reasonable guess (e.g., 0), and if upon completion, the imsf_numsrc field holds a larger value, the operation can be repeated with a large enough buffer. That is, on return from this API call with an request of SIOCGIPMSFILTER, imsf_numsrc is always updated to be the total number of sources in the filter, while imsf_slist will hold as many source addresses as will fit, up to the minimum of the array size passed in as the original imsf_numsrc value and the total number of sources in the filter.


Note Note: For a given socket, interface, multicast group address, the user has to either use the exclude mode, or the include mode. The user can switch between the include mode and the exclude mode. The user can only specify one source list. A new call replaces the source list.


SIOCSMSFILTER and SIOCGMSFILTER Notes

These tfIoctl() options provide access to the Treck IGMPv3 and MLDv2 protocols for IPv4 and IPv6, respectively. To use these options, you must define one or both of the following Treck configuration macros in your trsystem.h:

Instead of using these tfIoctl() options, consider using the alternate API:

The tfIoctl() options SIOCSMSFILTER and SIOCGMSFILTER utilize the group_filter structure, as well as some new macros that are located in <trsocket.h>.

#include <trsocket.h>
 
/*
 * Structure pointed to by the 3rd parameter of tfIoctl() when
 * the second parameter is either SIOCGMSFILTER, or SIOCSMSFILTER.
 */
struct group_filter
{
    ttUser32Bit             gf_interface; /* interface index */
    struct sockaddr_storage gf_group;     /* multicast address */
    ttUser32Bit             gf_fmode;     /* filter mode (MCAST_INCLUDE
                                           * or MCAST_EXCLUDE) */
    ttUser32Bit             gf_numsrc;    /* number of sources */
    struct sockaddr_storage gf_slist[1];  /* source address list */
};


group_filter Parameters

  • gf_interface
    Index of the corresponding configured interface as returned by if_nametoindex(). Note that a zero index is valid if the user has either designated a default multicast interface for the socket via the IP_MULTICAST_IF or IPV6_MULTICAST_IF socket options, or designated a default multicast interface for the system via tfSetMcastInterface() or tf6SetMcastInterface().
  • gf_group
    Destination multicast group address (IPv4 or IPv6).
  • gf_fmode
    Filter mode. Either MCAST_INCLUDE or MCAST_EXCLUDE.
  • gf_numsrc
    Number of source addresses in the gf_slist array.
  • gf_slist
    Points to an array of IPv4 or IPv6 source addresses to include or exclude, based on the value of gf_fmode. The address family (AF_INET or AF_INET6) of all source addresses must match that of gf_group.



The <trsocket.h> macros are:

Macro Name Usage Comments
MCAST_INCLUDE gf_fmode Set gf_fmode to MCAST_INCLUDE when you don't want to receive multicast messages at gf_group from any hosts, except those hosts listed in gf_slist. The number of sources in gf_slist can be zero, which is equivalent to setsockopt() MCAST_LEAVE_GROUP.
MCAST_EXCLUDE gf_fmode Set gf_fmode to MCAST_EXCLUDE when you want to receive multicast messages at gf_group from all hosts, except those hosts listed in gf_slist. The number of sources in gf_slist can be zero, which is equivalent to setsockopt() MCAST_JOIN_GROUP.
GROUP_FILTER_SIZE(x) Allocation size of the group_filter structure. When x is the number of sources as set in gf_numsrc, this macro gives the allocation size of the group_filter structure.


When the request parameter is one of the following IGMPv3/MLDv2 commands, the meaning of the argumentPtr parameter is as follows:

request Value argumentPtr Meaning
SIOCSMSFILTER In this case, the third parameter of the tfIoctl() API points to a group_filter structure. The size of the allocated structure must be at least GROUP_FILTER_SIZE(N), where N is what you will store in gf_numsrc corresponding to the number of addresses you will provide in gf_slist. Set gf_group to identify the multicast group. Set gf_interface to identify the interface. Set gf_fmode to MCAST_INCLUDE or MCAST_EXCLUDE.
SIOCGMSFILTER Set gf_group to identify the multicast group. Set gf_interface to identify the interface. Set gf_numsrc to some value N to indicate the maximum number of source addresses that Treck may store in gf_slist based on an allocation size of GROUP_FILTER_SIZE(N). You may use a value of zero for N to discover what value of N to use to get all the source addresses. Upon return, gf_fmode will be set to the current filter mode (MCAST_INCLUDE or MCAST_EXCLUDE), gf_slist will contain up to gf_numsrc unicast IP addresses and gf_numsrc will be set to the actual number of source addresses in the socket's filter for gf_group.


Note Note: For a given socket, interface, multicast group address, the user has to either use the exclude mode, or the include mode. The user can switch between the include mode and the exclude mode. The user can only specify one source list. A subsequent call replaces the previous mode and source list.

Example

Given a valid socketDescriptor, the following code will turn on the socket's non-blocking I/O flag.

int argValue;
argValue = 1;
tfIoctl(socketDescriptor, FIONBIO, &argValue);


Return Values

  • TM_ENOERROR
    Success
  • TM_SOCKET_ERROR
    Failure


Note Note: TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself.

To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).


Possible socket errors

  • TM_EBADF
    The socket descriptor is invalid.
  • TM_EINVAL
    The request is not one of the possible values listed in the table above.
  • TM_EPROTOTYPE
    The socket is not of type SOCK_DGRAM or SOCK_RAW.
  • TM_EADDRNOTAVAIL
    Address is invalid. Here are a few examples:
  • The interface address is not a valid configured address.
  • A source address is invalid.
  • Trying to add a source on a local multicast group.
  • The group address is not multicast.
  • Trying to get the source list from an unjoined multicast group.
  • Trying to drop an un-joined multicast group (by setting imsf_numsrc to 0 in include mode for an un-joined multicast group).
  • TM_ENOBUFS
    No memory for operation, most probably because the maximum number of filters has been reached.


Table of Contents >> Programmer's Reference