Page Comparison

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 the 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 File System Entry Access Functions 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 the directory in Table - Directory API functions table are 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.

Panel

borderWidth	0
title	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.

Code Block

language	cpp
title	Listing - Directory Module Function
linenumbers	true

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);

Code Block

language	cpp
title	Listing - POSIX API Equivalent
linenumbers	true


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.

Versions Compared

Old Version 16

New Version Current

Key

Directory Access Functions