GETAUEVENT(3BSM) Security and Auditing Library Functions GETAUEVENT(3BSM)


NAME


getauevent, getauevnam, getauevnum, getauevnonam, setauevent, endauevent,
getauevent_r, getauevnam_r, getauevnum_r - get audit_event entry

SYNOPSIS


cc [ flag... ] file... -lbsm -lsocket -lnsl [ library... ]
#include <sys/param.h>
#include <bsm/libbsm.h>

struct au_event_ent *getauevent(void);


struct au_event_ent *getauevnam(char *name);


struct au_event_ent *getauevnum(au_event_t event_number);


au_event_t getauevnonam(char *event_name);


void setauevent(void);


void endauevent(void);


struct au_event_ent *getauevent_r(au_event_ent_t *e);


struct au_event_ent *getauevnam_r(au_event_ent_t *e, char *name);


struct au_event_ent *getauevnum_r(au_event_ent_t *e,
au_event_t event_number);


DESCRIPTION


These functions document the programming interface for obtaining entries
from the audit_event(4) file. The getauevent(), getauevnam(),
getauevnum(), getauevent(), getauevnam(), and getauevnum() functions each
return a pointer to an audit_event structure.


The getauevent() and getauevent_r() functions enumerate audit_event
entries. Successive calls to these functions return either successive
audit_event entries or NULL.


The getauevnam() and getauevnam_r() functions search for an audit_event
entry with event_name.


The getauevnum() and getauevnum_r() functions search for an audit_event
entry with event_number.


The getauevnonam() function searches for an audit_event entry with
event_name and returns the corresponding event number.


The setauevent() function ``rewinds'' to the beginning of the enumeration
of audit_event entries. Calls to getauevnam(), getauevnum(),
getauevnonum(), getauevnam_r(), or getauevnum_r() can leave the
enumeration in an indeterminate state. The setauevent() function should
be called before the first call to getauevent() or getauevent_r().


The endauevent() function can be called to indicate that audit_event
processing is complete. The system can then close any open audit_event
file, deallocate storage, and so forth.


The getauevent_r(), getauevnam_r(), and getauevnum_r() functions each
take an argument e, which is a pointer to an au_event_ent_t. This pointer
is returned on a successful function call. To assure there is enough
space for the information returned, the applications programmer should be
sure to allocate AU_EVENT_NAME_MAX and AU_EVENT_DESC_MAX bytes for the
ae_name and ac_desc elements of the au_event_ent_t data structure.


The internal representation of an audit_event entry is an au_event_ent
structure defined in <bsm/libbsm.h> with the following members:

au_event_t ae_number
char *ae_name;
char *ae_desc*;
au_class_t ae_class;


RETURN VALUES


The getauevent(), getauevnam(), getauevnum(), getauevent_r(),
getauevnam_r(), and getauevnum_r() functions return a pointer to a
au_event_ent structure if the requested entry is successfully located.
Otherwise they return NULL.


The getauevnonam() function returns an event number of type au_event_t if
it successfully enumerates an entry. Otherwise it returns NULL,
indicating it could not find the requested event name.

FILES


/etc/security/audit_event
file that maps audit event numbers to audit
event names


/etc/passwd
file that stores user-ID to username
mappings


ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+---------------+-------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-------------------------+
|MT-Level | MT-Safe with exceptions |
+---------------+-------------------------+


The getauevent(), getauevnam(), and getauevnum() functions are Unsafe.
The equivalent functions getauevent_r(), getauevnam_r(), and
getauevnum_r() provide the same functionality and an MT-Safe function
call interface.

SEE ALSO


getauclassent(3BSM), getpwnam(3C), audit_class(4), audit_event(4),
passwd(4), attributes(5)

NOTES


All information for the getauevent(), getauevnam(), and getauevnum()
functions is contained in a static area, so it must be copied if it is to
be saved.


March 6, 2017 GETAUEVENT(3BSM)