lseek(2)

lseek, lseek64 -- move read/write file pointer

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

lseek moves a read/write file pointer. fildes is a file descriptor returned from a creat(2), open(2), dup(2), fcntl(2), pipe(2) or ioctl(2) system call. lseek sets 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.

lseek allows the file pointer to be set beyond the existing data in the file. If data is later written at this point, subsequent reads in the gap between the previous end of data and the newly written data return bytes of value 0 until data is written into the gap.

Return values

On success, lseek and lseek64 return a non-negative integer indicating the file pointer value. On failure, lseek and lseek64 return -1, set errno to identify the error, and the file pointer remains unchanged.

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

Errors

In the following conditions, lseek fails and sets errno to:

EOVERFLOW: The resulting file offset would be a value which cannot be represented correctly in an object of type off_t. The file pointer is not moved.

In the following conditions, lseek and lseek64 fail and set errno to:

EBADF: fildes is not an open file descriptor.
ESPIPE: fildes is associated with a pipe, fifo or socket.
EINVAL: The resulting file pointer would be negative.
fildes is a remote file descriptor accessed using NFS, the Network File System, and the resulting file pointer would be negative.
ENOSYS: The device for fstype does not support lseek or lseek64.

References

creat(2), dup(2), fcntl(2), intro(2), open(2)

Notices

Considerations for threads programming

Open file descriptors are a process resource and available to any sibling thread; if used concurrently, actions by one thread can interfere with those of a sibling. For example, the position of the file pointer is maintained per file descriptor, not per thread.

The pread(2) and pwrite(2) system calls combine positioning and I/O in a single operation.

Considerations for Large File Support

lseek64 supports large files, but is otherwise identical to lseek. For details on programming for large file capable applications, see ``Large File Support'' on intro(2).