Appends an event message to the system security audit log file or
    sends an alarm to a security operator terminal.

    Format

      SYS$AUDIT_EVENT  [efn] ,[flags] ,itmlst ,[audsts] ,[astadr]

                       ,[astprm]

    C Prototype

      int sys$audit_event  (unsigned int efn, unsigned int flags,

                           void *itmlst, unsigned int *audsts, void

                           (*astadr)(__unknown_params), int astprm);

1  –  Arguments

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag to be set when the audit completes. The
    efn argument is a longword containing the number of the event
    flag; however, $AUDIT_EVENT uses only the low-order byte. If efn
    is not specified, event flag 0 is used.

    Upon request initiation, $AUDIT_EVENT clears the specified event
    flag.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags specifying options for the $AUDIT_EVENT system operation.
    The flags argument is a longword bit mask, where each bit
    corresponds to an option.

    Each flag option has a symbolic name. The $NSADEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    NSA$M_ACL          Specifies an event generated by an Alarm ACE
                       or Audit ACE. This flag is Reserved to VSI.

    NSA$M_FLUSH        Specifies that all messages in the audit
                       server buffer be written to the audit log
                       file.

    NSA$M_INTERNAL     Specifies that the $AUDIT_EVENT call
                       originates in the context of a trusted
                       computing base (TCB) component. The auditing
                       components use this flag to indicate that
                       internal auditing failures should result in a
                       SECAUDTCB bugcheck. This flag is reserved to
                       VSI.

    NSA$M_MANDATORY    Specifies that an audit is to be performed,
                       regardless of system alarm and audit settings.

    NSA$M_NOEVTCHECK   Specifies that an audit is to be performed,
                       regardless of the system alarm or audit
                       settings. This flag is similar to the NSA$M_
                       MANDATORY bit but, unlike the NSA$M_MANDATORY
                       bit, this flag is not reflected in the NSA$W_
                       FLAGS field in the resulting audit record on
                       disk.

    NSA$M_SERVER       Indicates that the call originates in a TCB
                       server process and that the event should be
                       audited regardless of the state of a process-
                       specific, no-audit bit.

                       Trusted servers use this flag to override
                       the no-audit bit when they want to perform
                       explicit auditing on behalf of a client
                       process. This flag is Reserved to VSI.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying information to include in the audit record.
    The itmlst argument is the address of a list of item descriptors.
    The list of item descriptors is terminated by a longword of 0.

    The item list for all calls to $AUDIT_EVENT must include the
    following item codes:

    o  NSA$_EVENT_TYPE

    o  NSA$_EVENT_SUBTYPE

    o  At least one of the NSA$_ALARM_NAME item code or the NSA$_
       AUDIT_NAME item code.

    o  If the event being reported is an object access (NSA$C_MSG_
       OBJ_ACCESS) or an object delete (NSA$C_MSG_OBJ_DELETE), the
       NSA$_FINAL_STATUS, NSA$_ACCESS_DESIRED, and NSA$_OBJECT_CLASS
       item codes must be specified.

    o  If the event being reported is an object create (NSA$C_MSG_
       OBJ_CREATE), the NSA$_FINAL_STATUS and NSA$_OBJECT_CLASS item
       codes must be specified.

    o  If the event being reported is a privilege audit (NSA$C_MSG_
       PRVAUD), the NSA$_PRIVS_USED or the NSA$_PRIVS_MISSING item
       code must be specified.

    o  If the audit event being reported is a deaccess event (NSA$C_
       MSG_OBJ_DEACCESS), the NSA$_OBJECT_CLASS item code must be
       specified.

    The item list is a standard format item list.

    To view the item code diagram and descriptor fields table, see
    the VSI OpenVMS System Services Reference Manual.

 audsts

    OpenVMS usage:cond_value_type
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword condition value that receives the final completion
    status from the operation. If a security audit is required,
    the final completion status represents either the successful
    completion of the resulting security audit or any failing status
    that occurred while the security audit was performed within the
    audit server process.

    The audsts argument is valid only when the service returns
    success and the status is not SS$_EVTNOTENAB. In addition, the
    caller must either make use of the astadr argument or use the
    $AUDIT_EVENTW service before attempting to access audsts.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference
    Asynchronous system trap (AST) routine to be executed after the
    audsts is updated. The astadr argument, which is the address of a
    longword value, is the procedure value of the AST routine.

    The AST routine executes in the access mode of the caller of
    $AUDIT_EVENT.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Asynchronous system trap (AST) parameter passed to the AST
    service routine. The astprm argument is a longword value
    containing the AST parameter.