HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |BACKGROUND |SEE ALSO |COLOPHON | |
AUPLUGIN_FGETS(3) Linux Audit APIAUPLUGIN_FGETS(3)auplugin_fgets, auplugin_fgets_more, auplugin_fgets_eof, auplugin_fgets_clear, auplugin_setvbuf, auplugin_setvbuf_r - buffered line reader helpers
#include <auplugin.h>int auplugin_fgets(char *buf, size_tblen, intfd);int auplugin_fgets_more(size_tblen);int auplugin_fgets_eof(void);void auplugin_fgets_clear(void);int auplugin_setvbuf(void *buf, size_t buff_size, enumauplugin_memhow);int auplugin_setvbuf_r(auplugin_fgets_state_t *st, void *buf,size_t buff_size, enum auplugin_memhow);
auplugin_fgetsreads fromfd intobuf up toblen 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.auplugin_fgets_morechecks whether the buffer holds a newline or at leastblen - 1 bytes.auplugin_fgets_eofindicates whether end of file was reached onfdauplugin_fgets_clearresets the internal buffer and EOF state, discarding any stored text. When the memory type isMEM_MMAP_FILE , the buffer is rewound to the beginning making the entire file available again.auplugin_setvbufpoints the internal buffer atbuf and sets how it will be released whenauplugin_fgets_destroyis called. Thehow parameter should be one ofMEM_SELF_MANAGED, MEM_MALLOC, MEM_MMAP, orMEM_MMAP_FILE.The default isMEM_SELF_MANAGEDwhich means no action is taken on the memory block. WhenMEM_MMAP_FILEis used, the buffer is treated as a preloaded buffer (the entire file) and no reads will be performed on the descriptor provided toauplugin_fgets_r. The reentrant formauplugin_setvbuf_roperates on an explicit state handle. These functions maintain static state and are therefore not thread safe.
auplugin_fgetsreturns -1 on error, 0 when no data is available, or the number of characters copied otherwise.auplugin_fgets_moreandauplugin_fgets_eofreturn 1 for true and 0 for false.auplugin_fgets_clearreturns no value.auplugin_setvbufreturns 0 on success and 1 on failure.
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.
fgets(3)
This page is part of theaudit (Linux Audit) project. Information about the project can be found at ⟨http://people.redhat.com/sgrubb/audit/⟩. If you have a bug report for this manual page, send it to linux-audit@redhat.com. This page was obtained from the project's upstream Git repository ⟨https://github.com/linux-audit/audit-userspace.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-09.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgRed Hat June 2025AUPLUGIN_FGETS(3)Pages that refer to this page:auplugin(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |