githubmirror/audit-userspace

docs/auplugin_fgets.3
86 строк3 KB
Steve Grubb
Add MEM_MMAP_FILE storage type for auplugin-fgets
23 июл 2025, 22:48
23 июл 2025, 22:48217275e
.TH "AUPLUGIN_FGETS" "3" "June 2025" "Red Hat" "Linux Audit API"
.SH NAME
auplugin_fgets, auplugin_fgets_more, auplugin_fgets_eof, auplugin_fgets_clear, auplugin_setvbuf, auplugin_setvbuf_r \- buffered line reader helpers
.SH SYNOPSIS
.B #include <auplugin.h>
.sp
.BI "int auplugin_fgets(char *" buf ", size_t " blen ", int " fd ");"
.br
.BI "int auplugin_fgets_more(size_t " blen ");"
.br
.BI "int auplugin_fgets_eof(void);"
.br
.B void auplugin_fgets_clear(void);
.br
.BI "int auplugin_setvbuf(void *" buf ", size_t buff_size, enum auplugin_mem " how ");"
.br
.BI "int auplugin_setvbuf_r(auplugin_fgets_state_t *" st ", void *" buf ", size_t buff_size, enum auplugin_mem " how ");"
.SH DESCRIPTION
.B auplugin_fgets
reads from
.I fd
into
.I buf
up to
.I blen
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.
.PP
.B auplugin_fgets_more
checks whether the buffer holds a newline or at least
.I blen - 1
bytes.
.PP
.B auplugin_fgets_eof
indicates whether end of file was reached on
.I fd
.
.PP
.B auplugin_fgets_clear
resets the internal buffer and EOF state, discarding any stored text. When the memory type is
.B MEM_MMAP_FILE
, the buffer is rewound to the beginning making the entire file available again.
.PP
.B auplugin_setvbuf
points the internal buffer at
.I buf
and sets how it will be released when
.B auplugin_fgets_destroy
is called. The
.I how
parameter should be one of
.B MEM_SELF_MANAGED,
.B MEM_MALLOC,
.B MEM_MMAP,
or
.B MEM_MMAP_FILE.
The default is
.B MEM_SELF_MANAGED
which means no action is taken on the memory block.
When
.B MEM_MMAP_FILE
is used, the buffer is treated as a preloaded buffer (the entire file) and no reads will be performed on the descriptor provided to
.BR auplugin_fgets_r .
The reentrant form
.B auplugin_setvbuf_r
operates on an explicit state handle.
.PP
These functions maintain static state and are therefore not thread safe.
.SH RETURN VALUE
.B auplugin_fgets
returns -1 on error, 0 when no data is available, or the number of characters copied otherwise.
.PP
.B auplugin_fgets_more
and
.B auplugin_fgets_eof
return 1 for true and 0 for false.
.PP
.B auplugin_fgets_clear
returns no value.
.PP
.B auplugin_setvbuf
returns 0 on success and 1 on failure.
.SH BACKGROUND
 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.

.SH SEE ALSO
.BR fgets (3)