AUPLUGIN_FGETS(3)

✨ auplugin_fgets — the buffered line reader squad ✨

okay bestie, listen up 💖 this is the Linux Audit API page for auplugin_fgets(3) and honestly? it's giving "we fixed a genuinely cursed problem" energy. these functions are your buffered line reader helpers — a whole little family of them, and you're gonna meet all of them, no cap.

---

🌸 NAME 🌸

auplugin_fgets, auplugin_fgets_more, auplugin_fgets_eof, auplugin_fgets_clear, auplugin_setvbuf, auplugin_setvbuf_r — buffered line reader helpers. yes that's six (6) icons in one friend group, and yes they all pull their weight 💅

---

🎀 SYNOPSIS 🎀

#include <auplugin.h>

int auplugin_fgets(char *buf, size_t blen, int fd);
int auplugin_fgets_more(size_t blen);
int auplugin_fgets_eof(void);
void auplugin_fgets_clear(void);
int auplugin_setvbuf(void *buf, size_t buff_size, enum auplugin_mem how);
int auplugin_setvbuf_r(auplugin_fgets_state_t *st, void *buf, size_t buff_size, enum auplugin_mem how);

---

🦋 DESCRIPTION 🦋

auplugin_fgets reads from fd into buf up to blen bytes, or all the way through the next newline — whichever comes first, like it's not gonna overstay its welcome. here's the cute part: the text gets accumulated across calls in an internal buffer, so complete lines can actually be returned to you. and the string is NUL terminated, because of course it is, we're not monsters 🫶

auplugin_fgets_more does a little vibe check 🔍 — it checks whether the buffer holds a newline or at least blen - 1 bytes.

auplugin_fgets_eof tells you whether end of file was reached on fd. that's it, that's the whole job, and it does it flawlessly 💀

auplugin_fgets_clear resets the internal buffer and the EOF state, discarding any stored text like it never happened 🙈 and here's the spicy detail: when the memory type is MEM_MMAP_FILE, the buffer gets rewound to the beginning, making the entire file available again. it's giving time travel honestly ⭐

auplugin_setvbuf points the internal buffer at buf and sets how it will be released when auplugin_fgets_destroy is called. the how parameter should be one of these, bestie — memorize them:

• MEM_SELF_MANAGED — internal buffer owned by fgets 👑
• MEM_MALLOC — user-supplied malloc buffer; fgets frees it
• MEM_MMAP — user-supplied mmap buffer; fgets munmaps it
• MEM_MMAP_FILE — read-only mmap file data

the default is MEM_SELF_MANAGED, which means its lifecycle is automatically handled. you don't gotta do a thing, it's self-sufficient, main character energy ✨ when MEM_MMAP_FILE is used, the buffer is treated as a preloaded buffer (the entire file, yes, the whole thing) and no reads will be performed on the descriptor provided to auplugin_fgets_r. the reentrant form auplugin_setvbuf_r operates on an explicit state handle, for when you're feeling multi-threaded and fancy 🧚

⚠️ okay important warning time, no skipping: these functions maintain static state and are therefore not thread safe. for thread-safety, use the re-entrant variants. periodt. 💅

---

💖 RETURN VALUE 💖

• auplugin_fgets returns -1 on error, 0 when no data is available, or the number of characters copied otherwise.
• auplugin_fgets_more and auplugin_fgets_eof return 1 for true and 0 for false.
• auplugin_fgets_clear returns no value.
• auplugin_setvbuf returns 0 on success and 1 on failure.

---

🌈 BACKGROUND 🌈

okay so here's the lore, and it's actually iconic 📖

the reason this whole family of functions exists is because in auditd plugins, the event stream is stdin, which is descriptor 0. a typical pattern is to call select, poll, or epoll to wait for a record to arrive. as soon as it does, you need to read it.

and here's where it goes wrong: if you use fgets, you will wind up with big problems 😭 because you cannot mix low level descriptors with high level constructs like struct FILE. it's giving oil and water. it's giving incompatible situationship. 💀

this family of functions lets you correctly work only using descriptors, but with the convenience of fgets. best of both worlds, we ate and left no crumbs 🍓

---

⭐ SEE ALSO ⭐

• fgets(3)

---

and that's the whole page, bestie — you're officially fluent in auplugin_fgets(3) 🎀

this lil masterpiece came from Red Hat, dated June 2025 — go forth and read your lines responsibly 👑💜