Manual page for lseek(2)
lseek - move read/write file pointer
SYNOPSIS
#include <sys/types.h>
#include <unistd.h>
off_t lseek(int fildes,
off_t offset,
int whence);
DESCRIPTION
The
lseek()
function sets the file pointer associated with the
open file descriptor specified by
fildes
as follows:
-
- If
whence
is SEEK_SET, the pointer is set to
offset
bytes.
- If
whence
is SEEK_CUR, the pointer is set to its current location plus
offset.
- If
whence
is SEEK_END, the pointer is set to the size of the
file plus
offset.
The symbolic constants
SEEK_SET,
SEEK_CUR,
and
SEEK_END
are defined in the header
<unistd.h>.
Some devices are incapable of seeking.
The value of the file pointer associated with such a device
is undefined.
The
lseek()
function allows the file pointer to be set beyond the existing data
in the file. If data are later written at this point, subsequent reads
in the gap between the previous end of data and the newly written data
will return bytes of value 0 until data are written into the gap.
If fildes is a remote file descriptor
and offset is negative,
lseek()
returns the file pointer
even if it is negative.
The
lseek()
function will not, by itself, extend the size of a file.
RETURN VALUES
Upon successful completion, the resulting offset,
as measured in bytes from the beginning of the file, is returned.
Otherwise, (off_t)-1 is returned,
errno
is set to indicate the error and the file offset will remain unchanged.
ERRORS
The
lseek()
function fails if:
- EBADF
-
The
fildes
argument is not an open file descriptor.
- EINVAL
-
The
whence
argument is not SEEK_SET, SEEK_CUR,
or SEEK_END.
- EINVAL
-
The
fildes argument is not a remote file descriptor, and
the resulting file pointer would be negative.
- EOVERFLOW
-
The resulting file offset would be a value which cannot be
represented correctly in an object of type
off_t
for regular files.
- ESPIPE
-
The
fildes
argument is associated with a pipe, a FIFO, or a socket.
USAGE
The
lseek()
function has an explicit 64-bit equivalent. See
interface64.5
ATTRIBUTES
See
attributes.5
for descriptions of the following attributes:
+---------------+-------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-------------------+
|MT-Level | Async-Signal-Safe |
+---------------+-------------------+
SEE ALSO
creat.2
dup.2
fcntl.2
open.2
read.2
write.2
attributes.5
interface64.5
NOTES
In multithreaded programs, using
lseek()
in conjunction with a
read()
or
write()
on a file descriptor shared amongst more than one thread is not an atomic
operation. To ensure atomicity, use
pread()
or
pwrite().
Created by unroff & hp-tools.
© by Hans-Peter Bischof. All Rights Reserved (1997).
Last modified 07/October/97
