NAME

al_for_each_fs_entry - Allegro 5 API

SYNOPSIS

#include <allegro5/allegro.h>
int al_for_each_fs_entry(ALLEGRO_FS_ENTRY *dir,


                         int (*callback)(ALLEGRO_FS_ENTRY *dir, void *extra),


                         void *extra)
    

DESCRIPTION

This function takes the ALLEGRO_FS_ENTRY(3alleg5) dir, which should represent a directory, and looks for any other file system entries that are in it. This function will then call the callback function callback once for every filesystem entry in the directory dir.

The callback callback must be of type int callback(ALLEGRO_FS_ENTRY * entry, void * extra). The callback will be called with a pointer to an ALLEGRO_FS_ENTRY(3alleg5) that matches one file or directory in dir, and the pointer passed in the extra parameter to al_for_each_fs_entry(3alleg5).

When callback returns ALLEGRO_FOR_EACH_FS_ENTRY_STOP or ALLEGRO_FOR_EACH_FS_ENTRY_ERROR, iteration will stop immediately and al_for_each_fs_entry(3alleg5) will return the value the callback returned.

When callback returns ALLEGRO_FOR_EACH_FS_ENTRY_OK iteration will continue normally, and if the ALLEGRO_FS_ENTRY(3alleg5) parameter of callback is a directory, al_for_each_fs_entry(3alleg5) will call itself on that directory. Therefore the function will recusively descend into that directory.

However, when callback returns ALLEGRO_FOR_EACH_FS_ENTRY_SKIP iteration will continue, but al_for_each_fs_entry(3alleg5) will NOT recurse into the ALLEGRO_FS_ENTRY(3alleg5) parameter of callback even if it is a directory.

This function will skip any files or directories named . or .. which may exist on certain platforms and may signify the current and the parent directory. The callback will not be called for files or directories with such a name.

Returns ALLEGRO_FOR_EACH_FS_ENTRY_OK if successful, or ALLEGRO_FOR_EACH_FS_ENTRY_ERROR if something went wrong in processing the directory. In that case it will use al_set_errno(3alleg5) to indicate the type of error which occurred. This function returns ALLEGRO_FOR_EACH_FS_ENTRY_STOP in case iteration was stopped by making callback return that value. In this case, al_set_errno(3alleg5) will not be used.

SEE ALSO

ALLEGRO_FOR_EACH_FS_ENTRY_RESULT(3alleg5)

SINCE

5.1.9