sunos man page for lseek

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 <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, sub-
       sequent 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() func-
       tion 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 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 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 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 attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-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)