lseek(2)

NAME

     lseek - move read/write file pointer

SYNOPSIS

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

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

DESCRIPTION

     The lseek() function sets the file pointer  associated  with
     the open file descriptor specified by fildes as follows:

        o  If whence is SEEK_SET, the pointer is  set  to  offset
           bytes.

        o  If whence is SEEK_CUR,  the  pointer  is  set  to  its
           current location plus offset.

        o  If whence is SEEK_END, the pointer is set to the  size
           of the file plus offset.

     The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END  are
     defined in the header <unistd.h>.

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

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

     If fildes is a remote file descriptor and  offset  is  nega-
     tive,  lseek() returns the file pointer  even if it is nega-
     tive. The lseek() function will not, by itself,  extend  the
     size of a file.

RETURN VALUES

     Upon successful completion, the resulting offset,  as  meas-
     ured  in  bytes from the beginning of the file, is returned.
     Otherwise, (off_t)-1 is returned, the  file  offset  remains
     unchanged, and errno is set to indicate the error.

ERRORS

     The lseek() function will fail if:

     EBADF The fildes argument is not an open file descriptor.

     EINVAL
           The whence argument  is  not  SEEK_SET,  SEEK_CUR,  or
           SEEK_END;  or the fildes argument is not a remote file
           descriptor and the resulting  file  pointer  would  be
           negative.

     EOVERFLOW
           The resulting file offset would be a value which  can-
           not  be  represented  correctly  in  an object of type
           off_t for regular files.

     ESPIPE
           The fildes argument is associated with a pipe, a FIFO,
           or a socket.

USAGE

     The lseek() function has a transitional interface for 64-bit
     file offsets.  See lf64(5).

     In multithreaded applications, using lseek() in  conjunction
     with  a read(2) or write(2) call on a file descriptor shared
     by more than one thread is not an atomic operation.
      To ensure atomicity, use pread() or pwrite().

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

SEE ALSO

     creat(2),  dup(2),  fcntl(2),  open(2),  read(2),  write(2),
     attributes(5), lf64(5)