Technical Reference: Base Operating System and Extensions, Volume 1

auditobj Subroutine

Purpose

Gets or sets the auditing mode of a system data object.

Syntax

#include <sys/audit.h>

int auditobj ( Command, Obj_Events, ObjSize) int Command; struct o_event *Obj_Events; int ObjSize;

The auditobj subroutine queries or sets the audit events to be generated by accessing selected objects. For each object in the file system name space, it is possible to specify the event generated for each access mode. Using the auditobj subroutine, an administrator can define new audit events in the system that correspond to accesses to specified objects. These events are treated the same as system-defined events.

System auditing need not be enabled to set or query the object audit events. The audit subroutine can be directed with the AUDIT_RESET command to clear the definitions of object audit events.

Parameters

Command	Specifies whether the object audit event lists are to be read or written. The valid values, defined in the sys/audit.h file, for the Command parameter are: AUDIT_SET Sets the list of object audit events, after first clearing all previous definitions. AUDIT_GET Queries the list of object audit events. AUDIT_LOCK Queries the list of object audit events and 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 auditobj subroutine with the Command parameter set to AUDIT_SET.
Obj_Events	Specifies the array of o_event structures for the AUDIT_SET operation or for after the AUDIT_GET or AUDIT_LOCK operation. The o_event structure is defined in the sys/audit.h file and contains the following members: `o_type` Specifies the type of the object, in terms of naming space. Currently, only one object-naming space is supported: AUDIT_FILE Denotes the file system naming space. `o_name` Specifies the name of the object. `o_event` Specifies any array of event names to be generated when the object is accessed. Note that event names are currently limited to 16 bytes, including the trailing null. The index of an event name in this array corresponds to an access mode. Valid indexes are defined in the audit.h file and include the following: AUDIT_READ AUDIT_WRITE AUDIT_EXEC
ObjSize	For an AUDIT_SET operation, the ObjSize parameter specifies the number of object audit event definitions in the array pointed to by the Obj_Events parameter. For an AUDIT_GET or AUDIT_LOCK operation, the ObjSize parameter specifies the size of the buffer pointed to by the Obj_Events parameter.

Return Values

If the auditobj subroutine completes successfully, the number of object audit event definitions 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 auditobj subroutine fails if any of the following are true:

EFAULT	The Obj_Events parameter points outside the address space of the process.
EFAULT	The Command parameter is AUDIT_SET, and one or more of the `o_name` members points outside the address space of the process.
EFAULT	The Command parameter is AUDIT_GET or AUDIT_LOCK, and the buffer size of the Obj_Events parameter is not large enough to hold the integer.
EINVAL	The value of the Command parameter is not AUDIT_SET, AUDIT_GET or AUDIT_LOCK.
EINVAL	The Command parameter is AUDIT_SET, and the value of one or more of the `o_type` members is not AUDIT_FILE.
EINVAL	An event name was longer than 15 significant characters.
ENOENT	The Command parameter is AUDIT_SET, and the parent directory of one of the file-system objects does not exist.
ENOSPC	The value of the Command parameter is AUDIT_GET or AUDIT_LOCK, and the size of the buffer as specified by the ObjSize 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.
ENOMEM	Memory allocation failed.
EBUSY	Another process has called the auditobj subroutine with AUDIT_LOCK.
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, auditproc (auditproc Subroutine) subroutine.

The audit command.

The audit.h file.

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