usr/src/man/man3bsm/au_preselect.3bsm

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH AU_PRESELECT 3BSM "Mar 6, 2017"
   7 .SH NAME
   8 au_preselect \- preselect an audit event
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lbsm\fR \fB -lsocket \fR \fB -lnsl \fR  [ \fIlibrary\fR... ]
  13 #include <bsm/libbsm.h>
  14
  15 \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);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBau_preselect()\fR function determines whether the audit event
  21 \fIevent\fR is preselected  against the binary preselection mask pointed to by
  22 \fImask_p\fR (usually obtained by a call to \fBgetaudit\fR(2)). The
  23 \fBau_preselect()\fR function looks up the classes associated with \fIevent\fR
  24 in \fBaudit_event\fR(4) and compares them with the classes in \fImask_p\fR. If
  25 the classes associated with \fIevent\fR match the classes in the specified
  26 portions of the binary preselection mask  pointed to by \fImask_p\fR, the event
  27 is said to be preselected.
  28 .sp
  29 .LP
  30 The \fIsorf\fR argument indicates whether the comparison is made with the
  31 success portion, the failure portion, or both portions of the mask pointed to
  32 by \fImask_p\fR.
  33 .sp
  34 .LP
  35 The following are the valid values of \fIsorf\fR:
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fBAU_PRS_SUCCESS\fR\fR
  40 .ad
  41 .RS 18n
  42 Compare the event class with the success portion of the preselection mask.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fBAU_PRS_FAILURE\fR\fR
  49 .ad
  50 .RS 18n
  51 Compare the event class with the failure portion of the preselection mask.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBAU_PRS_BOTH\fR\fR
  58 .ad
  59 .RS 18n
  60 Compare the event class with both the success and failure portions of the
  61 preselection mask.
  62 .RE
  63
  64 .sp
  65 .LP
  66 The \fIflag\fR argument tells \fBau_preselect()\fR how to read the
  67 \fBaudit_event\fR(4) database. Upon initial invocation, \fBau_preselect()\fR
  68 reads the \fBaudit_event\fR(4) database and allocates space in an internal
  69 cache for each entry with \fBmalloc\fR(3C). In subsequent invocations, the
  70 value of \fIflag\fR determines where \fBau_preselect()\fR obtains audit event
  71 information. The following are the valid values of \fIflag\fR:
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBAU_PRS_REREAD\fR\fR
  76 .ad
  77 .RS 19n
  78 Get audit event information by searching the \fBaudit_event\fR(4) database.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBAU_PRS_USECACHE\fR\fR
  85 .ad
  86 .RS 19n
  87 Get audit event information from internal cache created upon the initial
  88 invocation. This option is much faster.
  89 .RE
  90
  91 .SH RETURN VALUES
  92 .LP
  93 Upon successful completion,\fBau_preselect()\fR returns 0 if \fIevent\fR is not
  94 preselected or 1 if \fIevent\fR is preselected. If \fBau_preselect()\fR could
  95 not allocate memory or could not find  \fIevent\fR in the \fBaudit_event\fR(4)
  96 database, \(mi1 is returned.
  97 .SH FILES
  98 .ne 2
  99 .na
 100 \fB\fB/etc/security/audit_class\fR\fR
 101 .ad
 102 .RS 29n
 103 file mapping audit class number to audit class names and descriptions
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fB/etc/security/audit_event\fR\fR
 110 .ad
 111 .RS 29n
 112 file mapping audit event number to audit event names, descriptions and
 113 associated audit classes
 114 .RE
 115
 116 .SH ATTRIBUTES
 117 .LP
 118 See \fBattributes\fR(5) for a description of the following attributes:
 119 .sp
 120
 121 .sp
 122 .TS
 123 box;
 124 c | c
 125 l | l .
 126 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 127 _
 128 Interface Stability     Stable
 129 _
 130 MT-Level        MT-Safe
 131 .TE
 132
 133 .SH SEE ALSO
 134 .LP
 135 \fBgetaudit\fR(2), \fBau_open\fR(3BSM),
 136 \fBgetauclassent\fR(3BSM), \fBgetauevent\fR(3BSM), \fBmalloc\fR(3C),
 137 \fBaudit_class\fR(4), \fBaudit_event\fR(4), \fBattributes\fR(5)
 138 .SH NOTES
 139 .LP
 140 The \fBau_preselect()\fR function is normally called prior to constructing and
 141 writing an audit record. If the event is not preselected, the overhead of
 142 constructing and writing the record can be saved.