/sys$common/syshlp/helplib.hlb System Services, $CHECK PRIVILEGE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Determines whether the caller has the specified privileges
    or identifier. In addition to checking for a privilege or an
    identifier, $CHECK_PRIVILEGE determines if the caller's use of
    privilege needs to be audited.

    Format

      SYS$CHECK_PRIVILEGE  [efn] ,prvadr ,[altprv] ,[flags] ,[itmlst]

                           ,[audsts] ,[astadr] ,[astprm]

    C Prototype

      int sys$check_privilege  (unsigned int efn, struct _generic_64

                               *prvadr, struct _generic_64

                               *altprv, unsigned int flags, void

                               *itmlst, unsigned int *audsts, void

                               (*astadr)(__unknown_params), int

                               astprm);

    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, $CHECK_PRIVILEGE uses only the low-order byte. If
    efn is not specified, event flag 0 is used.

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

 prvadr

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    The privilege, privileges, or identifier that the calling process
    must possess.

    The prvadr argument is either the address of a quadword bit
    array, where each bit corresponds to a privilege, or the address
    of a quadword identifier.

    When the array lists privileges, each bit has a symbolic name.
    The $PRVDEF macro defines these names. You form the bit array
    by specifying the symbolic name of each desired privilege in a
    logical OR operation. See the $SETPRV system service for the
    symbolic name and description of each privilege.

    If the caller passes an identifier, the caller must set the
    NSA$M_IDENTIFIER bit in the flags longword. The identifier
    structure is defined by the $KGBDEF macro. The identifier
    attributes (KGB$) are reserved for future use and should be set
    to 0.

 altprv

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Alternate privilege mask to check against. The altprv argument
    is the address of a quadword privilege mask, where each bit
    corresponds to a privilege. This argument and the flags NSA$M_
    AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually
    exclusive.

    With this argument, $CHECK_PRIVILEGE uses the supplied set of
    privileges instead of the current, active privileges. Each bit
    in the mask has a symbolic name, defined by the $PRVDEF macro.
    You form the bit array by specifying the symbolic name of each
    desired privilege in a logical OR operation. See the $SETPRV
    system service for the symbolic name and description of each
    privilege.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Flags that specify options for the $CHECK_PRIVILEGE 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. Be aware that the flags NSA$M_
    AUTHPRIV, NSA$M_IDENTIFIER, and NSA$M_PROCPRIV are mutually
    exclusive; therefore, you can specify only one of these flag
    options.

    Symbolic Name      Description

    NSA$M_AUTHPRIV     Checks the authorized privileges of the
                       process instead of the current (active)
                       privileges.
    NSA$M_FLUSH        Specifies that all messages in the audit
                       server buffer be written to the audit log
                       file.
    NSA$M_IDENTIFIER   Interprets the prvadr argument as the address
                       of an identifier instead of a privilege mask.
    NSA$M_INTERNAL     Specifies that the $CHECK_PRIVILEGE 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
                       Compaq.
    NSA$M_MANDATORY    Specifies that an audit is to be performed,
                       regardless of system alarm and audit settings.
    NSA$M_PROCPRIV     Checks the permanent privileges of the
                       process, instead of the privileges in the
                       current (active) mask.
    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 Compaq.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying additional security auditing information
    to be included in any security audit that is generated by the
    service. The itmlst argument is the address of a list of item
    descriptors, each of which describes an item of information. The
    list of item descriptors is terminated by a longword of 0.

    Refer to the OpenVMS System Services Reference Manual to view the
    item code diagram and descriptor fields table.

 audsts

    OpenVMS usage:cond_value_type
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword condition value that receives a 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
    $CHECK_PRIVILEGEW 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 argument is written. 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
    $CHECK_PRIVILEGE.

 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.