unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

lseek(2)                         System Calls                         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 <&lt;unistd.h>&gt;.

       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  negative,  lseek()
       returns  the file pointer  even if it is negative. The lseek() function
       will not, by itself, extend the size of a file.

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

RETURN VALUES
       Upon  successful completion, the resulting offset, as measured 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 indi-
       cate 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 neg-
                       ative.



       EOVERFLOW       The resulting file offset would be a value which cannot
                       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  off-
       sets.  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 attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityStan-
       dard MT-LevelAsync-Signal-Safe


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



SunOS 5.10                        17 Apr 2002                         lseek(2)