NAME

lseek, tell − move read/write pointer

SYNOPSIS

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

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

DESCRIPTION

The descriptor des refers to a file or device open for reading and/or writing.  lseek() sets the file pointer associated with des as follows:

If whence is L_SET, the pointer is set to offset bytes. 

If whence is L_INCR, the pointer is set to its current location plus offset.

If whence is L_XTND, the pointer is set to the size of the file plus offset.

Some devices are incapable of seeking.  The value of the pointer associated with such a device is undefined. 

The obsolete function tell(fildes) is identical to lseek(fildes, 0L, L_INCR). 

RETURN VALUE

Upon successful completion, the resulting pointer location, as measured in bytes from beginning of the file, is returned.  Otherwise, a value of −1 is returned and errno is set to indicate the error. 

ERRORS

lseek() will fail and the file pointer will remain unchanged if:

EBADF des is not an open file descriptor. 

ESPIPE des is associated with a pipe or a socket. 

EINVAL whence is not a proper value, or the seek operation would result in an illegal file offset value for the file. (e.g. negative file offset for a regular file.) 

SEE ALSO

dup(2), open(2V)

NOTES

Seeking far beyond the end of a file, then writing, may create a gap or “hole”, which occupies no physical space and reads as zeros. 

Sun Release 4.0  —  Last change: 25 March 1989