lseek(2)
NAME
lseek, tell − move read/write pointer
SYNTAX
long lseek(fildes, offset, whence)
int fildes, whence;
long offset;
long tell(fildes)
int fildes;
DESCRIPTION
The lseek system call moves the read/write pointer for the open file named by fildes. The read/write pointer for the file is set as follows:
•If whence is 0, the pointer is set to offset bytes.
•If whence is 1, the pointer is set to its current location plus offset.
•If whence is 2, the pointer is set to the size of the file plus offset.
The obsolete function tell(fildes) is identical to lseek(fildes, 0L, 1).
Seeking far beyond the end of a file, then writing, creates a gap or “hole”, which occupies no physical space and reads as zeros.
RESTRICTIONS
The lseek call is a no-op on character special files. Some devices are incapable of seeking. The value of the file pointer associated with such a device is undefined.
RETURN VALUE
If successful, returns the new file offset. If unsuccessful, returns a −1, and the global variable errno indicates the error code.
DIAGNOSTICS
The lseek call will fail if:
[EBADF] The specified fildes is not an open file descriptor.
[ESPIPE] The specified fildes is associated with a pipe.
[EINVAL and SIGSYS signal]
The specified whence is not 0,1, or 2.
[EINVAL] The resulting file pointer would be negative.
ASSEMBLER
(lseek = 19.)
(file descriptor in r0)
sys lseek; offset1; offset2; whence
The offset1 and offset2 are the high and low words of offset; r0 and r1 contain the pointer upon return.