lseek(2)lseek(2)NAME
lseek, lseek64 - move read/write file pointer
C SYNOPSIS
#include <sys/types.h>
#include <unistd.h>
off_t lseek (int fildes, off_t offset, int whence);
off64_t lseek64 (int fildes, off64_t offset, int whence);
DESCRIPTION
fildes is a file descriptor returned from a creat, open, dup, fcntl,
pipe, or ioctl system call. lseek and lseek64 set the file pointer
associated with 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.
On success, lseek returns the resulting pointer location, as measured in
bytes from the beginning of the file. Note that for file descriptors
that correspond to regular files or directories, lseek does not allow
negative file offsets. For device special files, the allowable offset
values are determined by the individual device drivers.
lseek 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.
lseek64 is identical in behavior to lseek except that the type of offset
is off64_t instead of off_t . The 64-bit offset value is useful for files
in XFS filesystems as well as in devices larger than 2 gigabytes in size,
such as large disks or volumes.
lseek fails and the file pointer remains unchanged if one or more of the
following are true:
EBADF fildes is not an open file descriptor.
ESPIPE fildes is associated with a pipe, fifo, or socket.
EINVAL whence is not SEEK_SET, SEEK_CUR, or SEEK_END. The
process also gets a SIGSYS signal.
Page 1
lseek(2)lseek(2)
EINVAL fildes corresponds to a regular file or directory 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.
SEE ALSOcreat(2), dup(2), fcntl(2), open(2).
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. For lseek, the return value type is
off_t; for lseek64, the return value type is off64_t.
Page 2
