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