mozilla

Revision 110946 of PR_Poll

  • Revision slug: PR_Poll
  • Revision title: PR_Poll
  • Revision id: 110946
  • Created:
  • Creator: newacct
  • Is current revision? Yes
  • Comment 4 words added

Revision Content

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

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 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 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 to NULL to indicate to PR_Poll that this PRFileDesc object should be ignored.
On Unix, the fd field can be set to a pointer to any PRFileDesc object, including one representing a file or a pipe. Cross-platform applications should only set the fd field to a pointer to a 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:
  • 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>{{ Nsprapiref("I/O Functions") }}</p>
<p>Detects when I/O is ready for a set of socket file descriptors.</p>
<h3 id="Syntax" name="Syntax">Syntax</h3>
<pre class="eval">#include &lt;prio.h&gt; 

<a href="/en/PRInt32" title="en/PRInt32">PRInt32</a> PR_Poll(
  PRPollDesc *pds, 
  <a href="/en/PRIntn" title="en/PRIntn">PRIntn</a> npds, 
  PRIntervalTime timeout);
</pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<p>The function has the following parameters:</p>
<dl> <dt><code>pds</code></dt> <dd>A pointer to the first element of an array of <code>PRPollDesc</code> structures.</dd> <dt><code>npds</code></dt> <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" title="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 id="Returns" 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" title="en/PR_GetError">PR_GetError</a></code>.</li>
</ul>
<h3 id="Description" name="Description">Description</h3>
<p>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.</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" title="en/PRFileDesc">PRFileDesc</a>* fd;
  <a href="/en/PRInt16" title="en/PRInt16">PRInt16</a> in_flags;
  <a href="/en/PRInt16" title="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 or a pollable event. 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. <div class="note">On Unix, the <code>fd</code> field can be set to a pointer to any <code>PRFileDesc</code> object, including one representing a file or a pipe. Cross-platform applications should only set the <code>fd</code> field to a pointer to a <code>PRFileDesc</code> object representing a socket or a pollable event because on Windows the <code>select</code> function can only be used with sockets.</div> </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