for_each_file_ex(3alleg4)

✨ for_each_file_ex ✨

okay bestie, welcome to the Allegro manual, section 3alleg4 💖 — this one's literally just "do a thing for every file that matches a wildcard", and it ate, no cap.

🌸 NAME 🌸

for_each_file_ex — runs callback() for each file that matches a wildcard. It's giving Allegro game programming library realness 🎀

🦋 SYNOPSIS 🦋

#include <allegro.h>

int for_each_file_ex(const char *name, int in_attrib, int out_attrib,
int (*callback)(const char *filename, int attrib, void *param), void
*param);

💅 DESCRIPTION 💅

So the way this works: it finds all the files on disk that match the wildcard spec you give it and the file attributes you asked for, then it fires callback() once for each one. Periodt. 💫

Basically? It's a convenient lil wrapper around al_findfirst(), al_findnext() and al_findclose() — the trio. Think of it as the group chat version of those three, where you don't have to @ each one individually 🫶

Now the tea on the two attribute masks:

• in_attrib — a bitmask saying which attributes the files must carry (vibe check: they gotta have these).
• out_attrib — a bitmask saying which attributes the files must not carry (nope, not these).
• Attributes that show up in neither bitmask are simply not taken into account when deciding whether callback() gets invoked or not. They're just there, unbothered, minding their business 🙈

💜 the callback 💜

Your callback function gets passed three arguments:

1. A string with the completed filename — which is exactly the same string you passed to for_each_file_ex(), but with meta characters. Yes bestie, same string, meta characters included, fr fr.
2. The actual attributes of the file.
3. A void pointer which is just a copy of param — use it for literally whatever you want, it's yours 👑

And the rule for the callback: it must return zero to let the enumeration keep going, or any non-zero value to stop it. That's the whole vibe check. ✋

Also important: if an error happens, the error code gets stored in errno, but the enumeration won't stop. She keeps going, iconic behaviour honestly 😭

Example, because you know we love an example:

int show_name(const char *filename, int attrib, void *param)
{
   allegro_message("Caught `%s', attribs %d\n",
                   filename, attrib);
   return 0;
}
...
   count = for_each_file_ex("data/level*", FA_DIREC,
                            0, show_name, 0);
   allegro_message("%d game directories\n", count);

look at her go 🥹 collecting all those data/level* directories like Pokémon.

⭐ RETURN VALUE ⭐

Returns the number of successful calls made to callback() — that is, the number of times callback() was called and returned 0. So if your callback bails early with a non-zero, that one doesn't count toward the number. Math is math 💀

👑 SEE ALSO 👑

• al_findfirst(3alleg4)
• al_findnext(3alleg4)
• al_findclose(3alleg4)

the whole squad, go read them next 💖

and that's the page, bestie — brought to you by Allegro, version 4.4.3, dated right there with for_each_file_ex(3alleg4) 💅✨ mwah, go enumerate some files, you're doing amazing sweetie 🎀🦋💜