lseek(), lseek64()

Set the current file position at the operating-system level

Synopsis:

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

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

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

Arguments:

filedes

The file descriptor of the file whose position you want to set.

offset

The relative offset from the file position determined by the whence argument.

whence

The position in the file. The possible values (defined in <unistd.h>) are:

SEEK_CUR

The new file position is computed relative to the current file position. The value of offset may be positive, negative or zero.

SEEK_END

The new file position is computed relative to the end of the file.

SEEK_SET

The new file position is computed relative to the start of the file. The value of offset must not be negative.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

These functions set the current file position for the file descriptor specified by filedes at the operating system level. File descriptors are returned by a successful execution of one of the creat(), dup(), dup2(), fcntl(), open() or sopen() functions.

An error occurs if the requested file position is before the start of the file.

If the requested file position is beyond the end of the file and data is written at this point, subsequent reads of data in the gap will return bytes whose value is equal to zero ('\0') until data is actually written into the gap.

These functions don't extend the size of a file (see chsize()).

Returns:

The current file position, with 0 indicating the start of the file, or -1 if an error occurs (errno is set).

Errors:

EBADF

The filedes argument isn't a valid file descriptor.

EINVAL

The whence argument isn't a proper value, or the resulting file offset is invalid.

ENOSYS

The lseek() function isn't implemented for the filesystem specified by filedes.

EOVERFLOW

The resulting file offset is a value that can't be represented correctly in an object of type off_t.

ESPIPE

The filedes argument is associated with a pipe or FIFO.

Examples:

Using the lseek() function, you can get the current file position (in fact, tell() is implemented this way). You can then use this value with another call to lseek() to reset the file position:

off_t file_posn;
int filedes;

/* get current file position */
file_posn = lseek( filedes, 0L, SEEK_CUR );

…

/* return to previous file position */
file_posn = lseek( filedes, file_posn, SEEK_SET );

If all records in the file are the same size, the position of the nth record can be calculated and read like this:

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

int read_record( int filedes, long rec_numb, 
                 int rec_size, char *buffer )
{
    if( lseek( filedes , rec_numb * rec_size, 
               SEEK_SET ) == -1L ) {
        return -1;
    }

    return( read( filedes , buffer, rec_size ) );
}

The read_record() function in this example assumes records are numbered starting with zero, and that rec_size contains the size of a record in the file, including any record-separator characters.

Classification:

lseek() is POSIX 1003.1; lseek64() is Large-file support

See also:

chsize(), close(), creat(), dup(), dup2(), eof(), errno, execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), fcntl(), fileno(), fstat(), isatty(), open(), read(), sopen(), stat(), tell(), umask(), write()