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(5) 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(7) 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(5), audit_event(5),
passwd(5), attributes(7)

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)