dir.h File Reference

Directory handling. More...

Go to the source code of this file.

Data Structures
struct	dir_t
	Directory entry structure. More...

Macros
Directory entry type definitions
#define	DT_REG   1
	Regular file.
#define	DT_DIR   2
	Directory.

Typedefs
typedef int(*	dir_walk_callback_t) (const char *fn, dir_t *dir, void *data)
	Callback function for directory walking.

Enumerations
enum	{   DIR_WALK_ABORT = -2 , DIR_WALK_ERROR = -1 , DIR_WALK_CONTINUE = 0 , DIR_WALK_SKIPDIR = 1 ,   DIR_WALK_GOUP = 2 }
	Supported return values for dir_walk_callback_t. More...

Functions
int	dir_findfirst (const char *const path, dir_t *dir)
	Find the first file in a directory.
int	dir_findnext (const char *const path, dir_t *dir)
	Find the next file in a directory.
int	dir_walk (const char *path, dir_walk_callback_t cb, void *data)
	Walk a directory tree.
bool	dir_fnmatch (const char *pattern, const char *fullpath)
	Check if a filename matches a pattern.
int	dir_glob (const char *pattern, const char *path, dir_walk_callback_t cb, void *data)
	Glob a directory tree using a pattern.

Detailed Description

Directory handling.

Author

Jennifer Taylor drago.nosp@m.nmin.nosp@m.ded@d.nosp@m.rago.nosp@m.nmind.nosp@m.ed.c.nosp@m.om

Giovanni Bajo giova.nosp@m.nnib.nosp@m.ajo@g.nosp@m.mail.nosp@m..com

Typedef Documentation

dir_walk_callback_t

typedef int(* dir_walk_callback_t) (const char *fn, dir_t *dir, void *data)

Callback function for directory walking.

This function is called for each file and each directory found during the directory walk.

The return value of this function determines the behavior of the directory walk. The possible return values are:

• DIR_WALK_CONTINUE: Continue walking the directory. This is the default expected return value.
• DIR_WALK_SKIPDIR: Skip the current directory. If the current entry is a directory, the directory will not be recursed into.
• DIR_WALK_GOUP: Stop walking the current directory and return up one level.
• DIR_WALK_ABORT: Abort the directory walk immediately. dir_walk will return -2, and errno will not be set.
• DIR_WALK_ERROR: An error occurred while walking the directory. The callback is responsible for setting errno to the appropriate value. dir_walk will return -1.

Parameters

fn	The full absolute filename of the file or directory
dir	The directory entry structure with information about the file or directory
data	User data passed to dir_walk

Returns

int The return value determines the behavior of the directory walk (one of DIR_WALK constants)

Enumeration Type Documentation

anonymous enum

anonymous enum

Supported return values for dir_walk_callback_t.

Enumerator
DIR_WALK_ABORT	Abort walking and exit immediately.
DIR_WALK_ERROR	Error walking the directory (errno will be set)
DIR_WALK_CONTINUE	Continue walking.
DIR_WALK_SKIPDIR	Do not recurse within the current directory.
DIR_WALK_GOUP	Stop walking the current directory, return up one level.

Function Documentation

dir_findfirst()

int dir_findfirst	(	const char *const	path,
		dir_t *	dir
	)

Find the first file in a directory.

This function should be called to start enumerating a directory or whenever a directory enumeration should be restarted.

Parameters

[in]	path	Path to the directory structure
[out]	dir	Directory entry structure to populate with first entry

Returns

0 on successful lookup, -1 if the directory existed and is empty, or a different negative value on error (in which case, errno will be set).

dir_findnext()

int dir_findnext	(	const char *const	path,
		dir_t *	dir
	)

Find the next file in a directory.

After finding the first file in a directory using dir_findfirst, call this to retrieve the rest of the directory entries. Call this repeatedly until a negative error is returned signifying that there are no more directory entries in the directory.

Parameters

[in]	path	Path to the directory structure
[out]	dir	Directory entry structure to populate with next entry

Returns

0 on successful lookup, -1 if there are no more files in the directory, or a different negative value on error (in which case, errno will be set).

dir_walk()

int dir_walk	(	const char *	path,
		dir_walk_callback_t	cb,
		void *	data
	)

Walk a directory tree.

This function walks a directory tree, calling the callback for each file and directory found.

The callback is of type dir_walk_callback_t, and its return value determines the behavior of the walk. In fact, the callback can request to abort the walk (DIR_WALK_ABORT), skip the current directory (DIR_WALK_SKIPDIR), or stop walking the current directory and return up one level (DIR_WALK_GOUP). See dir_walk_callback_t for more information.

Parameters

path	The path to the directory to walk
cb	The callback function to call for each file and directory
data	User data to pass to the callback

Returns

0 on success

-1 on error (errno will be set)

-2 if abort was requested by the callback via DIR_WALK_ABORT

dir_fnmatch()

bool dir_fnmatch	(	const char *	pattern,
		const char *	fullpath
	)

Check if a filename matches a pattern.

This function is a simplified version of fnmatch that only supports the following special characters:

• ? - Matches any single character
• * - Matches any sequence of characters, except '/'. It can be used to match multiple files in a single directory.
• ** - Matches any sequence of characters, including '/'. It can be used to match files within directory trees

Example of patterns:

*.txt              - Matches all files with a .txt extension
**/*.txt           - Matches all files with a .txt extension in all directories
                     under the starting directory
hero/**/*.sprite   - Matches all files with a .sprite extension in the
                     hero directory and all its subdirectories
catalog?.dat       - Matches catalog1.dat, catalog2.dat, etc.
*w*/*.txt          - Matches all files with a .txt extension in directories
                     that contain the letter 'w'

Parameters

pattern	The pattern to match against
fullpath	The full path to match

Returns

true The filename matches the pattern

false The filename does not match the pattern

dir_glob()

int dir_glob	(	const char *	pattern,
		const char *	path,
		dir_walk_callback_t	cb,
		void *	data
	)

Glob a directory tree using a pattern.

This function walks a directory tree searching for files and directories that match a pattern. The pattern is a simplified version of fnmatch; see dir_fnmatch for more information about the supported special characters.

The callback function is called for each file and directory that matches the pattern. The callback can then decide how to proceed using its return value (see dir_walk_callback_t for more information).

int mycb(const char *fn, dir_t *dir, void *data) {
   debugf("Found sprite file: %s\n", fn);
   return DIR_WALK_CONTINUE;
}
 
// Search for all files with a .sprite extension in all directories under rom:/
dir_glob("**/*.sprite", "rom:/", mycb, NULL);

Note

the glob pattern is matched against pathnames relative to the starting directory. For example, if you start the search at "rom:/sprites", the pattern "hero/*.sprite" will match all files with a .sprite extension in the "rom:/sprites/hero" directory.

Parameters

pattern	The pattern to match against (see dir_fnmatch)
path	The path to the directory to start the search
cb	The callback function to call for each file and directory
data	User data to pass to the callback

Returns

0 on success,

-1 on error (errno will be set)

-2 if abort was requested by the callback via DIR_WALK_ABORT