PR_Poll

  • Revision slug: PR_Poll
  • Revision title: PR_Poll
  • Revision id: 110941
  • Created:
  • Creator: Rappo
  • Is current revision? No
  • Comment

Revision Content

{{template.Nsprapiref("I/O Functions")}}

Detects when I/O is ready for a set of 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 an array of PRPollDesc structures.

npds

The number of elements in the pds array. If this parameter is zero, PR_Poll is equivalent to 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, 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 PR_GetError.

Description

This function returns as soon as I/O is ready on one or more of the underlying file/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. This field can be set to NULL to indicate to PR_Poll that this PRFileDesc object should be ignored.
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 and PR_POLL_NVAL flags are used only in out_flags. The PR_POLL_ERR and PR_POLL_NVAL events are always reported by PR_Poll.

Revision Source

<p>
{{template.Nsprapiref("I/O Functions")}}
</p><p>Detects when I/O is ready for a set of file descriptors.
</p>
<h3 name="Syntax"> Syntax </h3>
<pre class="eval">#include &lt;prio.h&gt; 

<a href="en/PRInt32">PRInt32</a> PR_Poll(
  PRPollDesc *pds, 
  <a href="en/PRIntn">PRIntn</a> npds, 
  PRIntervalTime timeout);
</pre>
<h3 name="Parameters"> Parameters </h3>
<p>The function has the following parameters:
</p>
<dl><dt><code>pds</code>
</dt><dd>A pointer to an array of <code>PRPollDesc</code> structures.
</dd></dl>
<p><code>npds</code>
</p>
<dl><dd>The number of elements in the <code>pds</code> array. If this parameter is zero, <code>PR_Poll</code> is equivalent to <code><a href="en/PR_Sleep">PR_Sleep</a></code> with a timeout.
</dd><dt><code>timeout</code>
</dt><dd>Amount of time the call will block waiting for I/O to become ready. If this time expires without any I/O becoming ready, <code>PR_Poll</code> returns zero.
</dd></dl>
<h3 name="Returns"> Returns </h3>
<p>The function returns one of these values:
</p>
<ul><li> If successful, the function returns a positive number indicating the number of <code>PRPollDesc</code> structures in <code>pds</code> that have events.
</li><li> The value 0 indicates the function timed out.
</li><li> The value -1 indicates the function failed. The reason for the failure can be obtained by calling <code><a href="en/PR_GetError">PR_GetError</a></code>.
</li></ul>
<h3 name="Description"> Description </h3>
<p>This function returns as soon as I/O is ready on one or more of the underlying file/socket objects. A count of the number of ready descriptors is returned unless a timeout occurs, in which case zero is returned.
</p><p>The <code>in_flags</code> field of the <code>PRPollDesc</code> 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 <code>out_flags</code> field of the <code>PRPollDesc</code> data structure is set to indicate what kind of I/O is ready on the respective descriptor. <code>PR_Poll</code> uses the <code>out_flags</code> fields as scratch variables during the call. If <code>PR_Poll</code> returns 0 or -1, the <code>out_flags</code> fields do not contain meaningful values and must not be used.
</p><p>The <code>PRPollDesc</code> structure is defined as follows:
</p>
<pre class="eval">struct PRPollDesc {
  <a href="en/PRFileDesc">PRFileDesc</a>* fd;
  <a href="en/PRInt16">PRInt16</a> in_flags;
  <a href="en/PRInt16">PRInt16</a> out_flags;
};

typedef struct PRPollDesc PRPollDesc;
</pre>
<p>The structure has the following fields:
</p>
<dl><dt><code>fd</code>
</dt><dd>A pointer to a <code>PRFileDesc</code> object representing a socket. This field can be set to <code>NULL</code> to indicate to <code>PR_Poll</code> that this <code>PRFileDesc object</code> should be ignored.
</dd><dt><code>in_flags</code>
</dt><dd>A bitwise <code>OR</code> of the following bit flags:
</dd></dl>
<ul><li> <code>PR_POLL_READ</code>: <code>fd</code> is readable.
</li><li> <code>PR_POLL_WRITE</code>: <code>fd</code> is writable.
</li><li> <code>PR_POLL_EXCEPT</code>: <code>fd</code> has an exception condition.
</li></ul>
<dl><dt><code>out_flags</code>
</dt><dd>A bitwise <code>OR</code> of the following bit flags:
</dd></dl>
<ul><li> <code>PR_POLL_READ</code>
</li><li> <code>PR_POLL_WRITE</code>
</li><li> <code>PR_POLL_EXCEPT</code>
</li><li> <code>PR_POLL_ERR</code>: <code>fd</code> has an error.
</li><li> <code>PR_POLL_NVAL</code>: <code>fd</code> is bad.
</li></ul>
<dl><dd>Note that the <code>PR_POLL_ERR</code> and <code>PR_POLL_NVAL</code> flags are used only in <code>out_flags</code>. The <code>PR_POLL_ERR</code> and <code>PR_POLL_NVAL</code> events are always reported by <code>PR_Poll</code>.
</dd></dl>
Revert to this revision