SDL_IOFromFile(3)

✨ SDL_IOFromFile ✨

okay bestie, welcome to the SDL_IOFromFile page in the SDL3 functions lineup 💖 this one is your lil' doorway to files, so let's get into it.

---

🌸 NAME 🌸

SDL_IOFromFile — use this function to make a brand new SDL_IOStream structure so you can read from and/or write to a file with an actual name. like, a real file on disk. iconic behavior honestly 👑

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_iostream.h>

SDL_IOStream * SDL_IOFromFile(const char *file, const char *mode);

---

💅 DESCRIPTION 💅

so the mode string gets treated roughly the same way it would in a call to the C library's fopen(), even if SDL isn't actually using fopen() under the hood. same vibe, not necessarily the same plumbing, iykyk.

here's the full lineup of available mode strings, no skips:

• "r" — opens a file for reading. the file has to exist, no exceptions bestie.
• "w" — makes an empty file for writing. if a file with that same name is already out there, its content gets erased and the file is treated like a fresh new empty file. it's giving glow-up but make it deletion 💀
• "wx" — creates an empty file for writing. if a file with the same name already exists, the call fails. no overwriting, we're being careful today.
• "a" — append to a file. writing operations put data at the end of the file. the file gets created if it doesn't exist yet. we love an auto-create 🫶
• "r+" — opens a file for update, both reading and writing. the file must exist.
• "w+" — creates an empty file for both reading and writing. if a file with the same name already exists, its content is erased and the file is treated as a new empty file.
• "w+x" — creates an empty file for both reading and writing. if a file with the same name already exists, the call fails.
• "a+" — opens a file for reading and appending. all writing operations happen at the end of the file, which protects the previous content from being overwritten. you can reposition the internal pointer anywhere in the file for reading using fseek or rewind, but writing operations will move it right back to the end of file. the file is created if it doesn't exist.

NOTE: to open a file as a binary file, a "b" character has to be included in the mode string. this extra "b" can either be appended at the end of the string (making these compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). additional characters may follow the sequence, although they should have no effect. for example, "t" is sometimes appended to make it explicit that the file is a text file.

this function supports Unicode filenames, but they have to be encoded in UTF-8 format, regardless of whatever the underlying operating system is doing. no cap.

on Android, SDL_IOFromFile() can be used to open content:// URIs. and as a fallback, SDL_IOFromFile() will transparently open a matching filename in the app's assets. sneaky! love that for us ✨

closing the SDL_IOStream will close SDL's internal file handle. so like, don't be out here leaking handles, bestie.

the following properties may be set at creation time by SDL:

• SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER — a pointer, that can be cast to a win32 HANDLE, that this SDL_IOStream is using to access the filesystem. if the program isn't running on Windows, or SDL used some other method to access the filesystem, this property will not be set.
• SDL_PROP_IOSTREAM_STDIO_FILE_POINTER — a pointer, that can be cast to a stdio FILE *, that this SDL_IOStream is using to access the filesystem. if SDL used some other method to access the filesystem, this property will not be set. PLEASE NOTE that if SDL is using a different C runtime than your app, trying to use this pointer will almost certainly result in a crash! this is mostly a problem on Windows; make sure you build SDL and your app with the same compiler and settings to avoid it. seriously, don't play with this one 😭
• SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER — a file descriptor that this SDL_IOStream is using to access the filesystem.
• SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER — a pointer, that can be cast to an Android NDK AAsset *, that this SDL_IOStream is using to access the filesystem. if SDL used some other method to access the filesystem, this property will not be set.

---

🦋 FUNCTION PARAMETERS 🦋

• file — a UTF-8 string representing the filename to open.
• mode — an ASCII string representing the mode to be used for opening the file.

---

💜 RETURN VALUE 💜

returns a pointer to the SDL_IOStream structure that is created, or NULL on failure. if it fails, call SDL_GetError() for more information — that's where the tea is 🍓

---

🌈 THREAD SAFETY 🌈

it is safe to call this function from any thread. multitasking queen energy, we stan 👑

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0.

---

🧚 SEE ALSO 🧚

• SDL_CloseIO(3)
• SDL_FlushIO(3)
• SDL_ReadIO(3)
• SDL_SeekIO(3)
• SDL_TellIO(3)
• SDL_WriteIO(3)

---

and that's the whole page, bestie!! this one came to you straight from Simple Directmedia Layer, version SDL 3.4.18, and it's the SDL_IOFromFile(3) page fr fr. go open some files, slay responsibly 💖✨🎀