select

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int select (
int numberOfSockets,
fd_set * readSocketPtr,
fd_set * writeSocketPtr,
fd_set * exceptionSocketPtr,
struct timeval * timeOutPtr
);


Function Description

select() examines the socket descriptor sets whose addresses are passed in readSocketsPtr, writeSocketsPtr, and exceptionSocketsPtr to see if any of their socket descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. Out-of-band data is the only exceptional condition. The numberOfSockets argument specifies the number of socket descriptors to be tested. Its value is the maximum socket descriptor to be tested plus one. The socket descriptors from 0 to numberOfSockets -1 in the socket descriptor sets are examined. On return, select() replaces the given socket descriptor sets with subsets consisting of those socket descriptors that are ready for the requested operation. The return value from the call to select() is the number of ready socket descriptors. The socket descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such file descriptor sets:


FD_ZERO(&fdset); Initializes a socket descriptor set (fdset) to the null set.
FD_SET(fd, &fdset); Includes a particular socket descriptor fd in fdset.
FD_CLR(fd, &fdset); Removes fd from fdset.
FD_ISSET(fd, &fdset); Is non-zero if fd is a member of fdset, zero otherwise.


Note Note: The term "fd" is used for BSD compatibility since select() is used on both file systems and sockets under BSD Unix.


The timeout parameter specifies a length of time to wait for an event to occur before exiting this routine. struct timeval contains the following members:


#include <trsocket.h>
 
#ifndef TM_BSD_TYPES_CLASH
/* This structure is usually defined by the compiler or kernel in time.h */
struct timeval
{
    long tv_sec;    /* Number of seconds */
    long tv_usec;   /* Number of microseconds */
};
#endif /* TM_BSD_TYPES_CLASH */


If the total time is less than one millisecond, select() will return immediately to the user. The resolution of this timer is equal to the system tick length (the amount of time between calls to tfTimerUpdate()/tfTimerUpdateIsr()).

select() may be used to sleep in blocking systems by specifying a valid timeout value and setting numberOfSockets and all three file descriptors to 0. The precision of using select in this manner depends on the Treck timer precision. The minimum sleep time is one tick length.


Parameters

  • numberOfSockets
    Biggest socket descriptor to be tested plus one.
  • readSocketPtr
    The pointer to a mask of sockets to check for a read condition.
  • writeSocketPtr
    The pointer to a mask of sockets to check for a write condition.
  • exceptionSocketPtr
    The pointer to a mask of sockets to check for an exception condition (out-of-band data).
  • timeOutPtr
    A pointer to a structure containing the length of time to wait for an event before exiting.


Return Values

  • > 0
    The number of socket descriptors ready across all of the socket descriptor sets.
  • 0
    Time limit exceeded.
  • 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
    One of the socket descriptors is invalid.
  • TM_EINVAL
    numberOfSockets is greater than FD_SETSIZE.
  • TM_ENOBUFS
    Unable to allocate the requested number of file descriptors.


Table of Contents >> Programmer's Reference