Technical Reference: Base Operating System and Extensions, Volume 1

auditbin Subroutine

Purpose

Defines files to contain audit records.

Library

Standard C Library (libc.a)

Syntax

#include <sys/audit.h>

int auditbin (Command, Current, Next, Threshold) int Command; int Current; int Next; int Threshold;

Description

The auditbin subroutine establishes an audit bin file into which the kernel writes audit records. Optionally, this subroutine can be used to establish an overflow bin into which records are written when the current bin reaches the size specified by the Threshold parameter.

Parameters

Command	If nonzero, this parameter is a logical ORing of the following values, which are defined in the sys/audit.h file: AUDIT_EXCL Requests exclusive rights to the audit bin files. If the file specified by the Current parameter is not the kernel's current bin file, the auditbin subroutine fails immediately with the errno variable set to EBUSY. AUDIT_WAIT The auditbin subroutine should not return until: bin full The kernel writes the number of bytes specified by the Threshold parameter to the file descriptor specified by the Current parameter. Upon successful completion, the auditbin subroutine returns a 0. The kernel writes subsequent audit records to the file descriptor specified by the Next parameter. bin failure An attempt to write an audit record to the file specified by the Current parameter fails. If this occurs, the auditbin subroutine fails with the errno variable set to the return code from the auditwrite subroutine. bin contention Another process has already issued a successful call to the auditbin subroutine. If this occurs, the auditbin subroutine fails with the errno variable set to EBUSY. system shutdown The auditing system was shut down. If this occurs, the auditbin subroutine fails with the errno variable set to EINTR.
Current	A file descriptor for a file to which the kernel should immediately write audit records.
Next	Specifies the file descriptor that will be used as the current audit bin if the value of the Threshold parameter is exceeded or if a write to the current bin fails. If this value is -1, no switch occurs.
Threshold	Specifies the maximum size of the current bin. If 0, the auditing subsystem will not switch bins. If it is nonzero, the kernel begins writing records to the file specified by the Next parameter, if writing a record to the file specified by the Cur parameter would cause the size of this file to exceed the number of bytes specified by the Threshold parameter. If no next bin is defined and AUDIT_PANIC was specified when the auditing subsystem was enabled, the system is shut down. If the size of the Threshold parameter is too small to contain a bin header and a bin tail, the auditbin subroutine fails and the errno variable is set to EINVAL.

Return Values

If the auditbin subroutine is successful, a value of 0 returns.

If the auditbin subroutine fails, a value of -1 returns and the errno global variable is set to indicate the error. If this occurs, the result of the call does not indicate whether any records were written to the bin.

Error Codes

The auditbin subroutine fails if any of the following is true:

EBADF	The Current parameter is not a file descriptor for a regular file open for writing, or the Next parameter is neither -1 nor a file descriptor for a regular file open for writing.
EBUSY	The Command parameter specifies AUDIT_EXCL and the kernel is not writing audit records to the file specified by the Current parameter.
EBUSY	The Command parameter specifies AUDIT_WAIT and another process has already registered a bin.
EINTR	The auditing subsystem is shut down.
EINVAL	The Command parameter specifies a nonzero value other than AUDIT_EXCL or AUDIT_WAIT.
EINVAL	The Threshold parameter value is less than the size of a bin header and trailer.
EPERM	The caller does not have root user authority.

Related Information

The audit (audit Subroutine) subroutine, auditevents (auditevents Subroutine) subroutine, auditlog (auditlog Subroutine) subroutine, auditobj (auditobj Subroutine) subroutine, auditproc (auditproc Subroutine) subroutine.

The audit command.

The audit file format.

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