LSEEK(2)                   System calls                  LSEEK(2)

       lseek - reposition read/write file offset

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

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

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

              The offset is set to offset bytes.

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

              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).

       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.

       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.

       SVr4, POSIX, BSD 4.3

       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.

       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.

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

Linux                    January 17, 1998                       1