Open System Services System Calls Reference Manual (G06.25+, H06.03+)

System Functions (k - m) lseek(2)
NAME
lseek - Sets file offset for read or write operation
LIBRARY
G-series native OSS processes: system library
H-series OSS processes: implicit libraries
SYNOPSIS
#include <sys/types.h> /* optional except for POSIX.1 */
#include <unistd.h>
off_t lseek(
int filedes,
off_t offset,
int whence);
PARAMETERS
filedes Specifies an open file descriptor obtained from a successful call to the accept(),
creat(), dup( ), dup2( ), fcntl( ), open(), pipe( ), socket(),orsocketpair() func-
tion.
offset Specifies a value, in bytes, that is used with the whence parameter to set the file
pointer. A negative value causes seeking in the reverse direction.
whence Specifies how to interpret the offset parameter in setting the file pointer associ-
ated with the filedes parameter. Values for the whence parameter are:
SEEK_CUR Sets the file pointer to its current location plus the value of the
offset parameter.
SEEK_END Sets the file pointer to the size of the file plus the value of the
offset parameter.
SEEK_SET Sets the file pointer to the value of the offset parameter.
DESCRIPTION
The lseek() function sets the file offset for the open file specified by the filedes parameter. The
whence parameter determines how the offset is to be interpreted.
The lseek() function allows the file offset to be set beyond the end of existing data in the file. If
data is later written at this point, subsequent reading of data in the gap returns bytes with the
value 0 (zero) until data is actually written into the gap.
The lseek() function does not, by itself, extend the size of the file.
RETURN VALUES
Upon successful completion, the resulting pointer location, measured in bytes from the beginning
of the file, is returned. For FIFOs, pipes, and character special files, 0 (zero) is returned. For char-
acter special files, errno is not set.
If the lseek() function fails, the file offset remains unchanged, a value of -1 cast to the type off_t
is returned, and errno is set to indicate the error.
ERRORS
If any of these conditions occurs, the file offset remains unchanged, and the lseek() function sets
errno to the corresponding value:
[EBADF] The filedes parameter is not an open file descriptor.
527186-003 Hewlett-Packard Company 4−11