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 .Dd April 19, 2005
  27 .Dt AU_EVENT 3
  28 .Os
  29 .Sh NAME
  30 .Nm free_au_event_ent ,
  31 .Nm setauevent ,
  32 .Nm endauevent ,
  33 .Nm getauevent ,
  34 .Nm getauevent_r ,
  35 .Nm getauevnam ,
  36 .Nm getauevnam_r ,
  37 .Nm getauevnum ,
  38 .Nm getauevnum_r ,
  39 .Nm getauevnonam ,
  40 .Nm getauevnonam_r
  41 .Nd "look up information from the audit_event database"
  42 .Sh LIBRARY
  43 .Lb libbsm
  44 .Sh SYNOPSIS
  45 .In bsm/libbsm.h
  46 .Ft void
  47 .Fn setauevent void
  48 .Ft void
  49 .Fn endauevent void
  50 .Ft "struct au_event_ent *"
  51 .Fn getauevent void
  52 .Ft "struct au_event_ent *"
  53 .Fn getauevent_r "struct au_event_ent *e"
  54 .Ft "struct au_event_ent *"
  55 .Fn getauevnam "const char *name"
  56 .Ft "struct au_event_ent *"
  57 .Fn getauevnam_r "struct au_event_ent *e" "const char *name"
  58 .Ft "struct au_event_ent *"
  59 .Fn getauevnum "au_event_t event_number"
  60 .Ft "struct au_event_ent *"
  61 .Fn getauevnum_r "struct au_event_ent *e" "au_event_t event_number"
  62 .Ft "au_event_t *"
  63 .Fn getauevnonam "const char *event_name"
  64 .Ft "au_event_t *"
  65 .Fn getauevnonam_r "au_event_t *ev" "const char *event_name"
  66 .Sh DESCRIPTION
  67 These interfaces may be used to look up information from the
  68 .Xr audit_event 5
  69 database, which describes audit events.
  70 Entries in the database are described by
  71 .Vt "struct au_event_ent"
  72 entries, which are returned by calls to
  73 .Fn getauevent ,
  74 .Fn getauevnam ,
  75 or
  76 .Fn getauevnum .
  77 It is also possible to look up an event number via a call to
  78 .Fn getauevnonam .
  79 .Pp
  80 The
  81 .Fn setauevent
  82 function
  83 resets the database access session for
  84 .Xr audit_event 5 ,
  85 so that the next call to
  86 .Fn getauevent
  87 will start with the first entry in the database.
  88 .Pp
  89 The
  90 .Fn endauevent
  91 function
  92 closes the
  93 .Xr audit_event 5
  94 database session.
  95 .Pp
  96 The
  97 .Fn getauevent
  98 function
  99 returns a reference to the next entry in the
 100 .Xr audit_event 5
 101 database.
 102 .Pp
 103 The
 104 .Fn getauevnam
 105 function
 106 returns a reference to the entry in the
 107 .Xr audit_event 5
 108 database with a name of
 109 .Fa name .
 110 .Pp
 111 .Fn getauevnum
 112 returns a reference to the entry in the
 113 .Xr audit_event 5
 114 database with an event number of
 115 .Fa event_number .
 116 .Pp
 117 The
 118 .Fn getauevnonam
 119 function
 120 returns a reference to an audit event number using the
 121 .Xr audit_event 5
 122 database.
 123 .Sh RETURN VALUES
 124 Functions
 125 .Fn getauevent ,
 126 .Fn getauevent_r ,
 127 .Fn getauevnam ,
 128 .Fn getauevnam_r ,
 129 .Fn getauevnum ,
 130 .Fn getauevnum_r ,
 131 and
 132 .Fn getauevnonam
 133 will return a reference to a
 134 .Vt "struct au_event_ent"
 135 or
 136 .Vt au_event_t
 137 on success, or
 138 .Dv NULL
 139 on failure, with
 140 .Va errno
 141 set to provide further error information.
 142 .Sh SEE ALSO
 143 .Xr libbsm 3 ,
 144 .Xr audit_event 5
 145 .Sh HISTORY
 146 The OpenBSM implementation was created by McAfee Research, the security
 147 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 148 It was subsequently adopted by the TrustedBSD Project as the foundation for
 149 the OpenBSM distribution.
 150 .Sh AUTHORS
 151 .An -nosplit
 152 This software was created by
 153 .An Robert Watson ,
 154 .An Wayne Salamon ,
 155 and
 156 .An Suresh Krishnaswamy
 157 for McAfee Research, the security research division of McAfee,
 158 Inc., under contract to Apple Computer, Inc.
 159 .Pp
 160 The Basic Security Module (BSM) interface to audit records and audit event
 161 stream format were defined by Sun Microsystems.
 162 .Sh BUGS
 163 The
 164 .Va errno
 165 variable
 166 is not always properly set following a failure.
 167 .Pp
 168 These routines are thread-safe, but not re-entrant, so simultaneous or
 169 interleaved use of these functions will affect the iterator.