Debian Codegraph @

upstream/debian-unstable/man3/auplugin.3

raw
1 .TH "AUPLUGIN" "3" "June 2025" "Red Hat" "Linux Audit API"
2 .SH NAME
3 auplugin_init, auplugin_stop, auplugin_event_loop, auplugin_event_feed \- plugin event processing helpers
4 .SH SYNOPSIS
5 .B #include <auplugin.h>
6 .sp
7 .BI "int auplugin_init(int " inbound_fd ", unsigned " queue_size ", int " q_flags ", const char *" path ");"
8 .br
9 .B void auplugin_stop(void);
10 .br
11 .BI "void auplugin_event_loop(auplugin_callback_ptr " callback ");"
12 .br
13 .BI "int auplugin_event_feed(auparse_callback_ptr " callback ", unsigned " timer_interval ", auplugin_timer_callback_ptr " timer_cb ");"
14 .SH DESCRIPTION
15 .B auplugin_init
16 initializes the plugin framework. The
17 .I inbound_fd
18 parameter specifies the file descriptor that will provide audit
19 messages, typically standard input. The
20 .I queue_size
21 argument controls the maximum number of events that may be queued for
22 processing. The
23 .I q_flags
24 parameter selects in-memory or file-backed storage using the
25 .B AUPLUGIN_Q_*
26 constants defined in
27 .BR auplugin.h .
28 If
29 .I q_flags
30 includes
31 .B AUPLUGIN_Q_IN_FILE,
32 .I path
33 specifies the backing file. Any events already present in the file are queued
34 on startup so plugins resume processing previously unhandled records.
35 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.
36 .PP
37 .B auplugin_stop
38 signals the framework to terminate. It is normally called from a
39 SIGTERM handler or other shutdown logic.
40 .PP
41 .B auplugin_event_loop
42 starts a worker thread to deliver queued events to the supplied
43 .I callback
44 function one record at a time. The function blocks in the caller until
45 .B auplugin_stop
46 is invoked.
47 .PP
48 .B auplugin_event_feed
49 behaves like
50 .BR auplugin_event_loop ,
51 except that queued events are fed to libauparse. The provided
52 .I callback
53 must match the
54 .B auparse_callback_ptr
55 type. The
56 .I timer_interval
57 argument specifies how many seconds the worker thread will wait for new
58 records. A value of 0 disables the timer logic. When the interval elapses,
59 .B auparse_feed_age_events
60 is called to flush aged events. If
61 .I timer_cb
62 is not
63 .B NULL,
64 it is invoked with the interval before the flush. Passing a
65 .I timer_cb
66 of
67 .B NULL
68 keeps the default behaviour of calling
69 .B auparse_feed_age_events
70 only. The function returns 0 on success or \-1 if
71 libauparse could not be initialized.
72 .PP
73 Plugins can query queue statistics with
74 .BR auplugin_queue_depth ,
75 .BR auplugin_queue_max_depth ,
76 and
77 .BR auplugin_queue_overflow .
78 Register a callback with
79 .BR auplugin_register_stats_callback ,
80 and invoke it using
81 .BR auplugin_report_stats .
82 .SH SIGNAL HANDLING
83 Plugins should establish signal handlers with sigaction(2) 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.
84 .PP
85 Example:
86 .nf
87 static volatile sig_atomic_t reload;
88 static void handler(int sig)
89 {
90 if (sig == SIGTERM)
91 auplugin_stop();
92 else if (sig == SIGHUP)
93 reload = 1;
94 }
95 .fi
96 .PP
97 .SH SEE ALSO
98 .BR auplugin_fgets (3),
99 .BR auparse_feed (3)
100 .SH AUTHOR
101 Steve Grubb