355 lines
14 KiB
HTML
355 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>poll</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="poll"></a> <a name="tag_03_419"></a><!-- poll -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_419_01"></a>NAME</h4>
|
|
|
|
<blockquote>poll - input/output multiplexing</blockquote>
|
|
|
|
<h4><a name="tag_03_419_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/poll.h.html">poll.h</a>><br>
|
|
<br>
|
|
int poll(struct pollfd</tt> <i>fds</i><tt>[], nfds_t</tt> <i>nfds</i><tt>, int</tt> <i>timeout</i><tt>); <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_419_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>poll</i>() function provides applications with a mechanism for multiplexing input/output over a set of file descriptors.
|
|
For each member of the array pointed to by <i>fds</i>, <i>poll</i>() shall examine the given file descriptor for the event(s)
|
|
specified in <i>events</i>. The number of <b>pollfd</b> structures in the <i>fds</i> array is specified by <i>nfds</i>. The
|
|
<i>poll</i>() function shall identify those file descriptors on which an application can read or write data, or on which certain
|
|
events have occurred.</p>
|
|
|
|
<p>The <i>fds</i> argument specifies the file descriptors to be examined and the events of interest for each file descriptor. It is
|
|
a pointer to an array with one member for each open file descriptor of interest. The array's members are <b>pollfd</b> structures
|
|
within which <i>fd</i> specifies an open file descriptor and <i>events</i> and <i>revents</i> are bitmasks constructed by OR'ing a
|
|
combination of the following event flags:</p>
|
|
|
|
<dl compact>
|
|
<dt>POLLIN</dt>
|
|
|
|
<dd>Data other than high-priority data may be read without blocking.
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
For STREAMS, this flag is set in <i>revents</i> even if the message is of zero length. This flag shall be equivalent to POLLRDNORM
|
|
| POLLRDBAND. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</dd>
|
|
|
|
<dt>POLLRDNORM</dt>
|
|
|
|
<dd>Normal data may be read without blocking.
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
For STREAMS, data on priority band 0 may be read without blocking. This flag is set in <i>revents</i> even if the message is of
|
|
zero length. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</dd>
|
|
|
|
<dt>POLLRDBAND</dt>
|
|
|
|
<dd>Priority data may be read without blocking.
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
For STREAMS, data on priority bands greater than 0 may be read without blocking. This flag is set in <i>revents</i> even if the
|
|
message is of zero length. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</dd>
|
|
|
|
<dt>POLLPRI</dt>
|
|
|
|
<dd>High-priority data may be read without blocking.
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
For STREAMS, this flag is set in <i>revents</i> even if the message is of zero length. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
</dd>
|
|
|
|
<dt>POLLOUT</dt>
|
|
|
|
<dd>Normal data may be written without blocking.
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
For STREAMS, data on priority band 0 may be written without blocking. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></p>
|
|
</dd>
|
|
|
|
<dt>POLLWRNORM</dt>
|
|
|
|
<dd>Equivalent to POLLOUT.</dd>
|
|
|
|
<dt>POLLWRBAND</dt>
|
|
|
|
<dd>Priority data may be written.
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
For STREAMS, data on priority bands greater than 0 may be written without blocking. If any priority band has been written to on
|
|
this STREAM, this event only examines bands that have been written to at least once. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
</dd>
|
|
|
|
<dt>POLLERR</dt>
|
|
|
|
<dd>An error has occurred on the device or stream. This flag is only valid in the <i>revents</i> bitmask; it shall be ignored in
|
|
the <i>events</i> member.</dd>
|
|
|
|
<dt>POLLHUP</dt>
|
|
|
|
<dd>The device has been disconnected. This event and POLLOUT are mutually-exclusive; a stream can never be writable if a hangup has
|
|
occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually-exclusive. This flag is only valid in
|
|
the <i>revents</i> bitmask; it shall be ignored in the <i>events</i> member.</dd>
|
|
|
|
<dt>POLLNVAL</dt>
|
|
|
|
<dd>The specified <i>fd</i> value is invalid. This flag is only valid in the <i>revents</i> member; it shall ignored in the
|
|
<i>events</i> member.</dd>
|
|
</dl>
|
|
|
|
<p>The significance and semantics of normal, priority, and high-priority data are file and device-specific.</p>
|
|
|
|
<p>If the value of <i>fd</i> is less than 0, <i>events</i> shall be ignored, and <i>revents</i> shall be set to 0 in that entry on
|
|
return from <i>poll</i>().</p>
|
|
|
|
<p>In each <b>pollfd</b> structure, <i>poll</i>() shall clear the <i>revents</i> member, except that where the application
|
|
requested a report on a condition by setting one of the bits of <i>events</i> listed above, <i>poll</i>() shall set the
|
|
corresponding bit in <i>revents</i> if the requested condition is true. In addition, <i>poll</i>() shall set the POLLHUP, POLLERR,
|
|
and POLLNVAL flag in <i>revents</i> if the condition is true, even if the application did not set the corresponding bit in
|
|
<i>events</i>.</p>
|
|
|
|
<p>If none of the defined events have occurred on any selected file descriptor, <i>poll</i>() shall wait at least <i>timeout</i>
|
|
milliseconds for an event to occur on any of the selected file descriptors. If the value of <i>timeout</i> is 0, <i>poll</i>()
|
|
shall return immediately. If the value of <i>timeout</i> is -1, <i>poll</i>() shall block until a requested event occurs or until
|
|
the call is interrupted.</p>
|
|
|
|
<p>Implementations may place limitations on the granularity of timeout intervals. If the requested timeout interval requires a
|
|
finer granularity than the implementation supports, the actual timeout interval shall be rounded up to the next supported
|
|
value.</p>
|
|
|
|
<p>The <i>poll</i>() function shall not be affected by the O_NONBLOCK flag.</p>
|
|
|
|
<p>The <i>poll</i>() function shall support regular files, terminal and pseudo-terminal devices, FIFOs, pipes, sockets and <sup>[<a
|
|
href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
STREAMS-based files. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> The behavior of <i>poll</i>() on
|
|
elements of <i>fds</i> that refer to other types of file is unspecified.</p>
|
|
|
|
<p>Regular files shall always poll TRUE for reading and writing.</p>
|
|
|
|
<p>A file descriptor for a socket that is listening for connections shall indicate that it is ready for reading, once connections
|
|
are available. A file descriptor for a socket that is connecting asynchronously shall indicate that it is ready for writing, once a
|
|
connection has been established.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>poll</i>() shall return a non-negative value. A positive value indicates the total number of file
|
|
descriptors that have been selected (that is, file descriptors for which the <i>revents</i> member is non-zero). A value of 0
|
|
indicates that the call timed out and no file descriptors have been selected. Upon failure, <i>poll</i>() shall return -1 and set
|
|
<i>errno</i> to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>poll</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd>The allocation of internal data structures failed but a subsequent request may succeed.</dd>
|
|
|
|
<dt>[EINTR]</dt>
|
|
|
|
<dd>A signal was caught during <i>poll</i>().</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>nfds</i> argument is greater than {OPEN_MAX}, <sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> or one of the <i>fd</i> members refers to a STREAM or multiplexer
|
|
that is linked (directly or indirectly) downstream from a multiplexer. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_419_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<h5><a name="tag_03_419_06_01"></a>Checking for Events on a Stream</h5>
|
|
|
|
<p>The following example opens a pair of STREAMS devices and then waits for either one to become writable. This example proceeds as
|
|
follows:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Sets the <i>timeout</i> parameter to 500 milliseconds.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Opens the STREAMS devices <b>/dev/dev0</b> and <b>/dev/dev1</b>, and then polls them, specifying POLLOUT and POLLWRBAND as the
|
|
events of interest.</p>
|
|
|
|
<p>The STREAMS device names <b>/dev/dev0</b> and <b>/dev/dev1</b> are only examples of how STREAMS devices can be named; STREAMS
|
|
naming conventions may vary among systems conforming to the IEEE Std 1003.1-2001.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Uses the <i>ret</i> variable to determine whether an event has occurred on either of the two STREAMS. The <i>poll</i>() function
|
|
is given 500 milliseconds to wait for an event to occur (if it has not occurred prior to the <i>poll</i>() call).</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Checks the returned value of <i>ret</i>. If a positive value is returned, one of the following can be done:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>Priority data can be written to the open STREAM on priority bands greater than 0, because the POLLWRBAND event occurred on the
|
|
open STREAM ( <i>fds</i>[0] or <i>fds</i>[1]).</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Data can be written to the open STREAM on priority-band 0, because the POLLOUT event occurred on the open STREAM ( <i>fds</i>[0]
|
|
or <i>fds</i>[1]).</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the returned value is not a positive value, permission to write data to the open STREAM (on any priority band) is denied.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the POLLHUP event occurs on the open STREAM ( <i>fds</i>[0] or <i>fds</i>[1]), the device on the open STREAM has
|
|
disconnected.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<pre>
|
|
<tt>#include <stropts.h>
|
|
#include <poll.h>
|
|
...
|
|
struct pollfd fds[2];
|
|
int timeout_msecs = 500;
|
|
int ret;
|
|
int i;
|
|
<br>
|
|
/* Open STREAMS device. */
|
|
fds[0].fd = open("/dev/dev0", ...);
|
|
fds[1].fd = open("/dev/dev1", ...);
|
|
fds[0].events = POLLOUT | POLLWRBAND;
|
|
fds[1].events = POLLOUT | POLLWRBAND;
|
|
<br>
|
|
ret = poll(fds, 2, timeout_msecs);
|
|
<br>
|
|
if (ret > 0) {
|
|
/* An event on one of the fds has occurred. */
|
|
for (i=0; i<2; i++) {
|
|
if (fds[i].revents & POLLWRBAND) {
|
|
/* Priority data may be written on device number i. */
|
|
...
|
|
}
|
|
if (fds[i].revents & POLLOUT) {
|
|
/* Data may be written on device number i. */
|
|
...
|
|
}
|
|
if (fds[i].revents & POLLHUP) {
|
|
/* A hangup has occurred on device number i. */
|
|
...
|
|
}
|
|
}
|
|
}
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xsh_chap02_06.html#tag_02_06"><i>STREAMS</i></a> , <a href="getmsg.html"><i>getmsg</i>()</a> , <a href=
|
|
"putmsg.html"><i>putmsg</i>()</a> , <a href="read.html"><i>read</i>()</a> , <a href="select.html"><i>select</i>()</a> , <a href=
|
|
"write.html"><i>write</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/poll.h.html"><i><poll.h></i></a>, <a href="../basedefs/stropts.h.html"><i><stropts.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4, Version 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from X/OPEN UNIX extension to BASE.</p>
|
|
|
|
<p>The description of POLLWRBAND is updated.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_419_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>Text referring to sockets is added to the DESCRIPTION.</p>
|
|
|
|
<p>Text relating to the XSI STREAMS Option Group is marked.</p>
|
|
|
|
<p>The Open Group Corrigendum U055/3 is applied, updating the DESCRIPTION of POLLWRBAND.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|