User`s manual

146 digi.com File Systems
The call to fat_Open() creates a file in the root directory and names it HELLO.TXT. A file must be
opened before you can write or read it.
rc = fat_Open(first_part, "HELLO.TXT", FAT_FILE, FAT_CREATE,
&my_file, &prealloc);
The parameters are as follows:
• first_part points to the partition structure initialized by fat_AutoMount().
• "HELLO.TXT" is the file name, and is always an absolute path name relative to the root directory. All
paths in Dynamic C must specify the full directory path explicitly.
• FAT_FILE identifies the type of object, in this case a file. Use FAT_DIR to open a directory.
• FAT_CREATE creates the file if it does not exist. If the file does exist, it will be opened, and the posi-
tion pointer will be set to the start of the file. If you write to the file without moving the position
pointer, you will overwrite existing data.
Use FAT_OPEN instead of FAT_CREATE if the file or directory should already exist. If the file does
not exist, you will get an -ENOENT error.
Use FAT_MUST_CREATE if you know the file does not exist. This is a fail-safe way to avoid opening
and overwriting an existing file since an -EEXIST error is returned if you attempt to create a file that
already exists.
• &my_file is a file handle that points to an available file structure. It will be used for this file until the
file is closed.
• &prealloc points to the number of bytes to allocate for the file. You do not want to pre-allocate any
more than the minimum number of bytes necessary for storage, and so prealloc was set to 0. You
could also use NULL instead of prealloc and prealloc = 0.
Next, the sample program writes the data "Hello, world!\r\n" to the file.
fat_Write( &my_file, "Hello, world!\r\n", 15 );
The parameters are as follows:
• &my_file is a pointer to the file handle opened by fat_Open().
• “Hello, world!\r\n” is the data written to the file. Note that \r\n (carriage return, line feed)
appears at the end of the string in the call. This is essentially a FAT (or really, DOS) convention for text
files. It is good practice to use the standard line-end conventions. (If you just use \n, the file will read
just fine on Unix systems, but some DOS-based programs may have difficulties.)
• 15 is the number of characters to write. Be sure to 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.