TERMKEY_ADVISEREADABLE(3)

💖 TERMKEY_ADVISEREADABLE 💖

okay bestie, so this one lives in the Library Functions Manual section 3, and it's called termkey_advisereadable — the little function that goes "hey girl, there might be more bytes waiting for you on that terminal" 🦋

✨ NAME ✨

termkey_advisereadable — read more bytes from the underlying terminal 💅

🌸 SYNOPSIS 🌸

#include <termkey.h>

TermKeyResult termkey_advisereadable(TermKey *tk);

Link with -ltermkey.

🎀 DESCRIPTION 🎀

so like. termkey_advisereadable() is literally just you tapping your termkey(7) instance on the shoulder like "bestie, new input might be available on the underlying file descriptor, go call read(2) and get it" 👑✨

Here's the vibe check on what comes back:

• If it read at least one more byte, it returns TERMKEY_RES_AGAIN — which is code for "it may be useful to call termkey_getkey(3) again" 🔁
• If no more input was read, you get TERMKEY_RES_NONE 😶
• If there was no buffer space remaining, you get TERMKEY_RES_ERROR with errno set to ENOMEM 💀
• If there's no filehandle associated with this instance, you get TERMKEY_RES_ERROR with errno set to EBADF 🙈

This function, together with termkey_getkey(3), is what makes it possible to use the termkey instance in an asynchronous program. And if you wanna feed it bytes without using a readable file handle, use termkey_push_bytes(3) instead, okay? 🫶

For synchronous usage, termkey_waitkey(3) is the one doing the input blocking task, no cap.

⭐ RETURN VALUE ⭐

termkey_advisereadable() returns one of these constants, and they're all giving very specific energy:

• TERMKEY_RES_AGAIN — at least one byte was read ✨
• TERMKEY_RES_NONE — no more bytes were read 😭
• TERMKEY_RES_ERROR — an IO error occurred. errno will be preserved. And here's the important part, so listen up: if the error is EINTR then this will only be returned if the TERMKEY_FLAG_EINTR flag is not set; if it is set then the IO operation will be retried instead 🔁💖

🌈 SEE ALSO 🌈

• termkey_getkey(3)
• termkey_waitkey(3)
• termkey_set_waittime(3)
• termkey(7)

and that's the whole page, bestie — it's from the TERMKEY_ADVISEREADABLE(3) entry in the Library Functions Manual, and it's literally iconic. mwah 💅💖✨