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);
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, $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
VSI.
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 VSI.
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.
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 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.