friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/connec.htm

780 lines
23 KiB
HTML
Raw Normal View History

Add readme and dist folders
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>connect()--Establish Connection or Destination Address</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 -->
<!-- Unix8 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 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>connect()--Establish Connection or Destination Address</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;BSD 4.3 Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/socket.h&gt;
int connect(int <em>socket_descriptor</em>,
struct sockaddr *<em>destination_address</em>,
int <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>
<br>
<div class="box" style="width: 60%;">
<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 connect(int <em>socket_descriptor</em>,
const struct sockaddr *<em>destination_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>
<br>
<p>The <em>connect()</em> function is used to establish a connection on a
connection-oriented socket or establish the destination address on a
connectionless socket.</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 structures 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 that is to be connected.<br>
<br>
</dd>
<dt><strong>destination_address</strong></dt>
<dd>(Input) A pointer to a buffer of type <strong>struct sockaddr</strong> that
contains the destination address to which the socket is to be bound. 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>
</dd>
<dt><strong>address_length</strong></dt>
<dd>(Input) The length of the <em>destination_address</em>.</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>When the address type of the socket identified by the
<strong>socket_descriptor</strong> is AF_INET and is running IP over SNA, the
thread must have retrieve, insert, delete, and update authority to the APPC
device. When the thread does not have this level of authority, then an
<em>errno</em> of EACCES is returned.</p>
<h3>Return Value</h3>
<p><em>connect()</em> returns an integer. Possible values are:</p>
<ul>
<li>-1 (unsuccessful)</li>
<li>0 (successful)</li>
</ul>
<br>
<h3>Error Conditions</h3>
<p>When a <em>connect()</em> fails, <em>errno</em> can be set to one of the
following. For additional debugging information, see <a href=
"snadbg.htm">Debugging IP over SNA Configurations</a>.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>[EACCES]</em></td>
<td align="left" valign="top">Permission denied.
<p>This error code indicates one of the following:</p>
<ul>
<li>The process does not have the appropriate privileges to connect to the
address pointed to by the <em>destination_address</em> parameter.<br>
<br>
</li>
<li>The socket pointed to by <em>socket_descriptor</em> is using a
connection-oriented transport service, and the <em>destination_address</em>
parameter specifies a TCP/IP limited broadcast address (internet address of all
ones).<br>
</li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EADDRINUSE]</em></td>
<td align="left" valign="top">Address already in use.
<p>This error code indicates one of the following:</p>
<ul>
<li>The <em>socket_descriptor</em> parameter points to a connection-oriented
socket that has been bound to a local address that contained no wildcard
values, and the <em>destination_address</em> parameter specified an address
that matched the bound address.<br>
<br>
</li>
<li>The <em>socket_descriptor</em> parameter points to a socket that has been
bound to a local address that contained no wildcard values, and the
<em>destination_address</em> parameter (also containing no wildcard values)
specified an address that would have resulted in a connection with a non-unique
association.<br>
</li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EADDRNOTAVAIL]</em></td>
<td align="left" valign="top">Address not available.
<p>This error code is returned if
the <em>socket_descriptor</em> parameter points to a socket with an address
family of <samp>AF_INET</samp>
or <samp>AF_INET6</samp> and
either a port was not available or a route to the address specified by the
<em>destination_address</em> parameter could not be found.
</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EAFNOSUPPORT]</em></td>
<td align="left" valign="top">The type of socket is not supported in this
protocol family.
<p>The address family specified in the address structure pointed to by
<em>destination_address</em> parameter cannot be used with the socket pointed
to by the <em>socket_descriptor</em> parameter.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EALREADY]</em></td>
<td align="left" valign="top">Operation already in progress.
<p>A previous <em>connect()</em> function had already been issued for the
socket pointed to by the <em>socket_descriptor</em> parameter, and has yet to
be completed. This error code is returned only on sockets that use a
connection-oriented transport service.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EBADF]</em></td>
<td align="left" valign="top">Descriptor not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ECONNREFUSED]</em></td>
<td align="left" valign="top">The destination socket refused an attempted
connect operation.
<p>This error occurs when there is no application that is bound to the address
specified by the <em>destination_address</em> parameter.</p>
</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>destination_address</em> parameter.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EHOSTUNREACH]</em></td>
<td align="left" valign="top">A route to the remote host is not available.
<p>This error code is returned on sockets that use the <samp>AF_INET</samp>
and <samp>AF_INET6</samp> address families.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EINPROGRESS]</em></td>
<td align="left" valign="top">Operation in progress.
<p>The <em>socket_descriptor</em> parameter points to a socket that is marked
as nonblocking and the connection could not be completed immediately. This
error code is returned only on sockets that use a connection-oriented transport
service.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EINTR]</em></td>
<td align="left" valign="top">Interrupted function call.</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 specifies a length that is negative
or not valid for the address family.<br>
</li>
<li>The <samp>AF_INET</samp> or
<samp>AF_INET6</samp> socket is
of type <samp>SOCK_STREAM</samp>, and a previous <em>connect()</em> has already
completed unsuccessfully. Only one connection attempt is allowed on a
connection-oriented socket.
<p><strong>Note:</strong> For sockets that have an address family of
<samp>AF_UNIX</samp>, or <samp>AF_UNIX_CCSID</samp>, if a <em>connect()</em>
fails, a subsequent <em>connect()</em> is allowed, even if the transport
service being used is connection-oriented.</p>
</li>
<li><em>connect()</em> cannot be issued on the socket pointed to by the
<em>socket_descriptor</em> parameter because the socket is using a
connection-oriented transport service (with an address family of
<samp>AF_INET</samp> or
<samp>AF_INET6</samp>), and a
<em>shutdown()</em> that disabled the sending of data was previously
issued.<br>
<br>
</li>
<li>The destination address pointed to by the <em>destination_address</em>
parameter specified an address that was not valid.<br>
<br>
</li>
<li>The <em>socket_descriptor</em> points to a socket with an address family of
<samp>AF_UNIX_CCSID</samp>, and the CCSID specified in <em>sunc_qlg</em> in the
<strong>sockaddr_unc</strong> structure (pointed to by <em>local_address</em>)
cannot be converted to the current default CCSID for integrated file system
path names.<br>
<br>
</li>
<li>The <em>socket_descriptor</em> points to a socket with an address family of
<samp>AF_UNIX_CCSID</samp>, and there was an incomplete character or shift
state sequence at the end of <em>sunc_path</em> in the
<strong>sockaddr_unc</strong> structure (pointed to by
<em>local_address</em>).<br>
<br>
</li>
<li>The <em>socket_descriptor</em> points to a socket with an address family of
<samp>AF_UNIX_CCSID</samp>, and the <strong>sockaddr_unc</strong> structure
(pointed to by <em>local_address</em>) was not valid:<br>
<br>
<ul>
<li>The sunc_format was not set to SO_UNC_DEFAULT or SO_UNC_USE_QLG.<br>
<br>
</li>
<li>The sunc_zero was not initialized to zeros.<br>
<br>
</li>
<li>The sunc_format field was set to SO_UNC_USE_QLG and the sunc_qlg structure
was not valid:<br>
<br>
<ul>
<li>The path type was less than 0 or greater than 3.<br>
<br>
</li>
<li>The path length was less than 0 or out of bounds. For example, a single
byte path name was greater than 126 bytes or a double byte path name was
greater than 252 bytes.<br>
<br>
</li>
<li>A reserved field was not initialized to zeros.</li>
</ul>
</li>
</ul>
<br></li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EIO]</em></td>
<td align="left" valign="top">Input/output error.</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EISCONN]</em></td>
<td align="left" valign="top">A connection has already been established.
<p>This error code is returned only on sockets that use a connection-oriented
transport service.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ELOOP]</em></td>
<td align="left" valign="top">A loop exists in symbolic links encountered
during pathname resolution.
<p>This error code is only returned on sockets that use the
<samp>AF_UNIX</samp> or <samp>AF_UNIX_CCSID</samp> address family.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENAMETOOLONG]</em></td>
<td align="left" valign="top">File name too long.
<p>This error code is only returned on sockets that use the
<samp>AF_UNIX</samp> or <samp>AF_UNIX_CCSID</samp> address family.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENETDOWN]</em></td>
<td align="left" valign="top">The network is not currently available.</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENETUNREACH]</em></td>
<td align="left" valign="top">Cannot reach the destination network.
<p>This error code is returned for sockets that use the
<samp>AF_INET</samp> or <samp>AF_INET6</samp> address families, the address specified by the
<em>destination_address</em> parameter requires the use of a router, and the
socket option <samp>SO_DONTROUTE</samp> is currently set on.</p>
</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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOENT]</em></td>
<td align="left" valign="top">No such file or directory.
<p>This error code is only returned on sockets that use the
<samp>AF_UNIX</samp> or <samp>AF_UNIX_CCSID</samp> address family.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOSYS]</em></td>
<td align="left" valign="top">Function not implemented.
<p>This error code is only returned on sockets that use the
<samp>AF_UNIX</samp> and <samp>AF_UNIX_CCSID</samp> address families.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOTDIR]</em></td>
<td align="left" valign="top">Not a directory.</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.
<p>This error code is only returned on sockets that use the
<samp>AF_UNIX</samp> or <samp>AF_UNIX_CCSID</samp> address family.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EOPNOTSUPP]</em></td>
<td align="left" valign="top">Operation not supported.
<p><em>connect()</em> is not allowed on a passive socket (a socket for which a
<em>listen()</em> has been done).</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EPROTOTYPE]</em></td>
<td align="left" valign="top">The socket type or protocols are not compatible.
<p>This error code is only returned on sockets that use the
<samp>AF_UNIX</samp> or <samp>AF_UNIX_CCSID</samp> address family.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ETIMEDOUT]</em></td>
<td align="left" valign="top">A remote host did not respond within the timeout
period.
<p>This error code is returned when connection establishment times out. No
connection is established. A possible cause may be that the partner application
is bound to the address specified by the <em>destination_address</em>
parameter, but the partner application has not yet issued a
<em>listen()</em>.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EUNKNOWN]</em></td>
<td align="left" valign="top">Unknown system state.</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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EPROTO]</em></td>
<td align="left" valign="top">An underlying protocol error has occurred.</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><em>connect()</em> establishes an end-to-end connection. It can only be
issued once on sockets that have an address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp> and are of type
<samp>SOCK_STREAM</samp>. (If the <em>connect()</em> fails to successfully
establish the connection, you must close the socket and create a new socket if
you wish to try to establish a connection again.) For sockets of other address
families that are connection-oriented, you may simply try the
<em>connect()</em> again to the same or to a new address. <em>connect()</em>
can be issued on sockets of type <samp>SOCK_DGRAM</samp> and
<samp>SOCK_RAW</samp> multiple times. Each time <em>connect()</em> is issued,
it changes the destination address from which packets may be received and to
which packets may be sent.
<p><strong>Note:</strong> Issuing <em>connect()</em> on sockets of type
<samp>SOCK_DGRAM</samp> and <samp>SOCK_RAW</samp> is not recommended because of
dynamic route reassignment (picking a new route when a route that was
previously used is no longer available). When this reassignment occurs, the
next packet from the partner program can be received from a different IP
address than the address your application specified on the <em>connect()</em>.
This results in the data being discarded.</p>
</li>
<li>When a <em>connect()</em> is issued successfully on sockets with an address
family of <samp>AF_INET</samp>
or <samp>AF_INET6</samp> and
type of <samp>SOCK_DGRAM</samp>, errors relating to the unsuccessful delivery
of outgoing packets may be received as <em>errno</em> values. For example,
assume an application has issued the <em>connect()</em> for a
<em>destination_address</em> at which no server is currently bound for the port
specified in <em>destination_address</em>, and the application sends several
packets to that <em>destination_address</em>. Eventually, one of the
application output functions (for example, <em>send()</em>) will receive an
error <samp>[ECONNREFUSED]</samp>. If the application had not issued the
<em>connect()</em>, this diagnostic information would have been discarded.<br>
<br>
</li>
<li>A connectionless transport socket for which a <em>connect()</em> has been
issued can be disconnected by either setting the <em>destination_address</em>
parameter to NULL or setting the <em>address_length</em> parameter to zero, and
issuing another <em>connect()</em>.<br>
<br>
</li>
<li>For sockets that use a connection-oriented transport service and an address
family of <samp>AF_INET</samp>
or <samp>AF_INET6</samp> there
is a notion of a directed connect. A <strong>directed connect</strong> allows
two socket endpoints (socket A and socket B) to be connected without having a
passive socket to accept an incoming connection request. The idea is for both
sockets to bind to addresses. Socket A then issues a <em>connect()</em>
specifying the address that socket B is bound to, and socket B issues a
<em>connect()</em> specifying the address that socket A is bound to. At this
point sockets A and B are connected, and data transfer between the sockets can
now take place.<br>
<br>
</li>
<li>For sockets with an address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp>, the following is applicable:
<ul>
<li>For sockets of type <samp>SOCK_STREAM</samp> or <samp>SOCK_DGRAM</samp>, a
local port number is implicitly assigned to the socket if the
<em>connect()</em> is issued without previously issuing a <em>bind()</em>.</li>
</ul>
<br>
</li>
<li>For sockets with an address family of <samp>AF_INET</samp>, the following
is applicable:
<ul>
<li>If the destination address has an IP address that is set to zero, the
system selects an appropriate destination IP address using the following
algorithm:
<ul>
<li>If the socket is bound to an IP address of zero, a loopback address is
used. If a loopback interface is not configured (or the associated interface is
not active), the address of the next available interface that is active is
used. Otherwise, the destination IP address is not changed (and results in an
error on the <em>connect()</em>).<br>
<br>
</li>
<li>If the socket is bound to a nonzero IP address, then the IP address that
the socket is bound to is used.</li>
</ul>
<br>
</li>
<li>If the destination address has an internet IP address that is set to
<samp>INADDR_BROADCAST</samp> (hex 0xFFFFFFFF), the system selects an
appropriate destination IP address using the following algorithm:
<ul>
<li>If the socket is bound to an IP address of zero and:
<ul>
<li>It is using a connectionless transport service, then the first active
interface found that supports broadcast frames is used by the networking
software.<br>
</li>
<li>It is using a connection-oriented transport service, an error is returned
(<samp>[EACCES]</samp>).</li>
</ul>
<br>
</li>
<li>If the socket is bound to a nonzero IP address and is using a
connectionless transport service and:
<ul>
<li>The address that the socket is bound to denotes an interface that supports
broadcast frames (for example, not a loopback address), then the limited
broadcast address of the IP address that the socket is bound to is used.<br>
</li>
<li>The address that the socket is bound to is a loopback address, an error is
returned (<samp>[EINVAL]</samp>).</li>
</ul>
<br>
</li>
<li>If the socket is bound to a nonzero IP address and it is using a
connection-oriented transport service, an error is returned
(<samp>[EACCES]</samp>).</li>
</ul>
</li>
</ul>
<br>
</li>
<li>For sockets with an address family of <samp>AF_UNIX</samp> or
<samp>AF_UNIX_CCSID</samp>, the following is applicable:<br>
<ul>
<li>There is no implicit binding of an address to the socket. The socket is
unnamed if the <em>connect()</em> is issued without previously issuing a
<em>bind()</em>.<br>
<br>
</li>
<li>The process must have write access to the destination address and search
permission along all the components of the path.<br>
<br>
</li>
<li>For <samp>AF_UNIX</samp>, the path name is assumed to be in the default
coded character set identifier (CCSID) currently in effect for the job. For
<samp>AF_UNIX_CCSID</samp>, the path name is assumed to be in the format and
coded character set identifier (CCSID) specified in the
<strong>sockaddr_unc</strong> (pointed to by <em>local_address</em>).</li>
</ul>
<br>
<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>connect()</em> API is mapped to
<em>qso_connect98()</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="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="bind.htm">bind()</a>--Set Local Address for Socket<br>
<br>
</li>
<li><a href="accept.htm">accept()</a>--Wait for Connection Request and Make
Connection<br>
<br>
</li>
<li><a href="sendto.htm">sendto()</a>--Send Data<br>
<br>
</li>
<li><a href="sendms.htm">sendmsg()</a>--Send Data or Descriptors or Both</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>
Reference in New Issue Copy Permalink