NET_WriteToStreamSocket(3)

💌 NET_WriteToStreamSocket(3) — the SDL_net3 glow-up edition

okay bestie, pull up a chair, we're learning how to yeet bytes across the internet 💖 this one lives in the SDL_net3 functions, and it's genuinely one of the most useful little guys in the whole library. no cap.

---

✨ NAME ✨

NET_WriteToStreamSocket — send bytes over a stream socket to a remote system. that's it. that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

#include <SDL3_net/SDL_net.h>

bool NET_WriteToStreamSocket(NET_StreamSocket *sock, const void *buf, int buflen);

---

✨ DESCRIPTION ✨

okay so first things first: stream sockets are _reliable_. like, that's their whole personality. data you send over them arrives in the exact order it was transmitted, and the system will retransmit stuff as needed to make sure it actually shows up. which basically means: short of catastrophic failure, your data will arrive. possibly with severe delays, bestie. and also — and I need you to hear me on this — "catastrophic failure" is not an uncommon event. 😭 it's giving "your package will arrive, probably, unless the truck explodes, and sometimes the truck explodes."

(this is the opposite of Datagram sockets, which send chunks of data that might arrive in any order, or might not arrive at all — but at least you never sit there waiting for missing chunks to show up. different energy 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 right back at you. mutual. reciprocal. iconic. 👑

and here's the part that makes this function so chill: this call never blocks. if it can't send the data immediately, the library just queues it for later transmission. no hanging, no drama, no frozen main loop. if you wanna peek at how much is still sitting in the queue, call NET_GetStreamSocketPendingWrites(). or if you need to actually wait until all that pending data has gone out, NET_WaitUntilStreamSocketDrained() will block for you. pick your fighter. 💪

now the sad part 🥀 — if the connection has failed (remote side dropped us, or one of a million other networking failures occurred), this function reports failure by returning false. stream sockets only report failure for unrecoverable conditions. so once a stream socket fails, assume it is no longer usable and destroy it with NET_DestroyStreamSocket(). it's not coming back. grieve and move on. 🫶

---

✨ FUNCTION PARAMETERS ✨

• sock — the stream socket you're sending data through. your little tube of destiny. 🌈
• buf — a pointer to the data to send. the actual goods. 🎀
• buflen — the size of the data to send, in bytes. how much of the goods. 📏

---

✨ RETURN VALUE ✨

returns true if the data was sent or queued for transmission, and false on failure. and if it's a false situation? call SDL_GetError() for the details, because it will absolutely tell you what went wrong. 💀

---

✨ THREAD SAFETY ✨

do not operate on the same socket from multiple threads at the same time without supplying a serialization mechanism. like, that's a whole mess, don't do it. however — different threads may access different sockets at the same time with zero problems. so parallelize responsibly, bestie. ✨

---

✨ AVAILABILITY ✨

this function is available since SDL_net 3.0.0. so if you're on anything older… babes. upgrade. 🙈

---

✨ SEE ALSO ✨

• NET_GetStreamSocketPendingWrites(3)
• NET_WaitUntilStreamSocketDrained(3)
• NET_ReadFromStreamSocket(3)

---

and that's the whole page, periodt. 💅 this was NET_WriteToStreamSocket(3) from the SDL_net manual, page version SDL_net 3.2.0 — go forth and send ur bytes, main character. you've got this. 🦋💖🌸