Technical Reference: Base Operating System and Extensions, Volume 1

auditproc Subroutine

Purpose

Gets or sets the audit state of a process.

Library

Standard C Library (libc.a)

Syntax

#include <sys/audit.h>

int auditproc (ProcessID, Command, Argument, Length) int ProcessID; int Command; char * Argument; int Length;

Description

The auditproc subroutine queries or sets the auditing state of a process. There are two parts to the auditing state of a process:

The list of classes to be audited for this process. Classes are defined by the auditevents (auditevents Subroutine) subroutine. Each class includes a set of audit events. When a process causes an audit event, that event may be logged in the audit trail if it is included in one or more of the audit classes of the process.
The audit status of the process. Auditing for a process may be suspended or resumed. Functions that generate an audit record can first check to see whether auditing is suspended. If process auditing is suspended, no audit events are logged for a process. For more information, see the auditlog (auditlog Subroutine) subroutine.

Parameters

ProcessID	The process ID of the process to be affected. If ProcessID is 0, the auditproc subroutine affects the current process.
Command	The action to be taken. Defined in the audit.h file, valid values include: AUDIT_KLIST_EVENTS Sets the list of audit classes to be audited for the process and also sets the user's default audit classes definition within the kernel. The Argument parameter is a pointer to a list of null-terminated audit class names. The Length parameter is the length of this list, including null bytes. AUDIT_QEVENTS Returns the list of audit classes defined for the current process if ProcessID is 0. Otherwise, it returns the list of audit classes defined for the specified process ID. The Argument parameter is a pointer to a character buffer. The Length parameter specifies the size of this buffer. On return, this buffer contains a list of null-terminated audit class names. A null name terminates the list. AUDIT_EVENTS Sets the list of audit classes to be audited for the process. The Argument parameter is a pointer to a list of null-terminated audit class names. The Length parameter is the length of this list, including null bytes. AUDIT_QSTATUS Returns the audit status of the current process. You can only check the status of the current process. If the ProcessID parameter is nonzero, a -1 is returned and the errno global variable is set to EINVAL. The Length and Argument parameters are ignored. A return value of AUDIT_SUSPEND indicates that auditing is suspended. A return value of AUDIT_RESUME indicates normal auditing for this process. AUDIT_STATUS Sets the audit status of the current process. The Length parameter is ignored, and the ProcessID parameter must be zero. If Argument is AUDIT_SUSPEND, the audit status is set to suspend event auditing for this process. If the Argument parameter is AUDIT_RESUME, the audit status is set to resume event auditing for this process.
Argument	A character pointer for the audit class buffer for an AUDIT_EVENT or AUDIT_QEVENTS value of the Command parameter or an integer defining the audit status to be set for an AUDIT_STATUS operation.
Length	Size of the audit class character buffer.

Return Values

The auditproc subroutine returns the following values upon successful completion:

The previous audit status (AUDIT_SUSPEND or AUDIT_RESUME), if the call queried or set the audit status (the Command parameter specified AUDIT_QSTATUS or AUDIT_STATUS)
A value of 0 if the call queried or set audit events (the Command parameter specified AUDIT_QEVENTS or AUDIT_EVENTS)

Error Codes

If the auditproc subroutine fails if one or more of the following are true:

EINVAL	An invalid value was specified for the Command parameter.
EINVAL	The Command parameter is set to the AUDIT_QSTATUS or AUDIT_STATUS value and the pid value is nonzero.
EINVAL	The Command parameter is set to the AUDIT_STATUS value and the Argument parameter is not set to AUDIT_SUSPEND or AUDIT_RESUME.
ENOSPC	The Command parameter is AUDIT_QEVENTS, and the buffer size is insufficient. In this case, the first word of the Argument parameter is set to the required size.
EFAULT	The Command parameter is AUDIT_QEVENTS or AUDIT_EVENTS and the Argument parameter points to a location outside of the process' allocated address space.
ENOMEM	Memory allocation failed.
EPERM	The caller does not have root user authority.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The audit (audit Subroutine) subroutine, auditbin (auditbin Subroutine) subroutine, auditevents (auditevents Subroutine) subroutine, auditlog (auditlog Subroutine) subroutine, auditobj (auditobj Subroutine) subroutine, auditwrite (auditwrite Subroutine) subroutine.

List of Security and Auditing Subroutines and Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.