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

FreeBSD Manual Pages

  
 
  

home | help
LSEEK(2)			 System	calls			      LSEEK(2)

NAME
       lseek - reposition read/write file offset

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

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

DESCRIPTION
       The lseek function repositions the offset of the	file descriptor	fildes
       to the argument offset according	to the directive whence	as follows:

       SEEK_SET
	      The offset is set	to offset bytes.

       SEEK_CUR
	      The offset is set	to its current location	plus offset bytes.

       SEEK_END
	      The offset is set	to the size of the file	plus offset bytes.

       The lseek function allows the file offset to be set beyond the  end  of
       the existing end-of-file	of the file.  If data is later written at this
       point, subsequent reads of the data in the gap return  bytes  of	 zeros
       (until data is actually written into the	gap).

RETURN VALUE
       Upon successful completion, lseek returns the resulting offset location
       as measured in bytes from the beginning	of  the	 file.	 Otherwise,  a
       value of	(off_t)-1 is returned and errno	is set to indicate the error.

ERRORS
       EBADF  Fildes is	not an open file descriptor.

       ESPIPE Fildes is	associated with	a pipe,	socket,	or FIFO.

       EINVAL Whence is	not a proper value.

CONFORMING TO
       SVr4, POSIX, BSD	4.3

RESTRICTIONS
       Some  devices are incapable of seeking and POSIX	does not specify which
       devices must support it.

       Linux specific restrictions:  using  lseek  on  a  tty  device  returns
       ESPIPE.	 Other	systems	return the number of written characters, using
       SEEK_SET	to set the counter.  Some devices, e.g.	/dev/null do not cause
       the error ESPIPE, but return a pointer which value is undefined.

NOTES
       This  document's	use of whence is incorrect English, but	maintained for
       historical reasons.

       When converting old code, substitute values for whence with the follow-
       ing macros:

	old	  new
       0	SEEK_SET
       1	SEEK_CUR

       2	SEEK_END
       L_SET	SEEK_SET
       L_INCR	SEEK_CUR
       L_XTND	SEEK_END

       SVR1-3 returns long instead of off_t, BSD returns int.

       Note  that file descriptors created by dup(2) or	fork(2)	share the cur-
       rent file position pointer, so seeking on such files may	be subject  to
       race conditions.

SEE ALSO
       dup(2), fork(2),	open(2), fseek(3)

Linux				  2001-09-24			      LSEEK(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | RESTRICTIONS | NOTES | SEE ALSO

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

home | help