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
       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.

       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