Debian Codegraph @

upstream/fedora-44/man3/auplugin_fgets.3

raw
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 .RS
52 .TP 9
53 .B MEM_SELF_MANAGED " - " Internal buffer owned by fgets
54 .TP
55 .B MEM_MALLOC " - " User-supplied malloc buffer; fgets frees it
56 .TP
57 .B MEM_MMAP " - " User-supplied mmap buffer; fgets munmaps it
58 .TP
59 .B MEM_MMAP_FILE " - " Read-only mmap file data
60 .RE
61 .PP
62 The default is
63 .B MEM_SELF_MANAGED
64 which means its lifecycle is automatically handled. When
65 .B MEM_MMAP_FILE
66 is used, the buffer is treated as a preloaded buffer (the entire file) and no reads will be performed on the descriptor provided to
67 .BR auplugin_fgets_r .
68 The reentrant form
69 .B auplugin_setvbuf_r
70 operates on an explicit state handle.
71 .PP
72 These functions maintain static state and are therefore not thread safe. For thread-safety, use the re-entrant variants.
73 .SH RETURN VALUE
74 .B auplugin_fgets
75 returns -1 on error, 0 when no data is available, or the number of characters copied otherwise.
76 .PP
77 .B auplugin_fgets_more
78 and
79 .B auplugin_fgets_eof
80 return 1 for true and 0 for false.
81 .PP
82 .B auplugin_fgets_clear
83 returns no value.
84 .PP
85 .B auplugin_setvbuf
86 returns 0 on success and 1 on failure.
87 .SH BACKGROUND
88 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.
89
90 .SH SEE ALSO
91 .BR fgets (3)