Technical Reference: Base Operating System and Extensions, Volume 1

auditevents Subroutine

Purpose

Gets or sets the status of system event auditing.

Syntax

#include <sys/audit.h>

int auditevents ( Command, Classes, NClasses) int Command; struct audit_class *Classes; int NClasses;

Description

The auditevents subroutine queries or sets the audit class definitions that control event auditing. Each audit class is a set of one or more audit events.

System auditing need not be enabled before calling the auditevents subroutine. The audit (audit Subroutine)subroutine can be directed with the AUDIT_RESET command to clear all event lists.

Parameters

Command	Specifies whether the event lists are to be queried or set. The values, defined in the sys/audit.h file, for the Command parameter are: AUDIT_SET Sets the lists of audited events after first clearing all previous definitions. AUDIT_GET Queries the lists of audited events. AUDIT_LOCK Queries the lists of audited events. This value also blocks any other process attempting to set or lock the list of audit events. The lock is released when the process holding the lock dies or calls the auditevents subroutine with the Command parameter set to AUDIT_SET.
Classes	Specifies the array of a_event structures for the AUDIT_SET operation, or after an AUDIT_GET or AUDIT_LOCK operation. The audit_class structure is defined in the sys/audit.h file and contains the following members: `ae_name` A pointer to the name of the audit class. `ae_list` A pointer to a list of null-terminated audit event names for this audit class. The list is ended by a null name (a leading null byte or two consecutive null bytes). Note: Event and class names are limited to 15 significant characters. `ae_len` The length of the event list in the ae_list member. This length includes the terminating null bytes. On an AUDIT_SET operation, the caller must set this member to indicate the actual length of the list (in bytes) pointed to by `ae_list`. On an AUDIT_GET or AUDIT_LOCK operation, the auditevents subroutine sets this member to indicate the actual size of the list.
NClasses	Serves a dual purpose. For AUDIT_SET, the NClasses parameter specifies the number of elements in the events array. For AUDIT_GET and AUDIT_LOCK, the NClasses parameter specifies the size of the buffer pointed to by the Classes parameter.

Attention: Only 32 audit classes are supported. One class is implicitly defined by the system to include all audit events (ALL). The administrator of your system should not attempt to define more than 31 audit classes.

Security

The calling process must have root user authority in order to use the auditevents subroutine.

Return Codes

If the auditevents subroutine completes successfully, the number of audit classes is returned if the Command parameter is AUDIT_GET or AUDIT_LOCK. A value of 0 is returned if the Command parameter is AUDIT_SET. If this call fails, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The auditevents subroutine fails if one or more of the following are true:

EPERM	The calling process does not have root user authority.
EINVAL	The value of Command is not AUDIT_SET, AUDIT_GET, or AUDIT_LOCK.
EINVAL	The Command parameter is AUDIT_SET, and the value of the NClasses parameter is greater than or equal to 32.
EINVAL	A class name or event name is longer than 15 significant characters.
ENOSPC	The value of Command is AUDIT_GET or AUDIT_LOCK and the size of the buffer specified by the NClasses parameter is not large enough to hold the list of event structures and names. If this occurs, the first word of the buffer is set to the required buffer size.
EFAULT	The Classes parameter points outside of the process' address space.
EFAULT	The `ae_list` member of one or more audit_class structures passed for an AUDIT_SET operation points outside of the process' address space.
EFAULT	The Command value is AUDIT_GET or AUDIT_LOCK and the size of the Classes buffer is not large enough to hold an integer.
EBUSY	Another process has already called the auditevents subroutine with AUDIT_LOCK.
ENOMEM	Memory allocation failed.

Implementation Specifications

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

Related Information

The audit (audit Subroutine) subroutine, auditbin (auditbin Subroutine) subroutine, auditlog (auditlog Subroutine) subroutine, auditobj (auditobj Subroutine) subroutine, auditproc (auditproc Subroutine) subroutine, auditread (auditread, auditread_r Subroutines) subroutine, auditwrite (auditwrite Subroutine)subroutine.

The audit command.

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