xHarbour Reference Documentation > Function Reference

FRead()

Reads characters from a binary file into a memory variable.

Syntax

FRead( <nFileHandle>, ;
      @<cBuffer>    , ;
       <nBytes>     , ;
      [<nOffset>]     ) --> nBytesRead

Arguments

<nFileHandle>

This is a numeric file handle returned from function FOpen() or FCreate().

@<cBuffer>

A memory variable holding a character string must be passed by reference to FRead(). It must have at least <nBytes> characters.

<nBytes>

This is a numeric value specifying the number of bytes to transfer from the file into the memory variable <cBuffer>, beginning at the current file pointer position.

<nOffset>

This is a numeric value specifying the number of bytes to skip at the beginning of <cBuffer> where the result is copied to. This allows to copy the data from the file into the middle of a string buffer. The default value is zero. Note that the sum of <nBytes>+<nOffset> must be smaller than or equal Len(<cBuffer>).

The function returns a numeric value indicating the number of bytes that are transfered from the file into the memory variable. If the return value is smaller than Len(<cBuffer>), either the end of file is reached, or a file read error ocurred. This can be identified using function FError().

Description

The low-level file function FRead() reads bytes from a file and copies them into a memory variable. To accomplish this, FRead() must receive a string buffer <cBuffer>, large enough to receive the number of bytes specified with <nBytes>. Since the bytes are copied into a memory variable, the buffer variable must be passed by reference to FRead().

FRead() advances the file pointer by the number of bytes read and returns this number. When the end of file is reached, the file pointer cannot be advanced further, so that the return value is usually smaller than <nBytes>. Use FSeek() to reposition the file pointer without reading the file.

If an error occurs during the operation, function FError() returns an error code indicating the cause of failure.

Info

See also:	Bin2I(), Bin2L(), Bin2U(), Bin2W(), FClose(), FCreate(), FError(), FOpen(), FReadStr(), FSeek(), FWrite(), HB_FReadLine()
Category:	File functions , Low level file functions
Source:	rtl\philes.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example reads an entire file in blocks of 4096 bytes and fills
// them into an array

   #define BLOCK_SIZE     4096

   PROCEDURE Main
      LOCAL cBuffer     := Space( BLOCK_SIZE )
      LOCAL nFileHandle := FOpen( "MyFile.log")
      LOCAL aBlocks     := {}
      LOCAL nRead

      IF FError() <> 0
         ? "Error opening file:", FERROR()
         QUIT
      ENDIF

      DO WHILE .T.
         nRead := FRead( nFileHandle, @cBuffer, BLOCK_SIZE )
         IF nRead == BLOCK_SIZE
            AAdd( aBlocks, cBuffer )
         ELSE
            // end of file reached
            AAdd( aBlocks, SubStr(cBuffer,nRead) )
            EXIT
         ENDIF
      ENDDO

      FClose( nFileHandle )
      ? Len( aBlocks ), "Blocks of", BLOCK_SIZE, "bytes read"
   RETURN