SDL_AsyncIOFromFile(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💖 SDL_AsyncIOFromFile(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_AsyncIOFromFile. it's giving "let's open a file but make it async-core." 🦋

✨ NAME ✨

SDL_AsyncIOFromFile — use this function to create a brand new SDL_AsyncIO object for reading from and/or writing to a named file. yes, and/or. it's versatile like that. 💅

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_asyncio.h>

SDL_AsyncIO * SDL_AsyncIOFromFile(const char *file, const char *mode);

🎀 DESCRIPTION 🎀

so the mode string? it understands these values, and you have to pick one of them, no freestyling:

  • "r" — opens a file for reading only. it must exist, bestie. no file, no vibe. 😭
  • "w" — opens a file for writing only. it'll create the file if it's missing, or truncate it if it's already there. bye bye old content 💀
  • "r+" — opens a file for update, both reading and writing. the file must exist. it's a two-for-one, we love to see it 🫶
  • "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 gets treated as a new empty file. periodt. 🔥
no "b" mode, because there's only "binary" style I/O around here — that's just the house style. and no "a" mode for appending either, because you specify the position when you start a task. you're the boss of that. 👑

also: this function supports Unicode filenames, but they must be encoded in UTF-8 format, regardless of the underlying operating system. no exceptions, no excuses. ✨

and like, lowkey important — this call is _not_ asynchronous. it opens the file before returning, operating on the assumption that opening a file is generally a fast operation. but the future reads and writes to the opened file will be async, however. slay. 🌈

🧚 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. pick from the list above, iykyk.

⭐ RETURN VALUE ⭐

returns a pointer to the SDL_AsyncIO structure that is created, or NULL on failure — and if it fails, call SDL_GetError() for more information. don't just sit there guessing, the error message is right there bestie 💜

🔥 THREAD SAFETY 🔥

it is safe to call this function from any thread. go off, multithreaded queen 👑

🌟 AVAILABILITY 🌟

this function is available since SDL 3.2.0. vintage-ish but make it fresh.

👑 SEE ALSO 👑

and that's the whole page, no cap. brought to you by Simple Directmedia Layer, version SDL 3.4.18 — catch you in the next manpage, mwah 💖✨🎀

📦 where this page comes from