dce_aud_prev(3sec)
Reads the previous 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_prev(
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, in the following form:
attribute =
value1,attribute>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:
| 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). |
| 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: = (equal to). |
| 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). |
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-specification information, or use different formats dynamically.
Output
ard
A pointer to the audit record descriptor containing the returned record.
status
The status code returned by this function. 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_prev( ) function attempts to read the previous 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 previous record and returns a matching record if one exists. dce_aud_prev( ) can be used to search for previous records in
the trail file that match the defined predicate. By default, if no predicate is explicitly defined, the function returns the previous record read from the audit trail.
If no record satisfies the predicate specified for the call, a value of zero (NULL) 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 moved to the previous record in the audit trail file.
If no appropriate record can be found in the audit trail, an ard value of zero is returned and the cursor is set back to the beginning of the audit trail. If a call is unsuccessful, the position of the cursor does not change.
Return Value
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 audit trail 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: