Page Comparison

When an application needs to access a file, it must first open it using fs_fopen():

Code Block

language	cpp

p_file = fs_fopen("\\file.txt", /* file name   */
                  "w+");        /* mode string */
if (p_file == (FS_FILE *)0) {
    /* $$$$ Handle error */
}

The return value of this function should always be verified as non-NULL before the application proceeds to access the file. The first argument of this function is the path of the file; if working directories are disabled, this must be the absolute file path, beginning with either a volume name or a ‘\’ (see µC/FS File and Directory Names and Paths). The second argument of this function is a string indicating the mode of the file; this must be one of the strings shown in Table - fs_fopen() mode strings interpretations. Note that in all instances, the ‘b’ (binary) option has no affect on the behavior of file accesses.

Panel

borderWidth	0
title	Table - fs_fopen() mode strings interpretations

fs_fopen() Mode String	Read?	Write?	Truncate?	Create?	Append?
“r” or “rb”	Yes	No	No	No	No
“w” or “wb”	No	Yes	Yes	Yes	No
“a” or “ab”	No	Yes	No	Yes	Yes
“r+” or “rb+” or “r+b”	Yes	Yes	No	No	No
“w+” or “wb+” or “w+b”	Yes	Yes	Yes	Yes	No
“a+” or “ab+” or “a+b”	Yes	Yes	No	Yes	Yes

After a file is opened, any of the file access functions valid for that its mode can be called. The most commonly used functions are fs_fread() and fs_fwrite(), which read or write a certain number of ‘items’ from a file:

Code Block

language	cpp

cnt = fs_fread(p_buf,   /* pointer to buffer */
               1,       /* size of each item */
               100,     /* number of items   */
               p_file); /* pointer to file   */

The return value, the number of items read (or written), should be less than or equal to the third argument. If the operation is a read, this value may be less than the third argument for one of two reasons. First, the file could have encountered the end-of-file (EOF), which means that there is no more data in the file. Second, the device could have been removed, or some other error could have prevented the operation. To diagnose the cause, the fs_feof() function should be used. This function returns a non-zero value if the file has encountered the EOF.

...

An example of reading a file is given below:

Code Block

language	cpp
title	Listing - Example file read
linenumbers	true

void  App_Fnct (void)
{
    FS_FILE         *p_file;
    fs_size_t        cnt;
    unsigned  char   buf[50];
    .
    .
    .
    
    p_file = fs_fopen("\\file.txt", "r");          /* Open file.                           */ 
           
    if (p_file != (FS_FILE *)0) {                  /* If file is opened ...                */
                                                   /* ... read from file.	               */
        do {
            cnt = fs_fread(&buf[0], 1, sizeof(buf), p_file);
            if (cnt > 0) {
                APP_TRACE_INFO(("Read %d bytes.\r\n", cnt));
            }
        } while (cnt >= sizeof(buf));
        eof = fs_feof(p_file);                     /* Chk for EOF.	                       */
        if (eof != 0) {                            (1)
            APP_TRACE_INFO(("Reached EOF.\r\n"));
        } else {
            err = fs_ferror(p_file);               /* Chk for error.                      */
            if (err != 0) {                        (2)
                APP_TRACE_INFO(("Read error.\r\n"));
            } 
        }
        fs_fclose(p_file);                         /* Close file.                         */
    } else {
        APP_TRACE_INFO(("Could not open \"\\file.txt\".\r\n"));
    }
    .
    .
    .
}

Panel

(1) To determine whether a file read terminates because of reaching the EOF or a device error/removal, the EOF condition should be checked using fs_feof().

(2) In most situations, either the EOF or the error indicator will be set on the file if the return value of fs_fread() is smaller than the buffer size. Consequently, this check is unnecessary.

Versions Compared

Old Version 14

New Version 15

Key