off_t lseek(int fildes, off_t offset, int whence);
Description
The fildes argument is a file descriptor returned from a
creat, open, dup, or fcntl
system call.
The lseek system call
sets the file pointer associated with
fildes as follows:
If whence is 0, the pointer is set to
offset bytes.
If whence is 1, the pointer is set to
its current location plus offset.
If whence
is 2, the pointer is set to
the size of the file plus offset.
Symbolic constants for whence are
defined in the <unistd.h> header file:
Name
Description
SEEK_CUR
Set file-pointer to current location plus offset.
SEEK_END
Set file-pointer to EOF plus offset.
SEEK_SET
Set file-pointer equal to offset bytes.
Upon successful completion, the resulting pointer location,
as measured in bytes from the beginning of the file, is returned.
Note that if fildes is a remote file descriptor
and offset is negative,
lseek returns the file pointer
even if it is negative.
lseek fails
and the file pointer remains unchanged
if one or more of the following is true:
[EBADF]
fildes is not an open file descriptor.
[EINVAL]
(with SIGSYS signal is present):
The whence argument is not 0, 1, or 2.
fildes is not a remote file descriptor, and
the resulting file pointer would be negative.
Some devices are incapable of seeking.
The value of the file pointer associated with such a device
is undefined.
[ESPIPE]
fildes is associated with a pipe or fifo.
Diagnostics
Upon successful completion, a non-negative integer
indicating the file pointer value is returned.
Otherwise, a value of -1 is returned, and
errno is set to indicate the error.