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:

The lseek() and lseek64() functions set the current file position for the file descriptor specified by filedes at the operating system level. The lseek64() function is a large-file support version of lseek(). File descriptors are returned by a successful execution of one of the creat(), dup(), dup2(), fcntl(), open() or sopen() functions.

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see “Classification” in What's in a Function Description?

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 ftruncate()).

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 underlying device is incapable of seeking.
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, FIFO, or socket.

Examples:

Using the lseek() function, you can get the current file position. 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

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes