NET_ReadFromStreamSocket(3)

💖 NET_ReadFromStreamSocket(3) 💖

okay bestie, this one's a page out of the SDL_net3 FUNCTIONS collection, and it's literally the "gimme the bytes someone sent me" function. no cap. let's get into it 🫶

---

✨ NAME ✨

NET_ReadFromStreamSocket — receive bytes that a remote system sent to a stream socket. it's giving mailbox energy, but make it networking 📬

---

✨ SYNOPSIS ✨

#include <SDL3_net/SDL_net.h>

int NET_ReadFromStreamSocket(NET_StreamSocket *sock, void *buf, int buflen);

---

✨ DESCRIPTION ✨

so stream sockets are _reliable_, and when I say reliable I mean it, like the data that gets sent over them shows up in the exact order it was transmitted, and the system will straight-up retransmit stuff as needed to make sure it actually gets delivered. which is to say: short of catastrophic failure, the data will arrive. possibly with severe delays tho 😭

and also, "catastrophic failure" is not an uncommon event. so. there's that 💀

this is the opposite of Datagram sockets, which yeet chunks of data that might show up in literally any order, or might not show up at all, but at least you never sit around waiting for missing chunks to appear. different vibe entirely.

stream sockets are also _bidirectional_ — you can read and write from the same stream, and the other end of the connection can do the exact same thing. mutual. reciprocal. iconic. 🔥

this function hands you the data that has arrived for the stream socket and hasn't been read yet. the data comes out in the order it was sent on the remote side, no rearranging. heads up: this function may return less data than you requested, depending on what's available at that moment, and the app isn't required to read all the available data at once either. you do you, take what you need 🌸

this call never blocks. if there's no new data at the time you call it, it returns 0 immediately and you can just try again later. no hanging, no awkward silence, periodt ✨

now the sad part 🙈 if the connection has failed — remote side dropped us, or one of a million other networking failures happened — this function reports failure by returning -1. stream sockets only report failure for unrecoverable conditions. so once a stream socket fails, assume it's donezo and destroy it with NET_DestroyStreamSocket(). it's not coming back bestie 💔

---

✨ FUNCTION PARAMETERS ✨

• sock — the stream socket to receive data from. your little data straw 🥤
• buf — a pointer to a buffer where the received data will be collected. this is where the goodies land.
• buflen — the size of the buffer that buf points to, in bytes. this is the maximum that will be read from the stream socket. don't overpromise and under-deliver.

---

✨ RETURN VALUE ✨

returns the number of bytes read from the stream socket — which can be less than buflen, or zero if none is available — or -1 on failure. and if you get that -1, call SDL_GetError() for the details. she will tell you what went wrong 💅

---

✨ THREAD SAFETY ✨

do not operate on the same socket from multiple threads at the same time unless you bring a serialization mechanism to the party. that's a recipe for chaos, fr fr.

however! different threads can access different sockets at the same time with zero problems. go off, parallelize 🦋

---

✨ AVAILABILITY ✨

this function has been available since SDL_net 3.0.0. vintage but make it modern ⭐

---

✨ SEE ALSO ✨

• NET_WriteToStreamSocket(3) — the other half of the conversation 💬

---

okay that's the whole page, you're officially fluent in NET_ReadFromStreamSocket 👑

later bestie, this was SDL_net 3.2.0 coming at you from the SDL_net corner of the manual, and yes we absolutely ate this documentation up 💖🎀🫶