ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/accept.htm

529 lines
14 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>accept()--Wait for Connection Request and Make Connection</title>
<!-- Begin Header Records -->
<!-- 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Edited by Kersten Feb 02 -->
<!-- 041207 MULLENBA Added SO_ACCEPTECONNABORTED -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a> <!--Java sync-link-->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>accept()--Wait for Connection Request and Make Connection</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;BSD 4.3 Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/socket.h&gt;
int accept(int <em>socket_descriptor</em>,
struct sockaddr *<em>address</em>,
int *<em>address_length</em>)
</pre>
&nbsp;&nbsp;Service Program Name: QSOSRV1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<br>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;<a href="_xopen_source.htm">UNIX 98 Compatible Syntax</a><br>
<pre>
#define _XOPEN_SOURCE 520
#include &lt;sys/socket.h&gt;
int accept(int <em>socket_descriptor</em>,
struct sockaddr *<em>address</em>,
socklen_t *<em>address_length</em>)
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QSOSRV1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <em>accept()</em> function is used to wait for connection requests.
<em>accept()</em> takes the first connection request on the queue of pending
connection requests and creates a new socket to service the connection
request.</p>
<p><em>accept()</em> is used with connection-oriented socket types, such as
<samp>SOCK_STREAM</samp>.</p>
<p>There are two versions of
the API, as shown above. The base i5/OS API uses BSD 4.3 structures and
syntax. The other uses syntax and struc<SUP>(TM)</SUP>tures compatible with the UNIX 98
programming interface specifications. You can select the UNIX 98 compatible
interface with the <a href="_xopen_source.htm">_XOPEN_SOURCE</a> macro.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>socket_descriptor</strong></dt>
<dd>(Input) The descriptor of the socket on which to wait.<br>
<br>
</dd>
<dt><strong>address</strong></dt>
<dd>(Output) A pointer to a buffer of type <strong>struct sockaddr</strong> in
which the address from which the connection request was received is stored. The
structure <strong>sockaddr</strong> is defined in
<strong>&lt;sys/socket.h&gt;</strong>.
<p> The BSD 4.3 structure is:</p>
<pre>
struct sockaddr {
u_short sa_family;
char sa_data[14];
};
</pre>
<p>The BSD 4.4/UNIX 98 compatible structure is:</p>
<pre>
typedef uchar sa_family_t;
struct sockaddr {
uint8_t sa_len;
sa_family_t sa_family;
char sa_data[14];
};
</pre>
<p>The BSD 4.4 <em>sa_len</em> field is the length of the address. The
<em>sa_family</em> field identifies the address family to which the address
belongs, and <em>sa_data</em> is the address whose format is dependent on the
address family.</p>
<p><strong>Note:</strong> See the usage notes about using different address
families with <strong>sockaddr_storage</strong>.</p>
</dd>
<dt><strong>address_length</strong></dt>
<dd>(Input/output) This parameter is a value-result field. The caller passes a
pointer to the length of the <em>address</em> parameter. On return from the
call, <em>address_length</em> contains the actual length of the address from
which the connection request was received.</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>When the socket identified by the <strong>socket_descriptor</strong> is of
type AF_INET and a connection indication request is received over an APPC
device, the thread must have adequate authority. The thread must have retrieve,
insert, delete, and update authority to the APPC device. When the thread does
not have this level of authority, an <em>errno</em> of EACCES is returned.</p>
<br>
<h3>Return Value</h3>
<p><em>accept()</em> returns an integer. Possible values are:</p><ul>
<li>-1 (unsuccessful)<br>
<br>
</li>
<li>n (successful), where n is a socket descriptor.</li>
</ul>
<br>
<h3>Error Conditions</h3>
<p>When <em>accept()</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>[EACCES]</em></td>
<td align="left" valign="top">Permission denied.
<p>A connection indication request was received on the socket referenced by the
<em>socket_descriptor</em> parameter, but the process that issued the
<em>accept()</em> did not have the appropriate privileges required to handle
the request. The connection indication request is reset by the system.</p>
</td>
</tr>
<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>[ECONNABORTED]</em></td>
<td align="left" valign="top">Connection ended abnormally.
<p>An <em>accept()</em> was issued on a socket for which receives have been
disallowed (due to a <em>shutdown()</em> call).</p>
<p>This also could be encountered if time elapsed since a successful
<em>Rbind()</em> is greater than the margin allowed by the associated <em>SOCKS
server</em>.</p>
<p><img src="delta.gif" alt="Start of change">An <em>accept()</em> was
issued on a socket in blocking mode and
one or more connections have been reset and there are no acceptable connections
in the queue. This is only valid if socket option <samp>SO_ACCEPTECONNABORTED</samp>
was enabled for the listening socket.<img src="deltaend.gif" alt="End of change"></p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EFAULT]</em></td>
<td align="left" valign="top">Bad address.
<p>System detected an address which was not valid while attempting to access
the <em>address</em> or <em>address_length</em> parameters.</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>address_length</em> parameter is set to a value that is less than
zero, and the <em>address</em> parameter is set to a value other than a NULL
pointer.<br>
<br>
</li>
<li>A <em>listen()</em> has not been issued against the socket referenced by
the <em>socket_descriptor</em> parameter.<br><br></li>
</ul>
</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>[EMFILE]</em></td>
<td align="left" valign="top">Too many descriptions for this
process.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENFILE]</em></td>
<td align="left" valign="top">Too many descriptions in system.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOBUFS]</em></td>
<td align="left" valign="top">There is not enough buffer space for
the requested operation.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOTSOCK]</em></td>
<td align="left" valign="top">The specified descriptor does not
reference a socket.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EOPNOTSUPP]</em></td>
<td align="left" valign="top">Operation not supported.
<p>The <em>socket_descriptor</em> parameter references a socket that does not
support the <em>accept()</em>. The <em>accept()</em> is only valid on sockets
that are connection-oriented (for example, type of
<samp>SOCK_STREAM</samp>).</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EUNATCH]</em></td>
<td align="left" valign="top">The protocol required to support the
specified address family is not available at this time.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EUNKNOWN]</em></td>
<td align="left" valign="top">Unknown system state.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EWOULDBLOCK]</em></td>
<td align="left" valign="top">Operation would have caused the
thread to be suspended.<br>
<br>
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3418 E</td>
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;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>
</table>
<br>
<br>
<h3>Usage Notes</h3>
<ol>
<li>If the <em>address</em> parameter is set to a NULL pointer or the
<em>address_length</em> parameter points to an integer which has a value that
is equal to zero, the address from which the connection request was received is
not returned.<br>
<br>
</li>
<li>If the length of the address to be returned exceeds the length of the
<em>address</em> parameter, the returned address is truncated.<br>
<br>
</li>
<li>The following are inherited by the descriptor returned by the accept()
call:<br>
<br>
<ul>
<li>All socket options with a level of SOL_SOCKET.<br>
<br>
</li>
<li>The status flags:<br>
<br>
<ul>
<li>Blocking flag (set/reset either by the <em>ioctl()</em> call with the
FIONBIO request or by the <em>fcntl()</em> call with the F_SETFL command and
the status flag set to O_NONBLOCK).<br>
<br>
</li>
<li>Asynchronous flag (set/reset either by the <em>ioctl()</em> call with the
FIOASYNC request or by the <em>fcntl()</em> call with the F_SETFL command and
the status flag set to FASYNC).<br>
<br>
</li>
</ul>
</li>
<li>The process ID or process group ID that is to receive SIGIO or SIGURG
signals (set/reset by either the <em>ioctl()</em> call with the FIOSETOWN or
the SIOCSPGRP request, or by the <em>fcntl()</em> call with the F_SETOWN
command).<br>
<br>
</li>
</ul>
</li>
<li>Closing a socket causes any queued but unaccepted connection requests to be
reset.<br>
<br>
</li>
<li>The structure
<strong>sockaddr</strong> is a generic structure used for any address family
but it is only 16 bytes long. The actual address returned for some address
families may be much larger. You should declare storage for the address with
the structure <strong>sockaddr_storage</strong>. This structure is large enough
and aligned for any protocol-specific structure. It may then be cast as
<strong>sockaddr</strong> structure for use on the APIs. The <em>ss_family</em>
field of the <strong>sockaddr_storage</strong> will always align with the
family field of any protocol-specific structure. The BSD 4.3 structure is:<br>
<br>
<pre>
#define _SS_MAXSIZE 304
#define _SS_ALIGNSIZE (sizeof (char*))
#define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t))
#define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+
_SS_PAD1SIZE + _SS_ALIGNSIZE))
struct sockaddr_storage {
sa_family_t ss_family;
char _ss_pad1[_SS_PAD1SIZE];
char* _ss_align;
char _ss_pad2[_SS_PAD2SIZE];
};
</pre>
The BSD 4.4/UNIX 98 compatible structure is:<br>
<br>
<pre>
#define _SS_MAXSIZE 304
#define _SS_ALIGNSIZE (sizeof (char*))
#define _SS_PAD1SIZE (_SS_ALIGNSIZE - (sizeof(uint8_t) + sizeof(sa_family_t)))
#define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(uint8_t) + sizeof(sa_family_t)+
_SS_PAD1SIZE + _SS_ALIGNSIZE))
struct sockaddr_storage {
uint8_t ss_len;
sa_family_t ss_family;
char _ss_pad1[_SS_PAD1SIZE];
char* _ss_align;
char _ss_pad2[_SS_PAD2SIZE];
};
</pre>
</li>
<li>If the socket is using an address family of <samp>AF_UNIX</samp>, the
address (which is a path name) is returned in the default coded character set
identifier (CCSID) currently in effect for the job.<br>
<br>
</li>
<li>If the socket is using an address family of <samp>AF_UNIX_CCSID</samp>, the
output structure sockaddr_unc defines the format and coded character set
identifier (CCSID) of the address (which is a path name).<br>
<br>
</li>
<li>If a successful <em>Rbind()</em> has been performed on the listening
socket, then a new connection is not returned, but rather an inbound connection
occurs on the same listening socket. The descriptor number returned is
different, but it actually refers to the same connection referred to by the
listening socket.<br>
<br>
</li>
<li>When you develop in C-based
languages and an application is compiled with the _XOPEN_SOURCE macro defined
to the value 520 or greater, the <em>accept()</em> API is mapped to
<em>qso_accept98()</em>.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li><a href=
"_xopen_source.htm">_XOPEN_SOURCE</a>--Using _XOPEN_SOURCE for the UNIX 98
compatible interface<br>
<br>
</li>
<li><a href="bind.htm">bind()</a>--Set Local Address for Socket<br>
<br>
</li>
<li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command<br>
<br>
</li>
<li><a href="ioctl.htm">ioctl()</a>--Perform I/O Control Request<br>
<br>
</li>
<li><a href="listen.htm">listen()</a>--Invite Incoming Connections
Requests</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>