Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  ex-
       isting  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() function
       will not, by itself, extend the size of a 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  re-
	     sulting file pointer would	be negative.

       EOVERFLOW
	     The resulting file	offset would be	a value	which cannot be	repre-
	     sented 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:

       +-----------------------------+-----------------------------+
       |      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)

SunOS 5.9			  28 Jan 1998			      lseek(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lseek&sektion=2&manpath=SunOS+5.9>

home | help