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