al_for_each_fs_entry(3)

✨ NAME ✨

al_for_each_fs_entry — Allegro 5 API. You're on the al_for_each_fs_entry(3) page from the Allegro reference manual, bestie, and it's giving "let's walk a directory tree together" main character energy 🌈

🦋 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 💅

Okay so here's the vibe: al_for_each_fs_entry(3) takes the ALLEGRO_FS_ENTRY(3) dir — which should represent a directory — and looks for any other file system entries that are in it. Then it calls the callback function callback once for every filesystem entry in the directory dir. Obsessed? Same. 💖

The callback callback must be of type int callback(ALLEGRO_FS_ENTRY * entry, void * extra). It gets called with a pointer to an ALLEGRO_FS_ENTRY(3) that matches one file or directory in dir, plus the pointer passed in the extra parameter to al_for_each_fs_entry(3). No cap, that's the whole handoff. 🫶

Now the return-value vibe check, because this is where the recursion drama happens:

• If callback returns ALLEGRO_FOR_EACH_FS_ENTRY_STOP or ALLEGRO_FOR_EACH_FS_ENTRY_ERROR, iteration stops immediately and al_for_each_fs_entry(3) returns the value the callback returned. Bye, loop. 💀
• If callback returns ALLEGRO_FOR_EACH_FS_ENTRY_OK, iteration continues normally. And if the ALLEGRO_FS_ENTRY(3) parameter of callback is a directory, al_for_each_fs_entry(3) will call itself on that directory — so yes, it recursively descends into that directory. It's giving recursion, periodt. 🔥
• If callback returns ALLEGRO_FOR_EACH_FS_ENTRY_SKIP, iteration continues, but al_for_each_fs_entry(3) will NOT recurse into the ALLEGRO_FS_ENTRY(3) parameter of callback even if it is a directory. Skip means skip, bestie. 💅

Also important: 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, because yes there are layers:

• ALLEGRO_FOR_EACH_FS_ENTRY_OK — returns this if successful. Slay. ✅
• ALLEGRO_FOR_EACH_FS_ENTRY_ERROR — returns this if something went wrong in processing the directory. In that case it will use al_set_errno(3) to indicate the type of error which occurred. So check that errno, bestie. 😭
• ALLEGRO_FOR_EACH_FS_ENTRY_STOP — returns this in case iteration was stopped by making callback return that value. In this case, al_set_errno(3) will not be used. Important distinction, iykyk. ⭐

🎀 SEE ALSO 🎀

• ALLEGRO_FOR_EACH_FS_ENTRY_RESULT(3)

🌸 SINCE 🌸

5.1.9 — iconic since then, fr fr. 👑

---

💖 okay that's the whole page, bestie! from the Allegro reference manual, all about al_for_each_fs_entry(3); the footer date is whatever your local copy says, and we're not inventing one — mwah 💋