dg_auditctl(2) C2 Trusted DG/UX 5.4.2T dg_auditctl(2)
NAME
dgauditctl - perform a variety of audit control functions
SYNOPSIS
#include <sys/audit.h>
int dgauditctl (int command, int argument, int sizearg);
where:
command One of the audit control commands listed below.
argument Additional information needed by the command. The type of
argument depends upon the command, but it is generally an
integer or a pointer to a command-specific data structure.
sizearg The size of the object given by argument when its size is
not fixed. sizearg is usually an integer variable
containing the byte size of the object given by argument.
DESCRIPTION
The dgauditctl() system call is used to query or change the current
audit state.
When the caller does not have appropriate privilege dgauditctl fails
and sets errno to EPERM. When command is not one of those listed
below errno is set to EINVAL.
Command Functions
The following describes the dgauditctl commands and the error codes
returned by each:
AUDSTART Turns on auditing and writes an audit trail header
record. When auditing is on, audit records are created
for auditable events (as determined by the effective
audit mask of each process), and are written to the
current audit trail file.
When argument is NULL the current trail file is used.
The current trail file is the one in use when auditing
was last stopped unless changed by the AUDSETTRAILSPEC
command (see below.)
When argument is not NULL, it must be a pointer to a
structure of type audtrailspect. If the specified file
can be successfully opened, it will replace the current
trail file prior to starting auditing.
The size of the audtrailspect structure pointed to by
argument is given by sizearg.
The trail specification (audtrailspect) contains the
following members:
uint maxblocks;
Licensed material--property of copyright holder(s) 1
dg_auditctl(2) C2 Trusted DG/UX 5.4.2T dg_auditctl(2)
timet endtime;
booleant recycle;
booleant truncate;
sizet actualtrailspecsize;
char filename [];
The entries maxblocks, endtime and recycle are currently
not supported but should all be set to zero. When
truncate is set to BTRUE the trail file (if it exists)
is opened and truncated, otherwise it is opened and
appended to. The actualtrailspecsize is the size [in
bytes] of this structure, including the pathname string
(including the terminating NULL). The pathname of the
trail file must be rooted (begin at the system's root
filesystem \) and is given by filename.
On failure, errno is set to one of the following values:
EINVAL Auditing is already started.
EINVAL sizearg does not match the size field in
the trail-specification pointed to by
argument.
EINVAL A current trail specification does not
exist and argument is NULL.
EINVAL The trail pathname does not begin with "\".
ENOMEM Unable to allocate enough memory to
complete the request.
EFAULT The caller does not have read access to one
or more bytes of the block of memory
specified by argument and sizearg.
EACCES filename is a directory or an unsupported
file type.
ENOSPC Insufficient contiguous space to create a
file entry or inode.
ENOENT A non-terminal component of the pathname
does not exist.
ENOTDIR A non-terminal component of the pathname
was not a directory.
ENAMETOOLONG The pathname exceeds the length limit for
pathnames or a component of the pathname
exceeds the length limit for filenames.
EPERM The pathname contains a character not in
the allowed character set.
Licensed material--property of copyright holder(s) 2
dg_auditctl(2) C2 Trusted DG/UX 5.4.2T dg_auditctl(2)
AUDSTOP Auditing is stopped and a trail-tail record is written
to the current audit trail. On failure, errno is set to
one of the following values:
EINVAL Auditing is not on.
AUDSWITCH When auditing is on, all cached records are flushed to
the current trail file, a trail tail record is written
and the file is closed. The trail file given by
argument becomes the current trail file, it is opened
and a trail header record is written to it. The
parameters sizearg and the audtrailspect structure
are as described above for the AUDSTART command. When
a new file cannot be switched to, for any reason,
auditing continues to the current trail file.
Note that switching to the current file with truncate
TRUE deletes the contents of the file before the trail
header record is written.
On failure, errno is set to one of the following values:
EINVAL Auditing is not on.
EINVAL argument is NULL.
EINVAL The trail pathname does not begin with "\".
EINVAL sizearg does not match the
actualtrailspecsize field in the
structure pointed to by argument.
ENOMEM Unable to allocate memory to complete the
request.
EACCES filename is a directory or an unsupported
file type.
ENOSPC Insufficient contiguous space to create a
file entry or inode.
ENOENT A non-terminal component of the pathname
does not exist.
ENOTDIR A non-terminal component of the pathname
was not a directory.
ENAMETOOLONG The pathname exceeds the length limit for
pathnames or a component of the pathname
exceeds the length limit for filenames.
EPERM The pathname contains a character not in
the allowed character set.
Licensed material--property of copyright holder(s) 3
dg_auditctl(2) C2 Trusted DG/UX 5.4.2T dg_auditctl(2)
AUDFLUSH Flush all cached audit records to the current trail
file. There is no guarantee that on return from this
request the record cache is empty, only that records
stored there before the request have been written to the
file. On failure, errno is set to one of the following
values:
EINVAL auditing is not on.
AUDMUSTSTART
Specifies the action to be taken when auditing cannot be
started. When argument is BTRUE, init(1m) will not
exit single-user level when auditing is not on. When
argument is BFALSE, the audit state does not affect the
init process' decision to exit single-user level. This
command always returns 0, indicating success.
AUDMUSTAUDIT
Specifies the action to be taken when auditing fails and
the system is in multiuser mode. When argument is
BTRUE the system signals init to change state to
single-user state if auditing cannot continue due to a
failure. When argument is BFALSE, the system turns
auditing off and continues. This command always returns
0, indicating success.
AUDSETMASK Replaces the system-wide audit mask with the audit mask
pointed to by argument. An audit mask, type audmaskt,
is an array of AUDCLASSCOUNT reason codes. A reason
code is of type audreasont and specifies the reason
for auditing a class of events --see sys/audit.h.
sizearg is ignored. On failure, errno is set to one of
the following values:
EFAULT The caller does not have read access to one
or more bytes of the mask.
AUDGETSTATUS
Returns the audit state in the structure pointed to by
argument. argument points to a structure of type
audconfigurationt containing the following fields:
booleant auditingison;
booleant shutdownonstartupfailure;
booleant shutdownonauditfailure;
booleant stoppedbysystem;
audmaskt systemauditmask;
When the booleant types are BTRUE the conditions
described by their names are enabled. systemauditmask
contains a copy of the system-wide audit mask. On
failure, errno is set to one of the following values:
EFAULT The caller does not have read/write access
Licensed material--property of copyright holder(s) 4
dg_auditctl(2) C2 Trusted DG/UX 5.4.2T dg_auditctl(2)
to one or more bytes of the structure
pointed to by argument.
AUDGETTRAILSPECSIZE
Returns the size of a buffer that will hold the current
trail specification structure. This structure contains
the trail file name and is therefore of variable size.
The return value from the command is the minimum number
of bytes of memory needed to hold the current trail
specification structure. A zero (0) is returned when
there is no current trail specification.
AUDGETTRAILSPEC
Copy the current trailspec into the structure pointed to
by argument. On failure, errno is set to one of the
following values and argument is not changed:
EFAULT The caller does not have read/write access
to the block of memory given by argument
and sizearg.
EINVAL The sizearg is less than the size of the
current trail specification structure.
ENOENT There is no trail specification.
AUDSETTRAILSPEC
The current trail specification is replaced by the one
pointed to by argument. Auditing must currently be off.
Whenever auditing is started without specifying a trail
specification the current trail is used.
This command verifies that the trail file is on a
writable file system that currently has room for a file
of at least maxblocks blocks. On failure, errno is set
to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and
sizearg.
EINVAL The trail pathname does not begin with a
"\".
EINVAL Auditing is on.
EINVAL The trail file is in a read-only file
system.
EINVAL Not enough room exists on the file system
for a file of size
maxblocks.
Licensed material--property of copyright holder(s) 5
dg_auditctl(2) C2 Trusted DG/UX 5.4.2T dg_auditctl(2)
AUDSETCMDSETMAP
When auditing is off this option replace the array of
audit classes used to map user-level events to their
designated classes. The number of entries in the map
pointed to by argument is given by sizearg.
The class to which an event is mapped is found by
indexing into the class map given an event number. The
index is calculated by subtracting AUDETCOMMANDSBASE
from the user-level event number.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and
sizearg.
EINVAL sizearg is less than the size
corresponding to AUDNUMCOMMANDEVENTS;
where AUDNUMCOMMANDEVENTS is the minimum
number of non-kernel events defined by the
TCB.
ENOMEM Couldn't allocate memory for the new map.
AUDSETKERNELETMAP
When auditing is off this option replace the array of
audit classes used to map kernel-level events to their
designated classes. The number of entries in the map
pointed to by argument is given by sizearg.
The class to which an event is mapped is found by
indexing into the class map given an event number. The
index is calculated by subtracting AUDETKERNELBASE
from the kernel event number.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and
sizearg.
EINVAL sizearg is not equal to the size
corresponding to AUDNUMKERNELEVENTS.
ENOMEM Couldn't allocate memory for the new map.
ACCESS CONTROL
The caller must have appropriate privilege.
RETURN VALUE
Unless specified otherwise above, the return value from dgauditctl
is 0 upon success and -1 upon failure with errno set as indicated.
Licensed material--property of copyright holder(s) 6
dg_auditctl(2) C2 Trusted DG/UX 5.4.2T dg_auditctl(2)
SEE ALSO
init(1m), audadmin(1m)
Audit System Administrator's Guide for the C2 Trusted DG/UX System
Licensed material--property of copyright holder(s) 7