lseek() sets the seek pointer associated with the open file or device referred to by the descriptor fd according to the value supplied for whence. whence must be one of the following constants defined in <unistd.h>:

SEEK_SET SEEK_CUR SEEK_END

If whence is SEEK_SET, the seek pointer is set to offset bytes. If whence is SEEK_CUR, the seek pointer is set to its current location plus offset. If whence is SEEK_END, the seek pointer is set to the size of the file plus offset.

Some devices are incapable of seeking. The value of the seek pointer associated with such a device is undefined.

The obsolete function tell(fd) is equivalent to lseek(fd, 0L, SEEK_CUR).

On success, lseek() returns the seek pointer location as measured in bytes from the beginning of the file. On failure, it returns -1 and sets errno to indicate the error.

lseek() will fail and the seek pointer will remain unchanged if:

EBADF

fd is not an open file descriptor.

EINVAL

whence is not a proper value. The seek operation would result in an illegal file offset value for the file (for example, a negative file offset for a file other than a character special file).

ESPIPE

fd is associated with a pipe or a socket.

Seeking far beyond the end of a file, then writing, may create a gap or (hole), which occupies no physical space and reads as zeros.

The constants L_SET, L_INCR, and L_XTND are provided as synonyms for SEEK_SET, SEEK_CUR, and SEEK_END, respectively for backward compatibility but they will disappear in a future release. It is unlikely that the underlying constants 0, 1 and 2 will ever change.