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/writev.htm

887 lines
20 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>writev()--Write to Descriptor Using Multiple Buffers</title>
<!-- 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. -->
<!-- Begin Header Records ========================================== -->
<!-- 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: -->
<!-- 010320 JTROUS Include Journal ERRNOs, should have in V5R1 -->
<!-- 010703 JTROUS ERESTART, EINTR,Add dev/zero, V5R2, DCR 98686 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- also add in info from PASE I0 for 98391 -->
<!-- 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 -->
<!-- End Header Records -->
<!-- Edited by Kersten Feb 02 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>writev()--Write to Descriptor Using Multiple Buffers</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/uio.h&gt;
int writev(int <em>descriptor</em>,
struct iovec *<em>io_vector</em>[],
int <em>vector_length</em>)
</pre>
<br>
&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 <strong>writev()</strong> function is used to write data to a file or socket
descriptor. <strong>writev()</strong> provides a way for the data that is going to be
written to be stored in several different buffers (<em>scatter/gather
I/O</em>).</p>
<p><strong>Note:</strong> When the write completes successfully, the S_ISUID
(set-user-ID) and S_ISGID (set-group-ID) bits of the file mode will be cleared.
If the write is unsuccessful, the bits are undefined.</p>
<p>See <a href="write.htm">write()--Write to Descriptor</a> for more
information related to writing to a descriptor.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>descriptor</strong></dt>
<dd>(Input) The descriptor to which the data is to be written. The descriptor
refers to either a file or a socket.<br>
<br>
</dd>
<dt><strong>io_vector</strong>[]</dt>
<dd>(Input) 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 written 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>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>value</em></td>
<td align="left" valign="top"><strong>writev()</strong> was successful. The
value returned is the number of bytes actually written.
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>writev()</strong> was not successful. The
<em>errno</em> global variable is set to indicate the error.</td>
</tr>
</table>
<br>
<h3>Error Conditions</h3>
<p>If <strong>writev()</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>If writing to a socket, this error code indicates one of the following:</p>
<ul>
<li>The destination address specified is a broadcast address and the socket
option <samp>SO_BROADCAST</samp> was not set (with a <em>
setsockopt()</em>).</li>
<li>The process does not have the appropriate privileges to the destination
address. This error code can only be returned on a socket with an address
family of <samp>AF_INET</samp> and a type of <samp>SOCK_DGRAM</samp>.</li>
</ul>
</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#EFBIG">EFBIG</a>]</em></td>
<td align="left" valign="top">
<p>The size of the object would exceed the system allowed maximum size or the
process soft file size limit.
The file is a regular file, <em>nbyte</em> is greater than 0, and the
starting offset is greater than or equal to 2 GB minus 2 bytes.</p>
</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>For example, the file resides in a file system that does not support large files, and the
starting offset exceeds 2GB 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#EJRNDAMAGE">EJRNDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNENTTOOLONG">EJRNENTTOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNINACTIVE">EJRNINACTIVE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNRCVSPC">EJRNRCVSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr><tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENEWJRN">ENEWJRN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENEWJRNRCV">ENEWJRNRCV</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#ENOSPC">ENOSPC</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#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#ETRUNC">ETRUNC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</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>
<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#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
<td>
<p>This error code can only be returned on sockets that use a connectionless
transport service.</p>
</td></tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EDESTADDRREQ">EDESTADDRREQ</a>]</em></td>
<td align="left" valign="top">
<p>A destination address has not been associated with the socket pointed to by
the <em>fildes</em> parameter. This error code can only be returned on sockets
that use a connectionless transport service.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td>
<td align="left" valign="top">
<p>This error code can only be returned on sockets that use a connectionless
transport service.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td>
<td align="left" valign="top">
<p>This error code can only be returned on sockets that use a connectionless
transport service.</p>
</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#EMSGSIZE">EMSGSIZE</a>]</em></td>
<td align="left" valign="top">
<p>The data to be sent could not be sent atomically because the size specified
by <em>nbyte</em> is too large.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td>
<td align="left" valign="top">
<p>This error code can only be returned on sockets that use a connectionless
transport service.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td>
<td align="left" valign="top">
<p>This error code can only be returned on sockets that use a connectionless
transport service.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOBUFS">ENOBUFS</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">
<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>[<a href="unix14.htm#EPIPE">EPIPE</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>
<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>
<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 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">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:
<ul>
<li>Where multiple threads exist in the job.</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:
<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>
<p><strong>writev()</strong> only works with sockets on which a <em>connect()</em> has
been issued, since the call does not allow the caller to specify a destination
address.</p>
</li>
<li>
<p><strong>writev()</strong> is an atomic operation on sockets of type <samp>
SOCK_DGRAM</samp> and <samp>SOCK_RAW</samp> in that it produces one packet of
data every time it is issued. For example, a <strong>writev()</strong> to a datagram
socket results in a single datagram.</p>
</li>
<li>
<p>To broadcast on an <samp>AF_INET</samp> socket, the socket option <samp>
SO_BROADCAST</samp> must be set (with a <em>setsockopt()</em>).</p>
</li>
<li>When using a connection-oriented transport service, all errors except
<samp>[EUNATCH]</samp> and <samp>[EUNKNOWN]</samp> are mapped to <samp>
[EPIPE]</samp> on an output operation when either of the following occurs:
<ul>
<li>A connection that is in progress is unsuccessful.<br>
</li>
<li>An established connection is broken.</li>
</ul>
<br>
<p>To get the actual error, use <em>getsockopt()</em> with the <samp>
SO_ERROR</samp> option, or perform an input operation (for example, <em>
read()</em>).</p>
</li>
<li>
<p>For the file systems that do not support large files, <strong>
writev()</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>writev()</strong> will return [EFBIG] if the
starting offset exceeds 2GB minus 2 bytes and the file was not opened for large
file access.</p>
</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 writing to files on volumes formatted in Universal Disk Format (UDF),
byte locks on the range being written are ignored.</p>
</li>
<li>
<p>Using this function successfully on the dev/null or /dev/zero character
special file results in a return value of the total number of bytes requested
to be written. No data is written to the character special file. In addition,
the change and modification times for the file are updated.</p>
</li>
<li>
<p>If the write exceeds the process soft file size limit, signal SIFXFSZ is
issued.</p>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>fcntl.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="readv.htm">readv()</a>--Read from Descriptor Using Multiple
Buffers
</li>
<li><a href="send.htm">send()</a>--Send Data
</li>
<li><a href="sendms.htm">sendmsg()</a>--Send Data or Descriptors or Both
</li>
<li><a href="sendto.htm">sendto()</a>--Send Data
</li>
<li><a href="write.htm">write()</a>--Write to Descriptor</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