PERFORCE change 144903 for review

[Stacey Son]

http://perforce.freebsd.org/chv.cgi?CH=144903

Change 144903 by sson at sson_amd64 on 2008/07/08 18:55:23

	Added additional detail concerning API.

Affected files ...

.. //depot/projects/trustedbsd/openbsm/man/setaudit.2#8 edit

Differences ...

==== //depot/projects/trustedbsd/openbsm/man/setaudit.2#8 (text+ko) ====

@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/trustedbsd/openbsm/man/setaudit.2#7 $
+.\" $P4: //depot/projects/trustedbsd/openbsm/man/setaudit.2#8 $
 .\"
 .Dd April 19, 2005
 .Dt SETAUDIT 2
@@ -54,9 +54,113 @@
 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 setaudit_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. */
+};
+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
 These system calls require an appropriate privilege to complete.
 .Sh RETURN VALUES
 .Rv -std setaudit setaudit_addr
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er EPERM
+The caller does not possess the appropriate privileges.
+.TP
+.It Bq Er EFAULT/EINVAL
+Invalid argument.
+.El
 .Sh SEE ALSO
 .Xr audit 2 ,
 .Xr auditon 2 ,