NAME

lseek − move read/write file pointer; seek

SYNOPSIS

#include <unistd.h>

off_t lseek(int fildes, off_t offset, int whence);

DESCRIPTION

lseek() sets the file pointer associated with the file descriptor 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.

These symbolic constants are defined in <unistd.h>. 

RETURN VALUE

When lseek() completes successfully, it returns an integer, which is the resulting file offset 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. 

For all files that are not character or block special files, the integer returned on successful completion is non-negative.  For character or block special files that correspond to disk sections larger than 2 gigabytes, a non-negative integer is returned for successful seeks beyond 2 gigabytes.  This value is the resulting file offset as measured in bytes from the beginning of the file, when taken as an unsigned value.  -1 always indicates an error return, even when encountered on greater than 2 gigabyte disk sections. 

ERRORS

lseek() fails and the file offset remains unchanged if one or more of the following is true:

[EBADF] fildes is not an open file descriptor. 

[ESPIPE] fildes is associated with a pipe, socket, or FIFO. 

[EINVAL] whence is not one of the supported values. 

[EINVAL] The resulting file offset would be negative. 

[EINVAL] The resulting file offset would be a value which cannot be represented correctly in an object of type off_t. 

WARNINGS

Some devices are incapable of seeking.  The value of the file offset associated with such a device is undefined. 

Using lseek() with a whence of SEEK_END on device special files is not supported and the results are not defined. 

SEE ALSO

creat(2), dup(2), fcntl(2), lseek64(2), open(2), unistd(5). 

STANDARDS CONFORMANCE

lseek(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996