'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH AU_PRESELECT 3BSM "Mar 6, 2017"
.SH NAME
au_preselect \- preselect an audit event
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lbsm\fR \fB -lsocket \fR \fB -lnsl \fR  [ \fIlibrary\fR... ]
#include <bsm/libbsm.h>

\fBint\fR \fBau_preselect\fR(\fBau_event_t\fR \fIevent\fR, \fBau_mask_t *\fR\fImask_p\fR, \fBint\fR \fIsorf\fR, \fBint\fR \fIflag\fR);
.fi

.SH DESCRIPTION
.LP
The \fBau_preselect()\fR function determines whether the audit event
\fIevent\fR is preselected  against the binary preselection mask pointed to by
\fImask_p\fR (usually obtained by a call to \fBgetaudit\fR(2)). The
\fBau_preselect()\fR function looks up the classes associated with \fIevent\fR
in \fBaudit_event\fR(4) and compares them with the classes in \fImask_p\fR. If
the classes associated with \fIevent\fR match the classes in the specified
portions of the binary preselection mask  pointed to by \fImask_p\fR, the event
is said to be preselected.
.sp
.LP
The \fIsorf\fR argument indicates whether the comparison is made with the
success portion, the failure portion, or both portions of the mask pointed to
by \fImask_p\fR.
.sp
.LP
The following are the valid values of \fIsorf\fR:
.sp
.ne 2
.na
\fB\fBAU_PRS_SUCCESS\fR\fR
.ad
.RS 18n
Compare the event class with the success portion of the preselection mask.
.RE

.sp
.ne 2
.na
\fB\fBAU_PRS_FAILURE\fR\fR
.ad
.RS 18n
Compare the event class with the failure portion of the preselection mask.
.RE

.sp
.ne 2
.na
\fB\fBAU_PRS_BOTH\fR\fR
.ad
.RS 18n
Compare the event class with both the success and failure portions of the
preselection mask.
.RE

.sp
.LP
The \fIflag\fR argument tells \fBau_preselect()\fR how to read the
\fBaudit_event\fR(4) database. Upon initial invocation, \fBau_preselect()\fR
reads the \fBaudit_event\fR(4) database and allocates space in an internal
cache for each entry with \fBmalloc\fR(3C). In subsequent invocations, the
value of \fIflag\fR determines where \fBau_preselect()\fR obtains audit event
information. The following are the valid values of \fIflag\fR:
.sp
.ne 2
.na
\fB\fBAU_PRS_REREAD\fR\fR
.ad
.RS 19n
Get audit event information by searching the \fBaudit_event\fR(4) database.
.RE

.sp
.ne 2
.na
\fB\fBAU_PRS_USECACHE\fR\fR
.ad
.RS 19n
Get audit event information from internal cache created upon the initial
invocation. This option is much faster.
.RE

.SH RETURN VALUES
.LP
Upon successful completion,\fBau_preselect()\fR returns 0 if \fIevent\fR is not
preselected or 1 if \fIevent\fR is preselected. If \fBau_preselect()\fR could
not allocate memory or could not find  \fIevent\fR in the \fBaudit_event\fR(4)
database, \(mi1 is returned.
.SH FILES
.ne 2
.na
\fB\fB/etc/security/audit_class\fR\fR
.ad
.RS 29n
file mapping audit class number to audit class names and descriptions
.RE

.sp
.ne 2
.na
\fB\fB/etc/security/audit_event\fR\fR
.ad
.RS 29n
file mapping audit event number to audit event names, descriptions and
associated audit classes
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.LP
\fBgetaudit\fR(2), \fBau_open\fR(3BSM),
\fBgetauclassent\fR(3BSM), \fBgetauevent\fR(3BSM), \fBmalloc\fR(3C),
\fBaudit_class\fR(4), \fBaudit_event\fR(4), \fBattributes\fR(5)
.SH NOTES
.LP
The \fBau_preselect()\fR 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.