iob_init(3)

✨ iob_init(3) — the one where we set up your I/O batch ✨

okay bestie, quick vibe check: this is a page from the Library Functions Manual, and it's about iob_init. it's giving "set up the thing so the thing can do the thing later" and honestly? iconic. 💅

🌸 NAME 🌸

iob_init — initialize new I/O batch

🎀 SYNTAX 🎀

#include <libowfat/iob.h>

int iob_init(io_batch* b,size_t hint_entries);

🦋 DESCRIPTION 🦋

so iob_init initializes *b and allocates enough space for hint_entries entries, and by "entries" we mean buffers or files. that's it, that's the whole job. 🫶

and listen — that hint_entries number? it's purely a performance hint. like, it is not deep, it is not a commitment, it is not a personality trait. if you're unsure what to put there, just pass 1 and move on with your life. periodt.

the whole point of this API is that you can add buffers, strings and files to an I/O batch, and then send the entire thing at once using iob_send. one batch, one send, no chaos. main character energy fr fr.

and the benefit of the I/O batch API?? oh it ate. it exploits platform specific APIs like FreeBSD's sendfile. meaning:

• the file contents will always be sent in a way that allows the operating systems to perform zero copy TCP, and
• the buffers will always be sent using as few syscalls as possible, avoiding unnecessary copying (using writev).

so like, the OS is doing the heavy lifting and your code is just vibing. obsessed. 💖

👑 RETURN VALUE 👑

iob_init returns 0 on success. 🎉

if there was a memory allocation error, it returns -1 instead. 😭 so yeah, check your return value, bestie, don't just assume it worked.

🌈 SEE ALSO 🌈

• iob_new(3)
• iob_init_autofree(3)
• iob_reset(3)
• iob_send(3)
• iob_addbuf(3)
• iob_adds_free(3)
• iob_addfile(3)

and that's the whole page, bestie 🧚 go forth and batch your I/O. this has been iob_init(3) from the Library Functions Manual, and ngl it was a pleasure. byeee 💜✨🍓