dce_aud_commit(3sec)
Writes the audit record in the audit trail file.
Used by client/server applications.
Synopsis
#include <dce/audit.h>
void dce_aud_commit(
dce_aud_trail_t at,
dce_aud_rec_t ard,
unsigned32 options,
unsigned16 format,
unsigned32 outcome,
unsigned32 *status);
Parameters
Input
at
Designates an audit trail file to which the completed audit record will be written. The audit trail file must have been previously opened by a successful call to the
dce_aud_open( ) function.
ard
Designates an audit record descriptor that was returned by a previously successful call to one of the dce_aud_start_*( ) functions. The content of this record
buffer will be appended to the audit trail specified by at.
options
Bitwise OR of option values described below. A value of 0 for options results in the default operation (normal writing to the file without
flushing to stable storage). The possible option value is:
| aud_c_evt_commit_sync | Flushes the audit record to stable storage before the function returns. |
| Aud_c_evt_always_log | Unconditionally logs the audit record to the audit trail. |
| Aud_c_evt_always_alarm | Unconditionally displays the audit record on the console. |
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.
outcome
The event outcome to be stored in the header. The possible event-outcome values are:
| aud_c_esl_cond_success | The event completed successfully. |
| Aud_c_esl_cond_denial | The event failed because of access denial. |
| Aud_c_esl_cond_failure | The event failed because of reasons other than access denial. |
| Aud_c_esl_cond_pending | The event is in an intermediate state, and the outcome is pending, being one in a series of connected events, where the application desires to record the real outcome only after the last event. |
| Aud_c_esl_cond_unknown | The event outcome (denial, failure, pending, or success) is not known. This outcome exists only between a dce_aud_start( ) (all varieties of this routine) call and the next dce_aud_commit( ) call. You can also use 0 to specify this outcome. |
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or not. If the routine did not complete successfully,
the reason for the failure is given.
Description
The dce_aud_commit( ) function determines whether the event should be audited given the event outcome. If it should be audited, the function completes the
audit record identified by ard and writes it to the audit trail designated by at. If any of the aud_c_evt_always_log or aud_c_evt_always_alarm options is
selected, the event is always audited (logged or an alarm message is sent to the standard output).
If the aud_c_evt_commit_sync option is selected, the function attempts to flush the audit record to stable storage. If the stable storage write cannot be performed, the function either continues to try until the stable-storage write is completed or returns an error status.
Upon successful completion, dce_aud_commit( ) calls dce_aud_discard( ) internally to release the memory of the audit record that is being committed.
The caller should not change the outcome between the dce_aud_start( ) and dce_aud_commit( ) calls arbitrarily. In this case, the outcome can be made more specific, for example, from aud_c_esl_cond_unknown to aud_c_esl_cond_success or from aud_c_esl_cond_pending to aud_c_esl_cond_success.
An outcome change from aud_c_esl_cond_success to aud_c_esl_cond_denial is not logically correct because the outcome aud_c_esl_cond_success may have caused a NULL ard to be returned in this function. If the final outcome can be aud_c_esl_cond_success, then it should be specified in this function, or use aud_c_esl_cond_unknown.
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_wrong_protection_level
Client used the wrong protection level.
aud_s_dmn_disabled
The daemon is disabled for logging.
aud_s_log_access_denied
The client's access to the audit log was denied.
aud_s_cannot_gettime
The audit library cannot backup a trail file due to failure of the utc_gettime( ) call.
aud_s_cannot_getgmtime
The audit library cannot backup a trail file due to failure of the utc_gmtime( ) call.
aud_s_rename_trail_file_rc
Cannot rename the audit trail file.
aud_s_cannot_reopen_trail_file_rc
Internally, the audit trail file was being reopened and the reopening of the file failed.
aud_s_rename_trail_index_file_rc
Internally, the audit trail index file was being renamed and the renaming of the file failed.
aud_s_cannot_reopen_trail_index_file_rc
Internally, the audit trail index file was being reopened and the reopening of the file failed.
aud_s_invalid_record_descriptor
The audit record descriptor is invalid.
aud_s_invalid_outcome
The event outcome parameter that was provided is invalid.
aud_s_outcomes_inconsistent
The event outcome parameter is inconsistent with the outcome parameter provided in the dce_aud_start( ) call.
aud_s_trl_write_failure
The audit record cannot be written to stable storage option
aud_s_ok
The call was successful.
Status codes passed from dce_aud_discard( )
Status codes passed from rpc_binding_inq_auth_caller( )
Status codes passed from
dce_acl_is_client_authorized( )
Status codes passed from audit_pickle_dencode_ev_info( ) (RPC IDL compiler)
Related Information
Functions:
dce_aud_start_with_server_binding(3sec)