contrib/openbsm/libbsm/au_io.3

   1 .\"-
   2 .\" Copyright (c) 2009 Apple, Inc.
   3 .\" Copyright (c) 2005 Robert N. M. Watson
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/au_io.3#9 $
  28 .\"
  29 .Dd August 4, 2009
  30 .Dt AU_IO 3
  31 .Os
  32 .Sh NAME
  33 .Nm au_fetch_tok ,
  34 .Nm au_print_tok ,
  35 .Nm au_print_flags_tok ,
  36 .Nm au_read_rec
  37 .Nd "perform I/O involving an audit record"
  38 .Sh LIBRARY
  39 .Lb libbsm
  40 .Sh SYNOPSIS
  41 .In bsm/libbsm.h
  42 .Ft int
  43 .Fn au_fetch_tok "tokenstr_t *tok" "u_char *buf" "int len"
  44 .Ft void
  45 .Fo au_print_tok
  46 .Fa "FILE *outfp" "tokenstr_t *tok" "char *del" "char raw" "char sfrm"
  47 .Fc
  48 .Ft void
  49 .Fo au_print_flags_tok
  50 .Fa "FILE *outfp" "tokenstr_t *tok" "char *del" "int oflags"
  51 .Fc
  52 .Ft int
  53 .Fn au_read_rec "FILE *fp" "u_char **buf"
  54 .Sh DESCRIPTION
  55 These interfaces support input and output (I/O) involving audit records,
  56 internalizing an audit record from a byte stream, converting a token to
  57 either a raw or default string, and reading a single record from a file.
  58 .Pp
  59 The
  60 .Fn au_fetch_tok
  61 function
  62 reads a token from the passed buffer
  63 .Fa buf
  64 of length
  65 .Fa len
  66 bytes, and returns a pointer to the token via
  67 .Fa tok .
  68 .Pp
  69 The
  70 .Fn au_print_tok
  71 function
  72 prints a string form of the token
  73 .Fa tok
  74 to the file output stream
  75 .Fa outfp ,
  76 either in default mode, or raw mode if
  77 .Fa raw
  78 is set non-zero.
  79 The delimiter
  80 .Fa del
  81 is used when printing.
  82 The
  83 .Fn au_print_flags_tok
  84 function is a replacement for
  85 .Fn au_print_tok .
  86 The
  87 .Fa oflags
  88 controls how the output should be formatted and is specified by
  89 or'ing the following flags:
  90 .Pp
  91 .Bl -tag -width AU_OFLAG_NORESOLVE -compact -offset indent
  92 .It Li AU_OFLAG_NONE
  93 Use the default form.
  94 .It Li AU_OFLAG_NORESOLVE
  95 Leave user and group IDs in their numeric form.
  96 .It Li AU_OFLAG_RAW
  97 Use the raw, numeric form.
  98 .It Li AU_OFLAG_SHORT
  99 Use the short form.
 100 .It Li AU_OFLAG_XML
 101 Use the XML form.
 102 .El
 103 .Pp
 104 The flags options AU_OFLAG_SHORT and AU_OFLAG_RAW are exclusive and
 105 should not be used together.
 106 .Pp
 107 The
 108 .Fn au_read_rec
 109 function
 110 reads an audit record from the file stream
 111 .Fa fp ,
 112 and returns an allocated memory buffer containing the record via
 113 .Fa *buf ,
 114 which must be freed by the caller using
 115 .Xr free 3 .
 116 .Pp
 117 A typical use of these routines might open a file with
 118 .Xr fopen 3 ,
 119 then read records from the file sequentially by calling
 120 .Fn au_read_rec .
 121 Each record would be broken down into components tokens through sequential
 122 calls to
 123 .Fn au_fetch_tok
 124 on the buffer, and then invoking
 125 .Fn au_print_flags_tok
 126 to print each token to an output stream such as
 127 .Dv stdout .
 128 On completion of the processing of each record, a call to
 129 .Xr free 3
 130 would be used to free the record buffer.
 131 Finally, the source stream would be closed by a call to
 132 .Xr fclose 3 .
 133 .Sh RETURN VALUES
 134 The
 135 .Fn au_fetch_tok
 136 and
 137 .Fn au_read_rec
 138 functions
 139 return 0 on success, or \-1 on failure along with additional error information
 140 returned via
 141 .Va errno .
 142 .Sh SEE ALSO
 143 .Xr free 3 ,
 144 .Xr libbsm 3
 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 .Pp
 151 The
 152 .Fn au_print_flags_tok
 153 function was added by Stacey Son as a replacement for the
 154 .Fn au_print_tok
 155 so new output formatting flags can be easily added without changing the API.
 156 The
 157 .Fn au_print_tok
 158 is obsolete but remains in the API to support legacy code.
 159 .Sh AUTHORS
 160 .An -nosplit
 161 This software was created by
 162 .An Robert Watson ,
 163 .An Wayne Salamon ,
 164 and
 165 .An Suresh Krishnaswamy
 166 for McAfee Research, the security research division of McAfee,
 167 Inc., under contract to Apple Computer, Inc.
 168 .Pp
 169 The Basic Security Module (BSM) interface to audit records and audit event
 170 stream format were defined by Sun Microsystems.
 171 .Sh BUGS
 172 The
 173 .Va errno
 174 variable
 175 may not always be properly set in the event of an error.