User`s manual

Dynamic C User’s Manual digi.com 157
Remember to check the return code from fat_Close() since an error return code may indicate the loss
of data. Once you are completely finished, call fat_UnmountDevice() to make sure any data stored
in the cache is written to the flash device.
10.2.4.2.2 Read and Write Operations
Use fat_Read() to read a file.
The first parameter, &my_file, is a pointer to the file handle already opened by fat_Open(). The
parameter buf points to a buffer for reading the file. The sizeof(buf) parameter is the number of
bytes to be read into the buffer. It does not have to be the full size of the buffer. If the file contains fewer
than sizeof(buf) characters from the current position to the end-of-file marker (EOF), the transfer will
stop at the EOF. If the file position is already at the EOF, 0 is returned. The maximum number of charac-
ters read is 32767 bytes per call.
The function returns the number of characters read or an error code. Characters are read beginning at the
current position of the file. If you have just written to the file that is being read, the file position pointer
will be where the write left off. If this is the end of the file and you want to read from the beginning of the
file you must change the file position pointer. This can be done by closing the file and reopening it, thus
moving the position pointer to the start of the file. Another way to change the position pointer is to use the
fat_Seek() function. This function is explained in Section 10.2.4.2.3.
Use fat_ReadDir() to read a directory. This function is explained in Section 10.2.4.2.5.
Use fat_Write() or fat_xWrite() to write to a file. The difference between the two functions is
that fat_xWrite() copies characters from a string stored in extended memory.
The first parameter, &my_file, is a pointer to the file handle already opened by fat_Open(). Because
fat_Open() sets the position pointer to the start of the file, you will overwrite any data already in the
file. You will need to call fat_Seek() if you want to start the write at a position other than the start of
the file (see Section 10.2.4.2.3).
The second parameter contains the data to write to the file. Note that \r\n (carriage return, line feed)
appear at the end of the string in the function. This is essentially a FAT (or really, DOS) convention for text
files. It is good practice to use these standard line-end conventions. (If you only use \n, the file will read
just fine on Unix systems, but some DOS-based programs may have difficulties.) The third parameter
specifies the number of characters to write. Select this number with care since a value that is too small will
result in your data being truncated, and a value that is too large will append any data that already exists
beyond your new data.
Remember that once you are finished with a file you must close it to release its handle. You can call the
fat_Close() function, or, if you are finished using the file system on a particular partition, call
fat_UnmountPartition(), which will close any open files and then unmount the partition. If you
are finished using the device, it is best to call fat_UnmountDevice()
, which will close any open FAT
rc = fat_Close(&my_file);
rc = fat_Read(&my_file, buf, sizeof(buf));
rc = fat_Write(&my_file, "Write data\r\n", 12);