User`s manual

Dynamic C User’s Manual digi.com 147
The file is closed to release the file handle to allow it to be used to identify a different file.
rc = fat_Close( &my_file );
The parameter &my_file is a handle to the file to be closed. Remember to check for any return code
from fat_Close() since an error return code may indicate the loss of data.
The file must be opened for any further work, even though &my_file may still reference the desired file.
The file must be open to be active, so we call fat_Open() again. Now the file can be read.
rc = fat_Read( &my_file, buf, sizeof(buf));
The function fat_Read() returns the number of characters actually read. The parameters are as follows:
• &my_file is a handle to the file to be read.
• buf is a buffer for reading/writing the file that was defined at the beginning of the program.
• sizeof(buf) is the number of bytes to be read into buf. It does not have to be the full size of the
buffer
Characters are read beginning at the current position of the file. (The file position can be changed with the
fat_Seek() function.) If the file contains fewer than sizeof(buf) characters from the current posi-
tion to the end-of-file marker (EOF), the transfer will stop at the EOF. If the file position is already at EOF,
0 is returned. The maximum number of characters read is 32767 bytes per call.
The file can now be closed. Call fat_UnmountDevice()
i
rather than simply calling fat_Close() to
ensure that any data stored in cache will be written to the device. With a write-back cache, writes are
delayed until either:
• all cache buffers are full and a new FAT read request requires a “dirty” cache buffer to be written out
before the read can take place, or
• cache buffers for a partition or a device are being flushed due to an unmount call or explicit flush call.
Calling fat_UnmountDevice() will close all open files and unmount all mounted FAT partitions. This
is the safest way to shut down a device. The parameter first_part->dev is a handle to the device to
be unmounted.
fat_UnmountDevice( first_part->dev );
NOTE: A removable device must be unmounted in order to flush its data before removal.
Failure to unmount any partition on a device that has been written to could corrupt the file
system.
i. Call fat_UnmountPartition() when using a FAT version prior to v2.06.