io_waitread(3)

💖 io_waitread(3) 💖

okay so bestie, welcome to io_waitread — the <libowfat/io.h> girlies know 💅 this one is literally about reading from a descriptor. that's it. that's the whole vibe. no cap.

✨ NAME ✨

io_waitread — read from a descriptor 🫶

🌸 SYNTAX 🌸

#include <libowfat/io.h>

int io_waitread(int64 fd,char* buf,int64 len);

🦋 DESCRIPTION 🦋

so what io_waitread does is it tries to read len bytes of data from descriptor fd into buf[0], buf[1], ..., buf[len-1]. yes queen, straight into your buffer, index by index, no skips.

⚠️ real talk though: the effects are undefined if len is 0 or smaller. undefined. not "kinda weird", not "probably fine" — undefined. do not do it. do not test it. do not look at it funny. 🚫

there are a few possible outcomes, and each one is its own little moment:

• io_waitread returns an integer between 1 and len — yay! that many bytes were available for immediate reading, and they got read into the beginning of buf. but bestie, hear me: this number can be, and often is, smaller than len. you must not assume io_waitread always succeeds in reading exactly len bytes. it's giving "partial read" and that is completely valid behaviour. 💀 don't write code that pretends otherwise.
• io_waitread returns 0 — no bytes were read, because the descriptor is at end of file. like, for example, this descriptor has reached the end of a disk file, or it's reading an empty pipe that has been closed by all writers. that's it, that's the end, the story is over, nobody's writing anymore. 🎀
• io_waitread returns -3, setting errno to something other than EAGAIN — no bytes were read, because the read attempt encountered a persistent error. and by persistent we mean persistent, like: a serious disk failure (EIO), an unreachable network (ENETUNREACH), or an invalid descriptor number (EBADF). this is not a "try again later" moment, this is a "something is actually wrong" moment. 😭

🔥 SEE ALSO 🔥

• io_nonblock(3)
• io_waitread(3)
• io_waitreadtimeout(3)

and that's the page, bestie 🧚 straight from the Library Functions Manual, filed under io_waitread(3) — the same name up top and down at the bottom, iconic symmetry fr fr. now go read your descriptor responsibly 💜✨