423 lines
13 KiB
HTML
423 lines
13 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>select()--Wait for Events on Multiple Sockets</title>
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- (C) Copyright IBM Corporation, 2004 -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Unix8 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- 020319 JTROUS Changes for Virus scanner, 98860, V5R3 -->
|
||
|
|
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
|
||
|
|
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
|
||
|
|
<!-- 030812 JTROUS Fix discussion on what will happen for scan, V5R3 -->
|
||
|
|
<!-- 040720 TIMCLARK Remove non-threadsafe file system usage note; -->
|
||
|
|
<!-- see PTR9A74361, v5r4 -->
|
||
|
|
<!-- 050414 JTROUS Add cross refernce to DosSetRelMaxFH, V5R4 -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!--End Header Records --><!-- Edited by Kersten Feb 02 -->
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
|
||
|
|
<h2>select()--Wait for Events on Multiple Sockets</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <sys/types.h>
|
||
|
|
#include <sys/time.h>
|
||
|
|
|
||
|
|
int select(int <em>max_descriptor</em>,
|
||
|
|
fd_set *<em>read_set</em>,
|
||
|
|
fd_set *<em>write_set</em>,
|
||
|
|
fd_set *<em>exception_set</em>,
|
||
|
|
struct timeval *<em>wait_time</em>)
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program Name: QP0LLIB1<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <em>select()</em> function is used to enable an application to multiplex
|
||
|
|
I/O. By using <em>select()</em>, an application with multiple interactive I/O
|
||
|
|
sources avoids blocking on one I/O stream while the other stream is ready.
|
||
|
|
Thus, for example, an application that receives inputs from two distinct
|
||
|
|
communication endpoints (using sockets) can use <em>select()</em> to sleep
|
||
|
|
until input is available from either of the sources. When input is available,
|
||
|
|
the application wakes up and receives an indication as to which descriptor is
|
||
|
|
ready for reading.</p>
|
||
|
|
|
||
|
|
<p>The application identifies descriptors to be checked for read, write, and
|
||
|
|
exception status and specifies a timeout value. If any of the specified
|
||
|
|
descriptors is ready for the specified event (read, write, or exception),
|
||
|
|
<em>select()</em> returns, indicating which descriptors are ready. Otherwise,
|
||
|
|
the process waits until one of the specified events occur or the wait times
|
||
|
|
out.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>max_descriptor</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Descriptors are numbered starting at zero, so the
|
||
|
|
<em>max_descriptor</em> parameter must specify a value that is one greater than
|
||
|
|
the largest descriptor number that is to be tested.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>read_set</strong></dt>
|
||
|
|
|
||
|
|
<dd>(I/O) A pointer to a set of descriptors that should be checked to see if
|
||
|
|
they are ready for reading. This parameter is a value-result field. Each
|
||
|
|
descriptor to be tested should be added to the set by issuing a FD_SET() macro.
|
||
|
|
If no descriptor is to be tested for reading, <em>read_set</em> should be NULL
|
||
|
|
(or point to an empty set). On return from the call, only those descriptors
|
||
|
|
that are ready to be read are in the set. FD_ISSET() should be used to test for
|
||
|
|
membership of a descriptor in the set.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>write_set</strong></dt>
|
||
|
|
|
||
|
|
<dd>(I/O) A pointer to a set of descriptors that should be checked to see if
|
||
|
|
they are ready for writing. This parameter is a value-result field. Each
|
||
|
|
descriptor to be tested should be added to the set by issuing a FD_SET() macro.
|
||
|
|
If no descriptor is to be tested for writing, <em>write_set</em> should be NULL
|
||
|
|
(or point to an empty set). On return from the call, only those descriptors
|
||
|
|
that are ready to be written are in the set. FD_ISSET() should be used to test
|
||
|
|
for membership of a descriptor in the set.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>exception_set</strong></dt>
|
||
|
|
|
||
|
|
<dd>(I/O) A pointer to a set of descriptors that should be checked for pending
|
||
|
|
exception events. This parameter is a value-result field. Each descriptor to be
|
||
|
|
tested should be added to the set by issuing a FD_SET() macro. If no descriptor
|
||
|
|
is to be tested for exceptions, <em>exception_set</em> should be NULL (or point
|
||
|
|
to an empty set). On return from the call, only those descriptors that have an
|
||
|
|
exception event are in the set. FD_ISSET() should be used to test for
|
||
|
|
membership of a descriptor in the set.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>wait_time</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A pointer to a structure which specifies the maximum time to wait
|
||
|
|
for at least one of the selection criteria to be met. A time to wait of 0 is
|
||
|
|
allowed; this returns immediately with the current status of the sockets. The
|
||
|
|
parameter may be specified even if NO descriptors are specified
|
||
|
|
(<em>select()</em> is being used as a timer). If <em>wait_time</em> is NULL,
|
||
|
|
<em>select()</em> blocks indefinitely. The structure pointed to by the
|
||
|
|
<em>wait_time</em> parameter is defined in
|
||
|
|
<strong><sys/time.h></strong>.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>No authorization is required.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p><em>select()</em> returns an integer. Possible values are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>-1 (unsuccessful)<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>0 (if the time limit expires)<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>n (total number of descriptors in all sets that met selection
|
||
|
|
criteria)</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> The <strong>timeval</strong> structure (pointed to by
|
||
|
|
<em>wait_time</em>) is unchanged.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When <em>select()</em> fails, <em>errno</em> can be set to one of the
|
||
|
|
following:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="20 80" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[EBADF]</em></td>
|
||
|
|
<td align="left" valign="top">Descriptor not valid.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[ENOTSAFE]</em></td>
|
||
|
|
<td align="left" valign="top">Function not allowed.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[EFAULT]</em></td>
|
||
|
|
<td align="left" valign="top">Bad address.
|
||
|
|
|
||
|
|
<p>The system detected an address which was not valid while attempting to
|
||
|
|
access the <em>read_set</em>, <em>write_set</em>, <em>exception_set</em>, or
|
||
|
|
<em>wait_time</em> parameter.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[EINTR]</em></td>
|
||
|
|
<td align="left" valign="top">Interrupted function call.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[EINVAL]</em></td>
|
||
|
|
<td align="left" valign="top">Parameter not valid.
|
||
|
|
|
||
|
|
<p>This error code indicates one of the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The <em>max_descriptor</em> parameter specifies a negative value or a value
|
||
|
|
greater than [FD_SETSIZE].<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <em>wait_time</em> parameter specifies a time value which was not
|
||
|
|
valid.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[EIO]</em></td>
|
||
|
|
<td align="left" valign="top">Input/output error.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[ENOTSUP]</em></td>
|
||
|
|
<td align="left" valign="top">Operation not supported.
|
||
|
|
|
||
|
|
<p>The operation, though supported in general, is not supported for the
|
||
|
|
requested object or the requested arguments.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[EUNKNOWN]</em></td>
|
||
|
|
<td align="left" valign="top">Unknown system state.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPE3418 E</td>
|
||
|
|
<td align="left" valign="top">Possible APAR condition or hardware failure.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
||
|
|
<td align="left" valign="top">Error(s) occurred during running of &1
|
||
|
|
API.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
|
&2 ended. Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFA081 E</td>
|
||
|
|
<td align="left" valign="top">Unable to set return value or error code.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFA0D4 E</td>
|
||
|
|
<td align="left" valign="top">File system error occurred.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
The <a href="poll.htm">poll()</a> API is more efficient than the <em>select()</em> API and
|
||
|
|
therefore <em>poll()</em> is always recommended over <em>select()</em>.
|
||
|
|
<img src="deltaend.gif" alt="End of change"><br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>An application program must include the header file
|
||
|
|
<strong><sys/types.h></strong> to use <em>select()</em>. The header file
|
||
|
|
contains the type and macro definitions needed to use <em>select()</em>. The
|
||
|
|
maximum number of descriptors that can be selected is defined by FD_SETSIZE.
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
See <a href="dossrmfh.htm"><strong>DosSetRelMaxFH()</strong></a>
|
||
|
|
for additional considerations when <em>select()</em>
|
||
|
|
and <em>DosSetRelMaxFH()</em> are used within the same process.
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
<p>The following macros can be used to manipulate descriptor sets:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><samp>FD_ZERO</samp>(fd_set *<em>p</em>) removes all descriptors from the
|
||
|
|
set specified by <em>p</em>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><samp>FD_CLR</samp>(int <em>n</em>, fd_set *<em>p</em>) removes descriptor
|
||
|
|
<em>n</em> from the set specified by <em>p</em>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><samp>FD_SET</samp>(int <em>n</em>, fd_set *<em>p</em>) adds descriptor
|
||
|
|
<em>n</em> to the set specified by <em>p</em>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><samp>FD_ISSET</samp>(int <em>n</em>, fd_set *<em>p</em>) returns a nonzero
|
||
|
|
value if descriptor <em>n</em> is returned in the set specified by <em>p</em>;
|
||
|
|
otherwise, a zero value is returned.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> Values of type fd_set should only be manipulated by
|
||
|
|
the macros supplied in the <strong><sys/types.h></strong> header
|
||
|
|
file.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A descriptor can be returned in the set specified by <em>read_set</em> to
|
||
|
|
indicate one of the following:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>An error event exists on the descriptor.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A connection request is pending on a socket descriptor. This technique can
|
||
|
|
be used to wait for connections on multiple socket descriptors. When a
|
||
|
|
listening socket is returned in the set specified by <em>read_set</em>, an
|
||
|
|
application can then issue an <em>accept()</em> call to accept the
|
||
|
|
connection.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>No data can be read from the underlying instance represented by the
|
||
|
|
descriptor. For example, a socket descriptor for which a <em>shutdown()</em>
|
||
|
|
call has been done to disable the reception of data.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A descriptor can be returned in the set specified by <em>write_set</em> to
|
||
|
|
indicate one of the following:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Completion of a non-blocking <em>connect()</em> call on a socket
|
||
|
|
descriptor. This allows an application to set a socket descriptor to
|
||
|
|
nonblocking (with <em>fcntl()</em> or <em>ioctl()</em>), issue a
|
||
|
|
<em>connect()</em> and receive <samp>[EINPROGRESS]</samp>, and then use
|
||
|
|
<em>select()</em> to verify that the connection has completed.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>No data can be written to the underlying instance represented by the
|
||
|
|
descriptor (for example, a socket descriptor for which a <em>shutdown()</em>
|
||
|
|
has been done to disable the sending of data).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>When a <em>write()</em> can be successfully issued without blocking (or,
|
||
|
|
for nonblocking, so it does not return <samp>[EWOULDBLOCK]</samp>).</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A socket descriptor is returned in the set specified by
|
||
|
|
<em>exception_set</em> to indicate that out-of-band data has arrived at the
|
||
|
|
socket. This is only supported for connection-oriented sockets with an address
|
||
|
|
family of <samp>AF_INET</samp>
|
||
|
|
or <samp>AF_INET6</samp>.
|
||
|
|
<br>
|
||
|
|
<br></li>
|
||
|
|
<li>
|
||
|
|
Unpredictable results will appear if
|
||
|
|
this function or any of its associated type and macro definitions are used
|
||
|
|
in a thread executing one of the scan-related exit programs
|
||
|
|
(or any of its' created threads). See
|
||
|
|
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Programs</a> and
|
||
|
|
<a href="ifscloseexit.htm">Integrated File System Scan on Close Exit Programs</a>
|
||
|
|
for more information.
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="poll.htm">poll()</a>--Wait for events on Multiple
|
||
|
|
Sockets</li>
|
||
|
|
<li><a href="dossrmfh.htm"><strong>DosSetRelMaxFH()</strong></a>--Change Maximum
|
||
|
|
Number of File Descriptors</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V3R1
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
||
|
|
<a href="unix.htm">UNIX-Type APIs</a> |
|
||
|
|
<a href="aplist.htm">APIs by category</a> </td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|