lseek(), lseek64()

reposition read/write file offset 

Function


SYNOPSIS

#include <sys/types.h>

#include <unistd.h>

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

off64_t lseek64(int fildes, off64_t offset, int whence);


DESCRIPTION

The lseek() function repositions the read/write file offset. The fildes parameter is an open file descriptor. Specifically, the lseek() function sets the file offset for the open file description associated with fildes as follows:

The lseek() function allows the file offset to be set beyond the end of existing data in the file. Later, if data are written at this point, subsequent reads of data in the gap return bytes with the value zero until data is actually written into the gap.

The lseek() function cannot, by itself, extend the size of a file.

The lseek64() function is identical to the lseek() function except that it uses the larger off64_t in order to manipulate the file position of files that are larger than 2 gigabytes. The lseek64() function is a part of the large file extensions.

Some devices cannot seek. The value of the file pointer associated with a non-seeking device is undefined.


PARAMETERS

fildes 

Is the file descriptor of an open file.

offset 

Specifies the number of bytes to offset the file pointer from a specified file origin.

whence 

Specifies the location from which to start seeking.


RETURN VALUES

If successful, lseek() and lseek64() return a nonnegative integer that indicates the file pointer value. On failure, lseek() and lseek64() return a value of -1, do not change the file offset, and set errno to one of the following values:

EBADF 

fildes is not a valid file descriptor.

EINVAL 

whence is not a proper value (SEEK_SET, SEEK_CUR, or SEEK_END), or the resulting file offset would be invalid.

EISDIR 

fildes is associated with a directory.

EOVERFLOW 

The resulting file offset would be a value which cannot be represented correctly in an object of type off_t.

ESPIPE 

fildes is associated with a pipe or FIFO.


CONFORMANCE

POSIX.1 (1996).

lseek64(): Large File Specification, revision 1.5.


MULTITHREAD SAFETY LEVEL

Async-signal-safe.


PORTING ISSUES

When performing I/O to text mode files, the return value from read() or write() is not an accurate indication of how much the file position may have changed. For example, writing 10 bytes to a text mode file may cause the file position to change by more than 10 bytes, because of line termination issues. Text lines on Windows end in carriage return-linefeed, rather than in linefeed alone as on UNIX.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
creat(), dup(), fcntl(), open(), read(), write()

Miscellaneous:
lf64


PTC MKS Toolkit 10.1 patch 1 Documentation Build 2.