summaryrefslogtreecommitdiffstats
path: root/docs/nspr/reference/pr_poll.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/nspr/reference/pr_poll.rst')
-rw-r--r--docs/nspr/reference/pr_poll.rst110
1 files changed, 110 insertions, 0 deletions
diff --git a/docs/nspr/reference/pr_poll.rst b/docs/nspr/reference/pr_poll.rst
new file mode 100644
index 0000000000..bc40620a2a
--- /dev/null
+++ b/docs/nspr/reference/pr_poll.rst
@@ -0,0 +1,110 @@
+PR_Poll
+=======
+
+Detects when I/O is ready for a set of socket file descriptors.
+
+
+Syntax
+------
+
+.. code::
+
+ #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, :ref:`PR_Poll` is equivalent to :ref:`PR_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, :ref:`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 in ``pds`` 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 :ref:`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.
+:ref:`PR_Poll` uses the ``out_flags`` fields as scratch variables during
+the call. If :ref:`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:
+
+.. code::
+
+ 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 :ref:`PRFileDesc` object representing a socket or a
+ pollable event. This field can be set to ``NULL`` to indicate to
+ :ref:`PR_Poll` that this ``PRFileDesc object`` should be ignored.
+
+ .. note::
+
+ On Unix, the ``fd`` field can be set to a pointer to any
+ :ref:`PRFileDesc` object, including one representing a file or a
+ pipe. Cross-platform applications should only set the ``fd`` field
+ to a pointer to a :ref:`PRFileDesc` object representing a socket or a
+ pollable event because on Windows the ``select`` function can only
+ be used with sockets.
+``in_flags``
+ A bitwise ``OR`` of the following bit flags:
+
+ - :ref:`PR_POLL_READ`: ``fd`` is readable.
+ - :ref:`PR_POLL_WRITE`: ``fd`` is writable.
+ - :ref:`PR_POLL_EXCEPT`: ``fd`` has an exception condition.
+
+``out_flags``
+ A bitwise ``OR`` of the following bit flags:
+
+ - :ref:`PR_POLL_READ`
+ - :ref:`PR_POLL_WRITE`
+ - :ref:`PR_POLL_EXCEPT`
+ - :ref:`PR_POLL_ERR`: ``fd`` has an error.
+ - :ref:`PR_POLL_NVAL`: ``fd`` is bad.
+
+Note that the ``PR_POLL_ERR`` and ``PR_POLL_NVAL`` flags are used only
+in ``out_flags``. The ``PR_POLL_ERR`` and ``PR_POLL_NVAL`` events are
+always reported by :ref:`PR_Poll`.