lseek(), lseek64() -- reposition read/write file offset

SYNOPSIS

#include <sys/types.h>

#include <unistd.h>

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

off64_t lseek64(int fildes, off64_t offset, int whence);

The lseek() function repositions the read/write file offset. The fildes parameter is an open file descriptor. Specifically, the lseek() function sets the file offset for the open file description associated with fildes as follows:

If whence is SEEK_SET, the offset is set to offset bytes.

If whence is SEEK_CUR, the offset is set to its current value plus offset bytes.

If whence is SEEK_END, the offset is set to the size of the file plus offset bytes.

The lseek() function allows the file offset to be set beyond the end of existing data in the file. Later, if data are written at this point, subsequent reads of data in the gap return bytes with the value zero until data is actually written into the gap.

The lseek() function cannot, by itself, extend the size of a file.

The lseek64() function is identical to the lseek() function except that it uses the larger off64_t in order to manipulate the file position of files that are larger than 2 gigabytes. The lseek64() function is a part of the large file extensions.

Some devices cannot seek. The value of the file pointer associated with a non-seeking device is undefined.

PARAMETERS

fildes: Is the file descriptor of an open file.
offset: Specifies the number of bytes to offset the file pointer from a specified file origin.
whence: Specifies the location from which to start seeking.

RETURN VALUES

If successful, lseek() and lseek64() return a nonnegative integer that indicates the file pointer value. On failure, lseek() and lseek64() return a value of -1, do not change the file offset, and set errno to one of the following values:

EBADF: fildes is not a valid file descriptor.
EINVAL: whence is not a proper value (SEEK_SET, SEEK_CUR, or SEEK_END), or the resulting file offset would be invalid.
EISDIR: fildes is associated with a directory.
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.

CONFORMANCE

POSIX.1 (1996).

lseek64(): Large File Specification, revision 1.5.

MULTITHREAD SAFETY LEVEL

Async-signal-safe.

PORTING ISSUES

When performing I/O to text mode files, the return value from read() or write() is not an accurate indication of how much the file position may have changed. For example, writing 10 bytes to a text mode file may cause the file position to change by more than 10 bytes, because of line termination issues. Text lines on Windows end in carriage return-linefeed, rather than in linefeed alone as on UNIX.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

lseek(), lseek64()
reposition read/write file offset

Function