dce_aud_next(3sec)
Reads the next audit record from a specified audit trail file into a buffer.
Used by the trail analysis and examination tools.
Synopsis
#include <dce/audit.h>
void dce_aud_next(
dce_aud_trail_t at,
char *predicate,
unsigned16 format,
dce_aud_rec_t *ard,
unsigned32 *status);
Parameters
Input
at
A pointer to the descriptor of an audit trail file previously opened for reading by the function dce_aud_open( ).
predicate
Criteria 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), >= (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, of the 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:
| SERVER | The UUID of the server principal that generated the record. The attribute value must be a UUID string. Operator allowed: = (equal to). |
| EVENT | The audit event number. The attribute value must be an integer. 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). |
| STATUS | The 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). |
| CLIENT | The UUID of the client principal. The attribute value must be a UUID string. Operator allowed: =. |
| TIME | The 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). |
| CELL | The UUID of the client's cell. The attribute value must be a UUID string. Operator allowed: =. |
| GROUP | The UUID of one of the client's group(s). The attribute value must be a UUID string. 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). |
| ADDR | The address of the client. The attribute is typically the string representation of an RPC binding handle. Operator allowed: = (equal to). |
format
Event'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 accommodate changes in the formats of the event-specific information, or use different formats dynamically.
Output
ard
A pointer to the audit record descriptor containing the returned record.
status
Returns the status code from 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.
Description
The dce_aud_next( ) function attempts to read the next record from the audit trail that is 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 read from the audit trail.
If no record satisfies the predicate specified for the call, a value of zero is returned in ard.
The value returned in ard can be supplied as an input parameter to the functions dce_aud_get_header( ), dce_aud_length( ), dce_aud_get_ev_info( ), and dce_aud_discard( ).
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.
If no appropriate record can be found in the audit trail, an ard value of zero 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_invalid_trail_descriptor
The audit trail descriptor is invalid.
aud_s_trail_file_corrupted
The trail file is corrupted.
aud_s_cannot_allocate_memory
The malloc( ) call failed.
aud_s_ok
The call was successful.
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: