Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <stdio.h>
    #include <io.h>
    long int lseek( int handle, long int offset, int whence );

Description:
    The lseek function sets the current file position at the operating
    system level.  The file is referenced using the file handle handle
    returned by a successful execution of one of the  creat,  dup,  dup2,
     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 upon the value
    of whence which may have one of three possible values (defined in the
    <stdio.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.  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.

    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, the current file position is returned in a
    system-dependent manner.  A value of 0 indicates the start of the file.
     When an error occurs, -1 is returned and  errno is set to indicate the
    error.

Errors:
    When an error has occurred,  errno contains a value indicating the type
    of error that has been detected.

    EBADF
        The handle argument is not a valid file handle.

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


See Also:
    chsize, close, creat, dup, dup2, eof, exec Functions Functions, filelength,
    fileno, fstat, isatty, open, read, setmode, sopen, stat, tell, write,
    umask

Example:
    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:

    long int file_posn;
    int handle;

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

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

    If all records in the file are the same size, the position of the n'th
    record can be calculated and read, as illustrated in the following
    sample function:

    #include <stdio.h>
    #include <io.h>

    int read_record( int  handle,
                     long rec_numb,
                     int  rec_size,
                     char *buffer )
      {
        if( lseek( handle, rec_numb * rec_size, SEEK_SET )
             == -1L ) {
          return( -1 );
        }
        return( read( handle, 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 carriage-return character in text files).

Classification:
    POSIX 1003.1

Systems:
    All