#include <unistd.h> off_t
lseek (int fildes off_t offset int whence);
DESCRIPTION
The
lseek ();
system call repositions the offset of the file descriptor
Fa fildes
to the
argument
Fa offset
according to the directive
Fa whence .
The argument
Fa fildes
must be an open
file descriptor.
The
lseek ();
system call
repositions the file position pointer associated with the file
descriptor
Fa fildes
as follows:
If
Fa whence
is
SEEK_SET
the offset is set to
Fa offset
bytes.
If
Fa whence
is
SEEK_CUR
the offset is set to its current location plus
Fa offset
bytes.
If
Fa whence
is
SEEK_END
the offset is set to the size of the
file plus
Fa offset
bytes.
If
Fa whence
is
SEEK_HOLE
the offset of the start of the next hole greater than or equal to the supplied
Fa offset
is returned.
The definition of a hole is provided below.
If
Fa whence
is
SEEK_DATA
the offset is set to the start of the next non-hole file region greater
than or equal to the supplied
Fa offset .
The
lseek ();
system call allows the file offset to be set beyond the end
of the existing end-of-file of the file.
If data is later written
at this point, subsequent reads of the data in the gap return
bytes of zeros (until data is actually written into the gap).
Some devices are incapable of seeking.
The value of the pointer
associated with such a device is undefined.
A
Qq hole
is defined as a contiguous range of bytes in a file, all having the value of
zero, but not all zeros in a file are guaranteed to be represented as holes
returned with
SEEK_HOLE
File systems are allowed to expose ranges of zeros with
SEEK_HOLE
but not required to.
Applications can use
SEEK_HOLE
to optimise their behavior for ranges of zeros, but must not depend on it to
find all such ranges in a file.
The existence of a hole at the end of every data region allows for easy
programming and implies that a virtual hole exists at the end of the file.
Applications should use
fpathconf (_PC_MIN_HOLE_SIZE);
or
pathconf (_PC_MIN_HOLE_SIZE);
to determine if a file system supports
SEEK_HOLE
See
pathconf(2).
For file systems that do not supply information about holes, the file will be
represented as one entire data region.
RETURN VALUES
Upon successful completion,
lseek ();
returns the resulting offset location as measured in bytes from the
beginning of the file.
Otherwise,
a value of -1 is returned and
errno
is set to indicate
the error.
ERRORS
The
lseek ();
system call
will fail and the file position pointer will remain unchanged if:
Bq Er EBADF
The
Fa fildes
argument
is not an open file descriptor.
Bq Er EINVAL
The
Fa whence
argument
is not a proper value
or the resulting file offset would
be negative for a non-character special file.
Bq Er ENXIO
For
SEEK_DATA
there are no more data regions past the supplied offset.
For
SEEK_HOLE
there are no more holes past the supplied offset.
Bq Er EOVERFLOW
The resulting file offset would be a value which cannot be represented
correctly in an object of type
Fa off_t .
Bq Er ESPIPE
The
Fa fildes
argument
is associated with a pipe, socket, or FIFO.
