<!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>lseek()--Set File Read/Write 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 --> <!-- file cleaned --> <!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- 010703 JTROUS Chg for PTR SE01918, less restrictive on CCSID, --> <!-- also add info on dev/zero, v5r2 --> <!-- 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 --> <!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 --> <!-- 050404 JTROUS: fix enums, no change flag, V5R4 --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <!--End Header Records --><!-- Java sync-link --> <script language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <a name="Top_Of_Page"></a> <h2>lseek()--Set File Read/Write Offset</h2> <div class="box" style="width: 80%;"> <br> Syntax<br> <pre> #include <unistd.h> off_t lseek(int <em>file_descriptor</em>, off_t <em>offset</em>, int <em>whence)</em>; </pre> Service Program Name: QP0LLIB1<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Conditional; see <a href="#HDRLSKUSAG">Usage Notes</a>.<br> <!-- iddvc RMBR --> <br> </div> <p>The <strong>lseek()</strong> function changes the current file offset to a new position in the file. The new position is the given byte <em>offset</em> from the position specified by <em>whence</em>. After you have used <strong> lseek()</strong> to seek to a new location, the next I/O operation on the file begins at that location.</p> <p><strong>lseek()</strong> lets you specify new file offsets past the current end of the file. If data is written at such a point, read operations in the gap between this data and the old end of the file will return bytes containing binary zeros (or bytes containing blanks in the QSYS.LIB and independent ASP QSYS.LIB file systems). In other words, the gap is assumed to be filled with zeros (or with blanks in the QSYS.LIB and independent ASP QSYS.LIB file systems). Seeking past the end of a file, however, does not automatically extend the length of the file. There must be a write operation before the file is actually extended.</p> <p>There are some important considerations for <strong>lseek()</strong> if the O_TEXTDATA and O_CCSID flags were specified on the <strong>open()</strong>, the file CCSID and open CCSID are not the same, and the converted data could expand or contract:</p> <ul> <li>Making assumptions about data size and the current file offset is extremely dangerous. For example, a file might have a physical size of 100 bytes, but after an application has read 100 bytes from the file, the current file offset may be only 50. To read the whole file, the application might have to read 200 bytes or more, depending on the CCSIDs involved. Therefore, <strong> lseek()</strong> will only be allowed to change the current file offset to:<br> <br> <ul> <li>The start of the file (<em>offset</em> 0, <em>whence</em> SEEK_SET)<br> </li> <li>The end of the file (<em>offset</em> 0, <em>whence</em> SEEK_END). In this case, the function will return a calculated value based on the physical size of the file, the CCSID of the file, and the CCSID of the open instance. This may be different than the actual file offset.</li> </ul> <p>If any other combination of values is specified, <strong>lseek()</strong> fails and <em>errno</em> is set to ENOTSUP.</p> </li> <li>Internally-buffered data from a read or write operation is discarded. See <a href="read.htm">read()--Read from Descriptor</a> and <a href="write.htm"> write()--Write to Descriptor</a> for more information concerning internal buffering of text data.<br> <br> </li> <li>The expected state for the current text conversion is reset to the initial state. This consideration applies only when using a CCSID that can represent data using more than one graphic character set or containing characters of different byte lengths. Some CCSIDs require an escape or shift sequence to signify a state change from one character set or byte length to another. Failing to account for this consideration could lead to incorrect text conversion if, for instance, a double-byte character at the new file offset was treated as two single-byte characters by the conversion function.<br> <br> </li> </ul> <p>In the QSYS.LIB file and independent ASP QSYS.LIB file systems, you can seek only to the beginning of a member while in text mode.</p> <br> <h3>Parameters</h3> <dl> <dt><strong><em>file_descriptor</em></strong></dt> <dd>(Input) The file whose current file offset you want to change.<br> </dd> <dt><strong><em>offset</em></strong></dt> <dd>(input) The amount (positive or negative) the byte offset is to be changed. The sign indicates whether the offset is to be moved forward (positive) or backward (negative).<br> </dd> <dt><strong><em>whence</em></strong></dt> <dd>(Input) One of the following symbols (defined in the <<strong>unistd.h</strong>> header file): <dl compact> <dt><em>SEEK_SET</em></dt> <dd>The start of the file</dd> <dt><em>SEEK_CUR</em></dt> <dd>The current file offset in the file</dd> <dt><em>SEEK_END</em></dt> <dd>The end of the file</dd> </dl> </dd> </dl> <p>If bits in <em>whence</em> are set to values other than those defined above, <strong>lseek()</strong> fails with the [EINVAL] error.</p> <br> <h3>Authorities</h3> <p>No authorization is required. Authorization is verified during <strong> open()</strong> or <strong>creat()</strong>.</p> <br> <h3>Return Value</h3> <dl compact> <dt><em>value</em></dt> <dd><strong>lseek()</strong> was successful. The value returned is the new file offset, measured in bytes from the beginning of the file.</dd> <dt><em>-1</em></dt> <dd><strong>lseek()</strong> was not successful. The <em>errno</em> global variable is set to indicate the error.</dd> </dl> <br> <h3><a name="HDRLSKERRS">Error Conditions</a></h3> <p>If <strong>lseek()</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"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EBADF">EBADF</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EIO">EIO</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOSYSRSC">ENOSYSRSC</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENOTSUP">ENOTSUP</a>]</em></td> <td align="left" valign="top"> </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 resulting file offset would be a value that cannot be represented correctly in a variable of type off_t (the offset is greater than 2GB minus 2 bytes).</p> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ESPIPE">ESPIPE</a>]</em></td> <td align="left" valign="top"> </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"> </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"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td> <td align="left" valign="top"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td> <td align="left" valign="top"> </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"> </td> </tr> <tr> <td align="left" valign="top"> <em>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td> <td align="left" valign="top"> </td> </tr> </table> <br> <br> <h3>Error Messages</h3> <p>The following messages may be sent from this function:</p> <table width="100%"> <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 valign="top">CPFA0D4 E</td> <td valign="top">File system error occurred. Error number &1.</td> </tr> <tr> <td valign="top">CPF3CF2 E</td> <td valign="top">Error(s) occurred during running of &1 API.</td> </tr> <tr> <td valign="top">CPF9872 E</td> <td valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td> </tr> </table> <br> <h3><a name="HDRLSKUSAG">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> </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>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> </li> <li>QSYS.LIB and Independent ASP QSYS.LIB File System Differences <p>This function is not supported for save files and will fail with error code [ENOTSUP].</p> </li> <li>This function will fail with the [EOVERFLOW] error if the resulting file offset would be a value that cannot be represented correctly in a variable of type off_t (the offset is greater than 2 GB minus 2 bytes).<br> <br> </li> <li>When you develop in C-based languages and an application is compiled with the _LARGE_FILES macro defined, the <strong>lseek()</strong> API will be mapped to a call to the <strong>lseek64()</strong> API. Additionally, the data type off_t will be mapped to the type off64_t.<br> <br> </li> <li>Using this function with the write(), pwrite(), and pwrite64() functions on the /dev/null or /dev/zero character special file will not result in the file data size changing from zero.<br> <br> </li> </ol> <br> <h3>Related Information</h3> <ul> <li>The <<strong>unistd.h</strong>> file (see <a href="unix13.htm">Header Files for UNIX-Type Functions</a>)<br> </li> <li><a href="creat.htm">creat()</a>--Create or Rewrite File<br> </li> <li><a href="dup.htm">dup()</a>--Duplicate Open File Descriptor<br> </li> <li> <a href="fclear.htm">fclear()</a>--Write (Binary Zeros) to Descriptor<br> </li> <li><a href="fclear64.htm">fclear64()</a>--Write (Binary Zeros) to Descriptor (Large File Enabled)<br> </li> <li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command<br> </li> <li><a href="lseek64.htm">lseek64()</a>--Set File Read/Write Offset (Large File Enabled)<br> </li> <li><a href="open.htm">open()</a>--Open File<br> </li> <li><a href="pread.htm">pread()</a>--Read from Descriptor with Offset<br> </li> <li><a href="pread64.htm">pread64()</a>--Read from Descriptor with Offset (large file enabled)<br> </li> <li><a href="pwrite.htm">pwrite()</a>--Write to Descriptor with Offset<br> </li> <li><a href="pwrite64.htm">pwrite64()</a>--Write to Descriptor with Offset (large file enabled)<br> </li> <li><a href="read.htm">read()</a>--Read from Descriptor<br> </li> <li><a href="write.htm">write()</a>--Write to Descriptor</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 positions a file (that has at least 11 bytes) to an offset of 10 bytes before the end of the file:</p> <pre> lseek(file_descriptor,-<samp>1</samp>0,SEEK_END); </pre> <br> <hr> API introduced: V4R4 <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>