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  offset
          bytes.

     SEEK_END
          The offset is set to the size of the file  plus  offset
          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 actually writ-
     ten 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 written
     characters, using SEEK_SET to set the  counter.   Some  dev-
     ices,  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:

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