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

    Whence     Definition

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

    The _lseek function is identical to lseek.  Use _lseek for ANSI/ISO
    naming conventions.

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.

    Constant     Meaning

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.


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:
    lseek is POSIX 1003.1, _lseek is not POSIX

_lseek conforms to ANSI/ISO naming conventions

Systems:
     lseek - All, Netware

    _lseek - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

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