---
name: "auplugin"
section: "3"
platform: "linux"
package: "audit"
version: "4.2.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/auplugin"
---

# auplugin(3)

plugin event processing helpers

## NAME

auplugin\_init, auplugin\_stop, auplugin\_event\_loop, auplugin\_event\_feed - plugin event processing helpers

## SYNOPSIS

**#include \<auplugin.h\>**

**int auplugin\_init(int** *inbound\_fd***, unsigned** *queue\_size***, int** *q\_flags***, const char \****path***);**\
 **void auplugin\_stop(void);**\
 **void auplugin\_event\_loop(auplugin\_callback\_ptr** *callback***);**\
 **int auplugin\_event\_feed(auparse\_callback\_ptr** *callback***, unsigned** *timer\_interval***, auplugin\_timer\_callback\_ptr** *timer\_cb***);**

## DESCRIPTION

**auplugin\_init** initializes the plugin framework. The *inbound\_fd* parameter specifies the file descriptor that will provide audit messages, typically standard input. The *queue\_size* argument controls the maximum number of events that may be queued for processing. The *q\_flags* parameter selects in-memory or file-backed storage using the **AUPLUGIN\_Q\_\*** constants defined in **auplugin.h**. If *q\_flags* includes **AUPLUGIN\_Q\_IN\_FILE,** *path* specifies the backing file. Any events already present in the file are queued on startup so plugins resume processing previously unhandled records. The library maintains global state for its queue and worker threads. Only one plugin instance is supported, so callers must not invoke auplugin\_init() concurrently from multiple threads. The function returns 0 on success or -1 if initialization fails.

**auplugin\_stop** signals the framework to terminate. It is normally called from a SIGTERM handler or other shutdown logic.

**auplugin\_event\_loop** starts a worker thread to deliver queued events to the supplied *callback* function one record at a time. The function blocks in the caller until **auplugin\_stop** is invoked.

**auplugin\_event\_feed** behaves like **auplugin\_event\_loop**, except that queued events are fed to libauparse. The provided *callback* must match the **auparse\_callback\_ptr** type. The *timer\_interval* argument specifies how many seconds the worker thread will wait for new records. A value of 0 disables the timer logic. When the interval elapses, **auparse\_feed\_age\_events** is called to flush aged events. If *timer\_cb* is not **NULL,** it is invoked with the interval before the flush. Passing a *timer\_cb* of **NULL** keeps the default behaviour of calling **auparse\_feed\_age\_events** only. The function returns 0 on success or -1 if libauparse could not be initialized.

Plugins can query queue statistics with **auplugin\_queue\_depth**, **auplugin\_queue\_max\_depth**, and **auplugin\_queue\_overflow**. Register a callback with **auplugin\_register\_stats\_callback**, and invoke it using **auplugin\_report\_stats**.

## SIGNAL HANDLING

Plugins should establish signal handlers with [sigaction(2)](/sigaction/2.md) before entering the event loop. The SIGTERM handler should call auplugin\_stop() to shut down the worker thread. Handlers for other signals, such as SIGHUP or SIGUSR1, should set global flags that are processed in the event or timer callbacks.

Example:

```
static volatile sig_atomic_t reload;
static void handler(int sig)
{
    if (sig == SIGTERM)
        auplugin_stop();
    else if (sig == SIGHUP)
        reload = 1;
}
```

## SEE ALSO

[**auplugin\_fgets**(3)](/auplugin_fgets/3.md), [**auparse\_feed**(3)](/auparse_feed/3.md)

## AUTHOR

Steve Grubb