335 lines
19 KiB
HTML
335 lines
19 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>pselect</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="pselect"></a> <a name="tag_03_485"></a><!-- pselect -->
|
|
<!--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_485_01"></a>NAME</h4>
|
|
|
|
<blockquote>pselect, select - synchronous I/O multiplexing</blockquote>
|
|
|
|
<h4><a name="tag_03_485_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/sys/select.h.html">sys/select.h</a>><br>
|
|
<br>
|
|
int pselect(int</tt> <i>nfds</i><tt>, fd_set *restrict</tt> <i>readfds</i><tt>,<br>
|
|
fd_set *restrict</tt> <i>writefds</i><tt>, fd_set *restrict</tt> <i>errorfds</i><tt>,<br>
|
|
const struct timespec *restrict</tt> <i>timeout</i><tt>,<br>
|
|
const sigset_t *restrict</tt> <i>sigmask</i><tt>);<br>
|
|
int select(int</tt> <i>nfds</i><tt>, fd_set *restrict</tt> <i>readfds</i><tt>,<br>
|
|
fd_set *restrict</tt> <i>writefds</i><tt>, fd_set *restrict</tt> <i>errorfds</i><tt>,<br>
|
|
struct timeval *restrict</tt> <i>timeout</i><tt>);<br>
|
|
void FD_CLR(int</tt> <i>fd</i><tt>, fd_set *</tt><i>fdset</i><tt>);<br>
|
|
int FD_ISSET(int</tt> <i>fd</i><tt>, fd_set *</tt><i>fdset</i><tt>);<br>
|
|
void FD_SET(int</tt> <i>fd</i><tt>, fd_set *</tt><i>fdset</i><tt>);<br>
|
|
void FD_ZERO(fd_set *</tt><i>fdset</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pselect</i>() function shall examine the file descriptor sets whose addresses are passed in the <i>readfds</i>,
|
|
<i>writefds</i>, and <i>errorfds</i> parameters to see whether some of their descriptors are ready for reading, are ready for
|
|
writing, or have an exceptional condition pending, respectively.</p>
|
|
|
|
<p>The <i>select</i>() function shall be equivalent to the <i>pselect</i>() function, except as follows:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>For the <i>select</i>() function, the timeout period is given in seconds and microseconds in an argument of type <b>struct
|
|
timeval</b>, whereas for the <i>pselect</i>() function the timeout period is given in seconds and nanoseconds in an argument of
|
|
type <b>struct timespec</b>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <i>select</i>() function has no <i>sigmask</i> argument; it shall behave as <i>pselect</i>() does when <i>sigmask</i> is a
|
|
null pointer.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Upon successful completion, the <i>select</i>() function may modify the object pointed to by the <i>timeout</i> argument.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>pselect</i>() and <i>select</i>() functions shall support regular files, terminal and pseudo-terminal devices, <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"> FIFOs, pipes, and sockets. The behavior
|
|
of <i>pselect</i>() and <i>select</i>() on file descriptors that refer to other types of file is unspecified.</p>
|
|
|
|
<p>The <i>nfds</i> argument specifies the range of descriptors to be tested. The first <i>nfds</i> descriptors shall be checked in
|
|
each set; that is, the descriptors from zero through <i>nfds</i>-1 in the descriptor sets shall be examined.</p>
|
|
|
|
<p>If the <i>readfds</i> argument is not a null pointer, it points to an object of type <b>fd_set</b> that on input specifies the
|
|
file descriptors to be checked for being ready to read, and on output indicates which file descriptors are ready to read.</p>
|
|
|
|
<p>If the <i>writefds</i> argument is not a null pointer, it points to an object of type <b>fd_set</b> that on input specifies the
|
|
file descriptors to be checked for being ready to write, and on output indicates which file descriptors are ready to write.</p>
|
|
|
|
<p>If the <i>errorfds</i> argument is not a null pointer, it points to an object of type <b>fd_set</b> that on input specifies the
|
|
file descriptors to be checked for error conditions pending, and on output indicates which file descriptors have error conditions
|
|
pending.</p>
|
|
|
|
<p>Upon successful completion, the <i>pselect</i>() or <i>select</i>() function shall modify the objects pointed to by the
|
|
<i>readfds</i>, <i>writefds</i>, and <i>errorfds</i> arguments to indicate which file descriptors are ready for reading, ready for
|
|
writing, or have an error condition pending, respectively, and shall return the total number of ready descriptors in all the output
|
|
sets. For each file descriptor less than <i>nfds</i>, the corresponding bit shall be set on successful completion if it was set on
|
|
input and the associated condition is true for that file descriptor.</p>
|
|
|
|
<p>If none of the selected descriptors are ready for the requested operation, the <i>pselect</i>() or <i>select</i>() function
|
|
shall block until at least one of the requested operations becomes ready, until the <i>timeout</i> occurs, or until interrupted by
|
|
a signal. The <i>timeout</i> parameter controls how long the <i>pselect</i>() or <i>select</i>() function shall take before timing
|
|
out. If the <i>timeout</i> parameter is not a null pointer, it specifies a maximum interval to wait for the selection to complete.
|
|
If the specified time interval expires without any requested operation becoming ready, the function shall return. If the
|
|
<i>timeout</i> parameter is a null pointer, then the call to <i>pselect</i>() or <i>select</i>() shall block indefinitely until at
|
|
least one descriptor meets the specified criteria. To effect a poll, the <i>timeout</i> parameter should not be a null pointer, and
|
|
should point to a zero-valued <b>timespec</b> structure.</p>
|
|
|
|
<p>The use of a timeout does not affect any pending timers set up by <a href="../functions/alarm.html"><i>alarm</i>()</a>, <a href=
|
|
"../functions/ualarm.html"><i>ualarm</i>()</a>, or <a href="../functions/setitimer.html"><i>setitimer</i>()</a>.</p>
|
|
|
|
<p>Implementations may place limitations on the maximum timeout interval supported. All implementations shall support a maximum
|
|
timeout interval of at least 31 days. If the <i>timeout</i> argument specifies a timeout interval greater than the
|
|
implementation-defined maximum value, the maximum value shall be used as the actual timeout value. Implementations may also 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>If <i>sigmask</i> is not a null pointer, then the <i>pselect</i>() function shall replace the signal mask of the process by the
|
|
set of signals pointed to by <i>sigmask</i> before examining the descriptors, and shall restore the signal mask of the process
|
|
before returning.</p>
|
|
|
|
<p>A descriptor shall be considered ready for reading when a call to an input function with O_NONBLOCK clear would not block,
|
|
whether or not the function would transfer data successfully. (The function might return data, an end-of-file indication, or an
|
|
error other than one indicating that it is blocked, and in each of these cases the descriptor shall be considered ready for
|
|
reading.)</p>
|
|
|
|
<p>A descriptor shall be considered ready for writing when a call to an output function with O_NONBLOCK clear would not block,
|
|
whether or not the function would transfer data successfully.</p>
|
|
|
|
<p>If a socket has a pending error, it shall be considered to have an exceptional condition pending. Otherwise, what constitutes an
|
|
exceptional condition is file type-specific. For a file descriptor for use with a socket, it is protocol-specific except as noted
|
|
below. For other file types it is implementation-defined. If the operation is meaningless for a particular file type,
|
|
<i>pselect</i>() or <i>select</i>() shall indicate that the descriptor is ready for read or write operations, and shall indicate
|
|
that the descriptor has no exceptional condition pending.</p>
|
|
|
|
<p>If a descriptor refers to a socket, the implied input function is the <a href="../functions/recvmsg.html"><i>recvmsg</i>()</a>
|
|
function with parameters requesting normal and ancillary data, such that the presence of either type shall cause the socket to be
|
|
marked as readable. The presence of out-of-band data shall be checked if the socket option SO_OOBINLINE has been enabled, as
|
|
out-of-band data is enqueued with normal data. If the socket is currently listening, then it shall be marked as readable if an
|
|
incoming connection request has been received, and a call to the <a href="../functions/accept.html"><i>accept</i>()</a> function
|
|
shall complete without blocking.</p>
|
|
|
|
<p>If a descriptor refers to a socket, the implied output function is the <a href="../functions/sendmsg.html"><i>sendmsg</i>()</a>
|
|
function supplying an amount of normal data equal to the current value of the SO_SNDLOWAT option for the socket. If a non-blocking
|
|
call to the <a href="../functions/connect.html"><i>connect</i>()</a> function has been made for a socket, and the connection
|
|
attempt has either succeeded or failed leaving a pending error, the socket shall be marked as writable.</p>
|
|
|
|
<p>A socket shall be considered to have an exceptional condition pending if a receive operation with O_NONBLOCK clear for the open
|
|
file description and with the MSG_OOB flag set would return out-of-band data without blocking. (It is protocol-specific whether the
|
|
MSG_OOB flag would be used to read out-of-band data.) A socket shall also be considered to have an exceptional condition pending if
|
|
an out-of-band data mark is present in the receive queue. Other circumstances under which a socket may be considered to have an
|
|
exceptional condition pending are protocol-specific and implementation-defined.</p>
|
|
|
|
<p>If the <i>readfds</i>, <i>writefds</i>, and <i>errorfds</i> arguments are all null pointers and the <i>timeout</i> argument is
|
|
not a null pointer, the <i>pselect</i>() or <i>select</i>() function shall block for the time specified, or until interrupted by a
|
|
signal. If the <i>readfds</i>, <i>writefds</i>, and <i>errorfds</i> arguments are all null pointers and the <i>timeout</i> argument
|
|
is a null pointer, the <i>pselect</i>() or <i>select</i>() function shall block until interrupted by a signal.</p>
|
|
|
|
<p>File descriptors associated with regular files shall always select true for ready to read, ready to write, and error
|
|
conditions.</p>
|
|
|
|
<p>On failure, the objects pointed to by the <i>readfds</i>, <i>writefds</i>, and <i>errorfds</i> arguments shall not be modified.
|
|
If the timeout interval expires without the specified condition being true for any of the specified file descriptors, the objects
|
|
pointed to by the <i>readfds</i>, <i>writefds</i>, and <i>errorfds</i> arguments shall have all bits set to 0.</p>
|
|
|
|
<p>File descriptor masks of type <b>fd_set</b> can be initialized and tested with <i>FD_CLR</i>(), <i>FD_ISSET</i>(),
|
|
<i>FD_SET</i>(), and <i>FD_ZERO</i>(). It is unspecified whether each of these is a macro or a function. If a macro definition is
|
|
suppressed in order to access an actual function, or a program defines an external identifier with any of these names, the behavior
|
|
is undefined.</p>
|
|
|
|
<p><i>FD_CLR</i>(<i>fd</i>, <i>fdsetp</i>) shall remove the file descriptor <i>fd</i> from the set pointed to by <i>fdsetp</i>. If
|
|
<i>fd</i> is not a member of this set, there shall be no effect on the set, nor will an error be returned.</p>
|
|
|
|
<p><i>FD_ISSET</i>(<i>fd</i>, <i>fdsetp</i>) shall evaluate to non-zero if the file descriptor <i>fd</i> is a member of the set
|
|
pointed to by <i>fdsetp</i>, and shall evaluate to zero otherwise.</p>
|
|
|
|
<p><i>FD_SET</i>(<i>fd</i>, <i>fdsetp</i>) shall add the file descriptor <i>fd</i> to the set pointed to by <i>fdsetp</i>. If the
|
|
file descriptor <i>fd</i> is already in this set, there shall be no effect on the set, nor will an error be returned.</p>
|
|
|
|
<p><i>FD_ZERO</i>(<i>fdsetp</i>) shall initialize the descriptor set pointed to by <i>fdsetp</i> to the null set. No error is
|
|
returned if the set is not empty at the time <i>FD_ZERO</i>() is invoked.</p>
|
|
|
|
<p>The behavior of these macros is undefined if the <i>fd</i> argument is less than 0 or greater than or equal to FD_SETSIZE, or if
|
|
<i>fd</i> is not a valid file descriptor, or if any of the arguments are expressions with side effects.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, the <i>pselect</i>() and <i>select</i>() functions shall return the total number of bits set in the
|
|
bit masks. Otherwise, -1 shall be returned, and <i>errno</i> shall be set to indicate the error.</p>
|
|
|
|
<p><i>FD_CLR</i>(), <i>FD_SET</i>(), and <i>FD_ZERO</i>() do not return a value. <i>FD_ISSET</i>() shall return a non-zero value if
|
|
the bit for the file descriptor <i>fd</i> is set in the file descriptor set pointed to by <i>fdset</i>, and 0 otherwise.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>Under the following conditions, <i>pselect</i>() and <i>select</i>() shall fail and set <i>errno</i> to:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EBADF]</dt>
|
|
|
|
<dd>One or more of the file descriptor sets specified a file descriptor that is not a valid open file descriptor.</dd>
|
|
|
|
<dt>[EINTR]</dt>
|
|
|
|
<dd>The function was interrupted before any of the selected events occurred and before the timeout interval expired.
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If SA_RESTART has been set for the interrupting signal, it is implementation-defined whether the function restarts or returns with
|
|
[EINTR]. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>An invalid timeout interval was specified.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>nfds</i> argument is less than 0 or greater than FD_SETSIZE.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
One of the specified file descriptors 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_485_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>In previous versions of the Single UNIX Specification, the <i>select</i>() function was defined in the <a href=
|
|
"../basedefs/sys/time.h.html"><i><sys/time.h></i></a> header. This is now changed to <a href=
|
|
"../basedefs/sys/select.h.html"><i><sys/select.h></i></a>. The rationale for this change was as follows: the introduction of
|
|
the <i>pselect</i>() function included the <a href="../basedefs/sys/select.h.html"><i><sys/select.h></i></a> header and the
|
|
<a href="../basedefs/sys/select.h.html"><i><sys/select.h></i></a> header defines all the related definitions for the
|
|
<i>pselect</i>() and <i>select</i>() functions. Backwards-compatibility to existing XSI implementations is handled by allowing <a
|
|
href="../basedefs/sys/time.h.html"><i><sys/time.h></i></a> to include <a href=
|
|
"../basedefs/sys/select.h.html"><i><sys/select.h></i></a>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="accept.html"><i>accept</i>()</a> , <a href="alarm.html"><i>alarm</i>()</a> , <a href=
|
|
"connect.html"><i>connect</i>()</a> , <a href="fcntl.html"><i>fcntl</i>()</a> , <a href="poll.html"><i>poll</i>()</a> , <a href=
|
|
"read.html"><i>read</i>()</a> , <a href="recvmsg.html"><i>recvmsg</i>()</a> , <a href="sendmsg.html"><i>sendmsg</i>()</a> , <a
|
|
href="setitimer.html"><i>setitimer</i>()</a> , <a href="ualarm.html"><i>ualarm</i>()</a> , <a href="write.html"><i>write</i>()</a>
|
|
, the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/sys/select.h.html"><i><sys/select.h></i></a>, <a href=
|
|
"../basedefs/sys/time.h.html"><i><sys/time.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4, Version 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from X/OPEN UNIX extension to BASE.</p>
|
|
|
|
<p>In the ERRORS section, the text has been changed to indicate that [EINVAL] is returned when <i>nfds</i> is less than 0 or
|
|
greater than FD_SETSIZE. It previously stated less than 0, or greater than or equal to FD_SETSIZE.</p>
|
|
|
|
<p>Text about <i>timeout</i> is moved from the APPLICATION USAGE section to the DESCRIPTION.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_485_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The Open Group Corrigendum U026/6 is applied, changing the occurrences of <i>readfs</i> and <i>writefs</i> in the
|
|
<i>select</i>() DESCRIPTION to be <i>readfds</i> and <i>writefds</i>.</p>
|
|
|
|
<p>Text referring to sockets is added to the DESCRIPTION.</p>
|
|
|
|
<p>The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are marked as part of the XSI STREAMS Option
|
|
Group.</p>
|
|
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>These functions are now mandatory.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>pselect</i>() function is added for alignment with IEEE Std 1003.1g-2000 and additional detail related to
|
|
sockets semantics is added to the DESCRIPTION.</p>
|
|
|
|
<p>The <i>select</i>() function now requires inclusion of <a href=
|
|
"../basedefs/sys/select.h.html"><i><sys/select.h></i></a>.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>select</i>() prototype for alignment with the ISO/IEC 9899:1999
|
|
standard.</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>
|
|
|