NAME

dce_aud_next —  Reads the next audit record from a specified audit trail file into a buffer.  Used by the trail analysis and examination tools. 

Synopsis

void dce_aud_next(
dce_aud_trail_t ∗at,
char ∗predicate,
unsigned16 format,
dce_aud_rec_t ∗ard,
unsigned32 ∗status);

Parameters

Input

atA pointer to the descriptor of an audit trail file previously opened for reading by the function dce_aud_open(). 

predicateCriteria for selecting the audit records that are to be read from the audit trail file. A predicate statement consists of an attribute and its value, separated by any of the following operators: = (equal to), < (less than), <= (less than or equal to), > (greater than), and >= (greater than or equal to):

   •attribute=value

   •attribute>value

   •attribute>=value

   •attribute<value

   •attribute<=value

Attribute names are case sensitive, and no space is allowed within a predicate expression. Multiple predicates are delimited by a comma, in the following form:

attribute1=value1,attribute2>value2, ...

No space is allowed between predicates. Note that when multiple predicates are defined, the values are logically ANDed together. 

The possible attribute names, their values, and allowable operators are as follows:

SERVERThe UUID of the server principal that generated the record. The attribute value must be a UUID string. Operator allowed: = (equal to). 

EVENTThe audit event number. The attribute value must be a hexadecimal number.  Operator allowed: = (equal to). 

OUTCOME
The event outcome of the record. The possible attribute values are SUCCESS, FAILURE, PENDING, or DENIAL.  Operator allowed: = (equal to). 

STATUSThe authorization status of the client. The possible attribute values are DCE for DCE authorization (PAC based), and NAME for name-based authorization. Operator allowed: = (equal to). 

CLIENTThe UUID of the client principal. The attribute value must be a UUID string.  Operator allowed: = (equal to). 

TIMEThe time the record was generated. The attribute value must be a null-terminated string that expresses an absolute time. Operators allowed: <= (less than or equal to), < (less than), >= (greater than or equal to), and > (greater than). 

CELLThe UUID of the client’s cell. The attribute value must be a UUID string.  Operator allowed: = (equal to). 

GROUPThe UUID of one of the client’s group(s). The attribute value must be a UUID string. Operator allowed: = (equal to). 

ADDRThe address of the client. The attribute is typically the string representation of an RPC binding handle. Operator allowed: = (equal to). 

FORMAT
The format version number of the audit event record. The attribute value must be an integer. Operators allowed: = (equal to), < (less than), and > (greater than). 

formatEvent’s tail format used for the event-specific information. This format can be configured by the user. With this format version number, the servers and audit analysis tools can accomodate changes in the formats of the event specification information, or use different formats dynamically. 

Output

ardA pointer to the audit record descriptor containing the returned record. 

statusThe status code returned by this routine. This status code indicates whether the routine was completed successfully or not. If the routine was not completed successfully, the reason for the failure is given. See “Errors” for a list of the possible status codes and their meanings. 

Description

The dce_aud_next() function attempts to read the next record from the audit trail file specified by the audit trail descriptor, at. This function also defines the predicate to be used to search for the next record and returns a matching record if one exists. The dce_aud_next() function can be used to search for successive records in the trail that match the defined predicate. By default, if no predicate is explicitly defined, the function returns the next record from the audit trail. 

If no record satisfies the predicate specified for the call, a value of zero (NULL) is returned through ard. 

The value returned through ard can be supplied as an input parameter to the functions dce_aud_get_header(), dce_aud_length(), dce_aud_discard(), dce_aud_print(), dce_aud_get_event(), and dce_aud_get_ev_info(). 

Storage allocated by this function must be explicitly freed by a call to dce_aud_discard() with ard as the input parameter. 

If the function successfully reads an audit trail record, the cursor associated with the audit trail descriptor at will be advanced to the next record in the audit trail. The calling routine does not need to set or move the cursor explicitly. 

If no appropriate record can be found in the audit trail, an ard value of NULL is returned and the cursor is advanced to the end of the audit trail.  If a call is unsuccessful, the position of the cursor does not change. 

Return Values

No value is returned. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

aud_s_ok
The call was successfully completed.

aud_s_invalid_trail_descriptor
The audit trail descriptor is invalid.

aud_s_trail_file_corrupted
The trail file is corrupted.

aud_s_index_file_corrupted
The index trail file is corrupted.

aud_s_cannot_allocate_memory
The malloc() call failed. 

Status codes passed from idl_es_decode_buffer()

Status codes passed from idl_es_handle_free()

Status codes passed from audit_pickle_dencode_ev_info()
(RPC IDL compiler)

Related Information

Functions: dce_aud_next(3sec), dce_aud_get_header(3sec), dce_aud_length(3sec), dce_aud_get_ev_info(3sec), dce_aud_open(3sec), dce_aud_discard(3sec), dce_aud_print(3sec), dce_aud_get_event(3sec).