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

649 lines
19 KiB
HTML
Raw Permalink Blame History

<!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>pread()--Read from 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 -->
<!-- 010307 JTROUS Creation based on read.htm, 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 -->
<!-- File cleanup completed Feb 2002 by v2cdijab -->
<!-- 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 -->
<!-- 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>pread()--Read from Descriptor with Offset</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;unistd.h&gt;
ssize_t pread(int <em>file_descriptor</em>,
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>From the file indicated by <em>file_descriptor</em>, the <strong>
pread()</strong> function reads <em>nbyte</em> bytes of input into the memory
area indicated by <em>buf</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="read.htm">read()--Read from Descriptor</a> for more information
relating to reading from a descriptor.</p>
<p>In the QSYS.LIB and independent ASP QSYS.LIB file systems, the offset will
be ignored for a member while in text mode.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>file_descriptor</em></strong></dt>
<dd>(Input) The descriptor to be read.<br>
<br>
</dd>
<dt><strong><em>buf</em></strong></dt>
<dd>(Output) A pointer to a buffer in which the bytes read are placed.<br>
<br>
</dd>
<dt><strong><em>nbyte</em></strong></dt>
<dd>(Input) The number of bytes to be read.<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>pread()</strong> was successful. The
value returned is the number of bytes actually read and placed in <em>buf</em>.
This number is less than or equal to <em>nbyte</em>. It is less than <em>
nbyte</em> only if <strong>pread()</strong> reached the end of the file before
reading the requested number of bytes. If <strong>pread()</strong> is reading a
regular file and encounters a part of the file that has not been written (but
before the end of the file), <strong>pread()</strong> places bytes containing
zeros into <em>buf</em> in place of the unwritten bytes.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>pread()</strong> was not successful. The
<em>errno</em> global variable is set to indicate the error. If the value of
<em>nbyte</em> is greater than SSIZE_MAX, <strong>pread()</strong> sets <em>
errno</em> to [EINVAL].</td>
</tr>
</table>
<br>
<h3>Error Conditions</h3>
<p>If <strong>pread()</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#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 resides in a file system that does not support
large files, and the starting offset of the file 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#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#ENXIO">ENXIO</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 the starting offset 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#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>
<br>
<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>This function will fail with error code [ENOTSAFE] if the object specified
is a save file and multiple threads exist in the
job.</p>
<p>This function will fail with error code [EIO] if the file specified is a
save file and the file does not contain complete save file data.</p>
<p>The file access time for a database member is updated using the normal rules
that apply to database files. At most, the access time is updated once per
day.</p>
<p>If you previously used the integrated file system interface to manipulate a
member that contains an end-of-file character, you should 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.</p>
</li>
<li>QOPT File System Differences
<p>The file access time is not updated on a <strong>pread()</strong>
operation.</p>
<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>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 file systems that do not support large files, <strong>pread()</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>pread()</strong> will return [EOVERFLOW] 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 zero. In addition, the access time
for the file is updated.<br>
<br>
</li>
<li>If <em>file_descriptor</em> refers to a descriptor obtained using the
<strong>open()</strong> API 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>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="pread64.htm">pread64()</a>--Read from Descriptor with Offset
(large file enabled)</li>
<li><a href="pwrite.htm">pwrite()</a>--Write to Descriptor with Offset</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="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>
<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 opens a file and reads input:</p>
<pre>
#include &lt;stdio.h&gt;
#include &lt;unistd.h&gt;
#include &lt;fcntl.h&gt;
main() {
int ret, file_descriptor;
off_t off=5;
char buf[]="Test text";
if ((file_descriptor = creat("test.output", S_IWUSR))!= 0)
perror("creat() error");
else {
if (-1==(rc=write(file_descriptor, buf, sizof(buf)-1)))
perror("write() error");
if (close(file_descriptor)!= 0)
perror("close() error");
}
if ((file_descriptor = open("test.output", O_RDONLY)) &lt; 0)
perror("open() error");
else {
ret = pread(file_descriptor, buf, ((sizeof(buf)-1)-off), off);
buf[ret] = 0x00;
printf("block pread: \n&lt;%s&gt;\n", buf);
if (close(file_descriptor)!= 0)
perror("close() error");
}
if (unlink("test.output")!= 0)
perror("unlink() error");
}
</pre>
<p><strong>Output:</strong></p>
<pre>
block pread:
&lt;text&gt;
</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>
Reference in New Issue View Git Blame Copy Permalink