X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/2d21ac55c334faf3a56e5634905ed6987fc787d4..13f56ec4e58bf8687e2a68032c093c0213dd519b:/bsd/man/man2/getaudit.2

diff --git a/bsd/man/man2/getaudit.2 b/bsd/man/man2/getaudit.2
index 4b40f6d32..d2895cd33 100644
--- a/bsd/man/man2/getaudit.2
+++ b/bsd/man/man2/getaudit.2
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2007 Apple Inc. All rights reserved.
+.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
 .\"
 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 .\" 
@@ -25,37 +25,169 @@
 .\" 
 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 .\"
-.Dd July 30, 2007
+.Dd March 6, 2009
 .Dt GETAUDIT 2
-.Os Darwin
+.Os
 .Sh NAME
-.Nm getaudit
-.Nd get the audit information for the current process  
+.Nm getaudit ,
+.Nm getaudit_addr
+.Nd "retrieve audit session state"
 .Sh SYNOPSIS
-.Fd #include <bsm/audit.h>
+.In bsm/audit.h
 .Ft int
-.Fn getaudit "struct auditinfo * auditinfo"
+.Fn getaudit "auditinfo_t *auditinfo"
+.Ft int
+.Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
 .Sh DESCRIPTION
 The
 .Fn getaudit
-function returns a 
-.Fa struct auditinfo 
-describing the current user audit settings for the calling process. The
-information is returned in the struct pointed at by
+system call
+retrieves the active audit session state for the current process via the
+.Vt auditinfo_t
+pointed to by
 .Fa auditinfo .
+The
+.Fn getaudit_addr
+system call
+retrieves extended state via
+.Fa auditinfo_addr
+and
+.Fa length .
+.Pp
+The
+.Fa auditinfo_t
+data structure is defined as follows:
+.nf
+.in +4n
+struct auditinfo {
+	au_id_t        ai_auid;         /* Audit user ID */
+	au_mask_t      ai_mask;         /* Audit masks */
+	au_tid_t       ai_termid;       /* Terminal ID */
+	au_asid_t      ai_asid;         /* Audit session ID */
+};
+typedef struct auditinfo        auditinfo_t;
+.in
+.fi
+.Pp
+The
+.Fa ai_auid
+variable contains the audit identifier which is recorded in the audit log for
+each event the process caused.
+.Pp
+The
+.Fa au_mask_t
+data structure defines the bit mask for auditing successful and failed events
+out of the predefined list of event classes. It is defined as follows:
+.nf
+.in +4n
+struct au_mask {
+	unsigned int    am_success;     /* success bits */
+	unsigned int    am_failure;     /* failure bits */
+};
+typedef struct au_mask  au_mask_t;
+.in
+.fi
+.Pp
+The
+.Fa au_termid_t
+data structure defines the Terminal ID recorded with every event caused by the
+process. It is defined as follows:
+.nf
+.in +4n
+struct au_tid {
+	dev_t           port;
+	u_int32_t       machine;
+};
+typedef struct au_tid   au_tid_t;
+.in
+.fi
+.Pp
+The
+.Fa ai_asid
+variable contains the audit session ID which is recorded with every event
+caused by the process.
+.Pp
+The
+.Fn getaudit_addr
+system call
+uses the expanded
+.Fa auditinfo_addr_t
+data structure supports Terminal IDs with larger addresses such as those used
+in IP version 6.  It is defined as follows:
+.nf
+.in +4n
+struct auditinfo_addr {
+	au_id_t         ai_auid;        /* Audit user ID. */
+	au_mask_t       ai_mask;        /* Audit masks. */
+	au_tid_addr_t   ai_termid;      /* Terminal ID. */
+	au_asid_t       ai_asid;        /* Audit session ID. */
+	u_int64_t	ai_flags;	/* Audit session flags. */
+};
+typedef struct auditinfo_addr   auditinfo_addr_t;
+.in
+.fi
+.Pp
+The
+.Fa au_tid_addr_t
+data structure which includes a larger address storage field and an additional
+field with the type of address stored:
+.nf
+.in +4n
+struct au_tid_addr {
+	dev_t           at_port;
+	u_int32_t       at_type;
+	u_int32_t       at_addr[4];
+};
+typedef struct au_tid_addr      au_tid_addr_t;
+.in
+.fi
+.Pp
+Without appropriate privilege the audit mask fields will be set to all
+ones. 
 .Sh RETURN VALUES
-Upon successful completion a value of 0 is returned.
-Otherwise, a value of -1 is returned and
-.Va errno
-is set to indicate the error.
+.Rv -std getaudit getaudit_addr
+.Sh ERRORS
+The
+.Fn getaudit
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+A failure occurred while data transferred to or from
+the kernel failed.
+.It Bq Er EINVAL
+Illegal argument was passed by a system call.
+.It Bq Er EOVERFLOW
+The
+.Fa length
+argument indicates an overflow condition will occur.
+.It Bq Er ERANGE
+The address is too big and, therefore, 
+.Fn getaudit_addr
+should be used instead.
+.El
 .Sh SEE ALSO
 .Xr audit 2 ,
 .Xr auditon 2 ,
-.Xr auditctl 2 ,
 .Xr getauid 2 ,
+.Xr setaudit 2 ,
 .Xr setauid 2 ,
-.Xr setaudit 2
+.Xr libbsm 3
 .Sh HISTORY
-The
-.Fn getaudit
-function call first appeared in Mac OS X 10.3 (Panther).
+The OpenBSM implementation was created by McAfee Research, the security
+division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
+It was subsequently adopted by the TrustedBSD Project as the foundation for
+the OpenBSM distribution.
+.Sh AUTHORS
+.An -nosplit
+This software was created by McAfee Research, the security research division
+of McAfee, Inc., under contract to Apple Computer Inc.
+Additional authors include
+.An Wayne Salamon ,
+.An Robert Watson ,
+and SPARTA Inc.
+.Pp
+The Basic Security Module (BSM) interface to audit records and audit event
+stream format were defined by Sun Microsystems.
+.Pp
+This manual page was written by
+.An Robert Watson Aq rwatson@FreeBSD.org .