al_findfirst(3alleg4)

al_findfirst 💖

okay bestie, gather round, because this is a low-level function for searching files from the Allegro game programming library, and she is iconic ✨ (manual section 3alleg4, iykyk)

✨ SYNOPSIS ✨

#include <allegro.h>

int al_findfirst(const char *pattern, struct al_ffblk *info, int attrib);

🦋 DESCRIPTION 🦋

So. You want to find files? This is the low-level function for searching files, and she does exactly one job: she finds the first file that matches the wildcard specification and file attributes you give her (see above, babes 👆).

The info about the file (if there even is one, no pressure) gets dropped into the al_ffblk structure — and you have to provide that structure, she's not gonna make it for you 🫶

The al_ffblk structure looks like this:

struct al_ffblk
{
   int attrib;       - actual attributes of the file found
   time_t time;      - modification time of file
   char name[512];   - name of file
};

ngl there is some other stuff in the structure as well, but it is there for internal use only, so don't touch it, don't look at it, it's not for you 💅

Example time, because obviously:

struct al_ffblk info;

if (al_findfirst("*.pcx", &info, FA_ALL) != 0) {
   /* Tell user there are no PCX files. */
   return;
}

🔥 RETURN VALUE 🔥

okay this part actually matters, listen up:

• She returns non-zero if no match is found, or if an error occurred — and in that error case she sets errno accordingly. 😭
• She returns zero if a match is found, and she allocates some memory for internal use in the structure.

⚠️ bestie. this is the important bit. because she allocates memory in there, you have to close your search when you are finished to avoid memory leaks in your program. do not leave her hanging, do not forget to close, your program will literally leak. periodt. 💀

👑 SEE ALSO 👑

• al_findnext(3alleg4)
• al_findclose(3alleg4)
• al_ffblk_get_size(3alleg4)

and that's the whole vibe, bestie 💜 this was Allegro version 4.4.3, and the page is al_findfirst(3alleg4) — slay, go find those files, and remember to close them 🎀✨🌸