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

FreeBSD Manual Pages


home | help
lseek(2)			 System	Calls			      lseek(2)

       lseek - move read/write file pointer

       #include	<sys/types.h>
       #include	<unistd.h>

       off_t lseek(int fildes, off_t offset, int whence);

       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.

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

       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.

       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-

       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.

       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

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |Async-Signal-Safe		   |

       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)


Want to link to this manual page? Use this URL:

home | help