<< Previous | Next >>

fat_xRead

fat_xRead( FATfile * file, char far * buf, int len );

Description

Given file, buf and len, this routine reads len characters from the specified file and places the characters into string buf. Returns the number of characters actually read on success.

Characters will be read beginning at the current position of the file and the position pointer will be left pointing to the next byte to be read. The file position can be manually set with the fat_Seek() function. If the file contains less the "len" characters from the current position to the end of the file (EOF), then the transfer will stop at the EOF. If already at the EOF, -EEOF is returned. The len parameter must be positive, limiting reads to 32767 bytes per call.

µC/OS-II USERS:

• The FAT API is not reentrant from multiple tasks. To use the FAT from multiple µC/OS-II tasks, put the following statement in your application:

     
  
  #define FAT_USE_UCOS_MUTEX
  

• Mutex timeouts or other mutex errors cause a run-time error ERR_FAT_MUTEX_ERROR. The default mutex timeout is 5 seconds and can be changed by #define'ing a different value for FAT_MUTEX_TIMEOUT_SEC.

• You MUST call fat_InitUCOSMutex() after calling OSInit() and before calling any other FAT API functions.

• You must run the FAT in blocking mode (#define FAT_BLOCK).

• You must not call low-level, non-API FAT or write-back cache functions. Only call FAT functions appended with "fat_" and with public function descriptions.

Parameters

file

Handle for the file being read

buf

Pointer to buffer where data is to be placed. May be NULL in order to discard data

len

Length of data to be read. If this is zero, then the return code will be `1' if not at EOF, or `0' if at EOF.

Return Value

Number of bytes read on Success. May be less than the requested amount in non-blocking mode, or if EOF was encountered.

-EEOF: stating position for read was at (or beyond) EOF.
-EIO: on device IO error
-EINVAL: if file, buf, or len contain invalid values
-EPERM: if the file is locked
-ENOENT: if file/directory does not exist
-EFSTATE: if file in inappropriate state (non-blocking)

See Also

fat_Open, fat_Read, fat_Write, fat_xWrite, fat_Seek