lseek

lseek is a POSIX system call used to reposition the file offset associated with an open file descriptor. It does not perform any input or output by itself; the next read or write will use the offset established by lseek. The file offset is maintained per open file description and may be shared among duplicates of the same descriptor.

Prototype and parameters: off_t lseek(int fd, off_t offset, int whence); Returns the new offset on success or -1 on error and sets errno. Whence must be one of SEEK_SET, SEEK_CUR, or SEEK_END. SEEK_SET sets the offset to the specified value relative to the beginning of the file; SEEK_CUR uses the current offset plus the offset; SEEK_END sets the offset to the size of the file plus the offset.

Behavior and errors: On regular files, lseek succeeds and the resulting offset reflects the new position from the start of the file. On non-seekable objects such as pipes, sockets, or terminals, lseek returns -1 with errno set to ESPIPE. If the resulting offset is outside the representable range, EOVERFLOW may be returned. EBADF can indicate a bad file descriptor, and EINVAL can indicate an invalid whence or an invalid combination of offset and whence. Some systems support additional whence values for sparse files, such as SEEK_DATA and SEEK_HOLE.

Large-file and portability notes: Offsets may be 32-bit or 64-bit depending on the platform. For large files, lseek64 or the combination of fseeko/ftello in the C standard library is often recommended for portable 64-bit offsets. In Windows environments, equivalents include _lseek and _lseeki64.

See also: fseek, ftell, fseeko, ftello.