SDL_GlobStorageDirectory(3)

💖 SDL_GlobStorageDirectory(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're talking about SDL_GlobStorageDirectory — yes it's a whole mouthful, yes it's iconic, no you don't have to be scared of it 🫶

---

✨ NAME ✨

SDL_GlobStorageDirectory — enumerate a directory tree, filtered by pattern, and return a list. it's giving "show me everything that matches, pls and thank you" 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_storage.h>

char ** SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count);

look at that signature. so clean. so powerful. char ** returning, bestie, that's a whole array of strings, main character energy fr fr ✨

---

🦋 DESCRIPTION 🦋

So here's the tea: files get filtered out if they don't match the string in pattern. and pattern is allowed to contain wildcard characters, okay?

• * — matches everything
• ? — matches one character

If pattern is NULL, then no filtering happens at all and literally all the results get returned. no gatekeeping, we love to see it 💖

Subdirectories are permitted, and you specify them with a path separator of /. but important caveat bestie, listen up: the wildcard characters * and ? never match a path separator. never ever. they said no ❌

flags may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching case-insensitive. so if you're like "idk what case the file is in" — that's your girl 🌈

The returned array is always NULL-terminated, for your iterating convenience (they're so thoughtful, honestly 🥹). But if count is non-NULL, on return it will contain the number of items in the array, not counting the NULL terminator. important distinction, don't get it twisted 💀

And if path is NULL, this is treated as a request to enumerate the root of the storage container's tree. An empty string also works for this. so NULL or "", both slay 👑

---

🎀 FUNCTION PARAMETERS 🎀

• storage — a storage container. yeah. that's the thing you're poking at 🫙
• path — the path of the directory to enumerate, or NULL for the root.
• pattern — the pattern that files in the directory must match. Can be NULL. (and if it is, we don't filter, remember? 💅)
• flags — SDL_GLOB_* bitflags that affect this search.
• count — on return, will be set to the number of items in the returned array. Can be NULL.

---

💜 RETURN VALUE 💜

Returns an array of strings on success, or NULL on failure. and bestie, if it fails, call SDL_GetError() for more information, okay? don't just sit there wondering 😭

The caller should pass the returned pointer to SDL_free when done with it. This is a single allocation that should be freed with SDL_free() when it is no longer needed.

⚠️ okay this part matters: free it with SDL_free(). it's ONE allocation. do not go freeing individual strings inside it. do not pass go. SDL_free() the pointer, and let it go 🧚

---

🌈 THREAD SAFETY 🌈

It is safe to call this function from any thread, assuming the storage object is thread-safe. so like — the function itself is chill, but if your storage object is messy, that's on the storage object, not on us 🙈

---

⭐ AVAILABILITY ⭐

This function is available since SDL 3.2.0. if you're on something older, sorry bestie, it's not there yet 💔

---

👑 SEE ALSO 👑

nothing else listed here, so this is a solo act. a one-woman show. periodt 💅

---

and that's the whole page, bestie! stay globbing, stay slaying, and remember: * matches everything except /, and SDL_free() is your friend 🫶

this has been SDL_GlobStorageDirectory(3) from Simple Directmedia Layer, SDL 3.4.18 edition — mwah, love u, bye 💖🎀🌸