poll

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int poll (
struct pollfd TM_FAR * fds,
int nfds,
int timeOut
);


Function Description

poll() performs a similar task to select(). It checks whether a set of socket descriptors has become ready for I/O, i.e. it checks if any of the socket descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. The nfds argument specifies the number of socket descriptors to be tested. Its value is the number of elements in the struct pollfd array. The socket descriptor fd, and events fields in each element of the struct pollfd array are examined. On return, poll() sets each revents field of the struct pollfd array with the events that actually occurred. The return value from the call to poll() is the number of ready socket descriptors. The timeOut parameter specifies a length of time (in milliseconds) to wait for an event to occur before exiting this routine. If the total time is less than one millisecond, poll() 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()). Right now the only supported timeOut value is 0.


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



Structure struct pollfd

Each element in the array fds is of the following form:

struct pollfd {
    int fd;           /* file descriptor */
    short events;     /* requested events */
    short revents;    /* returned events */
};


The events and revents parameters are a bitwise OR of the following flags:

Flag Meaning
TM_POLLIN Received data is available.
TM_POLLPRI Urgent, out-of-band data is available.
TM_POLLOUT There is room in the socket to send data.
TM_POLLERR There is an error condition (output only).
TM_POLLNVAL Invalid request (output only).


Parameters

  • fds
    Array of struct pollfd.
  • nfds
    Number of elements in the fds array.
  • timeOut
    Length of time to wait (in milliseconds) for an event before exiting. Only supported value is 0


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_EINVAL
    timeOut is greater than 0.


Table of Contents >> Programmer's Reference