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

   1 '\" te
   2 .\" Copyright (c) 2008, 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 GETAUEVENT 3BSM "Mar 6, 2017"
   7 .SH NAME
   8 getauevent, getauevnam, getauevnum, getauevnonam, setauevent, endauevent,
   9 getauevent_r, getauevnam_r, getauevnum_r \- get audit_event entry
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lbsm\fR \fB -lsocket \fR \fB -lnsl \fR  [ \fIlibrary\fR... ]
  14 #include <sys/param.h>
  15 #include <bsm/libbsm.h>
  16
  17 \fBstruct au_event_ent *\fR\fBgetauevent\fR(\fBvoid\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBstruct au_event_ent *\fR\fBgetauevnam\fR(\fBchar *\fR\fIname\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBstruct au_event_ent *\fR\fBgetauevnum\fR(\fBau_event_t\fR \fIevent_number\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBau_event_t\fR \fBgetauevnonam\fR(\fBchar *\fR\fIevent_name\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBvoid\fR \fBsetauevent\fR(\fBvoid\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBvoid\fR \fBendauevent\fR(\fBvoid\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBstruct au_event_ent *\fR\fBgetauevent_r\fR(\fBau_event_ent_t *\fR\fIe\fR);
  48 .fi
  49
  50 .LP
  51 .nf
  52 \fBstruct au_event_ent *\fR\fBgetauevnam_r\fR(\fBau_event_ent_t *\fR\fIe\fR, \fBchar *\fR\fIname\fR);
  53 .fi
  54
  55 .LP
  56 .nf
  57 \fBstruct au_event_ent *\fR\fBgetauevnum_r\fR(\fBau_event_ent_t *\fR\fIe\fR,
  58      \fBau_event_t\fR \fIevent_number\fR);
  59 .fi
  60
  61 .SH DESCRIPTION
  62 .LP
  63 These functions document the programming interface for obtaining entries from
  64 the \fBaudit_event\fR(4) file. The \fBgetauevent()\fR, \fBgetauevnam()\fR,
  65 \fBgetauevnum()\fR, \fBgetauevent()\fR, \fBgetauevnam()\fR, and
  66 \fBgetauevnum()\fR functions each return a pointer to an \fBaudit_event\fR
  67 structure.
  68 .sp
  69 .LP
  70 The \fBgetauevent()\fR and \fBgetauevent_r()\fR functions enumerate
  71 \fBaudit_event\fR entries. Successive calls to these functions return either
  72 successive \fBaudit_event\fR entries or \fINULL\fR.
  73 .sp
  74 .LP
  75 The \fBgetauevnam()\fR and \fBgetauevnam_r()\fR functions search for an
  76 \fBaudit_event\fR entry with \fIevent_name\fR.
  77 .sp
  78 .LP
  79 The \fBgetauevnum()\fR and \fBgetauevnum_r()\fR functions search for an
  80 \fBaudit_event\fR entry with \fIevent_number\fR.
  81 .sp
  82 .LP
  83 The \fBgetauevnonam()\fR function searches for an \fBaudit_event\fR entry with
  84 \fIevent_name\fR and returns the corresponding event number.
  85 .sp
  86 .LP
  87 The \fBsetauevent()\fR function ``rewinds'' to the beginning of the enumeration
  88 of  \fBaudit_event\fR entries.  Calls to \fBgetauevnam()\fR,
  89 \fBgetauevnum()\fR, \fBgetauevnonum()\fR, \fBgetauevnam_r()\fR, or
  90 \fBgetauevnum_r()\fR can leave the enumeration in an indeterminate state. The
  91 \fBsetauevent()\fR function should be called before the first call to
  92 \fBgetauevent()\fR or \fBgetauevent_r()\fR.
  93 .sp
  94 .LP
  95 The \fBendauevent()\fR function can be called to indicate that
  96 \fBaudit_event\fR processing is complete. The system can then close any open
  97 \fBaudit_event\fR file, deallocate storage, and so forth.
  98 .sp
  99 .LP
 100 The \fBgetauevent_r()\fR, \fBgetauevnam_r()\fR, and \fBgetauevnum_r()\fR
 101 functions each take an argument \fIe\fR, which is a pointer to an
 102 \fBau_event_ent_t\fR. This pointer is returned on a successful function call.
 103 To assure there is enough space for the information returned, the applications
 104 programmer should be sure to allocate \fBAU_EVENT_NAME_MAX\fR and
 105 \fBAU_EVENT_DESC_MAX\fR bytes for the \fBae_name\fR and \fBac_desc\fR elements
 106 of the \fBau_event_ent_t\fR data structure.
 107 .sp
 108 .LP
 109 The internal representation of an \fBaudit_event\fR entry is an
 110 \fBau_event_ent\fR structure defined in <\fBbsm/libbsm.h\fR> with the following
 111 members:
 112 .sp
 113 .in +2
 114 .nf
 115 au_event_t      ae_number
 116 char            *ae_name;
 117 char            *ae_desc*;
 118 au_class_t      ae_class;
 119 .fi
 120 .in -2
 121
 122 .SH RETURN VALUES
 123 .LP
 124 The \fBgetauevent()\fR, \fBgetauevnam()\fR, \fBgetauevnum()\fR,
 125 \fBgetauevent_r()\fR, \fBgetauevnam_r()\fR, and \fBgetauevnum_r()\fR functions
 126 return a pointer to a \fBau_event_ent\fR structure if the requested entry is
 127 successfully located. Otherwise they return \fINULL\fR.
 128 .sp
 129 .LP
 130 The \fBgetauevnonam()\fR function returns an event number of type
 131 \fBau_event_t\fR if it successfully enumerates an entry. Otherwise it returns
 132 \fINULL\fR, indicating it could not find the requested event name.
 133 .SH FILES
 134 .ne 2
 135 .na
 136 \fB\fB/etc/security/audit_event\fR\fR
 137 .ad
 138 .RS 29n
 139 file that maps audit event numbers to audit event names
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fB/etc/passwd\fR\fR
 146 .ad
 147 .RS 29n
 148 file that stores user-ID to username mappings
 149 .RE
 150
 151 .SH ATTRIBUTES
 152 .LP
 153 See \fBattributes\fR(5) for descriptions of the following attributes:
 154 .sp
 155
 156 .sp
 157 .TS
 158 box;
 159 c | c
 160 l | l .
 161 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 162 _
 163 MT-Level        MT-Safe with exceptions
 164 .TE
 165
 166 .sp
 167 .LP
 168 The \fBgetauevent()\fR,  \fBgetauevnam()\fR, and \fBgetauevnum()\fR functions
 169 are Unsafe. The equivalent functions \fBgetauevent_r()\fR,
 170 \fBgetauevnam_r()\fR, and \fBgetauevnum_r()\fR provide the same functionality
 171 and an MT-Safe function call interface.
 172 .SH SEE ALSO
 173 .LP
 174 \fBgetauclassent\fR(3BSM), \fBgetpwnam\fR(3C),
 175 \fBaudit_class\fR(4), \fBaudit_event\fR(4), \fBpasswd\fR(4),
 176 \fBattributes\fR(5)
 177 .SH NOTES
 178 .LP
 179 All information for the \fBgetauevent()\fR, \fBgetauevnam()\fR, and
 180 \fBgetauevnum()\fR functions is contained in a static area, so it must be
 181 copied if it is to be saved.