Opening Files

When an application needs to access a file, it must first open it using fs_fopen() or FSFile_Open(). For most applications, the former with its familiar interface suffices. In some cases, the flexibility of the latter is demanded (see Listing - Example FSFile_Open() usage).

file ptr --> p_file = FSFile_Open ("\\file.txt",             /* file name    */
                                    FS_FILE_ACCESS_MODE_RD,  /* access mode  */
                                   &err);                    /* return error */
       if (p_file == (FS_FILE *)0) {
         /* $$$$ Handle error */
       }

The return value of FSFile_Open() should always be verified as non-NULL before the application proceeds to access the file. The second argument to this function is a logical OR of mode flags:

FS_FILE_ACCESS_MODE_RD

File opened for reads.

FS_FILE_ACCESS_MODE_WR

File opened for writes.

FS_FILE_ACCESS_MODE_CREATE

File will be created, if necessary.

FS_FILE_ACCESS_MODE_TRUNC

File length will be truncated to 0.

FS_FILE_ACCESS_MODE_APPEND

All writes will be performed at EOF.

FS_FILE_ACCESS_MODE_EXCL

File will be opened if and only if it does not already exist.

FS_FILE_ACCESS_MODE_CACHED

File data will be cached.

For example, if you wanted to create a file to write to if and only if it does not exist, you would use the flags

FS_FILE_ACCESS_MODE_WR | FS_FILE_ACCESS_MODE_CREATE | FS_FILE_ACCESS_MODE_EXCL

It is impossible to do this in a single, atomic operation using fs_fopen().

Table - fopen() mode strings and mode equivalents lists the mode flag equivalents of the fs_fopen() mode strings.