opensolaris man page for au_preselect

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

NAME
       au_preselect - preselect an audit event

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

       int au_preselect(au_event_t event, au_mask_t *mask_p, int sorf, int flag);

DESCRIPTION
       The  au_preselect()  function  determines  whether the audit event event is preselected	against the binary preselection mask pointed to by
       mask_p (usually obtained by a  call  to	getaudit(2)).  The  au_preselect()  function  looks  up  the  classes  associated  with  event	in
       audit_event(4)  and  compares them with the classes in mask_p. If the classes associated with event match the classes in the specified por-
       tions of the binary preselection mask  pointed to by mask_p, the event is said to be preselected.

       The sorf argument indicates whether the comparison is made with the success portion, the failure portion, or  both  portions  of  the  mask
       pointed to by mask_p.

       The following are the valid values of sorf:

       AU_PRS_SUCCESS	 Compare the event class with the success portion of the preselection mask.

       AU_PRS_FAILURE	 Compare the event class with the failure portion of the preselection mask.

       AU_PRS_BOTH	 Compare the event class with both the success and failure portions of the  preselection mask.

       The  flag  argument  tells  au_preselect()  how	to  read  the  audit_event(4)  database. Upon initial invocation, au_preselect() reads the
       audit_event(4) database and allocates space in an internal cache for each entry with malloc(3C). In subsequent invocations,  the  value	of
       flag determines where au_preselect() obtains audit event information. The following are the valid values of flag:

       AU_PRS_REREAD	  Get audit event information by searching the audit_event(4) database.

       AU_PRS_USECACHE	  Get audit event information from internal cache created upon the initial invocation. This option is much faster.

RETURN VALUES
       Upon  successful  completion,au_preselect() returns 0 if event is not preselected or 1 if event is preselected. If au_preselect() could not
       allocate memory or could not find  event in the audit_event(4) database, -1 is returned.

FILES
       /etc/security/audit_class    file mapping audit class number to audit class names and descriptions

       /etc/security/audit_event    file mappint audit even number to audit event names and associates

ATTRIBUTES
       See attributes(5) for a description of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Stable			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       bsmconv(1M), getaudit(2), au_open(3BSM), getauclassent(3BSM), getauevent(3BSM), malloc(3C), audit_class(4), audit_event(4), attributes(5)

NOTES
       The au_preselect() function is normally called prior to constructing and writing an audit record. If the  event	is  not  preselected,  the
       overhead of constructing and writing the  record can be saved.

       The  functionality  described  on  this	manual	page is available only if the Solaris Auditing has been enabled.  See bsmconv(1M) for more
       information.

SunOS 5.11							    31 Mar 2005 						au_preselect(3BSM)