# auplugin_fgets

## 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.
    


* * *