auditobj Subroutine

Purpose

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

Library

Standard C Library (libc.a)

Syntax

#include <sys/audit.h>

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

Description

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

Item Description
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
Note: The C++ compiler will generate a warning indicating that o_event is defined both as a structure and a field within that structure. Although the o_event field can be used within C++, the warning can by bypassed by defining O_EVENT_RENAME. This will replace the o_event field with o_event_array. o_event is the default field.
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:

Item Description
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.