lseek(2) lseek(2)
NAME
lseek, lseek64 - move read/write file pointer
SYNOPSIS
#include <sys/types.h>
#include <unistd.h>
offt lseek(int fildes, offt offset, int whence);
off64t lseek64(int fildes, off64t offset, int whence);
DESCRIPTION
fildes is a file descriptor returned from a creat(), open(), dup(), or
fcntl() system call. lseek() sets the file pointer associated with
fildes as follows:
- If whence is SEEKSET, the pointer is set to offset bytes.
- If whence is SEEKCUR, the pointer is set to its current location
plus offset.
- If whence is SEEKEND, the pointer is set to the size of the file
plus offset.
On success, lseek() returns the resulting pointer location, as meas-
ured in bytes from the beginning of the file. Note that if fildes is a
remote file descriptor and offset is negative, lseek() returns the
file pointer even if it is negative.
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.
There is no functional difference between lseek() and lseek64(),
except for the interpretation of off64t [see lfs(5)].
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
lseek() fails and the file pointer remains unchanged if one or more of
the following apply:
EBADF fildes is not an open file descriptor.
ESPIPE fildes is associated with a pipe or fifo.
EINVAL whence is not SEEKSET, SEEKCUR, or SEEKEND. The process
also gets a SIGSYS signal.
Page 1 Reliant UNIX 5.44 Printed 11/98
lseek(2) lseek(2)
EINVAL fildes 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 offt.
Some devices are incapable of seeking. The value of the file pointer
associated with such a device is undefined.
RESULT
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.
NOTES
lseek() will fail if the resulting file offset would exceed the larg-
est value that can be represented correctly in the related data type
which is in use for the call, and will set errno to EOVERFLOW (permit-
ted by PASC Interpretation 1003.1-90 #75).
Programs typically, but incorrectly, fail to check the return value of
this function, which renders the error return less useful. On the
other hand, returning an incorrect offset can result in serious mal-
function as well.
An lseek() to the end of a file using
lseek(fd, 0, SEEKEND);
is quite common. It is unfortunate that these fail on a too-large file
since the return value is usually ignored.
Another potentially serious consequence of ignoring the return value
of lseek() is that programs which extend data files by attempting to
seek beyond the end-of-file and then writing may instead overwrite
existing data.
For example, typical implementations of the dbm and ndbm libraries
contain code such as:
(void) lseek(db->dbmpagf, blkno*PBLKSIZ, LSET);
if (write(db->dbmpagf, pagebuf, PBLKSIZ) != PBLKSIZ)
... error handling ...
The problem is that the return code of lseek() is not checked and so
if blkno*PBLKSIZ overflows the lseek() will fail (or will seek to an
unintended offset) and the data will be written to an unintended
offset.
SEE ALSO
creat(2), dup(2), fcntl(2), open(2), unistd(4), lfs(5), types(5).
Page 2 Reliant UNIX 5.44 Printed 11/98