809 lines
24 KiB
HTML
809 lines
24 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>recvmsg()--Receive a Message Over a Socket</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. -->
|
||
|
|
<!-- Unix8 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
||
|
|
<!-- 031006 JTROUS Changes for scan processing, V5R3, DCR 98680 -->
|
||
|
|
<!-- 031006 JTROUS Add usage note about binary read of taken desc, v5r3-->
|
||
|
|
<!-- 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>recvmsg()--Receive a Message Over a Socket</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
BSD 4.3 Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <sys/types.h>
|
||
|
|
#include <sys/socket.h>
|
||
|
|
|
||
|
|
int recvmsg(int <em>socket_descriptor</em>,
|
||
|
|
struct msghdr *<em>message_structure</em>,
|
||
|
|
int <em>flags</em>)
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program Name: QSOSRV1<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
<a href="_xopen_source.htm">UNIX 98 Compatible Syntax</a><br>
|
||
|
|
<pre>
|
||
|
|
#define _XOPEN_SOURCE 520
|
||
|
|
#include <sys/socket.h>
|
||
|
|
|
||
|
|
ssize_t recvmsg(int <em>socket_descriptor</em>,
|
||
|
|
struct msghdr *<em>message_structure</em>,
|
||
|
|
int <em>flags</em>)
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program Name: QSOSRV1<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <em>recvmsg()</em> function is used to receive data or descriptors or
|
||
|
|
both through a connected or unconnected 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 socket descriptor that is to be read from.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>message_structure</strong></dt>
|
||
|
|
|
||
|
|
<dd>(I/O) The pointer to the message structure that contains the following:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The address from which the message was received<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The vector array in which the data received is stored<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The ancillary data/access
|
||
|
|
rights list in which the received descriptors are stored</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
The structure pointed to by the <em>message_structure</em> parameter is defined
|
||
|
|
in <strong><sys/socket.h></strong>.
|
||
|
|
|
||
|
|
<p>The BSD 4.3 structure is:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
struct msghdr {
|
||
|
|
caddr_t msg_name;
|
||
|
|
int msg_namelen;
|
||
|
|
struct iovec *msg_iov;
|
||
|
|
int msg_iovlen;
|
||
|
|
caddr_t msg_accrights;
|
||
|
|
int msg_accrightslen;
|
||
|
|
};
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>The BSD 4.4/UNIX 98 compatible structure is:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
struct msghdr {
|
||
|
|
void *msg_name;
|
||
|
|
socklen_t msg_namelen;
|
||
|
|
struct iovec *msg_iov;
|
||
|
|
int msg_iovlen;
|
||
|
|
void *msg_control; /* Set to NULL if not needed */
|
||
|
|
socklen_t msg_controllen; /* Set to 0 if not needed */
|
||
|
|
int msg_flags;
|
||
|
|
};
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The <em>msg_name</em> and <em>msg_namelen</em> fields contain the address
|
||
|
|
and address length to which the message is sent. For further information on the
|
||
|
|
structure of socket addresses, see
|
||
|
|
<a href="../rzab6/rzab6soxoverview.htm">Sockets Programming</a> in the iSeries
|
||
|
|
Information Center. If the <em>msg_name</em> field is set to a NULL pointer,
|
||
|
|
the address information is not returned.</p>
|
||
|
|
|
||
|
|
<p>The <em>msg_iov</em> and <em>msg_iovlen</em> fields are for scatter/gather
|
||
|
|
I/O.</p>
|
||
|
|
|
||
|
|
<p>The BSD 4.3 structure uses
|
||
|
|
the <em>msg_accrights</em> and <em>msg_accrightslen</em> fields to pass
|
||
|
|
descriptors. The <em>msg_accrights</em> field is a list of zero or more
|
||
|
|
descriptors, and <em>msg_accrightslen</em> is the total length (in bytes) of
|
||
|
|
the descriptor list.</p>
|
||
|
|
|
||
|
|
<p>The BSD 4.4/UNIX 98 compatible structure uses the <em>msg_control</em> and
|
||
|
|
<em>msg_controllen</em> fields to pass ancillary data. The <em>msg_control</em>
|
||
|
|
field is a pointer to ancillary data (of length <em>msg_controllen</em>) with
|
||
|
|
the form:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
struct cmsghdr {
|
||
|
|
socklen_t cmsg_len; /* # bytes, including this header */
|
||
|
|
int cmsg_level; /* originating protocol */
|
||
|
|
int cmsg_type; /* protocol-specific type */
|
||
|
|
/* followed by unsigned char cmsg_data[]; */
|
||
|
|
};
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>The <em>cmsg_len</em> field is the total length including this header.
|
||
|
|
<em>cmsg_level</em> is the originating protocol. <em>cmsg_type</em> is the
|
||
|
|
protocol-specific type.
|
||
|
|
If ancillary data is not being passed,
|
||
|
|
the <em>msg_control</em> field must be initalized to NULL and the
|
||
|
|
<em>msg_controllen</em> field must be initialized to 0.
|
||
|
|
The following table lists the supported ancillary data types when
|
||
|
|
using the BSD 4.4/UNIX 98 compatible structures.</p>
|
||
|
|
|
||
|
|
<p><strong><a name="Table_1-1">Ancillary Data Types That Apply to the Socket Layer
|
||
|
|
(where <em>cmsg_level</em> is <samp>SOL_SOCKET</samp> ):</a></strong></p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">cmsg_type</th>
|
||
|
|
<th align="left" valign="top">cmsg_data</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><samp>SCM_RIGHTS</samp> </td>
|
||
|
|
<td align="left" valign="top">The rest of the buffer is a
|
||
|
|
list of zero or more descriptors received.
|
||
|
|
<p>This ancillary data type is only supported for sockets with an
|
||
|
|
address family of AF_UNIX or AF_UNIX_CCSID.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>Macros are provided for navigating these structures.</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><em><samp>CMSG_DATA(cmsg)</samp></em> If the argument is a pointer to a
|
||
|
|
<em>cmsghdr</em> structure, this macro returns an unsigned character pointer to
|
||
|
|
the data array associated with the <em>cmsghdr</em> structure.</li>
|
||
|
|
|
||
|
|
<li><em><samp>CMSG_NXTHDR(mhdr,cmsg)</samp></em> If the first argument is a
|
||
|
|
pointer to a <em>msghdr</em> structure and the second argument is a pointer to
|
||
|
|
a <em>cmsghdr</em> structure in the ancillary data, pointed to by the
|
||
|
|
msg_control field of that msghdr structure, this macro returns a pointer to the
|
||
|
|
next <em>cmsghdr</em> structure, or a null pointer if this structure is the
|
||
|
|
last <em>cmsghdr</em> in the ancillary data.</li>
|
||
|
|
|
||
|
|
<li><em><samp>CMSG_FIRSTHDR(mhdr)</samp></em> If the argument is a pointer to a
|
||
|
|
<em>msghdr</em> structure, this macro returns a pointer to the first
|
||
|
|
<em>cmsghdr</em> structure in the ancillary data associated with this
|
||
|
|
<em>msghdr</em> structure, or a null pointer if there is no ancillary data
|
||
|
|
associated with the <em>msghdr</em> structure.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The BSD 4.4/UNIX 98 compatible structure has the <em>msg_flags</em> for
|
||
|
|
message level flags including:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><em><samp>MSG_TRUNC</samp></em> Message data was truncated</li>
|
||
|
|
|
||
|
|
<li><em><samp>MSG_CTRUNC</samp></em> Ancillary data was truncated.</li>
|
||
|
|
|
||
|
|
<li><em><samp>MSG_EOR</samp></em> End of record (if supported by the
|
||
|
|
protocol).</li>
|
||
|
|
|
||
|
|
<li><em><samp>MSG_OOB</samp></em> Out-of-band data.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>flags</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A flag value that controls the reception of the data. The
|
||
|
|
<em>flags</em> value is either zero, or is obtained by performing an OR
|
||
|
|
operation on one or more of the following constants:
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em><samp>MSG_OOB</samp></em></td>
|
||
|
|
<td align="left" valign="top">Receive out-of-band data. Valid only for sockets
|
||
|
|
with an address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp> and type
|
||
|
|
<samp>SOCK_STREAM</samp>.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em><samp>MSG_PEEK</samp></em></td>
|
||
|
|
<td align="left" valign="top">Obtain a copy of the message without removing the
|
||
|
|
message from the socket.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em><samp>MSG_WAITALL</samp></em></td>
|
||
|
|
<td align="left" valign="top">Wait for a full request or an error.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>An <em>errno</em> of EACCES is returned when the socket pointed to by the
|
||
|
|
<strong><em>socket_descriptor</em></strong> field is address family AF_INET and
|
||
|
|
a nonblocking connect was attempted previously and was not successful. The
|
||
|
|
nonblocking connect was not successful because the thread did not have
|
||
|
|
authority to the associated APPC device. The thread performing the nonblocking
|
||
|
|
connect must have retrieve, insert, delete, and update authority to the APPC
|
||
|
|
device.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If this thread is receiving socket descriptors, it must have *ALLOBJ
|
||
|
|
special authority or must be running under the same user profile as the thread
|
||
|
|
that sent the descriptors using sendmsg. If both of these conditions are not
|
||
|
|
true, the descriptors are reclaimed by the machine and an <em>errno</em> of
|
||
|
|
EACCES is returned.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p><em>recvmsg()</em> returns an integer. Possible values are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>-1 (unsuccessful)<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>n (successful), where n is the number of bytes received.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When <em>recvmsg()</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>The socket pointed to by the <em>socket_descriptor</em> parameter is using a
|
||
|
|
connection-oriented transport service, and a <em>connect()</em> was previously
|
||
|
|
completed. The process, however, does not have the appropriate privileges to
|
||
|
|
the objects that were needed to establish a connection. For example, the
|
||
|
|
<em>connect()</em> required the use of an APPC device that the process was not
|
||
|
|
authorized to.</p>
|
||
|
|
|
||
|
|
<p>If the <em>msg_accrights</em> and <em>msg_accrightslen</em> fields (or the
|
||
|
|
BSD 4.4/UNIX 98 compatible fields <em>msg_control</em> and
|
||
|
|
<em>msg_controllen</em>) were specified and descriptors were sent, this error indicates
|
||
|
|
that this job does not have the appropriate privileges required to receive the
|
||
|
|
descriptor. When this occurs, the descriptor is reclaimed by the system and the
|
||
|
|
resource that it represented is closed.</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>This error code indicates that the transport provider ended the connection
|
||
|
|
abnormally because of one of the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The retransmission limit has been reached for data that was being sent on
|
||
|
|
the socket.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A protocol error was detected.<br>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[ECONNRESET]</em></td>
|
||
|
|
<td align="left" valign="top">A connection with a remote socket was reset by
|
||
|
|
that socket.<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>message_structure</em> parameter or a field within the structure
|
||
|
|
pointed to by the <em>message_structure</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>msg_iovlen</em> field or the <strong>iov_len</strong> field in a
|
||
|
|
<strong>iovec</strong> structure specifies a negative value.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <em>flags</em> parameter specifies a value that includes the
|
||
|
|
<samp>MSG_OOB</samp> flag, but no OOB data was available to be received.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <em>flags</em> parameter specifies a value that includes the
|
||
|
|
<samp>MSG_OOB</samp> flag, and the socket option <samp>SO_OOBINLINE</samp> has
|
||
|
|
been set.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <em>socket_descriptor</em> parameter points to a socket that is using a
|
||
|
|
connectionless transport service, is not a socket of type
|
||
|
|
<samp>SOCK_RAW</samp>, and is not bound to an address.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <em>msg_accrightslen</em> field in the <em>msghdr</em> structure
|
||
|
|
specifies a negative value or is not large enough when <em>msg_accrights</em>
|
||
|
|
was specified. <br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <em>msg_controllen</em> field in the <em>msghdr</em> structure
|
||
|
|
specifies a negative value or is not large enough when <em>msg_control</em>
|
||
|
|
was specified. <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>[EMSGSIZE]</em></td>
|
||
|
|
<td align="left" valign="top">Message size out of range.
|
||
|
|
|
||
|
|
<p>The <em>msg_iovlen</em> field specifies a value that is greater than
|
||
|
|
[MSG_MAXIOVLEN] (defined in <strong><sys/socket.h></strong>).</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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[ENOTCONN]</em></td>
|
||
|
|
<td align="left" valign="top">Requested operation requires a connection.
|
||
|
|
|
||
|
|
<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>[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>This error code indicates one of the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The <em>flags</em> parameter specifies a value that includes the
|
||
|
|
<samp>MSG_OOB</samp> flag, but the <em>socket_descriptor</em> parameter points
|
||
|
|
to a connectionless socket.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The <em>flags</em> parameter specifies a value that includes the
|
||
|
|
<samp>MSG_OOB</samp> flag, but the <em>socket_descriptor</em> parameter points
|
||
|
|
to a socket that does not have an address family of <samp>AF_INET</samp>
|
||
|
|
or <samp>AF_INET6</samp>.<br>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</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>A non-blocking <em>connect()</em> was previously issued that resulted in the
|
||
|
|
connection establishment timing out. No connection is established. 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>[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.</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 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">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>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>The following applies to sockets that use a connection-oriented transport
|
||
|
|
service (for example, sockets with a type of <samp>SOCK_STREAM</samp>),
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The <em>msg_name</em> and <em>msg_namelen</em> fields in the structure
|
||
|
|
pointed to by the <em>message_structure</em> parameter are ignored.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A returned value of zero indicates one of the following:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The partner program has issued a <em>close()</em> for the socket.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The partner program has issued a <em>shutdown()</em> to disable writing to
|
||
|
|
the socket.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The connection is broken and the error was returned on a previously issued
|
||
|
|
socket function.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A <em>shutdown()</em> to disable reading was previously done on the
|
||
|
|
socket.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The following applies to sockets that use a connectionless transport
|
||
|
|
service (for example, a socket with a type of <samp>SOCK_DGRAM</samp>):
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If a <em>connect()</em> has been issued previously, then data can be
|
||
|
|
received only from the address specified in the previous
|
||
|
|
<em>connect()</em>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the <em>msg_name</em> field is set to NULL or <em>msg_namelen</em> field
|
||
|
|
specifies a value of zero, the address from which data is received is
|
||
|
|
discarded.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the length of the address to be returned exceeds the length specified by
|
||
|
|
the <em>msg_namelen</em> field, the returned address is truncated.<br>
|
||
|
|
<br>
|
||
|
|
</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>The entire message must be read in a single read operation. If the size of
|
||
|
|
the message is too large to fit in the user supplied buffer, the remaining
|
||
|
|
bytes of the message are discarded.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A returned value of zero indicates one of the following:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The partner program has sent a NULL message (a datagram with no user
|
||
|
|
data).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A <em>shutdown()</em> to disable reading was previously done on the
|
||
|
|
socket.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The buffer length specified was zero.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The passing of descriptors is only supported over sockets that have an
|
||
|
|
address family of <samp>AF_UNIX</samp> or <samp>AF_UNIX_CCSID</samp>. The
|
||
|
|
<em>msg_accrightslen</em> and the <em>msg_accrights</em> fields (or the
|
||
|
|
BSD 4.4/UNIX 98 compatible fields <em>msg_control</em> and
|
||
|
|
<em>msg_controllen</em>) are ignored if the socket has any other
|
||
|
|
address family. The value of <em>msg_accrightslen</em> (or the BSD
|
||
|
|
4.4/UNIX 98 compatible field <em>msg_controllen</em>)
|
||
|
|
should be checked to determine if a descriptor has been returned. When you use
|
||
|
|
<em>sendmsg()</em> and <em>recvmsg()</em> to pass descriptors, the target job
|
||
|
|
must be running with either of the following:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The same user profile as the source job (in essence, passing the descriptor
|
||
|
|
to yourself)</li>
|
||
|
|
|
||
|
|
<li>*ALLOBJ special authority</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>If the target job closes the receiving end of the UNIX domain socket while a
|
||
|
|
descriptor is in transit, the descriptor is reclaimed by the system, and the
|
||
|
|
resource that it represented is closed. For files and directories, the ability
|
||
|
|
to pass descriptors using <em>sendmsg()</em> and <em>recvmsg()</em> is only
|
||
|
|
supported for objects in the
|
||
|
|
Root, QOpenSys, User-defined file systems (UDFS), and Network File System (NFS).
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> The <em>recvmsg()</em> API will not block unless a
|
||
|
|
data buffer is specified.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><em>recvmsg()</em> accepts a pointer to an array of <strong>iovec</strong>
|
||
|
|
structures in the <strong>msghdr</strong> structure. The <em>msg_iovlen</em>
|
||
|
|
field is used to determine the number of elements in the array (the number of
|
||
|
|
<strong>iovec</strong> structures specified). When <em>recvmsg()</em> is
|
||
|
|
issued, the system processes the array elements one at a time, starting with
|
||
|
|
the first structure. For each element of the array (for each structure),
|
||
|
|
<em>iov_len</em> bytes of received data are placed in storage pointed to by
|
||
|
|
<em>iov_base</em>. Data is placed in storage until all buffers are full, or
|
||
|
|
until there is no more data to receive. Only the memory pointed to by
|
||
|
|
<em>iov_base</em> is updated. No change is made to the <em>iov_len</em> fields.
|
||
|
|
To determine the end of the data, the application program must use the
|
||
|
|
following:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The function return value (the total number of bytes received).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The lengths of the buffers pointed to by <em>iov_base</em>.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<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>recvmsg()</em> API is mapped to
|
||
|
|
<em>qso_recvmsg98()</em>.<br><br></li>
|
||
|
|
|
||
|
|
<li>If this function is called
|
||
|
|
by a thread executing one of the scan-related exit programs (or any of its
|
||
|
|
created threads), it will fail with error code [ENOTSUP]. 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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>When the descriptor is obtained using <em>recvmsg()</em>, any information
|
||
|
|
accessed using that descriptor with the various read and write interfaces will
|
||
|
|
be in binary, even if the original descriptor's accesses would have had text
|
||
|
|
conversions occur. See
|
||
|
|
<a href="open.htm#HDRIFSCCSD">Using CCSIDs and code pages</a> in the
|
||
|
|
<a href="open.htm">open--Open file</a> documentation for more information on text conversion.
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>For additional information and sample programs on how to use sendmsg() and
|
||
|
|
recvmsg() to pass descriptors between system jobs, see <a href=
|
||
|
|
"../rzab6/rzab6soxoverview.htm">Sockets Programming</a> in the iSeries
|
||
|
|
Information Center.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<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="gvsoc.htm">givedescriptor()</a>--Pass Descriptor Access to Another
|
||
|
|
Job<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="recv.htm">recv()</a>--Receive Data<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="recvfr.htm">recvfrom()</a>--Receive Data<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="tksoc.htm">takedescriptor()</a>--Receive Descriptor Access from Another
|
||
|
|
Job</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>
|
||
|
|
|