BUFFER_GET_TOKEN_SA_PRED(3)

💖 buffer_get_token_sa_pred(3) — the "read me a token, bestie" page 💖

okay so this is one of those pages from the Library Functions Manual (yes, that's the manual name, it's giving very "official group chat" energy 👑) and it's all about a function literally called buffer_get_token_sa_pred. Say that five times fast. I'll wait. 🫶

---

✨ NAME ✨

buffer_get_token_sa_pred — read token from buffer 🎀

---

🌸 SYNTAX 🌸

like, the way you summon it:

#include <libowfat/stralloc.h>
#include <libowfat/buffer.h>

int buffer_get_token_sa_pred(buffer* b,stralloc* sa,
                 int (*predicate)(stralloc* * sa));

yes the includes are exactly those two, libowfat/stralloc.h and libowfat/buffer.h, no cap. 💅

---

💜 DESCRIPTION 💜

so here's the vibe: buffer_get_token_sa_pred appends data from b to sa until predicate(sa) returns 1 or -1. it just keeps sipping data and calling your little predicate until the predicate says "okay we're done here" (that's 1) or "ABORT" (that's -1). 🔥

if predicate returns 1 once a '\n' was read, that new-line character is still appended to sa — it does not get quietly removed for you, bestie, so use stralloc_chop or stralloc_chomp to get rid of it yourself. 🙈

and predicate can also return 0, which means "further input is required to complete the token", or -1, which means "abort and return -1". reach for -1 if your predicate wants to enforce a maximum message size, or does timeout handling, or detects a malformed message. basically -1 is the "nope, we're out" button. 💀

if reading from the buffer or allocating memory fails, buffer_get_token_sa_pred returns -1 and sets errno appropriately. and at that point sa may already contain a partial token — so yeah, heads up, it's not transactional, it's just vibes. 😭

on success, buffer_get_token_sa_pred returns 0. slay. ⭐

---

🦋 RATIONALE 🦋

why does it append instead of overwriting? because that's the whole point, bestie — appending instead of overwriting means it can be used on non-blocking sockets. those signal error and set errno to EAGAIN; in this case you can simply call buffer_get_token_sa again when select or poll indicate more data is available. see? it's a "come back later" situation, not a "start over" situation. 🌈

---

👑 SEE ALSO 👑

• buffer_getline_sa(3)
• buffer_get_token(3)
• buffer(3)

---

and that's the whole page, periodt. 💅 this one lives in the Library Functions Manual, and the footer is literally just the page name again — buffer_get_token_sa_pred(3) — because apparently even the manpage itself said "no notes, I'm perfect." iconic minimalism, honestly. 🎀✨💖