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

856 lines
22 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>pwrite()--Write to Descriptor with Offset</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 -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 010308 JTROUS Creation date based on write, for V5R2, DCR 98686 -->
<!-- 010703 JTROUS Add ERESTART, EINTR, V5R2, DCR 98686, Change -->
<!-- CCSID restriction, SE01918, add dev/zero -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 020624 RTHEIS: Add fclear() and fclear64(), V5R3 -->
<!-- 0205?? JET This file has undergone html cleanup -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 030730 VONBERGE: Add comment about qsys mbrs in text mode -->
<!-- 050406 JTROUS: fix enums, no change flag, V5R4 -->
<!-- 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>pwrite()--Write to Descriptor with Offset</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;unistd.h&gt;
ssize_t pwrite
(int <em>file_descriptor</em>, const void <em>*buf</em>,
size_t <em>nbyte</em>, off_t <em>offset</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 <strong>pwrite()</strong> function writes <em>nbyte</em> bytes from <em>
buf</em> to the file associated with <em>file_descriptor</em>. The <em>
offset</em> value defines the starting position in the file and the file
pointer position is not changed.</p>
<p>See <a href="write.htm">write()--Write to Descriptor</a> for more
information relating to writing to a descriptor.</p>
<p>The <em>offset</em> will also be ignored if <em>file_descriptor</em> refers
to a descriptor obtained using the <strong>open()</strong> function with
O_APPEND specified.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>file_descriptor</em></strong></dt>
<dd>(Input) The descriptor of the file to which the data is to be written.<br>
<br>
</dd>
<dt><strong><em>buf</em></strong></dt>
<dd>(Input) A pointer to a buffer containing the data to be written.<br>
<br>
</dd>
<dt><strong><em>nbyte</em></strong></dt>
<dd>(Input) The size in bytes of the data to be written.<br>
<br>
</dd>
<dt><strong><em>offset</em></strong></dt>
<dd>(Input) The offset to the desired starting position in the file.</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>pwrite()</strong> was successful. The
value returned is the number of bytes actually written. This number is less
than or equal to <em>nbyte</em>.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>pwrite()</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>pwrite()</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>
</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>The file system that the file resides in does not support large files, and
the starting offset exceeds 2GB minus 2 bytes.
This will also occur if the <em>offset</em> value is less than 0.</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#ENXIO">ENXIO</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#ETRUNC">ETRUNC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESPIPE">ESPIPE</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>
<p>If interaction with a file server is required to access the object, <em>
errno</em> could also 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>
<p>The following messages may be sent from this function:</p>
<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">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>
<h3><a name="usage_notes">Usage Notes</a></h3>
<ol type="1">
<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>
<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>QSYS.LIB and Independent ASP QSYS.LIB File System Differences
<p>
For a physical file member opened in text mode, the <em>offset</em> must be equal to the current file position. Otherwise, this operation will fail with error code [EIO].
</p>
<p>This function will fail with error code [ENOTSAFE] if the object on which
this function is operating is a save file and multiple threads exist in the
job.</p>
<p>If the file specified is a save file, only complete records will be written
into the save file. A <strong>pwrite()</strong> request that does not provide
enough data to completely fill a save file record will cause the partial
record's data to be saved by the file system. The saved partial record will
then be combined with additional data on subsequent <strong>pwrite()</strong>'s
until a complete record may be written into the save file. If the save file is
closed prior to a saved partial record being written into the save file, then
the saved partial record is discarded, and the data in that partial record will
need to be written again by the application.</p>
<p>A successful <strong>pwrite()</strong> updates the change, modification, and
access times for a database member using the normal rules that apply to
database files. At most, the access time is updated once per day.</p>
<p>You should be careful when writing end-of-file characters in the QSYS.LIB
and independent ASP QSYS.LIB file systems. For these file systems, end-of-file
characters are symbolic; that is, they are stored outside the file member.
However, some situations can result in actual, nonsymbolic end-of-file
characters being written to a member. These nonsymbolic end-of-file characters
could cause some tools or utilities to fail. For example:<br>
<br>
</p>
<ul>
<li>If you previously wrote an end-of-file character as the last character of a
member, do not continue to write data after that end-of-file character.
Continuing to write data will cause a nonsymbolic end-of-file to be written. As
a result, a compile of the member could fail.<br>
<br>
</li>
<li>If you previously wrote an end-of-file character as the last character of a
member, do not write other end-of-file characters preceding it in the file.
This will cause a nonsymbolic end-of-file to be written. As a result, a compile
of the member could fail.<br>
<br>
</li>
<li>If you previously used the integrated file system interface to manipulate a
member that contains an end-of-file character, avoid using other interfaces
(such as the Source Entry Utility or database reads and writes) to manipulate
the member. If you use other interfaces after using the integrated file system
interface, the end-of-file information will be lost.<br>
<br>
</li>
</ul>
</li>
<li>QOPT File System Differences
<p>The change and modification times of the file are updated when the file is
closed.</p>
<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>Network File System Differences
<p>Local access to remote files through the Network File System may produce
unexpected results due to conditions at the server. Once a file is open,
subsequent requests to perform operations on the file can fail because file
attributes are checked at the server on each request. If permissions on the
file are made more restrictive at the server or the file is unlinked or made
unavailable by the server for another client, your operation on an open file
descriptor will fail when the local Network File System receives these updates.
The local Network File System also impacts operations that retrieve file
attributes. Recent changes at the server may not be available at your client
yet, and old values may be returned from operations (several options on the Add
Mounted File System (ADDMFS) command determine the time between refresh
operations of local data).</p>
<p>Reading and writing to files with the Network File System relies on
byte-range locking to guarantee data integrity. To prevent data inconsistency,
use the <strong>fcntl()</strong> API to get and release these locks.</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>For the file systems that do not support large files, <strong>
pwrite()</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>pwrite()</strong> will return [EFBIG] if the
starting offset exceeds 2GB minus 2 bytes and the file was not opened for large
file access.<br>
<br>
</li>
<li>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 /dev/null or /dev/zero character
special file. In addition, the change and modification times for the file are
updated.<br>
<br>
</li>
<li>If the write exceeds the process soft file size limit, signal SIFXFSZ is
issued.<br>
<br>
</li>
<li>If <em>file_descriptor</em> refers to a descriptor obtained using the
<strong>open()</strong> function with O_TEXTDATA and O_CCSID specified, the
file CCSID and open CCSID are not the same, and the converted data could expand
or contract, then the <em>offset</em> value must be 0.<br>
<br>
</li>
<li>If <em>file_descriptor</em> refers to a character special file, the <em>
offset</em> value is ignored.</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="pread.htm">pread()</a>--Read from Descriptor with Offset</li>
<li><a href="pread64.htm">pread64()</a>--Read from Descriptor with Offset
(large file enabled)</li>
<li><a href="pwrite64.htm">pwrite64()</a>--Write to Descriptor with Offset
(large file enabled)</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>
<li><a href="writev.htm">writev()</a>--Write to Descriptor Using Multiple
Buffers</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example writes a specific number of bytes to a file:</p>
<pre>
#include &lt;unistd.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;fcntl.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#define mega_string_len 1000000
main() {
char *mega_string;
int file_descriptor;
int ret;
off_t off=5;
char fn[]="write.file";
if ((mega_string = (char*) malloc(mega_string_len+off)) == NULL)
perror("malloc() error");
else if ((file_descriptor = creat(fn, S_IWUSR)) &lt; 0)
perror("creat() error");
else {
memset(mega_string, '0', mega_string_len);
if ((ret = pwrite(file_descriptor, mega_string, mega_string_len, off)) == -1)
perror("pwrite() error");
else printf("pwrite() wrote %d bytes at offset %d\n", ret, off);
if (close(file_descriptor)!= 0)
perror("close() error");
if (unlink(fn)!= 0)
perror("unlink() error");
}
free(mega_string);
}
</pre>
<strong>Output:</strong>
<pre>
pwrite() wrote 1000000 bytes at offset 5
</pre>
<hr>
API introduced: V5R2
<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>