NAME

       auplugin_fgets,    auplugin_fgets_more,   auplugin_fgets_eof,   auplugin_fgets_clear,   auplugin_setvbuf,
       auplugin_setvbuf_r - buffered line reader helpers

SYNOPSIS

       #include <auplugin.h>

       int auplugin_fgets(char *buf, size_t blen, int fd);
       int auplugin_fgets_more(size_t blen);
       int auplugin_fgets_eof(void);
       void auplugin_fgets_clear(void);
       int auplugin_setvbuf(void *buf, size_t buff_size, enum auplugin_mem how);
       int auplugin_setvbuf_r(auplugin_fgets_state_t *st, void *buf, size_t buff_size, enum auplugin_mem how);

DESCRIPTION

       auplugin_fgets reads from fd into buf up to 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.

       auplugin_fgets_more checks whether the buffer holds a newline or at least blen - 1 bytes.

       auplugin_fgets_eof indicates whether end of file was reached on fd

       auplugin_fgets_clear  resets  the  internal  buffer  and  EOF state, discarding any stored text. When the
       memory type is MEM_MMAP_FILE , the buffer is rewound to the beginning making the  entire  file  available
       again.

       auplugin_setvbuf   points   the   internal  buffer  at  buf  and  sets  how  it  will  be  released  when
       auplugin_fgets_destroy is called. The how  parameter  should  be  one  of  MEM_SELF_MANAGED,  MEM_MALLOC,
       MEM_MMAP, or MEM_MMAP_FILE.  The default is MEM_SELF_MANAGED which means no action is taken on the memory
       block.   When 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  auplugin_fgets_r.   The   reentrant   form
       auplugin_setvbuf_r operates on an explicit state handle.

       These functions maintain static state and are therefore not thread safe.

RETURN VALUE

       auplugin_fgets  returns  -1  on  error,  0  when no data is available, or the number of characters copied
       otherwise.

       auplugin_fgets_more and auplugin_fgets_eof return 1 for true and 0 for false.

       auplugin_fgets_clear returns no value.

       auplugin_setvbuf returns 0 on success and 1 on failure.

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.

SEE ALSO

       fgets(3)

Red Hat                                             June 2025                                  AUPLUGIN_FGETS(3)