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

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

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