io_trywrite(3)

💖 io_trywrite — a lil manual page, section 3, from the Library Functions Manual 💖

okay bestie sit DOWN because we're about to talk about writing to a file descriptor without ever, ever blocking. no waiting. no pausing. just vibes and bytes. 🦋

---

🌸 NAME 🌸

io_trywrite — write to a descriptor without blocking

---

✨ SYNTAX ✨

#include <libowfat/io.h>

int io_trywrite(int64 fd,const char* buf,int64 len);

---

🎀 DESCRIPTION 🎀

so io_trywrite tries to write len bytes of data from buf[0], buf[1], ..., buf[len-1] over to descriptor fd. 🫶

⚠️ heads up queen: the effects are undefined if len is 0 or smaller. do not do that. we do not do that.

and listen, there are several possible outcomes here, so let's go through them one by one like the group chat debrief:

• io_trywrite returns an integer between 1 and len — this number of bytes was immediately written from the beginning of buf. and ngl, this number can be, and often is, smaller than len. do not assume io_trywrite always succeeds in writing exactly len bytes. it's giving "partial write, deal with it". 💅
• io_trywrite returns -1, setting errno to EAGAIN — zero bytes were written, because the descriptor is not ready. for example, the descriptor is writing to a full pipe that could still be read. not a fail, just a "not right now babe". 😭
• io_trywrite returns -3, setting errno to something other than EAGAIN — zero bytes were written, because the write attempt hit a persistent error. think a serious disk failure (EIO), an unreachable network (ENETUNREACH), or an invalid descriptor number (EBADF). that's a real problem, not a timing thing. 💀

io_trywrite does not pause waiting for a descriptor that is not ready. it will not sit there. it will not wait up for you. if you actually want to pause, use io_waitread or io_wait. ✨

you can make io_trywrite faster and more efficient by making the socket non-blocking with io_nonblock(). obsessed with an optimization. 🔥

---

📜 a lil history lesson (true story, no cap) 📜

once upon a time, many UNIX programs neglected to check the success of their writes. they would often encounter EPIPE, and would blithely continue writing, rather than exiting with an appropriate exit code. like. bestie. check your return values. 🙈

so the UNIX kernel developers decided to send a SIGPIPE signal, which terminates the process by default, along with returning EPIPE. this papers over the problem without fixing it: the same programs ignore other errors such as EIO. one hopes that the programs have been fixed by now; kernels nevertheless continue to generate the SIGPIPE signal. 💀

the first time io_trywrite or io_waitwrite is called, it arranges for SIGPIPE to be ignored. (technically, for SIGPIPE to be caught by an empty signal handler, so this doesn't affect child processes.) so like, heads up:

🚨 Do not use SIGPIPE elsewhere in the program. it's taken. it's spoken for. main character energy only. 👑

---

🌈 SEE ALSO 🌈

• io_nonblock(3)
• io_waitread(3)
• io_trywritetimeout(3)

---

and that's the whole page, bestie!! 🧚 this lil manual page is io_trywrite(3) from the Library Functions Manual — section 3, library functions, the one where all the good stuff lives. mwah. go write some bytes. 💜🌸✨