SDL_ReadIO(3)

💖 SDL_ReadIO(3) 💖

okay bestie, so this is a page from the SDL3 FUNCTIONS manual — like, the whole SDL3 crew — and today's main character is SDL_ReadIO. she reads stuff. from a data source. that's the whole gig and she's so good at it. 🎀

---

✨ NAME ✨

SDL_ReadIO — read from a data source, no cap 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_iostream.h>

size_t SDL_ReadIO(SDL_IOStream *context, void *ptr, size_t size);

---

🦋 DESCRIPTION 🦋

okay so picture this: this function reads up to size bytes from the data source, and it drops them into the area that ptr is pointing at. lowkey important detail though — it may read fewer bytes than you asked for. she's not being rude, that's just how it is. 😭

when the data stream is completely read, this function returns zero, and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. but here's the plot twist 👀 — if zero comes back and the stream is not at EOF, then SDL_GetIOStatus() will return a different error value instead, and SDL_GetError() will hand you a human-readable message so you actually know what went down. so like, zero doesn't always mean "we're done", fr fr. check the status. 🫶

and now for the cutest little detail: if you request zero bytes on a valid stream, it returns zero immediately without touching the stream at all. so the stream status (EOF, err, whatever) does not change. she said "i'm not even gonna look at it." iconic. ✨

---

💜 FUNCTION PARAMETERS 💜

• context — a pointer to an SDL_IOStream structure. that's the stream bestie, the whole vibe.
• ptr — a pointer to a buffer to read data into. this is where the bytes go to live. 🏠
• size — the number of bytes to read from the data source. how many, bestie, tell her how many.

---

👑 RETURN VALUE 👑

returns the number of bytes read — or 0 on end of file or other failure. and if you get that 0, call SDL_GetError() for more information. 💀 (not me saying always check the error, but like... always check the error.)

---

🔥 THREAD SAFETY 🔥

do not use the same SDL_IOStream from two threads at once. one stream, one thread, that's the rule. sharing is not caring here, it's a race condition. 🙈

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. so if you're on something older, she's not there yet, sorry bestie. 💖

---

🌈 SEE ALSO 🌈

• SDL_WriteIO(3)
• SDL_GetIOStatus(3)

---

and that's the tea 🍓 this page came to you courtesy of Simple Directmedia Layer, serving SDL 3.4.18 — mwah, take care of your streams, hydrate, and don't read into a buffer you didn't size correctly. 💅✨🧚