View Source: lseek(2) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages

!!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(2) 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(2) 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.
;[EOVERFLOW]: file is larger than can fit in off_t

!!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(2) 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 (hysterical?) reasons.

When converting old code, substitute values for ''whence'' with the following macros:

SVR1-3 returns __long__ instead of __off_t__, [BSD] returns __int__.

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

24 pages link to lseek(2):

This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.

Last edited on Wednesday, October 29, 2003 8:37:12 am by JohnMcPherson

Edit PageHistory Diff Info LikePages