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 .Dd August 4, 2009
  28 .Dt AU_IO 3
  29 .Os
  30 .Sh NAME
  31 .Nm au_fetch_tok ,
  32 .Nm au_print_tok ,
  33 .Nm au_print_flags_tok ,
  34 .Nm au_read_rec
  35 .Nd "perform I/O involving an audit record"
  36 .Sh LIBRARY
  37 .Lb libbsm
  38 .Sh SYNOPSIS
  39 .In bsm/libbsm.h
  40 .Ft int
  41 .Fn au_fetch_tok "tokenstr_t *tok" "u_char *buf" "int len"
  42 .Ft void
  43 .Fo au_print_tok
  44 .Fa "FILE *outfp" "tokenstr_t *tok" "char *del" "char raw" "char sfrm"
  45 .Fc
  46 .Ft void
  47 .Fo au_print_flags_tok
  48 .Fa "FILE *outfp" "tokenstr_t *tok" "char *del" "int oflags"
  49 .Fc
  50 .Ft int
  51 .Fn au_read_rec "FILE *fp" "u_char **buf"
  52 .Sh DESCRIPTION
  53 These interfaces support input and output (I/O) involving audit records,
  54 internalizing an audit record from a byte stream, converting a token to
  55 either a raw or default string, and reading a single record from a file.
  56 .Pp
  57 The
  58 .Fn au_fetch_tok
  59 function
  60 reads a token from the passed buffer
  61 .Fa buf
  62 of length
  63 .Fa len
  64 bytes, and returns a pointer to the token via
  65 .Fa tok .
  66 .Pp
  67 The
  68 .Fn au_print_tok
  69 function
  70 prints a string form of the token
  71 .Fa tok
  72 to the file output stream
  73 .Fa outfp ,
  74 either in default mode, or raw mode if
  75 .Fa raw
  76 is set non-zero.
  77 The delimiter
  78 .Fa del
  79 is used when printing.
  80 The
  81 .Fn au_print_flags_tok
  82 function is a replacement for
  83 .Fn au_print_tok .
  84 The
  85 .Fa oflags
  86 controls how the output should be formatted and is specified by
  87 or'ing the following flags:
  88 .Pp
  89 .Bl -tag -width AU_OFLAG_NORESOLVE -compact -offset indent
  90 .It Li AU_OFLAG_NONE
  91 Use the default form.
  92 .It Li AU_OFLAG_NORESOLVE
  93 Leave user and group IDs in their numeric form.
  94 .It Li AU_OFLAG_RAW
  95 Use the raw, numeric form.
  96 .It Li AU_OFLAG_SHORT
  97 Use the short form.
  98 .It Li AU_OFLAG_XML
  99 Use the XML form.
 100 .El
 101 .Pp
 102 The flags options AU_OFLAG_SHORT and AU_OFLAG_RAW are exclusive and
 103 should not be used together.
 104 .Pp
 105 The
 106 .Fn au_read_rec
 107 function
 108 reads an audit record from the file stream
 109 .Fa fp ,
 110 and returns an allocated memory buffer containing the record via
 111 .Fa *buf ,
 112 which must be freed by the caller using
 113 .Xr free 3 .
 114 .Pp
 115 A typical use of these routines might open a file with
 116 .Xr fopen 3 ,
 117 then read records from the file sequentially by calling
 118 .Fn au_read_rec .
 119 Each record would be broken down into components tokens through sequential
 120 calls to
 121 .Fn au_fetch_tok
 122 on the buffer, and then invoking
 123 .Fn au_print_flags_tok
 124 to print each token to an output stream such as
 125 .Dv stdout .
 126 On completion of the processing of each record, a call to
 127 .Xr free 3
 128 would be used to free the record buffer.
 129 Finally, the source stream would be closed by a call to
 130 .Xr fclose 3 .
 131 .Sh RETURN VALUES
 132 The
 133 .Fn au_fetch_tok
 134 and
 135 .Fn au_read_rec
 136 functions
 137 return 0 on success, or \-1 on failure along with additional error information
 138 returned via
 139 .Va errno .
 140 .Sh SEE ALSO
 141 .Xr free 3 ,
 142 .Xr libbsm 3
 143 .Sh HISTORY
 144 The OpenBSM implementation was created by McAfee Research, the security
 145 division of McAfee Inc., under contract to Apple Computer, Inc., in 2004.
 146 It was subsequently adopted by the TrustedBSD Project as the foundation for
 147 the OpenBSM distribution.
 148 .Pp
 149 The
 150 .Fn au_print_flags_tok
 151 function was added by Stacey Son as a replacement for the
 152 .Fn au_print_tok
 153 so new output formatting flags can be easily added without changing the API.
 154 The
 155 .Fn au_print_tok
 156 is obsolete but remains in the API to support legacy code.
 157 .Sh AUTHORS
 158 .An -nosplit
 159 This software was created by
 160 .An Robert Watson ,
 161 .An Wayne Salamon ,
 162 and
 163 .An Suresh Krishnaswamy
 164 for McAfee Research, the security research division of McAfee,
 165 Inc., under contract to Apple Computer, Inc.
 166 .Pp
 167 The Basic Security Module (BSM) interface to audit records and audit event
 168 stream format were defined by Sun Microsystems.
 169 .Sh BUGS
 170 The
 171 .Va errno
 172 variable
 173 may not always be properly set in the event of an error.