lseek() — Change the offset of a file

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <unistd.h>

off_t lseek(int fildes, off_t offset, int pos);

General description

Changes the current file offset to a new position in a z/OS UNIX file. The new position is the given byte offset from the position specified by pos. 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 zeros. (In other words, the gap is assumed to be filled with zeros.)

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.

Special behavior for POSIX C: For character special files, lseek() sets the file offset to the specified value. z/OS® UNIX services ignore the file offset value during the read/write processing to character special files.

int fildes;

The file whose current file offset you want to change.

off_t offset;

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).

int pos;

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

Large file support for z/OS UNIX files: Large z/OS UNIX files are supported automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable this function to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.

Returned value

If successful, lseek() returns the new file offset, measured in bytes from the beginning of the file.

If unsuccessful, lseek() returns -1 and sets errno to one of the following values:

Error Code: Description
EBADF: fildes is not a valid open file descriptor.
EINVAL: pos contained something other than one of the three options, or the combination of the pos values would have placed the file offset before the beginning of the file.
EOVERFLOW: The resulting file offset would be a value which cannot be represented correctly in an object of type off_t.
ESPIPE: fildes is associated with a pipe or FIFO special file.

Example

This fragment positions a file (that has at least 10 bytes) to an offset of 10 bytes before the end of the file.

lseek(fildes,-10,SEEK_END);