dce_aud_open(3sec)
Opens a specified audit trail file for read or write.
Used by client/server applications and trail analysis and examination tools.
Synopsis
#include <dce/audit.h>
void dce_aud_open(
unsigned32 flags,
char *description,
unsigned32 first_evt_number,
unsigned32 num_of_evts,
dce_aud_trail_t *at,
unsigned32 *status);
Parameters
Input
flags
Specifies the mode of opening. The flags parameter is set to the bitwise OR of the following values:
· aud_c_trl_open_read
· aud_c_trl_open_write
· aud_c_trl_ss_wrap
description
A character string specifying an audit trail file to be opened. If description is NULL, the default audit trail file is opened. When the audit
trail file is opened for write, the default audit trail is an RPC interface to a local Audit daemon.
first_evt_num
The lowest assigned audit event number used by the calling server.
num_of_evts
The number of audit events defined for the calling server.
Output
at
A pointer to an audit trail descriptor. When the audit trail descriptor is no longer needed, it must be released by calling the dce_aud_close( ) function.
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_open( ) function opens the audit trail file specified by the description parameter. If description is NULL, the
function uses the default audit trail which is an RPC interface to the local Audit daemon.
This function must be invoked after the server has finished registering with RPC and before calling rpc_server_listen( ).
If the flags parameter is set to aud_c_trl_open_read, the specified file (description cannot be null in this case) is opened for reading audit records, using the dce_aud_next( ) function. If flags is set to aud_c_trl_open_write, the specified file or the default audit trail device is opened and initialized for appending audit records using the dce_aud_commit( ) function. Only one of the aud_c_trl_open_read and aud_c_trl_open_write flags may be specified in any call to dce_aud_open( ). If the flags parameter is set to aud_c_trl_ss_wrap, the audit trail operation is set to wrap mode. The aud_c_trl_ss_wrap flag has meaning only if you specify the aud_c_trl_open_write flag.
If the audit trail specified is a file and the calling server does not have the read and write permissions to the file, a NULL pointer is returned in at, and status is set to aud_s_cannot_open_trail_file_rc. The same values will be returned if the default audit trail file is used (that is, through an audit daemon) and if the calling server is not authorized to use the audit daemon to log records.
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 successful.
aud_s_trl_invalid_open_flags
The flags argument must include either aud_c_trl_open_read or aud_c_trl_open_write flag, but not both.
aud_s_cannot_open_dmn_binding_file
The local audit daemon trail file is designated, but the daemon's binding file cannot be opened.
Status codes passed from sec_login_get_current_context( )
When the local audit daemon trail file is designated, a login context is needed for making secure audit logging RPC to
the audit daemon.
aud_s_cannot_open_dmn_identity_file
The local audit daemon trail file is designated, but the daemon's identity file cannot be opened.
Status codes passed from rpc_binding_set_auth_info( ).
When the local audit daemon trail file is designated, dce_aud_open( ) sets authentication information in the RPC
binding handle for making secure audit logging RPC to the audit daemon. This is done by calling rpc_binding_set_auth_info(~).
aud_s_cannot_open_trail_file_rc
Cannot open a local trail file.
aud_s_cannot_allocate_memory
Memory allocation failed.
aud_s_cannot_init_trail_mutex
Audit trail mutex initialization failed.
Status codes passed from rpc_server_inq_bindings( )
When filtering is turned on, dce_aud_open( ) gets the caller's RPC bindings to be used for registering an RPC
interface in receiving filter update notification from the local audit daemon. This is done by calling rpc_server_inq_bindings( ).
Status codes passed from rpc_binding_to_string_binding( )
When filtering is turned on, the caller's RPC bindings are converted to string bindings before they are stored in a
file. This is done by calling rpc_binding_to_string_binding( ).
aud_s_cannot_mkdir
Cannot create a directory for storing the bindings file for the filter update notification interface.
Related Information
Functions:
dce_aud_start_with_server_binding(3sec)