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

 fbreadp()           Read data from a binary file to a pointed-to buffer
------------------------------------------------------------------------------
 Declaration
   fileio.hdr

 Syntax
   func uint fbreadp extern
   param value _HFILE hFile, ;
         value ulong  pBuffer, ;
         value uint   uBytes

 Arguments
   hFile is the handle of the file to manipulate.

   xBuffer is a pointer to the buffer that receives data from the file.

   uBytes is the number of bytes to read. The maximum value is 65535
   or 0xffff bytes.

 Return
   The number of bytes read.

 Description
   The fbreadp() function attempts to read uBytes bytes from the
   file specified by hFile into the buffer, whose address is specified by
   pBuffer. The file must have been opened prior to the read.

   It returns the number of bytes actually transferred. If fbreadp() returns
   a value less than the value specified in uBytes, then the file is
   either at eof, truncated to 0 bytes or there is a physical defect with
   the file. It is most likely that the file is at eof.

   pBuffer represents the address to an area in memory, usually retrieved
   by calling malloc() before, to allocate dynamic memory. The function
   assumes that the buffer has been defined large enough to store uBytes bytes.
   If this is not true, successive memory will be overwritten.

   As data is read from the file, DOS adjusts the read write pointer by
   uBytes. So, if fbreadp() reads 20 bytes, the read/write pointer
   of the file is adjusted by 20 bytes. Use fbseek() to move the read write
   pointer.

 Example
   #define EXAMPLE_FILE
   #include example.hdr

   #define BUFFER_SIZE 60000UI
   
   proc Test_fbreadp
   // Read a file into a buffer and display it
   vardef
      ptr( char ) pBuffer
      ptr( byte ) pEnd
      uint        nRead
      _HFILE      hFile
   enddef
   if exist( argv( 1 ) )                  // if file name supplied
      pBuffer := malloc( BUFFER_SIZE )    // allocate buffer
      if pBuffer                          // if allocation successful
         if fbopen( hFile, argv( 1 ), FB_READ ) // open file
            nRead := fbreadp( hFile, pBuffer, BUFFER_SIZE )
            fbclose( hFile )              // close file
            pEnd := pBuffer + nRead       // point to end of file
            *pEnd := 0                    // close the string
            ? *pBuffer                    // display the file
         endif
         free( pBuffer )                  // free memory
      endif
   else
      ? "File not found"
   endif
   endproc

   proc main
   Test_fbreadp()
   endproc