📄 poll.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-2003 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, 2003 Edition<br>Copyright © 2001-2003 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 certainevents 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 isa pointer to an array with one member for each open file descriptor of interest. The array's members are <b>pollfd</b> structureswithin which <i>fd</i> specifies an open file descriptor and <i>events</i> and <i>revents</i> are bitmasks constructed by OR'ing acombination 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 ofzero 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 themessage 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 onthis 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 inthe <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 hasoccurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually-exclusive. This flag is only valid inthe <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 onreturn 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 applicationrequested a report on a condition by setting one of the bits of <i>events</i> listed above, <i>poll</i>() shall set thecorresponding 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 untilthe call is interrupted.</p><p>Implementations may place limitations on the granularity of timeout intervals. If the requested timeout interval requires afiner granularity than the implementation supports, the actual timeout interval shall be rounded up to the next supportedvalue.</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>[<ahref="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>() onelements 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 connectionsare available. A file descriptor for a socket that is connecting asynchronously shall indicate that it is ready for writing, once aconnection 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 filedescriptors that have been selected (that is, file descriptors for which the <i>revents</i> member is non-zero). A value of 0indicates 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 multiplexerthat 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 asfollows:</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 theevents 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; STREAMSnaming 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>() functionis 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 theopen 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 hasdisconnected.</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>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -