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

678 lines
19 KiB
HTML
Raw Permalink 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>readv()--Read from Descriptor Using Multiple Buffers</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. -->
<!-- file cleaned -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- 010703 JTROUS Add ERESTART, EINTR, dev/zero, V5R2, DCR 98686 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 020624 RTHEIS: Add fclear() and fclear64(), V5R3 -->
<!-- 0206?? JET This file has undergone html cleanup -->
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 050407 JTROUS: fix enums, no change flag, V5R4 -->
<!-- Edited by Kersten Jan 02 -->
<!-- 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>readv()--Read from Descriptor Using Multiple Buffers</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/uio.h&gt;
int readv(int <em>descriptor</em>,
struct iovec *<em>io_vector</em>[],
int <em>vector_length</em>)
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage
Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <em>readv()</em> function is used to receive data from a file or socket
descriptor. <em>readv()</em> provides a way for data to be stored in several
different buffers (<em>scatter/gather I/O</em>).</p>
<p>See <a href="read.htm">read()--Read from Descriptor</a> for more information
related to reading from a descriptor.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>descriptor</strong></dt>
<dd>(Input) The descriptor to be read. The descriptor refers to a file or a
socket.<br>
<br>
</dd>
<dt><strong>io_vector</strong>[]</dt>
<dd>(I/O) The pointer to an array of type <strong>struct iovec</strong>.
<strong>struct iovec</strong> contains a sequence of pointers to buffers in
which the data to be read is stored. The structure pointed to by the <em>
io_vector</em> parameter is defined in <strong>&lt;sys/uio.h&gt;</strong>.
<pre>
struct iovec {
void *iov_base;
size_t iov_len;
}
</pre>
<p><em>iov_base</em> and <em>iov_len</em> are the only fields in <em>iovec</em>
used by sockets. <em>iov_base</em> contains the pointer to a buffer and <em>
iov_len</em> contains the buffer length. The rest of the fields are
reserved.</p>
</dd>
<dt><strong>vector_length</strong></dt>
<dd>(Input) The number of entries in <em>io_vector</em>.</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>No authorization is required.</p>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>n</em></dt>
<dd><strong>readv()</strong> is successful, where n is the number of bytes read.
</dd>
<dt><em>-1</em></dt>
<dd><strong>readv()</strong> was not successful. The <em>errno</em> global
variable is set to indicate the error.</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>readv()</strong> is not successful, <em>errno</em> usually
indicates one of the following errors. Under some conditions, <em>errno</em>
could indicate an error other than those listed here.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top"><em>[<a href="unix14.htm#EACCES">EACCES</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, update
operations to file permissions at the server are not reflected at the client
until updates to data that is stored locally by the Network File System take
place. (Several options on the Add Mounted File System (ADDMFS) command
determine the time between refresh operations of local data.) Access to a
remote file may also fail due to different mappings of user IDs (UID) or group
IDs (GID) on the local and remote systems.</p>
<p>This may occur if <em>file_descriptor</em> refers to a socket and the socket
is using a connection-oriented transport service, and a <em>connect()</em> was
previously completed. The thread, 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
thread was not authorized to.</p>
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EAGAIN">EAGAIN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EBADF">EBADF</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EINTR">EINTR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
<p>This may occur if <em>file_descriptor</em> refers 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.</p>
<p>The file resides in a file system that does not support large files, and the
starting offset of the file exceeds 2 GB minus 2 bytes.</p>
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EIO">EIO</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ENOMEM">ENOMEM</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EOVERFLOW">EOVERFLOW</a>]</em></td>
<td align="left" valign="top">
<p>The file is a regular file, <em>nbyte</em> is greater than 0, the starting
offset is before the end-of-file and is greater than or equal to 2GB minus 2
bytes.</p>
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ERESTART">ERESTART</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EUNKNOWN">EUNKNOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
</table>
<br>
<p>When the descriptor refers to a socket, <em>errno</em> could indicate one of
the following errors:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td>
<td align="left" valign="top">
<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.</li>
<li>A protocol error was detected.</li>
</ul>
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EINTR">EINTR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ENOTCONN">ENOTCONN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ETIMEDOUT">ETIMEDOUT</a>]</em></td>
<td align="left" valign="top">
<p>A non-blocking <strong>connect()</strong> was previously completed that
resulted in the connection 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>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EWOULDBLOCK">EWOULDBLOCK</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
</table>
<br>
<p>If interaction with a file server is required to access the object, <em>
errno</em> could indicate one of the following errors:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EADDRNOTAVAIL">EADDRNOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#ETIMEDOUT">ETIMEDOUT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
<tr><td align="left" valign="top"><em>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td></tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<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">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</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>
<tr>
<td align="left" valign="top">CPFA0D4 E</td>
<td align="left" valign="top">File system error occurred. Error number
&amp;1.</td>
</tr>
</table>
<br>
<br>
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
<ol>
<li>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:<br>
<br>
<ul>
<li>Where multiple threads exist in the job.<br>
</li>
<li>The object on which this function is operating resides in a file system
that is not threadsafe. Only the following file systems are threadsafe for this
function:<br>
<br>
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined</li>
<li>QNTC</li>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
<li>QOPT</li>
<li>Network File System</li>
<li>QFileSvr.400</li>
</ul>
</li>
</ul>
<br>
</li>
<li>The <em>io_vector</em>[] parameter is an array of <strong>struct
iovec</strong> structures. When a <em>readv()</em> is issued, the system
processes the array elements one at a time, starting with <em>
io_vector</em>[0]. For each element, <strong>iov_len</strong> bytes of received
data are placed in storage pointed to by <strong>iov_base</strong>. Data is
placed in storage until all buffers are full, or until there is no more data to
receive. Only the storage pointed to by <strong>iov_base</strong> is updated.
No change is made to the <strong>iov_len</strong> fields. To determine the end
of the data, the application program must use the following:<br>
<br>
<ul>
<li>The function return value (the total number of bytes received).</li>
<li>The lengths of the buffers pointed to by <strong>iov_base</strong>.</li>
</ul>
<br>
</li>
<li>For sockets that use a connection-oriented transport service (for example,
sockets with a type of <samp>SOCK_STREAM</samp>), a returned value of zero
indicates one of the following:<br>
<br>
<ul>
<li>The partner program has issued a <em>close()</em> for the socket.<br>
</li>
<li>The partner program has issued a <em>shutdown()</em> to disable writing to
the socket.<br>
</li>
<li>The connection is broken and the error was returned on a previously issued
socket function.<br>
</li>
<li>A <em>shutdown()</em> to disable reading was previously done on the
socket.</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>
</li>
<li>The address from which data is received is discarded, because the <em>
readv()</em> has no address parameter.<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 buffers, the remaining
bytes of the message are discarded.<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>
</li>
<li>A <em>shutdown()</em> to disable reading was previously done on the
socket.<br>
</li>
<li>The buffer length specified by the application was zero.</li>
</ul>
</li>
</ul>
<br>
</li>
<li>For the file systems that do not support large files, <strong>
readv()</strong> will return [EINVAL] if the starting offset exceeds 2GB minus
2 bytes, regardless of how the file was opened. For the file systems that do
support large files, <strong>readv()</strong> will return [EOVERFLOW] if the
starting offset exceeds 2GB minus 2 bytes and file was not opened for large
file access.<br>
<br>
</li>
<li>QFileSvr.400 File System Differences
<p>The largest buffer size allowed is 16 megabytes. If a larger buffer is
passed, the error EINVAL will be received.</p>
</li>
<li>QOPT File System Differences
<p>When reading from files on volumes formatted in Universal Disk Format (UDF),
byte locks on the range being read are ignored.</p>
</li>
<li>Using this function successfully on the /dev/null or /dev/zero character
special file results in a return value of 0. In addition, the access time for
the file is updated.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>limits.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)
</li>
<li>The &lt;<strong>unistd.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)
</li>
<li><a href="creat.htm">creat()</a>--Create or Rewrite File
</li>
<li><a href="dup.htm">dup()</a>--Duplicate Open File Descriptor
</li>
<li><a href="dup2.htm">dup2()</a>--Duplicate Open File Descriptor to Another
Descriptor
</li>
<li><a href="fclear.htm">fclear()</a>--Write (Binary Zeros) to Descriptor
</li>
<li><a href="fclear64.htm">fclear64()</a>--Write (Binary Zeros) to Descriptor
(Large File Enabled)
</li>
<li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command
</li>
<li><a href="ioctl.htm">ioctl()</a>--Perform I/O Control Request
</li>
<li><a href="lseek.htm">lseek()</a>--Set File Read/Write Offset
</li>
<li><a href="open.htm">open()</a>--Open File
</li>
<li><a href="read.htm">read()</a>--Read from Descriptor
</li>
<li><a href="recv.htm">recv()</a>--Receive Data
</li>
<li><a href="recvfr.htm">recvfrom()</a>--Receive Data
</li>
<li><a href="recvms.htm">recvmsg()</a>--Receive Data or Descriptors or Both
</li>
<li><a href="write.htm">write()</a>--Write to Descriptor
</li>
<li><a href="writev.htm">writev()</a>--Write to Descriptor Using Multiple
Buffers</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