Manual Pages for UNIX Operating System command usage for man lseek

System Calls                                             lseek(2)



NAME
     lseek - move read/write file pointer

SYNOPSIS
     #include 
     #include 

     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.

         o    If whence is SEEK_HOLE, the offset of the start  of
              the next hole greater than or equal to the supplied
              offset is returned. The definition  of  a  hole  is
              provided near the end of the DESCRIPTION.

         o    If whence is SEEK_DATA, the file pointer is set  to
              the  start of the next non-hole file region greater
              than or equal to the supplied offset.


     The  symbolic  constants   SEEK_SET,   SEEK_CUR,   SEEK_END,
     SEEK_HOLE,   and   SEEK_DATA   are  defined  in  the  header
     .


     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



SunOS 5.11           Last change: 4 May 2005                    1






System Calls                                             lseek(2)



     size of a file.


     If fildes refers to a shared memory object, lseek()  behaves
     as if fildes referred to a regular file.


     A "hole" is defined as a contiguous  range  of  bytes  in  a
     file,  all  having the value of zero, but not all zeros in a
     file are guaranteed to be represented as holes returned with
     SEEK_HOLE. Filesystems are allowed to expose ranges of zeros
     with SEEK_HOLE, but not required to.  Applications  can  use
     SEEK_HOLE  to  optimise  their behavior for ranges of zeros,
     but must not depend on it to find all such ranges in a file.
     The  existence  of  a  hole  at the end of every data region
     allows for easy programming and implies that a virtual  hole
     exists  at  the  end  of  the  file. Applications should use
     fpathconf(_PC_MIN_HOLE_SIZE) or  pathconf(_PC_MIN_HOLE_SIZE)
     to  determine if a filesystem supports SEEK_HOLE. See fpath-
     conf(2).


     For filesystems that do not supply information about  holes,
     the file will be represented as one entire data region.

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.


     ENXIO        For SEEK_DATA, there are no more  data  regions
                  past  the supplied offset. For SEEK_HOLE, there
                  are no more holes past the supplied offset.


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



SunOS 5.11           Last change: 4 May 2005                    2






System Calls                                             lseek(2)



     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       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     creat(2), dup(2), fcntl(2), fpathconf(2), open(2),  read(2),
     write(2), attributes(5), lf64(5), standards(5)





















SunOS 5.11           Last change: 4 May 2005                    3