./_Man_SunOS_4.1.3_html/html2/lseek.2v.html

Manual page for LSEEK(2V)

lseek, tell - move read/write pointer

SYNOPSIS

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

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

long tell(fd)
int fd;

DESCRIPTION

lseek() sets the seek pointer associated with the open file or device referred to by the descriptor fd according to the value supplied for whence. whence must be one of the following constants defined in <unistd.h>:

SEEK_SET
SEEK_CUR
SEEK_END

If whence is SEEK_SET, the seek pointer is set to offset bytes. If whence is SEEK_CUR, the seek pointer is set to its current location plus offset. If whence is SEEK_END, the seek pointer is set to the size of the file plus offset.

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

The obsolete function tell(fd) is equivalent to lseek(fd, 0L, SEEK_CUR).

RETURN VALUES

On success, lseek() returns the seek pointer location as measured in bytes from the beginning of the file. On failure, it returns -1 and sets errno to indicate the error.

ERRORS

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

EBADF: fd is not an open file descriptor.
EINVAL: whence is not a proper value.
: The seek operation would result in an illegal file offset value for the file (for example, a negative file offset for a file other than a character special file).
ESPIPE: fd is associated with a pipe or a socket.

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.

The constants L_SET, L_INCR, and L_XTND are provided as synonyms for SEEK_SET, SEEK_CUR, and SEEK_END, respectively for backward compatibility but they will disappear in a future release. It is unlikely that the underlying constants 0, 1 and 2 will ever change.