'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH AU_TO 3BSM "Mar 6, 2017"
.SH NAME
au_to, au_to_arg, au_to_arg32, au_to_arg64, au_to_attr, au_to_cmd, au_to_data,
au_to_groups, au_to_in_addr, au_to_ipc, au_to_iport, au_to_me, au_to_newgroups,
au_to_opaque, au_to_path, au_to_process, au_to_process_ex, au_to_return,
au_to_return32, au_to_return64, au_to_socket, au_to_subject, au_to_subject_ex,
au_to_text \- create audit record tokens
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lbsm\fR \fB -lsocket \fR \fB -lnsl \fR  [ \fIlibrary\fR... ]
#include <sys/types.h>
#include <sys/vnode.h>
#include <netinet/in.h>
#include <bsm/libbsm.h>

\fBtoken_t *\fR\fBau_to_arg\fR(\fBchar\fR \fIn\fR, \fBchar *\fR\fItext\fR, \fBuint32_t\fR \fIv\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_arg32\fR(\fBchar\fR \fIn\fR, \fBchar *\fR\fItext\fR, \fBuint32_t\fR \fIv\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_arg64\fR(\fBchar\fR \fIn\fR, \fBchar *\fR\fItext\fR, \fBuint64_t\fR \fIv\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_attr\fR(\fBstruct vattr *\fR\fIattr\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_cmd\fR(\fBuint_t\fR \fIargc\fR, \fBchar **\fR\fIargv\fR, \fBchar **\fR\fIenvp\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_data\fR(\fBchar\fR \fIunit_print\fR, \fBchar\fR \fIunit_type\fR, \fBchar\fR \fIunit_count\fR,
     \fBchar *\fR\fIp\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_groups\fR(\fBint *\fR\fIgroups\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_in_addr\fR(\fBstruct in_addr *\fR\fIinternet_addr\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_ipc\fR(\fBchar\fR \fItype\fR, \fBint\fR \fIid\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_iport\fR(\fBu_short_t\fR \fIiport\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_me\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_newgroups\fR(\fBint\fR \fIn\fR, \fBgid_t *\fR\fIgroups\fR);
.fi

.LP
.nf
\fBtoken_t\fR \fB*au_to_opaque\fR(\fBchar *\fR\fIdata\fR, \fBshort\fR \fIbytes\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_path\fR(\fBchar *\fR\fIpath\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_process\fR(\fBau_id_t\fR \fIauid\fR, \fBuid_t\fR \fIeuid\fR, \fBgid_t\fR \fIegid\fR,
     \fBuid_t\fR \fIruid\fR, \fBgid_t\fR \fIrgid\fR, \fBpid_t\fR \fIpid\fR, \fBau_asid_t\fR \fIsid\fR, \fBau_tid_t *\fR\fItid\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_process_ex\fR(\fBau_id_t\fR \fIauid\fR, \fBuid_t\fR \fIeuid\fR, \fBgid_t\fR \fIegid\fR,
     \fBuid_t\fR \fIruid\fR, \fBgid_t\fR \fIrgid\fR, \fBpid_t\fR \fIpid\fR, \fBau_asid_t\fR \fIsid\fR, \fBau_tid_addr_t *\fR\fItid\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_return\fR(\fBchar\fR \fInumber\fR, \fBuin32t_t\fR \fIvalue\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_return32\fR(\fBchar\fR \fInumber\fR, \fBuin32t_t\fR \fIvalue\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_return64\fR(\fBchar\fR \fInumber\fR, \fBuin64t_t\fR \fIvalue\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_socket\fR(\fBstruct oldsocket *\fR\fIso\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_subject\fR(\fBau_id_t\fR \fIauid\fR, \fBuid_t\fR \fIeuid\fR, \fBgid_t\fR \fIegid\fR,
     \fBuid_t\fR \fIruid\fR, \fBgid_t\fR \fIrgid\fR, \fBpid_t\fR \fIpid\fR, \fBau_asid_t\fR \fIsid\fR, \fBau_tid_t *\fR\fItid\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_subject_ex\fR(\fBau_id_t\fR \fIauid\fR, \fBuid_t\fR \fIeuid\fR, \fBgid_t\fR \fIegid\fR,
     \fBuid_t\fR \fIruid\fR, \fBgid_t\fR \fIrgid\fR, \fBpid_t\fR \fIpid\fR, \fBau_asid_t\fR \fIsid\fR, \fBau_tid_addr_t *\fR\fItid\fR);
.fi

.LP
.nf
\fBtoken_t *\fR\fBau_to_text\fR(\fBchar *\fR\fItext\fR);
.fi

.SH DESCRIPTION
.LP
The \fBau_to_arg()\fR, \fBau_to_arg32()\fR, and \fBau_to_arg64()\fR functions
format the data in \fIv\fR into an "argument token". The \fIn\fR argument
indicates the argument number. The \fItext\fR argument is a null-terminated
string describing the argument.
.sp
.LP
The \fBau_to_attr()\fR function formats the data pointed to by \fIattr\fR into
a "vnode attribute token".
.sp
.LP
The \fBau_to_cmd()\fR function formats the data pointed to by \fIargv\fR into a
"command token". A command token reflects a command and its parameters as
entered. For example, the \fBpfexec\fR(1) utility uses \fBau_to_cmd()\fR to
record the command and arguments it reads from the command line.
.sp
.LP
The \fBau_to_data()\fR function formats the data pointed to by \fIp\fR into an
"arbitrary data token". The \fIunit_print\fR parameter determines the preferred
display base of the data and is one of \fBAUP_BINARY\fR, \fBAUP_OCTAL\fR,
\fBAUP_DECIMAL\fR, \fBAUP_HEX\fR,  or \fBAUP_STRING\fR.  The \fIunit_type\fR
parameter defines the basic unit of data and is one of \fBAUR_BYTE\fR,
\fBAUR_CHAR\fR, \fBAUR_SHORT\fR, \fBAUR_INT\fR,  or \fBAUR_LONG\fR.  The
\fIunit_count\fR parameter specifies the number of basic data units to be used
and must be positive.
.sp
.LP
The \fBau_to_groups()\fR function formats the array of 16 integers pointed to
by \fIgroups\fR into a "groups token". The \fBau_to_newgroups()\fR function
(see below) should be used in place of this function.
.sp
.LP
The \fBau_to_in_addr()\fR function formats the data pointed to by
\fIinternet_addr\fR into an "internet address token".
.sp
.LP
The \fBau_to_ipc()\fR function formats the data in the \fIid\fR parameter into
an "interprocess communications \fBID\fR token".
.sp
.LP
The \fBau_to_iport()\fR function formats the data pointed to by \fIiport\fR
into an "ip port address token".
.sp
.LP
The \fBau_to_me()\fR function collects audit information from the current
process and creates  a "subject token" by calling  \fBau_to_subject()\fR.
.sp
.LP
The \fBau_to_newgroups()\fR function formats the array of  \fIn\fR integers
pointed to by \fIgroups\fR into a "newgroups token". This function should be
used in place of \fBau_to_groups()\fR.
.sp
.LP
The \fBau_to_opaque()\fR function formats the \fIbytes\fR bytes pointed to by
\fIdata\fR into an "opaque token". The value of \fIsize\fR must be positive.
.sp
.LP
The \fBau_to_path()\fR function formats the path name pointed to by \fIpath\fR
into a ``path token.''
.sp
.LP
The \fBau_to_process()\fR function formats an \fIauid\fR (audit user \fBID\fR),
an \fIeuid\fR (effective user \fBID\fR), an \fIegid\fR (effective group
\fBID\fR), a \fIruid\fR (real user \fBID\fR), a \fIrgid\fR (real group
\fBID\fR), a \fIpid\fR (process \fBID\fR), an \fIsid\fR (audit session
\fBID\fR), and a \fItid\fR (audit terminal \fBID\fR containing an IPv4 IP
address), into a "process token".  A process token should be used when the
process is the object of an action (ie. when the process is the receiver of a
signal). The \fBau_to_process_ex()\fR function (see below) should be used in
place of this function.
.sp
.LP
The \fBau_to_process_ex()\fR function formats an \fIauid\fR (audit user
\fBID),\fR an \fIeuid\fR (effective user \fBID),\fR an \fIegid\fR (effective
group \fBID),\fR a \fIruid\fR (real user \fBID),\fR a \fIrgid\fR (real group
\fBID),\fR a \fIpid\fR (process \fBID),\fR an \fIsid\fR (audit session
\fBID),\fR and a \fItid\fR (audit terminal \fBID containing an IPv4 or IPv6 IP
address),\fR into a "process token".  A process token should be used when the
process is the object of an action (that is, when the process is the receiver
of a signal). This function should be used in place of \fBau_to_process()\fR.
.sp
.LP
The \fBau_to_return()\fR, \fBau_to_return32()\fR, and \fBau_to_return64()\fR
functions format an error number \fInumber\fR and a return value \fIvalue\fR
into a "return value token".
.sp
.LP
The \fBau_to_socket()\fR function format the data pointed to by \fIso\fR into a
``socket token.''
.sp
.LP
The \fBau_to_subject()\fR function formats an \fIauid\fR (audit user \fBID\fR),
an \fIeuid\fR (effective user \fBID\fR), an \fIegid\fR (effective group
\fBID\fR), a \fIruid\fR (real user \fBID\fR), an \fIrgid\fR (real group
\fBID\fR), a \fIpid\fR (process \fBID\fR), an \fIsid\fR (audit session
\fBID\fR), an \fItid\fR (audit terminal \fBID\fR containing an IPv4 IP
address), into a "subject token". The \fBau_to_subject_ex()\fR function (see
below) should be used in place of this function.
.sp
.LP
The \fBau_to_subject_ex()\fR function formats an \fIauid\fR (audit user
\fBID),\fR an \fIeuid\fR (effective user \fBID),\fR an \fIegid\fR (effective
group \fBID),\fR a \fIruid\fR (real user \fBID),\fR an \fIrgid\fR (real group
\fBID),\fR a \fIpid\fR (process \fBID),\fR an \fIsid\fR (audit session
\fBID),\fR an \fItid\fR (audit terminal \fBID containing an IPv4 or IPv6 IP
address),\fR into a "subject token". This function should be used in place of
\fBau_to_subject()\fR.
.sp
.LP
The \fBau_to_text()\fR function formats the null-terminated string pointed to
by \fItext\fR into a "text token".
.SH RETURN VALUES
.LP
These functions return \fINULL\fR if memory cannot be allocated to put the
resultant token into, or if an error in the input is detected.
.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.LP
.BR au_open (3BSM),
.BR attributes (7)