On Alpha and Integrity server systems, allows modification of
the user capability set for a specified kernel thread, or for the
global user capability process default.
This service accepts 64-bit addresses.
Format
SYS$PROCESS_CAPABILITIES [pidadr] [,prcnam] [,select_mask]
[,modify_mask] [,prev_mask] [,flags]
C Prototype
int sys$process_capabilities (unsigned int *pidadr, void
*prcnam, struct _generic_64
*select_mask, struct _generic_64
*modify_mask, struct _generic_64
*prev_mask, struct _generic_64
*flags);
1 – Arguments
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Process identification (PID) of a kernel thread whose user
capability mask is to be modified or returned. The pidadr
argument is the 32- or 64-bit address of a longword that contains
the PID.
Process selection is made through a combination of the pidadr and
prcnam arguments. If neither are specified or if both have a zero
value, the service operations are made to the user capability
mask of the current kernel thread of the calling process. The
pidadr argument takes precedence over the prcnam argument where
both are supplied in the service call.
If the constant CAP$M_FLAG_DEFAULT_ONLY is specified in flags,
then the user portion of the default process user capability
mask is modified or returned instead, regardless of the values
specified in pidadr.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Process name of the process whose user capability mask is to
be modified or returned. The prcnam argument is the 32- or 64-
bit address of a character string descriptor pointing to the
process name string. A process can be identified with a 1- to
15-character string. The service operations are made to the user
capability mask of the initial thread of the specified process.
You can use the prcnam argument only if the process identified
by the descriptor has the same UIC group number as the calling
process. To obtain information about processes in other groups,
the pidadr argument must be used.
If pidadr and prcnam are both specified, then prcnam is ignored.
If neither argument is specified, then the context of the current
kernel thread of the calling process is modified or returned.
select_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying which bits of the specified process' user
capability mask are to be modified. The select_mask argument
is the 32- or 64-bit address of a quadword bit vector wherein a
bit, when set, specifies that the corresponding user capability
is to be modified.
The individual user capability bits in select_mask can be
referenced by their symbolic bit constant names, CAP$M_USER1
through CAP$M_USER16. These constants (not zero-relative) specify
the position in the mask quadword that corresponds to the bit
name. Multiple capabilities can be selected by ORing together the
appropriate bits.
Alternatively, the constant CAP$K_ALL_USER, when specified as the
select_mask argument, selects all user capabilities.
modify_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Mask specifying the settings for those capabilities selected in
the select_mask argument. The modify_mask argument is the 32- or
64-bit address of a quadword bit vector wherein a bit, when set,
specifies that the corresponding user capability is to be added
to the specified kernel thread; when clear, the corresponding
user capability is to be removed.
The symbolic bit constants CAP$M_USER1 through CAP$M_USER16 can
be used to modify the appropriate bit position in modify_mask.
Multiple capabilities can be modified by ORing together the
appropriate bits.
To add a specific user capability to a kernel thread, that bit
position must be set in both select_mask and modify_mask. To
remove a specific user capability from a kernel thread, that bit
position must be set in select_mask and clear in modify_mask.
The symbolic constant CAP$K_ALL_USER_ADD, when specified in
modify_mask, indicates that all capabilities specified in
select_mask are to be added to the appropriate capability set.
The symbolic constant CAP$K_ALL_USER_REMOVE indicates that all
specified capabilities are to be removed from the set.
prev_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
Previous user capability mask for the specified process or thread
before execution of this call to $PROCESS_CAPABILITIES. The
prev_mask argument is the 32- or 64-bit address of a quadword
into which $PROCESS_CAPABILITIES writes the previous bit mask.
If CAP$M_FLAG_DEFAULT_ONLY is set in the flags argument, then
prev_mask will contain the user portion of the global default
capability mask.
flags
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference
Options selected for the user capability modification. The flags
argument is a quadword bit vector wherein a bit corresponds to an
option. Only the bits specified below are used; the remainder of
the quadword bits are reserved and must be zero.
Each option (bit) has a symbolic name, defined by the $CAPDEF
macro. The flags argument is constructed by performing a logical
OR operation using the symbolic names of each desired option.
The following table describes the symbolic name of each option:
Symbolic Name Description
CAP$M_FLAG_DEFAULT_ Indicates that the specified operations
ONLY are to be performed on the global
context cell instead of on a specific
kernel thread. This bit supersedes any
individual kernel thread specified in
pidadr or prcnam. Specifying this bit
constant applies the service operations
to the capabilities for all newly created
processes.
CAP$M_FLAG_PERMANENT Indicates whether to modify the permanent
user process capabilities in addition to
the current image copy. If CAP$M_FLAG_
PERMANENT is set, then both the permanent
and current user process capabilities are
modified. If this bit is clear or flags is
unspecified, then just the current image
process capabilities are modified.
This bit also determines which of the
capability masks are returned in prev_
mask. If set, the permanent mask, used
to reinitialize the current set at image
rundown, is returned. If the bit is clear
or the flags argument is not specified,
the current running mask is returned.
CAP$M_FLAG_CHECK_CPU Determines whether the kernel thread can
be left in a nonrunnable state under some
circumstances. No operation of this
service will allow a transition from
runnable to blocked state; however, if
the kernel thread is already at a blocked
state, this bit determines whether the
result of the operation must leave it
runnable. If CAP$M_FLAG_CHECK_CPU is set
or flags is unspecified, the kernel thread
will be checked to ensure it can safely
run on one of the CPUs in the active set;
otherwise, any state operations on kernel
threads already in a blocked state will be
allowed.
CAP$M_PURGE_WS_IF_ Causes the working set of the process
NEW_RAD to be purged if the choice of capability
results in a change to the home RAD of the
process.