lseek

Positions the file read or write offset.

Library:LibC
Classification:POSIX
Service:File and Directory I/O

Syntax

  #include <unistd.h> 
   
  off_t lseek (
     int     fildes,
     off_t   offset,
     int     whence);

Parameters

fildes

(IN) Specifies a file descriptor.

offset

(IN) Specifies the relative offset from the file position specified by the whence parameter.

whence

(IN) Specifies the seek starting point and uses one of the following flags:

Flag

Value

Description

SEEK_SET

0

The new file position is computed relative to the start of the file.

SEEK_CUR

1

The new file position is computed relative to the current file position.

SEEK_END

2

The new file position is computed relative to the end of the file.

Return Values

If successful, returns the resulting offset, as measured in bytes from the beginning of the file. Otherwise, returns -1 and sets errno to one of the following:

Decimal

Constant

Description

4

EBADF

Bad file number.

9

EINVAL

Either the whence parameter or the resulting file offset is an invalid value.

33

ESPIPE

The fildes argument is associated with a pipe, FIFO, or socket rather than a file.

81

EOVERFLOW

The resulting file offset cannot be represented correctly in an object of type off_t.

Remarks

The lseek function allows the file offset to be set beyond the end of existing data in the file. If data is written at this point, a data gap results. A subsequent read to the gap returns bytes with a zero value until data is actually written into the gap.

The lseek function cannot, by itself, extend the size of a file.

See Also