[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

lseek, llseek or lseek64 Subroutine

Purpose

Moves the read-write file pointer.

Library

Standard C Library (libc.a)

Syntax


off_t lseek ( FileDescriptor, Offset, Whence)
int FileDescriptor, Whence;
off_t Offset;

offset_t llseek (FileDescriptor, Offset, Whence)
int FileDescriptor, Whence;
offset_t Offset;

Note: The lseek64 subroutine applies to AIX 4.2 and later releases. 

off64_t lseek64 (FileDescriptor, Offset, Whence)
int FileDescriptor, Whence;
off64_t Offset;

Description

Note: The lseek64 subroutine applies to AIX 4.2 and later releases.

The lseek, llseek, and lseek64 subroutines set the read-write file pointer for the open file specified by the FileDescriptor parameter. The lseek subroutine limits the Offset to OFF_MAX.

In AIX 4.1, the llseek subroutine limits the Offset to OFF_MAX if the file associated with FileDescriptor is a regular file or a directory and to DEV_OFF_MAX if the file associated with FileDescriptor is a block special or character special file.

In AIX 4.2, both the llseek subroutine and the lseek64 subroutine limit the Offset to the maximum file size for the file size for the file associated with FileDescriptor and to DEV_OFF_MAX if the file associated with FileDescriptor is a block special or character special file.

In the large file enabled programming environment, lseek subroutine is redefined to lseek64.

Parameters


FileDescriptor Specifies a file descriptor obtained from a successful open or fcntl subroutine.
Offset Specifies a value, in bytes, that is used in conjunction 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 by setting the file pointer associated with the FileDescriptor parameter to one of the following variables:

SEEK_SET
Sets the file pointer to the value of the Offset parameter.

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.

Return Values

Upon successful completion, the resulting pointer location, measured in bytes from the beginning of the file, is returned. If either the lseek or llseek subroutines are unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The lseek or llseek subroutines are unsuccessful and the file pointer remains unchanged if any of the following are true:

EBADF The FileDescriptor parameter is not an open file descriptor.
ESPIPE The FileDescriptor parameter is associated with a pipe (FIFO) or a socket.
EINVAL The resulting offset would be greater than the maximum offset allowed for the file or device associated with FileDescriptor.
EOVERFLOW The resulting offset is larger than can be returned properly.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Files


/usr/include/unistd.h Defines standard macros, data types and subroutines.

Related Information

The fcntl (fcntl, dup, or dup2 Subroutine) subroutine, fseek, rewind, ftell, fgetpos, or fsetpos (fseek, fseeko, fseeko64, rewind, ftell, ftello, ftello64, fgetpos, fgetpos64, fsetpos, or fsetpos64 Subroutine) subroutine, open, openx, or creat (open, openx, open64, creat, or creat64 Subroutine) subroutine, read, readx, readv, or readvx subroutine, write, writex, writev, or writevx subroutine.

File Systems and Directories in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]