iob_write(3)

💖 iob_write(3) — from the Library Functions Manual, bestie 💖

okay so. you found the page for iob_write, and honestly? it's giving "quietly the most important function in your SSL stack." let's get into it 🫶

---

✨ NAME ✨

iob_write — send I/O batch through callback

like, that's the whole vibe. batch goes in, callback gets called, bytes come out. 💅

---

🌸 SYNTAX 🌸

#include <libowfat/iob.h>

typedef int64 (*io_write_callback)(int64 s,const void* buf,uint64 n);

int64 iob_write(int64 s,io_batch* b,io_write_callback cb);

there it is. one include, one typedef, one function. clean. no notes. ✨

---

🦋 DESCRIPTION 🦋

so iob_write takes your batch b — the rest of it, specifically — and sends it through the callback cb, passing s along as the first argument. and cb? it's expected to behave like io_trywrite(2). no cap.

this interface is made for sending an I/O batch through a filter — like if you wanna encrypt it or compress it before it goes anywhere. so cute, so useful. 🎀 but if you literally just wanna yeet an I/O batch at a socket, that's not this. that's iob_send, bestie. use that one.

now the return values, and you need to know these because they're basically the plot of the whole function:

• it returns the number of bytes written 🥳
• 0 — there were no more bytes to be written in the batch, we're done
• -1 — that's EAGAIN, we gotta wait
• -3 — a permanent error, like for example "connection reset by peer" 💀

the normal usage pattern, iykyk: use io_wait to figure out when a descriptor is actually writable, and then just call iob_write over and over until it returns 0, -1, or -3. that's the loop. that's the whole thing.

and then, depending on what it gave you:

• returned 0 → terminate the loop, everything was written OK 🎉
• returned -1 → call io_wait again, we're just waiting on the vibe
• returned -3 → signal an error, bestie, it's over 😭

the callback is supposed to behave like write(2), which means: return the number of bytes written, return 0 for EOF, return -1 for error (and heads up — iob_write will return -3 then). and if you're doing non-blocking I/O and you need to wait for the next write event, return -1 with errno==EAGAIN. when that happens, iob_write will return -1. teamwork, honestly. 🫶

---

🌈 NOTE 🌈

listen up because this one bites people 🙈

iob_write will keep calling your callback until it returns an error. like, it does not get tired. it does not get bored. it will just keep going.

so if you're in a state machine — say, a web server using this for SSL support — make sure you write at most n bytes at a time (e.g. 64k), and the next time you're called, return -1. otherwise iob_write might not return until the whole file is served. 💀 not a fun way to find out. protect your event loop, girl.

---

💜 SEE ALSO 💜

• iob_send(3)

---

and that's the page!! 💖✨ this one came from the Library Functions Manual, and the footer's just sitting there being all iob_write(3) at you. no date, no version drama, just the name and the manual, keeping it iconic. periodt. 👑🌸