Function FSeek() Foundation

Positions the file pointer within a file.

Syntax
FSeek( <nHandle>, <nOffset>, [<nOrigin>] ) --> nPosition
Parameters
<nHandle>
<nHandle> is an integer numeric value returned from either FCreate() or FOpen(). It is the file handle for the file provided by the operating system.
<nOffset>
<nOffset> is an integer numeric value indicating the number of bytes the file pointer is moved starting from the position specified with <nOrigin>. If <nOffset> is a negative number, the file pointer is moved backwards within the file, otherwise it is moved forwards.

The parameter <nOffset> must be a numeric value in the range between -2^45 and +2^45.

<nOrigin>
<nOrigin> specifies the beginning position from which the file pointer is moved. Symbolic constants for the start point are defined in the header file "Fileio.ch" and should be used for <nOrigin>.
Origin points for the movement of the file pointer with FSeek()
Constant Origin point for file pointer
FS_SET *) beginning of file
FS_RELATIVE current position of file pointer
FS_END end of file
  1. Default
Return

FSeek() returns an integer numeric value corresponding to the position of the file pointer relative to the start of the file.

Description

The low level file function FSeek() moves the file pointer of an open file forward or backward. The contents of the file are not read. The initial position from which the file pointer is moved is specified by <nOrigin> and can be the beginning of the file, end of the file, or current position of the file pointer. FSeek() returns the new position of the file pointer.

The maximum supported filesize is 2^45. An attemp to navigate the filepointer beyond this limit will result in a runtime error.

Examples
Extended low level file functions using FSeek()

// In this example, several functions analogous to the 
// functions Eof(), Bof(), DbSkip(), DbGoTop() and 
// DbGoBottom() for DBF files are created using FSeek(): 

#include "Fileio.ch" 

#define  F_HANDLE   1 
#define  F_POS      2 
#define  F_LASTREC  3 

PROCEDURE Main 
   LOCAL aFile 

   aFile := F_Use( "TEST.TXT" ) // open file 

   ? F_Bof( aFile )             // result: .T. 

   DO WHILE ! F_Eof( aFile )    // Continuously read 20 bytes 
      ?? F_Read( aFile, 20 )    // from the file until the end 
   ENDDO                        // of the file is reached 
   FClose( aFile[F_HANDLE] ) 
RETURN 

** Open a file 
FUNCTION F_Use( cFileName ) 
   LOCAL aFile := { 0, 0, 0 } 

   aFile[ F_HANDLE ] := FOpen( cFileName, FO_READWRITE ) 

   IF FError() == 0 
      aFile[ F_LASTREC ] := FSeek( aFile[F_HANDLE], 0 , FS_END ) 
      FSeek( aFile[F_HANDLE], 0 , FS_SET ) 
   ENDIF 
RETURN aFile 

** Go to begin of file 
FUNCTION F_GoTop( aFile ) 
   aFile[ F_POS ] := FSeek( aFile[F_HANDLE], 0 , FS_SET ) 
RETURN NIL 

** Go to end of file 
FUNCTION F_GoBottom( aFile ) 
   aFile[ F_POS ] := FSeek( aFile[F_HANDLE], 0 , FS_END ) 
RETURN NIL 

** "Skip" file pointer by nBytes 
FUNCTION F_Skip( aFile, nBytes ) 
   aFile[ F_POS ] := FSeek( aFile[F_HANDLE], nBytes, FS_RELATIVE ) 
RETURN  aFile[ F_POS ] 

** Read characters 
FUNCTION F_Read( aFile, nBytes ) 
   LOCAL cBuffer := Space( nBytes ) 
   nBytes := FRead( aFile[F_HANDLE], @cBuffer, nBytes ) 
   aFile[ F_POS ] += nBytes 
RETURN  Left( cBuffer, nBytes ) 

** Check for BOF 
FUNCTION F_Bof( aFile ) 
RETURN  aFile[ F_POS ] == 0 

** Check for EOF 
FUNCTION F_Eof( aFile ) 
RETURN  aFile[ F_POS ] == aFile[ F_LASTREC ] 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.