FSEEK()
 Set a binary file pointer to a new position
------------------------------------------------------------------------------
 Syntax

     FSEEK(<nHandle>, <nOffset>, [<nOrigin>]) --> nPosition

 Arguments

     <nHandle> is the file handle obtained from FOPEN(), FCREATE(), or
     predefined by DOS.

     <nOffset> is the number of bytes to move the file pointer from the
     position defined by <nOrigin>.  It can be a positive or negative number.
     A positive number moves the pointer forward, and a negative number moves
     the pointer backward in the file.

     <nOrigin> defines the starting location of the file pointer before
     FSEEK() is executed.  The default value is zero, representing the
     beginning of file.  If <nOrigin> is the end of file, <nOffset> must be
     zero or negative.

     Methods of Moving the File Pointer
     ------------------------------------------------------------------------
     Origin  Fileio.ch      Description
     ------------------------------------------------------------------------
     0       FS_SET         Seek from beginning of file
     1       FS_RELATIVE    Seek from the current pointer position
     2       FS_END         Seek from end of file
     ------------------------------------------------------------------------

 Returns

     FSEEK() returns the new position of the file pointer relative to the
     beginning of file (position 0) as an integer numeric value.  This value
     is without regard to the original position of the file pointer.

 Description

     FSEEK() is a low-level file function that moves the file pointer forward
     or backward in an open binary file without actually reading the contents
     of the specified file.  The beginning position and offset are specified
     as function arguments, and the new file position is returned.
     Regardless of the function arguments specified, the file pointer cannot
     be moved beyond the beginning or end of file boundaries.

     Warning!  This function allows low-level access to DOS files and
     devices.  It should be used with extreme care and requires a thorough
     knowledge of the operating system.

 Examples

     .  This example uses FSEEK() to determine the length of a file by
        seeking from the end of file.  Then, the file pointer is reset to the
        beginning of file:

        #include "Fileio.ch"
        //
        // Open the file read-only
        IF (nHandle := FOPEN("Temp.txt")) >= 0
           //
           // Get length of the file
           nLength := FSEEK(nHandle, 0, FS_END)
           //
           // Reset file position to beginning of file
           FSEEK(nHandle, 0)
           FCLOSE(nHandle)
        ELSE
           ? "File open error:", FERROR()
        ENDIF

     .  This pseudofunction positions the file pointer at the last
        byte in a binary file:

        #define FileBottom(nHandle);
              (FSEEK(nHandle, 0, FS_END))

     .  This pseudofunction positions the file pointer at the first
        byte in a binary file:

        #define FileTop(nHandle);
              (FSEEK(nHandle, 0))

     .  This pseudofunction reports the current position of the file
        pointer in a specified binary file:

        #define FilePos(nHandle);
              (FSEEK(nHandle, 0, FS_RELATIVE))

 Files   Library is CLIPPER.LIB, header file is Fileio.ch.

See Also: FCLOSE() FCREATE() FERROR() FOPEN() FREAD()