User`s manual

156 digi.com File Systems
10.2.4.2 File and Directory Operations
The Dynamic C FAT implementation supports the basic set of file and directory operations. Remember
that a partition must be mounted before it can be used with any of the file, directory or status operations.
10.2.4.2.1 Open and Close Operations
The fat_Open() function opens a file or a directory. It can also be used to create a file or a directory.
When using the non-blocking FAT, check the return code and call it again with the same arguments until it
returns something other than -EBUSY..
The first parameter, my_part, points to a partition structure. This pointer must point to a mounted parti-
tion. Some of the sample programs, like fat_create.c, declare a local pointer and then search for a
partition pointer in the global array fat_part_mounted[]. Other sample programs, like
fat_shell.c, define an integer to be used as an index into fat_part_mounted[]. Both methods
accomplish the same goal of gaining access to a partition pointer.
The second parameter contains the file name, including the directory (if applicable) relative to the root
directory. All paths in Dynamic C must specify the full directory path explicitly, e.g.,
DIR1\\FILE.EXT
or
DIR1/FILE.EXT. The direction of the slash in the pathname is a backslash by default. If you use the
default backslash for the path separator, you must always precede it with another backslash, as shown in
the above call to fat_Open(). This is because the backslash is an escape character in a Dynamic C
string. To use the forward slash as the path separator, define the macro FAT_USE_FORWARDSLASH in
your application (or in FAT.LIB to make it the system default).
The third parameter determines whether a file or directory is opened (FAT_FILE or FAT_DIR).
The fourth parameter is a flag that limits fat_Open() to the action specified. FAT_CREATE creates the
file (or directory) if it does not exist. If the file does exist, it will be opened, and the position 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_MUST_CREATE if you know the file does not exist; this last option is also a fail-
safe way to avoid opening and overwriting an existing file since an -EEXIST error message will be
returned if you attempt to create a file that already exists.
The fifth parameter, &my_file, is an available file handle. After a file or directory is opened, its handle is
used to identify it when using other API functions, so be wary of using local variables as your file handle.
The final parameter is an initial byte count if the object needs to be created. It is only used if the
FAT_CREATE or FAT_MUST_CREATE flag is used and the file or directory does not already exist. The
byte count is rounded up to the nearest whole number of clusters greater than or equal to 1. On return, the
variable prealloc is updated to the number of bytes allocated. Pre-allocation is used to set aside space
for a file, or to speed up writing a large amount of data as the space allocation is handled once.
Pass NULL as the final parameter to indicate that you are opening the file for reading or that a minimum
number of bytes needs to be allocated to the file at this time. If the file does not exist and you pass NULL,
the file will be created with the minimum one cluster allocation.
Once you are finished with the file, you must close it to release its handle so that it can be reused the next
time a file is created or opened.
rc = fat_Open(my_part, "DIR\\FILE.TXT", FAT_FILE, FAT_CREATE,
&my_file, &prealloc);