lseek()--Set File Read/Write Offset
Syntax
#include <unistd.h> off_t lseek(int file_descriptor, off_t offset, int whence);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The lseek() function changes the current file offset to a new position in the file. The new position is the given byte offset from the position specified by whence. After you have used lseek() to seek to a new location, the next I/O operation on the file begins at that location.
lseek() 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.
There are some important considerations for lseek() if the O_TEXTDATA and O_CCSID flags were specified on the open(), the file CCSID and open CCSID are not the same, and the converted data could expand or contract:
- 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,
lseek() will only be allowed to change the current file offset to:
- The start of the file (offset 0, whence SEEK_SET)
- The end of the file (offset 0, whence 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.
If any other combination of values is specified, lseek() fails and errno is set to ENOTSUP.
- The start of the file (offset 0, whence SEEK_SET)
- Internally-buffered data from a read or write operation is discarded. See
read()--Read from Descriptor and
write()--Write to Descriptor for more information concerning internal
buffering of text data.
- 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.
- The fcntl() API supports F_GETCVT and F_SETCVT which allow
the saving and restoring of the file offset and conversion
information. See the fcntl() API for more details.
In the QSYS.LIB file and independent ASP QSYS.LIB file systems, while in text mode, you can only seek to the beginning of a member; otherwise, error [EINVAL] will be returned.
Parameters
- file_descriptor
- (Input) The file whose current file offset you want to change.
- offset
- (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).
- whence
- (Input) One of the following symbols (defined in the
<unistd.h> header file):
- SEEK_SET
- The start of the file
- SEEK_CUR
- The current file offset in the file
- SEEK_END
- The end of the file
If bits in whence are set to values other than those defined above, lseek() fails with the [EINVAL] error.
Authorities
No authorization is required. Authorization is verified during open() or creat().
Return Value
- value
- lseek() was successful. The value returned is the new file offset, measured in bytes from the beginning of the file.
- -1
- lseek() was not successful. The errno global variable is set to indicate the error.
Error Conditions
If lseek() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Error condition | Additional information |
---|---|
[EACCES] |
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. |
[EAGAIN] | |
[EBADF] | |
[EBADFID] | |
[EBUSY] | |
[EDAMAGE] | |
[EINVAL] | |
[EIO] | |
[ENOENT] | |
[ENOSPC] | |
[ENOSYSRSC] | |
[ENOTAVAIL] | |
[ENOTSAFE] | |
[ENOTSUP] | |
[EOVERFLOW] |
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). |
[ESPIPE] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
If interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
- Where multiple threads exist in the job.
- 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:
- "Root" (/)
- QOpenSys
- User-defined
- QNTC
- QSYS.LIB
- Independent ASP QSYS.LIB
- QOPT
- Network File System
- QFileSvr.400
- Where multiple threads exist in the job.
- Network File System Differences
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).
- QSYS.LIB and Independent ASP QSYS.LIB File System Differences
This function is not supported for save files and will fail with error code [ENOTSUP].
- 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).
- When you develop in C-based languages and an application is compiled with
the _LARGE_FILES macro defined, the lseek() API will be mapped
to a call to the lseek64() API. Additionally, the data type
off_t will be mapped to the type off64_t.
- 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.
Related Information
- The <unistd.h> file (see Header
Files for UNIX®-Type Functions)
- creat()--Create or Rewrite File
- dup()--Duplicate Open File Descriptor
-
fclear()--Write (Binary Zeros) to Descriptor
- fclear64()--Write (Binary Zeros) to Descriptor
(Large File Enabled)
- fcntl()--Perform File Control Command
- lseek64()--Set File Read/Write Offset (Large File
Enabled)
- open()--Open File
- pread()--Read from Descriptor with Offset
- pread64()--Read from Descriptor with Offset
(large file enabled)
- pwrite()--Write to Descriptor with Offset
- pwrite64()--Write to Descriptor with Offset
(large file enabled)
- read()--Read from Descriptor
- write()--Write to Descriptor
Example
The following example positions a file (that has at least 11 bytes) to an offset of 10 bytes before the end of the file.
lseek(file_descriptor,-10,SEEK_END);
API introduced: V4R4