| 1 |
.TH "AUPLUGIN_FGETS" "3" "June 2025" "Red Hat" "Linux Audit API" |
| 2 |
.SH NAME |
| 3 |
auplugin_fgets, auplugin_fgets_more, auplugin_fgets_eof, auplugin_fgets_clear, auplugin_setvbuf, auplugin_setvbuf_r \- buffered line reader helpers |
| 4 |
.SH SYNOPSIS |
| 5 |
.B #include <auplugin.h> |
| 6 |
.sp |
| 7 |
.BI "int auplugin_fgets(char *" buf ", size_t " blen ", int " fd ");" |
| 8 |
.br |
| 9 |
.BI "int auplugin_fgets_more(size_t " blen ");" |
| 10 |
.br |
| 11 |
.BI "int auplugin_fgets_eof(void);" |
| 12 |
.br |
| 13 |
.B void auplugin_fgets_clear(void); |
| 14 |
.br |
| 15 |
.BI "int auplugin_setvbuf(void *" buf ", size_t buff_size, enum auplugin_mem " how ");" |
| 16 |
.br |
| 17 |
.BI "int auplugin_setvbuf_r(auplugin_fgets_state_t *" st ", void *" buf ", size_t buff_size, enum auplugin_mem " how ");" |
| 18 |
.SH DESCRIPTION |
| 19 |
.B auplugin_fgets |
| 20 |
reads from |
| 21 |
.I fd |
| 22 |
into |
| 23 |
.I buf |
| 24 |
up to |
| 25 |
.I blen |
| 26 |
bytes or through the next newline. Text is accumulated across calls in an internal buffer so that complete lines can be returned. The string is NUL terminated. |
| 27 |
.PP |
| 28 |
.B auplugin_fgets_more |
| 29 |
checks whether the buffer holds a newline or at least |
| 30 |
.I blen - 1 |
| 31 |
bytes. |
| 32 |
.PP |
| 33 |
.B auplugin_fgets_eof |
| 34 |
indicates whether end of file was reached on |
| 35 |
.I fd |
| 36 |
. |
| 37 |
.PP |
| 38 |
.B auplugin_fgets_clear |
| 39 |
resets the internal buffer and EOF state, discarding any stored text. When the memory type is |
| 40 |
.B MEM_MMAP_FILE |
| 41 |
, the buffer is rewound to the beginning making the entire file available again. |
| 42 |
.PP |
| 43 |
.B auplugin_setvbuf |
| 44 |
points the internal buffer at |
| 45 |
.I buf |
| 46 |
and sets how it will be released when |
| 47 |
.B auplugin_fgets_destroy |
| 48 |
is called. The |
| 49 |
.I how |
| 50 |
parameter should be one of |
| 51 |
.B MEM_SELF_MANAGED, |
| 52 |
.B MEM_MALLOC, |
| 53 |
.B MEM_MMAP, |
| 54 |
or |
| 55 |
.B MEM_MMAP_FILE. |
| 56 |
The default is |
| 57 |
.B MEM_SELF_MANAGED |
| 58 |
which means no action is taken on the memory block. |
| 59 |
When |
| 60 |
.B MEM_MMAP_FILE |
| 61 |
is used, the buffer is treated as a preloaded buffer (the entire file) and no reads will be performed on the descriptor provided to |
| 62 |
.BR auplugin_fgets_r . |
| 63 |
The reentrant form |
| 64 |
.B auplugin_setvbuf_r |
| 65 |
operates on an explicit state handle. |
| 66 |
.PP |
| 67 |
These functions maintain static state and are therefore not thread safe. |
| 68 |
.SH RETURN VALUE |
| 69 |
.B auplugin_fgets |
| 70 |
returns -1 on error, 0 when no data is available, or the number of characters copied otherwise. |
| 71 |
.PP |
| 72 |
.B auplugin_fgets_more |
| 73 |
and |
| 74 |
.B auplugin_fgets_eof |
| 75 |
return 1 for true and 0 for false. |
| 76 |
.PP |
| 77 |
.B auplugin_fgets_clear |
| 78 |
returns no value. |
| 79 |
.PP |
| 80 |
.B auplugin_setvbuf |
| 81 |
returns 0 on success and 1 on failure. |
| 82 |
.SH BACKGROUND |
| 83 |
The reason that this family of functions was created 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. 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. This family of functions allows you to correctly work only using descriptors but with the convenience of fgets. |
| 84 |
|
| 85 |
.SH SEE ALSO |
| 86 |
.BR fgets (3) |
| 87 |
|