al_for_each_fs_entry(3alleg5)

💖 al_for_each_fs_entry — the Allegro 5 API glow-up 💖

ok so bestie, welcome to the al_for_each_fs_entry(3alleg5) page from the Allegro reference manual. we're about to walk a whole directory tree together and it's gonna be adorable. let's GO 🧚✨

---

✨ 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 picture this: you hand this function an ALLEGRO_FS_ENTRY(3alleg5) called dir, and dir is supposed to be a directory. it goes looking for literally every other file system entry chillin' inside it. then it calls your callback function — yes, the one called callback — once for every single filesystem entry in that directory. one call per entry. no skipping, no favoritism, main character energy for every file. 👑

your callback has to be of type int callback(ALLEGRO_FS_ENTRY * entry, void * extra). every time it gets called, it receives a pointer to an ALLEGRO_FS_ENTRY(3alleg5) that matches one file or directory inside dir, plus the pointer you passed in through the extra parameter of al_for_each_fs_entry(3alleg5). cute, right? 🎀

now here's the part where the return values get spicy 🔥:

• when callback returns ALLEGRO_FOR_EACH_FS_ENTRY_STOP or ALLEGRO_FOR_EACH_FS_ENTRY_ERROR, iteration stops immediately, and al_for_each_fs_entry(3alleg5) hands back whatever value the callback returned. like, we're done, no more, periodt. 💅
• when callback returns ALLEGRO_FOR_EACH_FS_ENTRY_OK, iteration keeps going like normal. and — plot twist — if the ALLEGRO_FS_ENTRY(3alleg5) parameter of callback is itself a directory, al_for_each_fs_entry(3alleg5) will call itself on that directory. so yes bestie, it recursively descends into that directory. it's giving inception. 🌀
• however!! when callback returns ALLEGRO_FOR_EACH_FS_ENTRY_SKIP, iteration still continues, but al_for_each_fs_entry(3alleg5) will NOT recurse into the ALLEGRO_FS_ENTRY(3alleg5) parameter of callback, even if it happens to be a directory. we see it, we wave, we move on. 👋

also, lowkey important: this function skips any files or directories named . or .. — those little guys might exist on certain platforms and might mean the current directory and the parent directory. the callback will not be called for files or directories with such a name. not today, . and ... 🙈

---

🌈 RETURN VALUE 🌈

so what do you get back?

• ALLEGRO_FOR_EACH_FS_ENTRY_OK — slay, everything worked. ✅
• ALLEGRO_FOR_EACH_FS_ENTRY_ERROR — something went wrong while processing the directory 😭. in that case it will use al_set_errno(3alleg5) to indicate the type of error that occurred.
• ALLEGRO_FOR_EACH_FS_ENTRY_STOP — this one shows up when iteration was stopped by making callback return that value. and in this case, al_set_errno(3alleg5) will not be used. nope, not touching it.

ngl bestie, keep those three straight in your head, because mixing up ERROR and STOP is the kind of vibe check you do not want to fail. 💀

---

👀 SEE ALSO 👀

• ALLEGRO_FOR_EACH_FS_ENTRY_RESULT(3alleg5)

---

⭐ SINCE ⭐

5.1.9

---

and that's the whole page, bestie 🫶 — this was al_for_each_fs_entry(3alleg5) from the Allegro reference manual, and yeah, it's been around since way back in 5.1.9. go forth and recurse responsibly. mwah 💋