usr/src/cmd/praudit/print_audit.txt

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 /*
  23  * Copyright 2002 Sun Microsystems, Inc.  All rights reserved.
  24  * Use is subject to license terms.
  25  */
  26
  27 #pragma ident   "%Z%%M% %I%     %E% SMI"
  28
  29 This describes some private interfaces currently provided by praudit.
  30 In the future these may be provided by libbsm instead.  Note that
  31 these interfaces are MT-Safe.
  32
  33
  34 NAME
  35      print_audit, print_audit_buf  -  format and print audit trail data
  36      print_audit_xml_prolog,
  37      print_audit_xml_ending,
  38      print_audit_xml_prolog_buf,
  39      print_audit_xml_ending_buf    - print audit XML prolog and ending
  40
  41 SYNOPSIS
  42      int print_audit(const int flags, const char *separator);
  43
  44      int print_audit_buf(char **in_buf, int *in_buf_len, char **out_buf,
  45         int *out_buf_len, const int flags, const char *separator);
  46
  47      void print_audit_xml_prolog(void);
  48      void print_audit_xml_ending(void);
  49      int print_audit_xml_prolog_buf(char *out_buf, const int out_buf_len);
  50      int print_audit_xml_ending_buf(char *out_buf, const int out_buf_len);
  51
  52 DESCRIPTION
  53      print_audit() formats binary audit data from stdin and prints in
  54      ASCII on stdout. print_audit_buf() formats binary audit data from
  55      in_buf and copies in ASCII to out_buf, terminating with a null
  56      byte.
  57
  58      print_audit_xml_prolog and print_audit_xml_prolog_buf will print
  59      only the audit XML prolog. The XML, prolog includes identification
  60      of the DTD which is used to parse the XML, and also identifies the
  61      stylesheet which is used to view the XML conveniently (for example
  62      in a browser which supports these features).
  63
  64      print_audit_xml_ending and print_audit_xml_ending_buf print only
  65      the XML ending which completes the audit XML.
  66
  67 PARAMETERS
  68      flags - specifies the types of formatting to be done:
  69
  70      PRF_DEFAULTM
  71            Default formatting.  By default, times, user  and  group  IDs
  72            (UIDs and GIDs, respectively) are converted to their ASCII
  73            representation. Record type and  event fields  are converted
  74            to their  ASCII representation. If any other flags are
  75            specified they will override this flag.
  76
  77      PRF_RAWM
  78            Print records in their raw form. Times,   UIDs,  GIDs,
  79            record  types,  and  events are displayed as integers.
  80            This value and PRF_SHORTM are exclusive. If  both
  81            are used, no processing is done and EINVAL is returned.
  82
  83      PRF_SHORTM
  84            Print records in their short form. All numeric  fields
  85            are  converted to ASCII and displayed. The short ASCII
  86            representations for the record type and  event  fields
  87            are   used.   This  value an PRF_RAWM are exclusive. If
  88            both are used, no processing is done and EINVAL is returned.
  89
  90      PRF_XMLM
  91            Print records in XML format. "tags" are included in the
  92            output to identify tokens and fields within tokens.
  93            Output will not include an XML prolog or ending which
  94            are required to from complete, valid XML. The various
  95            print XML prolog and ending functions described here
  96            must be used separately from print_audit and print_audit_buf
  97            to accomplish that.
  98
  99      PRF_ONELINE
 100            Prints one line per record. The record type and  event
 101            fields  are  always  converted  to  their  short ASCII
 102            representation as is done for the -s option.
 103
 104
 105      separator -
 106         if non-NULL, this is used as the field delimiter instead of the
 107         default delimiter, which is the comma.  The maximum size of a
 108         delimiter is three characters (not counting the required
 109         null-terminator).  Note that the delimiter is not meaningful
 110         and this parameter is ignored when flags specifies XML format.
 111
 112      in_buf, in_buf_len,
 113      out_buf, out_buf_len  -
 114         pointers to the start of input and output buffers and their lengths.
 115         See Return Values for details about how these are used.
 116
 117
 118 RETURN VALUES
 119      print_audit() and print_audit_buf() return:
 120      0     on success.
 121      -1    on failure and set errno to indicate the error:
 122
 123      EINVAL - invalid input flags, delimiter, or error parsing the
 124               binary audit data.
 125
 126      ENOSPC - output buffer too small.
 127
 128      EIO    - input exhausted before end of an audit record.
 129
 130      EPERM  - internal or other unexpected error.
 131
 132      Partial results may also be returned for these errors.
 133
 134
 135      The following parameters are always returned:
 136
 137      out_buf_len -
 138
 139      updated to reflect size of output successfully produced. If
 140      non-zero, this will include the single terminating null byte.
 141
 142
 143      Upon return of partial results, these parameters will also be
 144      updated to reflect status (up to the end of the last completed
 145      audit record from the input):
 146
 147      in_buf, in_buf_len -
 148
 149      updated to reflect amount of input successfully consumed.  in_buf
 150      will point to the next byte which has not been processed.
 151      in_buf_len will be set to the remaining size from this address to
 152      the end of the original buffer.
 153
 154
 155      print_audit_xml_prolog_buf and print_audit_xml_ending_buf return:
 156      0     on success.
 157      -1    on failure and set errno to indicate the error:
 158
 159      ENOSPC - output buffer too small.
 160
 161
 162 EXAMPLES
 163        The following code fragment takes audit input from stdin, and
 164        will print on stdout complete XML including a prolog:
 165
 166         print_audit_xml_prolog();
 167
 168         /*
 169          * Format audit data from stdin and print to stdout.
 170          */
 171         retstat = print_audit(PRF_XMLM | PRF_ONELINE, NULL);
 172
 173         if (retstat == 0)
 174                 print_audit_xml_ending();
 175
 176