Directories

An application stores information in a file system by creating a file or appending new information to an existing file. At a later time, this information may be retrieved by reading the file. However, if a certain file must be found, or all files may be listed, the application can iterate through the entries in a directory using the directory access (or simply directory) functions. The available directory functions are listed in Table - Directory API functions.

A separate set of directory operations (or entry) functions manage the files and directories available on the system. Using these functions, the application can create, delete and rename directories, and get and set a directory’s attributes and date/time. More information about the entry functions can be found in Table - File API functions.

The entry functions and the directory Open() function accept one or more full directory paths. For information about using file and path names, see µC/FS File and Directory Names and Paths.

The functions listed in Table - Directory API functions are core functions in the directory access module (FSDir_####() functions). These are matched by API level functions that correspond to standard C or POSIX functions. More information about the API-level functions can be found in POSIX API. The core and API functions provide basically the same functionality; the benefits of the former are enhanced capabilities, a consistent interface and meaningful return error codes.

Directory Access Functions

The directory access functions provide an API for iterating through the entries within a directory. The FSDir_Open() function initiates this procedure, and each subsequent call to FSDir_Rd() (until all entries have been examined) returns a FS_DIRENT which holds information about a particular entry. The FSDir_Close() function releases any file system structures and locks.

Table - Directory API functions

Function	Description
`FSDir_Open()`	Open a directory.
`FSDir_Close()`	Close a directory
`FSDir_Rd()`	Read a directory entry.
`FSDir_IsOpen()`	Determine whether a directory is open or not.

These functions are almost exact equivalents to POSIX API functions (see Listing - Directory Module Function and Listing - POSIX API Equivalent); the primary difference is the advantage of valuable return error codes to the application.

Listing - Directory Module Function

FS_DIR *FSDir_Open (CPU_CHAR     *p_name_full,
                    FS_ERR       *p_err);
 
void    FSDir_Close(FS_DIR       *p_dir,
                    FS_ERR       *p_err);
 
void    FSDir_Rd   (FS_DIR       *p_dir,
                    FS_DIR_ENTRY *p_dir_entry,
                    FS_ERR       *p_err);

Listing - POSIX API Equivalent

FS_DIR *fs_opendir  (const char        *dirname);
 

int     fs_closedir (FS_DIR            *dirp);
 

int     fs_readdir_r(FS_DIR            *dirp,
                     struct fs_dirent  *entry,
                     struct fs_dirent **result);

For more information about and an example of using directories, see Directory Access Functions - POSIX.