contrib/openbsm/libbsm/au_control.3

   1 .\"-
   2 .\" Copyright (c) 2005 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_control.3#3 $
  27 .\"
  28 .Dd April 19, 2005
  29 .Dt AU_CONTROL 3
  30 .Os
  31 .Sh NAME
  32 .Nm setac ,
  33 .Nm endac ,
  34 .Nm getacdir ,
  35 .Nm getacmin ,
  36 .Nm getacflg ,
  37 .Nm getacna
  38 .Nd "Look up information from the audit_control database"
  39 .Sh LIBRARY
  40 .Lb libbsm
  41 .Sh SYNOPSIS
  42 .In libbsm.h
  43 .Ft void
  44 .Fn setac "void"
  45 .Ft void
  46 .Fn endac "void"
  47 .Ft int
  48 .Fn getacdir "char *name" "int len"
  49 .Ft int
  50 .Fn getacmin "int *min_val"
  51 .Ft int
  52 .Fn getacflg "char *auditstr" "int len"
  53 .Ft int
  54 .Fn getacna "char *auditstr" "int len"
  55 .Sh DESCRIPTION
  56 These interfaces may be used to look up information from the
  57 .Xr audit_control 5
  58 database, which contains various audit-related administrative parameters.
  59 .Pp
  60 .Fn setac
  61 resets the database iterator to the beginning of the database; see the
  62 BUGS section for more information.
  63 .Pp
  64 .Fn sendac
  65 closes the
  66 .Xr audit_control 5
  67 database.
  68 .Pp
  69 .Fn getacdir
  70 returns the name of the directory where log data is stored via the passed
  71 character buffer
  72 .Va name
  73 of length
  74 .Va len .
  75 .Pp
  76 .Fn getacmin
  77 returns the minimum free disk space for the audit log target file system via
  78 the passed
  79 .Va min_val
  80 variable.
  81 .Pp
  82 .Fn getacflg
  83 returns the audit system flags via the the passed character buffer
  84 .Va auditstr
  85 of length
  86 .Va len .
  87 .Pp
  88 .Fn getacna
  89 returns the non-attributable flags via the passed character buffer
  90 .Va auditstr
  91 of length
  92 .Va len .
  93 .Sh RETURN VALULES
  94 .Fn getacdir ,
  95 .Fn getacmin ,
  96 .Fn getacflg ,
  97 and
  98 .Fn getacna
  99 return 0 on success, or a negative value on failure, along with error
 100 information in
 101 .Va errno .
 102 Functions that return a string value will return a failure if there is
 103 insufficient room in the passed character buffer for the full string.
 104 .Sh SEE ALSO
 105 .Xr libbsm 3 ,
 106 .Xr audit_control 5
 107 .Sh AUTHORS
 108 This software was created by Robert Watson, Wayne Salamon, and Suresh
 109 Krishnaswamy for McAfee Research, the security research division of McAfee,
 110 Inc., under contract to Apple Computer, Inc.
 111 .Pp
 112 The Basic Security Module (BSM) interface to audit records and audit event
 113 stream format were defined by Sun Microsystems.
 114 .Sh HISTORY
 115 The OpenBSM implementation was created by McAfee Research, the security
 116 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 117 It was subsequently adopted by the TrustedBSD Project as the foundation for
 118 the OpenBSM distribution.
 119 .Sh BUGS
 120 These routines cannot currently distinguish between an entry not being found
 121 and an error accessing the database.
 122 The implementation should be changed to return an error via
 123 .Va errno
 124 when
 125 .Dv NULL
 126 is returned.
 127 .Sh BUGS
 128 There is no reason for the
 129 .Fn setac
 130 interface to be exposed as part of the public API, as it is called implicitly
 131 by other access functions and iteration is not supported.
 132 .Pp
 133 These interfaces inconsistently return various negative values depending on
 134 the failure mode, and do not always set
 135 .Va errno
 136 on failure.