LSEEK(2)                   System calls                  LSEEK(2)

NAME
       lseek - reposition read/write file offset

SYNOPSIS
       #include <sys/types.h>
       #include <unistd.h>

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

DESCRIPTION
       The  lseek  function  repositions  the  offset of the file
       descriptor fildes to the argument offset according to  the
       directive whence as follows:

       SEEK_SET
              The offset is set to offset bytes.

       SEEK_CUR
              The offset is set to its current location plus off-
              set bytes.

       SEEK_END
              The offset is set to the size of the file plus off-
              set bytes.

       The lseek function allows the file offset to be set beyond
       the end of the existing end-of-file of the file.  If  data
       is  later  written  at this point, subsequent reads of the
       data in the gap return bytes of zeros (until data is actu-
       ally written into the gap).

RETURN VALUES
       Upon  successful  completion,  lseek returns the resulting
       offset location as measured in bytes from the beginning of
       the file.  Otherwise, a value of (off_t)-1 is returned and
       errno is set to indicate the error.

ERRORS
       EBADF  Fildes is not an open file descriptor.

       ESPIPE Fildes is associated with a pipe, socket, or  FIFO.

       EINVAL Whence is not a proper value.

CONFORMING TO
       SVr4, POSIX, BSD 4.3

RESTRICTIONS
       Some  devices  are incapable of seeking and POSIX does not
       specify which devices must support it.

       Linux specific restrictions: using lseek on a  tty  device
       returns  ESPIPE.  Other systems return the number of writ-
       ten characters, using SEEK_SET to set the  counter.   Some
       devices, e.g. /dev/null do not cause the error ESPIPE, but
       return a pointer which value is undefined.

NOTES
       This document's use of whence is  incorrect  English,  but
       maintained for historical reasons.

       When  converting  old  code,  substitute values for whence
       with the following macros:

        old       new
       0        SEEK_SET
       1        SEEK_CUR
       2        SEEK_END
       L_SET    SEEK_SET
       L_INCR   SEEK_CUR
       L_XTND   SEEK_END

       SVR1-3 returns long instead of off_t, BSD returns int.

SEE ALSO
       dup(2), open(2), fseek(3)

Linux                    January 17, 1998                       1