Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for lseek (opensolaris section 2)

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 speci-
       fied 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 pro-
		  vided 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 <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 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.

       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  vir-
       tual   hole   exists   at   the	 end   of   the  file.	Applications  should  use  fpath-
       conf(_PC_MIN_HOLE_SIZE) or pathconf(_PC_MIN_HOLE_SIZE) to determine if a  filesystem  sup-
       ports SEEK_HOLE. See fpathconf(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 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.

       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 cor-
		    rectly 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),  fpathconf(2),  open(2),  read(2),	write(2),  attributes(5),
       lf64(5), standards(5)

SunOS 5.11				    4 May 2005					 lseek(2)


All times are GMT -4. The time now is 06:55 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password