NAME

lseek − move read/write file pointer

SYNOPSIS (SYSV.2)

#include <sys/types.h>
#include <unistd.h>
off_t lseek (fildes, offset, whence)
int fildes;
off_t offset;
int whence;

SYNOPSIS (4.2BSD)

#include <sys/types.h>
#include <sys/file.h>
off_t lseek (fildes, offset, whence)
int fildes;
off_t offset;
int whence;

DESCRIPTION

Fildes is a file descriptor returned from a creat, open, dup, or fcntl system call.  lseek sets the file pointer associated with fildes as follows:

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

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

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

In the ucb universe, <sys/file.h> contains definitions for the constants above:

L_SETset pointer relative to beginning of file
L_INCRset pointer relative to current position
L_XTNDset pointer relative to end of file

Upon successful completion, the resulting pointer location, as measured in bytes from the beginning of the file, is returned. 

lseek will fail and the file pointer will remain unchanged if one or more of the following are true:

­[EBADF] Fildes is not an open file descriptor. 

­[ESPIPE] Fildes is associated with a pipe, socket, or fifo. 

­[EINVAL] Whence is not SEEK_SET, SEEK_CUR, SEEK_END (or L_SET, L_INCR, L_XTND). 

­[EINVAL] The resulting file pointer would be negative. 

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

NOTES

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

This call is defined in the 88open Binary and Object Compatibility Standards (BCS/OCS) as well as their respective 88open Networking Supplements (BCSNS/OCSNS) for use in BCS/OCS compliant applications.  OCS/OCSNS-defined functions may be accessed by passing OCS options to cc(1) and ld(1). 

RETURN VALUE

Upon successful completion, a non-negative integer indicating the file pointer value is returned.  Otherwise, a value of −1 is returned and errno is set to indicate the error. 

SEE ALSO

creat(2), dup(2), fcntl(2), open(2). 

CX/UX Programmer’s Reference Manual