contrib/openbsm/libbsm/au_event.3

   1 .\"-
   2 .\" Copyright (c) 2005-2006 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_event.3#8 $
  27 .\"
  28 .Dd April 19, 2005
  29 .Dt AU_EVENT 3
  30 .Os
  31 .Sh NAME
  32 .Nm free_au_event_ent ,
  33 .Nm setauevent ,
  34 .Nm endauevent ,
  35 .Nm getauevent ,
  36 .Nm getauevent_r ,
  37 .Nm getauevnam ,
  38 .Nm getauevnam_r ,
  39 .Nm getauevnum ,
  40 .Nm getauevnum_r ,
  41 .Nm getauevnonam ,
  42 .Nm getauevnonam_r
  43 .Nd "look up information from the audit_event database"
  44 .Sh LIBRARY
  45 .Lb libbsm
  46 .Sh SYNOPSIS
  47 .In bsm/libbsm.h
  48 .Ft void
  49 .Fn setauevent void
  50 .Ft void
  51 .Fn endauevent void
  52 .Ft "struct au_event_ent *"
  53 .Fn getauevent void
  54 .Ft "struct au_event_ent *"
  55 .Fn getauevent_r "struct au_event_ent *e"
  56 .Ft "struct au_event_ent *"
  57 .Fn getauevnam "const char *name"
  58 .Ft "struct au_event_ent *"
  59 .Fn getauevnam_r "struct au_event_ent *e" "const char *name"
  60 .Ft "struct au_event_ent *"
  61 .Fn getauevnum "au_event_t event_number"
  62 .Ft "struct au_event_ent *"
  63 .Fn getauevnum_r "struct au_event_ent *e" "au_event_t event_number"
  64 .Ft "au_event_t *"
  65 .Fn getauevnonam "const char *event_name"
  66 .Ft "au_event_t *"
  67 .Fn getauevnonam_r "au_event_t *ev" "const char *event_name"
  68 .Sh DESCRIPTION
  69 These interfaces may be used to look up information from the
  70 .Xr audit_event 5
  71 database, which describes audit events.
  72 Entries in the database are described by
  73 .Vt "struct au_event_ent"
  74 entries, which are returned by calls to
  75 .Fn getauevent ,
  76 .Fn getauevnam ,
  77 or
  78 .Fn getauevnum .
  79 It is also possible to look up an event number via a call to
  80 .Fn getauevnonam .
  81 .Pp
  82 The
  83 .Fn setauevent
  84 function
  85 resets the database access session for
  86 .Xr audit_event 5 ,
  87 so that the next call to
  88 .Fn getauevent
  89 will start with the first entry in the database.
  90 .Pp
  91 The
  92 .Fn endauevent
  93 function
  94 closes the
  95 .Xr audit_event 5
  96 database session.
  97 .Pp
  98 The
  99 .Fn getauevent
 100 function
 101 returns a reference to the next entry in the
 102 .Xr audit_event 5
 103 database.
 104 .Pp
 105 The
 106 .Fn getauevnam
 107 function
 108 returns a reference to the entry in the
 109 .Xr audit_event 5
 110 database with a name of
 111 .Fa name .
 112 .Pp
 113 .Fn getauevnum
 114 returns a reference to the entry in the
 115 .Xr audit_event 5
 116 database with an event number of
 117 .Fa event_number .
 118 .Pp
 119 The
 120 .Fn getauevnonam
 121 function
 122 returns a reference to an audit event number using the
 123 .Xr audit_event 5
 124 database.
 125 .Sh RETURN VALUES
 126 Functions
 127 .Fn getauevent ,
 128 .Fn getauevent_r ,
 129 .Fn getauevnam ,
 130 .Fn getauevnam_r ,
 131 .Fn getauevnum ,
 132 .Fn getauevnum_r ,
 133 and
 134 .Fn getauevnonam
 135 will return a reference to a
 136 .Vt "struct au_event_ent"
 137 or
 138 .Vt au_event_t
 139 on success, or
 140 .Dv NULL
 141 on failure, with
 142 .Va errno
 143 set to provide further error information.
 144 .Sh SEE ALSO
 145 .Xr libbsm 3 ,
 146 .Xr audit_event 5
 147 .Sh HISTORY
 148 The OpenBSM implementation was created by McAfee Research, the security
 149 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 150 It was subsequently adopted by the TrustedBSD Project as the foundation for
 151 the OpenBSM distribution.
 152 .Sh AUTHORS
 153 .An -nosplit
 154 This software was created by
 155 .An Robert Watson ,
 156 .An Wayne Salamon ,
 157 and
 158 .An Suresh Krishnaswamy
 159 for McAfee Research, the security research division of McAfee,
 160 Inc., under contract to Apple Computer, Inc.
 161 .Pp
 162 The Basic Security Module (BSM) interface to audit records and audit event
 163 stream format were defined by Sun Microsystems.
 164 .Sh BUGS
 165 The
 166 .Va errno
 167 variable
 168 is not always properly set following a failure.
 169 .Pp
 170 These routines are thread-safe, but not re-entrant, so simultaneous or
 171 interleaved use of these functions will affect the iterator.