1 files changed, 126 insertions, 0 deletions
diff --git a/contrib/openbsm/libbsm/audit_submit.3 b/contrib/openbsm/libbsm/audit_submit.3
new file mode 100644
index 0000000..9e4d230
--- /dev/null
+++ b/contrib/openbsm/libbsm/audit_submit.3
@@ -0,0 +1,126 @@
+.\"
+.\" Copyright (c) 2006 Christian S.J. Peron
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1.  Redistributions of source code must retain the above copyright
+.\"     notice, this list of conditions and the following disclaimer.
+.\" 2.  Redistributions in binary form must reproduce the above copyright
+.\"     notice, this list of conditions and the following disclaimer in the
+.\"     documentation and/or other materials provided with the distribution.
+.\" 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
+.\"     its contributors may be used to endorse or promote products derived
+.\"     from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $P4: //depot/projects/trustedbsd/openbsm/libbsm/audit_submit.3#8 $
+.\"
+.Dd May 29, 2006
+.Dt audit_submit 3
+.Os
+.Sh NAME
+.Nm audit_submit
+.Nd general purpose audit record submission
+.Sh LIBRARY
+.Lb libbsm
+.Sh SYNOPSIS
+.In stdio.h
+.Ft int
+.Fn audit_submit "short au_event" "au_id_t auid" "char status" "int reterr" "const char * restrict format" ...
+.Sh DESCRIPTION
+The
+.Nm
+function provides a generic programming interface for audit record submission.
+This audit record will contain a header, subject token, an optional text token,
+return token, and a trailer.
+The header will contain the event class specified by
+.Fa au_event .
+The subject token will be generated based on
+.Fa au_ctx .
+The return token is dependant on the
+.Fa status
+and
+.Fa reterr
+arguments.
+Optionally, a text token will be created as a part of this record.
+.Pp
+Text token output is under the control of a
+.Fa format
+string that specifies how subsequent arguments (or arguments accessed via the
+variable-length argument facilities of
+.Xr stdarg 3 )
+are converted for output.
+If
+.Fa format
+is NULL, then no text token is created in the audit record.
+.Pp
+It should be noted that
+.Nm
+assumes that
+.Xr setaudit 2 ,
+or
+.Xr setaudit_addr 2 
+has already been called.
+As a direct result, the terminal ID for the
+subject will be retrieved from the kernel via
+.Xr getaudit 2 ,
+or
+.Xr getaudit_addr 2 .
+.Sh EXAMPLES
+.Bd -literal -offset indent
+#include <bsm/audit.h>
+#include <bsm/libbsm.h>
+#include <bsm/audit_uevents.h>
+
+#include <stdio.h>
+#include <stdarg.h>
+#include <errno.h>
+
+int
+audit_bad_su(char *from_login, char *to_login)
+{
+	int error;
+
+	error = audit_submit(AUE_su, getuid(), 1, EPERM,
+	    "bad su from %s to %s", from_login, to_login);
+	return (error);
+}
+.Ed
+.Pp
+Will generate the following audit record:
+.Bd -literal -offset indent
+header,94,1,su(1),0,Mon Apr 17 23:23:59 2006, + 271 msec
+subject,root,root,wheel,root,wheel,652,652,0,0.0.0.0
+text,bad su from from csjp to root
+return,failure : Operation not permitted,1
+trailer,94
+.Ed
+.Sh SEE ALSO
+.Xr auditon 2 ,
+.Xr getaudit 2 ,
+.Xr libbsm 3 ,
+.Xr stdarg 3
+.Sh HISTORY
+The
+.Nm
+function first appeared in OpenBSM version 1.0.
+OpenBSM 1.0 was introduced in FreeBSD 7.0.
+.Sh AUTHORS
+The
+.Nm
+function was written by
+.An Christian S.J. Peron Aq csjp@FreeBSD.org .