pr_poll.rst (3311B)
1 PR_Poll 2 ======= 3 4 Detects when I/O is ready for a set of socket file descriptors. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prio.h> 13 14 PRInt32 PR_Poll( 15 PRPollDesc *pds, 16 PRIntn npds, 17 PRIntervalTime timeout); 18 19 20 Parameters 21 ~~~~~~~~~~ 22 23 The function has the following parameters: 24 25 ``pds`` 26 A pointer to the first element of an array of ``PRPollDesc`` 27 structures. 28 ``npds`` 29 The number of elements in the ``pds`` array. If this parameter is 30 zero, :ref:`PR_Poll` is equivalent to :ref:`PR_Sleep` with a timeout. 31 ``timeout`` 32 Amount of time the call will block waiting for I/O to become ready. 33 If this time expires without any I/O becoming ready, :ref:`PR_Poll` 34 returns zero. 35 36 37 Returns 38 ~~~~~~~ 39 40 The function returns one of these values: 41 42 - If successful, the function returns a positive number indicating the 43 number of ``PRPollDesc`` structures in ``pds`` that have events. 44 - The value 0 indicates the function timed out. 45 - The value -1 indicates the function failed. The reason for the 46 failure can be obtained by calling :ref:`PR_GetError`. 47 48 49 Description 50 ~~~~~~~~~~~ 51 52 This function returns as soon as I/O is ready on one or more of the 53 underlying socket objects. A count of the number of ready descriptors is 54 returned unless a timeout occurs, in which case zero is returned. 55 56 The ``in_flags`` field of the ``PRPollDesc`` data structure should be 57 set to the I/O events (readable, writable, exception, or some 58 combination) that the caller is interested in. On successful return, the 59 ``out_flags`` field of the ``PRPollDesc`` data structure is set to 60 indicate what kind of I/O is ready on the respective descriptor. 61 :ref:`PR_Poll` uses the ``out_flags`` fields as scratch variables during 62 the call. If :ref:`PR_Poll` returns 0 or -1, the ``out_flags`` fields do 63 not contain meaningful values and must not be used. 64 65 The ``PRPollDesc`` structure is defined as follows: 66 67 .. code:: 68 69 struct PRPollDesc { 70 PRFileDesc* fd; 71 PRInt16 in_flags; 72 PRInt16 out_flags; 73 }; 74 75 typedef struct PRPollDesc PRPollDesc; 76 77 The structure has the following fields: 78 79 ``fd`` 80 A pointer to a :ref:`PRFileDesc` object representing a socket or a 81 pollable event. This field can be set to ``NULL`` to indicate to 82 :ref:`PR_Poll` that this ``PRFileDesc object`` should be ignored. 83 84 .. note:: 85 86 On Unix, the ``fd`` field can be set to a pointer to any 87 :ref:`PRFileDesc` object, including one representing a file or a 88 pipe. Cross-platform applications should only set the ``fd`` field 89 to a pointer to a :ref:`PRFileDesc` object representing a socket or a 90 pollable event because on Windows the ``select`` function can only 91 be used with sockets. 92 ``in_flags`` 93 A bitwise ``OR`` of the following bit flags: 94 95 - :ref:`PR_POLL_READ`: ``fd`` is readable. 96 - :ref:`PR_POLL_WRITE`: ``fd`` is writable. 97 - :ref:`PR_POLL_EXCEPT`: ``fd`` has an exception condition. 98 99 ``out_flags`` 100 A bitwise ``OR`` of the following bit flags: 101 102 - :ref:`PR_POLL_READ` 103 - :ref:`PR_POLL_WRITE` 104 - :ref:`PR_POLL_EXCEPT` 105 - :ref:`PR_POLL_ERR`: ``fd`` has an error. 106 - :ref:`PR_POLL_NVAL`: ``fd`` is bad. 107 108 Note that the ``PR_POLL_ERR`` and ``PR_POLL_NVAL`` flags are used only 109 in ``out_flags``. The ``PR_POLL_ERR`` and ``PR_POLL_NVAL`` events are 110 always reported by :ref:`PR_Poll`.