lseek()

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 );

Description:

The lseek() function sets the current file position at the operating system level. The file is referenced using the file descriptor filedes, returned by a successful execution of one of the creat(), dup(), dup2(), fcntl(), open() or sopen() functions. The value of offset is used as a relative offset from a file position determined by the value of the argument whence.

The new file position is determined in a manner dependent on the value of whence, which may have one of three possible values (defined in the <stdio.h> or <unistd.h> header file):

SEEK_SET

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

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.

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

The requested file position may be beyond the end of the file. On POSIX-conforming systems, if data is later written at this point, subsequent reads of data in the gap will return bytes whose value is equal to zero until data is actually written in the gap. On systems such DOS and OS/2 that are not POSIX-conforming, data that are read in the gap have arbitrary values.

Some versions of MS-DOS allow seeking to a negative offset, but it is not recommended, since it is not supported by other platforms, and may not be supported in future versions of MS-DOS.

The lseek() function does not, in itself, extend the size of a file (see the description of the chsize() function).

Returns:

If successful, lseek() returns the resulting offset location as measured in bytes from the beginning of the file. When an error occurs, it returns ((off_t) -1), errno is set to indicate the error, and the file offset isn't changed.

Errors:

EBADF

The filedes argument is not a valid file descriptor.

EINVAL

The whence argument is not a proper value, or the resulting file offset would be invalid.

ESPIPE

The filedes argument is associated with a pipe or FIFO.

Examples:

The lseek() function can be used to obtain the current file position (the tell() function is implemented in terms of lseek()). This value can then be used with the lseek() function to reset the file position to that point in the file:

off_t
file_posn;
int filedes ;

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

/* 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, as illustrated in the following sample function:

#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 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 the record-separator character.

Classification:

POSIX 1003.1

See also:

chsize(), close(), creat(), dup(), dup2(), eof(), errno, exec... functions, fcntl(), filelength(), fileno(), fstat(), isatty(), open(), read(), setmode(), sopen(), stat(), tell(), umask(), write()