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.

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.