Detects when I/O is ready for a set of socket file descriptors.
Syntax
#include <prio.h> PRInt32 PR_Poll( PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
Parameters
The function has the following parameters:
pds
- A pointer to the first element of an array of
PRPollDesc
structures. npds
- The number of elements in the
pds
array. If this parameter is zero,PR_Poll
is equivalent toPR_Sleep
with a timeout. timeout
- Amount of time the call will block waiting for I/O to become ready. If this time expires without any I/O becoming ready,
PR_Poll
returns zero.
Returns
The function returns one of these values:
- If successful, the function returns a positive number indicating the number of
PRPollDesc
structures inpds
that have events. - The value 0 indicates the function timed out.
- The value -1 indicates the function failed. The reason for the failure can be obtained by calling
PR_GetError
.
Description
This function returns as soon as I/O is ready on one or more of the underlying socket objects. A count of the number of ready descriptors is returned unless a timeout occurs, in which case zero is returned.
The in_flags
field of the PRPollDesc
data structure should be set to the I/O events (readable, writable, exception, or some combination) that the caller is interested in. On successful return, the out_flags
field of the PRPollDesc
data structure is set to indicate what kind of I/O is ready on the respective descriptor. PR_Poll
uses the out_flags
fields as scratch variables during the call. If PR_Poll
returns 0 or -1, the out_flags
fields do not contain meaningful values and must not be used.
The PRPollDesc
structure is defined as follows:
struct PRPollDesc { PRFileDesc* fd; PRInt16 in_flags; PRInt16 out_flags; }; typedef struct PRPollDesc PRPollDesc;
The structure has the following fields:
fd
- A pointer to a
PRFileDesc
object representing a socket or a pollable event. This field can be set toNULL
to indicate toPR_Poll
that thisPRFileDesc object
should be ignored.On Unix, thefd
field can be set to a pointer to anyPRFileDesc
object, including one representing a file or a pipe. Cross-platform applications should only set thefd
field to a pointer to aPRFileDesc
object representing a socket or a pollable event because on Windows theselect
function can only be used with sockets. in_flags
- A bitwise
OR
of the following bit flags:
PR_POLL_READ
:fd
is readable.PR_POLL_WRITE
:fd
is writable.PR_POLL_EXCEPT
:fd
has an exception condition.
out_flags
- A bitwise
OR
of the following bit flags:
PR_POLL_READ
PR_POLL_WRITE
PR_POLL_EXCEPT
PR_POLL_ERR
:fd
has an error.PR_POLL_NVAL
:fd
is bad.
- Note that the
PR_POLL_ERR
andPR_POLL_NVAL
flags are used only inout_flags
. ThePR_POLL_ERR
andPR_POLL_NVAL
events are always reported byPR_Poll
.