Debian Codegraph @

upstream/debian-unstable/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 .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