 |
OpenVMS System Services Reference Manual
Setting the prmflg argument to nonzero changes
privilege bits in both the CURPRIV mask and the PROCPRIV mask.
prvprv
| OpenVMS usage: |
mask_privileges |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Privileges previously possessed by the calling process. The
prvprv argument is the address of a quadword bit
vector wherein each bit corresponds to a privilege that was previously
either enabled or disabled. If you do not specify
prvprv or assign it the value 0, the previous
privilege mask is not returned.
Description
The Set Privileges service enables or disables specified privileges for
the calling process.
The operating system maintains four separate privilege masks for each
process:
- AUTHPRIV---Privileges that the process is authorized to enable, as
designated by the system manager or the process creator. The AUTHPRIV
mask never changes during the life of the process.
- PROCPRIV---Privileges that are designated as permanently enabled
for the process. The PROCPRIV mask can be modified by $SETPRV.
- IMAGPRIV---Privileges with which the current image is installed.
- CURPRIV---Privileges that are currently enabled. The CURPRIV mask
can be modified by $SETPRV.
When a process is created, its AUTHPRIV, PROCPRIV, and CURPRIV masks
have the same contents. Whenever a system service (other than $SETPRV)
must check the process privileges, that service checks the CURPRIV mask.
When a process runs an installed image, the privileges with which that
image was installed are enabled in the CURPRIV mask. When the installed
image exits, the PROCPRIV mask is copied to the CURPRIV mask.
The $SETPRV service can set bits only in the CURPRIV and PROCPRIV mask,
but $SETPRV checks the AUTHPRIV mask to see whether a process can set
specified privilege bits in the CURPRIV or PROCPRIV masks.
Consequently, a process can give itself the SETPRV privilege only if
this privilege is enabled in the AUTHPRIV mask.
You can obtain each of a process's four privilege masks by calling the
$GETJPI (Get Job/Process Information) service and specifying the
desired privilege mask or masks as item codes in the
itmlst argument. You construct the item code for a
privilege mask by prefixing the name of the privilege mask with the
characters JPI$_ (for example, JPI$_CURPRIV is the item code
for the current privilege mask).
The DCL command SET PROCESS/PRIVILEGES also enables or disables
specified privileges; refer to the OpenVMS DCL Dictionary for details.
Required Access or Privileges
To set a privilege permanently, the calling process must be authorized
to set the specified privilege, or the process must be executing in
kernel or executive mode.
To set a privilege temporarily, one of the following three conditions
must be true:
- The calling process must be authorized to set the specified
privilege.
- The calling process must be executing in kernel or executive mode.
- The image currently executing must be one that was installed with
the specified privilege.
Required Quota
None
Related Services
$CANEXH, $CMKRNL, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI,
$GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETRWM,
$SUSPND, $WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. All privileges were enabled or
disabled as specified.
|
|
SS$_NOTALLPRIV
|
The service completed successfully. Not all specified privileges were
enabled; see the Description section for details.
|
|
SS$_ACCVIO
|
The privilege mask cannot be read or the previous privilege mask cannot
be written by the caller.
|
|
SS$_IVSTSFLG
|
You specified a value other than 1 or 0 in either the
prmflg argument or the
enblfg argument.
|
$SETRWM
Allows a process to specify what action system services should take
when system resources required for their execution are unavailable.
Caution
Disabling resource waiting should be performed with caution, as doing
so can have unexpected effects on constituent sharable images and
runtime libraries.
|
Format
SYS$SETRWM [watflg]
C Prototype
int sys$setrwm ( char watflg);
Argument
watflg
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Indicator specifying whether system services should wait for required
resources. The watflg argument is a longword value.
The value 0 (the default) specifies that system services should wait
until resources needed for their execution become available. The value
1 specifies that system services should return failure status
immediately when resources needed for their execution are unavailable.
The operating system enables resource wait mode for all processes. You
can disable resource wait mode only by calling $SETRWM.
If resource wait mode is disabled, it remains disabled until it is
explicitly reenabled or until the process is deleted.
Description
The Set Resource Wait Mode service allows a process to specify what
action system services should take when system resources required for
their execution are unavailable.
When resource wait mode is enabled, system services wait for the
required system resources to become available and then continue
execution. When resource wait mode is disabled, system services return
to the caller when required system resources are unavailable. The
condition value returned by $SETRWM indicates whether resource wait
mode was previously enabled or previously disabled.
The following system resources and process quotas are affected by
resource wait mode:
- System dynamic memory
- UNIBUS adapter map registers
- Direct I/O limit (DIOLM) quota
- Buffered I/O limit (BIOLM) quota
- Buffered I/O byte count limit (BYTLM) quota
Caution
Due to the process-wide implications of resource waiting, disabling
resource waiting should be performed with caution.
Disabling resource wait mode can have unexpected effects on libraries
or shareable images upon which your application may be directly or
indirectly dependent. If resource waiting is disabled, these
constituent libraries or shareable images may not perform as expected.
It is possible that these constituent components are coded to assume
resource waiting is enabled; therefore, they may not be coded to
receive various quota-related errors such as SS$_EXQUOTA.
Note that you should have full control over the entire program context
down to the system calls before disabling resource wait mode.
|
Required Access or Privileges
None
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,
$HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SUSPND,
$WAKE
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. Resource wait mode was previously
enabled.
|
|
SS$_WASSET
|
The service completed successfully. Resource wait mode was previously
disabled.
|
$SETSHLV
Controls whether a process automatically unshelves files.
Format
SYS$SETSHLV [pidadr] ,[prcnam] ,[shlvflg]
C Prototype
int sys$setshlv (unsigned int *pidadr, void *prcnam, unsigned int
shlvflg);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process. The
pidadr argument is the address of the PID. The
pidadr argument can only refer to a process running on
the local node. You cannot modify a process on a remote node.
You must specify the pidadr argument to modify a
process whose UIC group number is different from that of the calling
process.
prcnam
| OpenVMS usage: |
process_name |
| type: |
character--coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Process name of the process. The prcnam argument is
the address of a character string descriptor pointing to the process
name. You identify a process with a 1- to 15-character string.
You can only use the prcnam argument to modify a
process in the same UIC group as the calling process. To modify a
process in another UIC group, you must specify the
pidadr argument.
shlvflg
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Value specifying whether automatic unshelving is to be turned on or
off. The shlvflg argument is a longword containing
this value. The value 0 turns automatic unshelving on. The value 1
turns automatic unshelving off.
Description
The Set Automatic Unshelving service controls whether a process
automatically unshelves files.
The pidadr and prcnam default to the
current process. If the longword at address pidadr is
0, the PID of the target process is returned.
The setting for automatic unshelving is inherited by subprocesses.
The DCL command SET PROCESS/[NO]AUTOUNSHELVE also controls automatic
unshelving for a process; refer to the OpenVMS DCL Dictionary for details.
Required Access or Privileges
Depending on the operation, the calling process might need one of the
following privileges to use $SETSHLV:
- GROUP privilege to modify a process in the same group, unless the
target process has the same UIC as the calling process.
- WORLD privilege to modify any process in the system.
Required Quota
None
Related Services
$GETJPI
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. Automatic unshelving was previously
on.
|
|
SS$_WASSET
|
The service completed successfully. Automatic unshelving was previously
off.
|
|
SS$_ACCVIO
|
An argument was not accessible by the caller.
|
|
SS$_BADPARAM
|
The
shlvflg argument was invalid.
|
|
SS$_IVLOGNAM
|
The
prcnam argument was invalid. The process name string
had either 0 characters or more than 15 characters.
|
|
SS$_NONEXPR
|
The specified process did not exist, or the specified process
identification was invalid.
|
|
SS$_NOPRIV
|
The caller did not have the privilege to modify other processes.
|
|
SS$_REMOTE_PROC
|
The specified process was not on the local node. The service cannot
modify a process on a remote node.
|
$SETSTK
Allows a process to change the size of its supervisor, executive, and
kernel stacks by altering the values in the stack limit and base arrays
held in P1 (per-process) space.
Format
SYS$SETSTK inadr ,[retadr] ,[acmode]
C Prototype
int sys$setstk (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode);
Arguments
inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Range of addresses that express the stack's new limits. The
inadr argument is the address of a 2-longword array
containing, in order, the address of the top of the stack and the
address of the base of the stack. Because stacks in P1 space expand
from high to low addresses, the address of the base of the stack must
be greater than the address of the top of the stack.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Range of addresses that express the stack's previous limits. The
retadr argument is the address of a 2-longword array
into which $SETSTK writes, in the first longword, the previous address
of the top of the stack and, in the second longword, the previous
address of the base of the stack.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode of the stack to be altered. The acmode
argument is a longword containing the access mode. The $PSLDEF macro
defines symbols for the four access modes. The most privileged access
mode used is the access mode of the caller.
If acmode specifies user mode, $SETSTK performs no
operation and returns the SS$_NORMAL condition value.
Description
The Set Stack Limits service allows a process to change the size of its
supervisor, executive, and kernel stacks by altering the values in the
stack limit and base arrays held in P1 (per-process) space.
Required Access or Privileges
The calling process can adjust the size of stacks only for access modes
that are equal to or less privileged than the access mode of the
calling process.
Required Quota
None
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,
$LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,
$UPDSECW
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The input address array cannot be read by the caller; the input range
is invalid; or the return address array cannot be written by the caller.
|
$SETSWM
Allows a process to control whether it can be swapped out of the
balance set.
Format
SYS$SETSWM [swpflg]
C Prototype
int sys$setswm (char swpflg);
Argument
swpflg
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Indicator specifying whether the process can be swapped. The
swpflg argument is a longword value. The value 0 (the
default) enables process swap mode, meaning the process can be swapped.
The value 1 disables process swap mode, meaning the process cannot be
swapped.
Description
The Set Process Swap Mode service allows a process to control whether
it can be swapped out of the balance set.
When the process swap mode is enabled, the process can be swapped out;
when disabled, the process remains in the balance set until (1) process
swap mode is reenabled or (2) the process is deleted.
The $SETSWM service returns a condition value indicating whether
process swap mode was enabled or disabled prior to the call to $SETSWM.
Required Access or Privileges
To change its process swap mode, the calling process must have PSWAPM
privilege.
Required Quota
None
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,
$LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $ULKPAG, $ULWSET, $UPDSEC,
$UPDSECW
To lock some but not necessarily all process pages into the balance
set, use the Lock Pages in Memory ($LCKPAG) service.
For more information, refer to the chapter on memory management in the
OpenVMS Programming Concepts Manual.
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. The process was not previously
locked in the balance set.
|
|
SS$_WASSET
|
The service completed successfully. The process was previously locked
in the balance set.
|
|
SS$_NOPRIV
|
The process does not have the necessary PSWAPM privilege.
|
$SETUAI
Modifies the user authorization file (UAF) record for a specified user.
Format
SYS$SETUAI [nullarg] ,[contxt] ,usrnam ,itmlst ,[nullarg] ,[nullarg]
,[nullarg]
C Prototype
int sys$setuai (unsigned int efn, unsigned int *contxt, void *usrnam,
void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int
astprm);
Arguments
nullarg
| OpenVMS usage: |
null_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Placeholding argument reserved to Compaq.
contxt
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
A longword used to maintain authorization file context. The
contxt argument is the address of a longword to
receive a $SETUAI context value. On the initial call, this longword
should contain the value --1. On subsequent calls, the value of the
contxt argument from the previous call should be
passed back in.
usrnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the user whose UAF record is modified. The
usrnam argument is the address of a descriptor
pointing to a character text string containing the user name. The user
name string can contain a maximum of 32 alphanumeric characters.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying which information from the specified UAF record is
to be modified. The itmlst argument is the address of
a list of one or more item descriptors, each of which specifies an item
code. The item list is terminated by the item code 0 or by the longword
0.
The following diagram depicts the format of a single item descriptor:
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Buffer length
|
A word specifying the length (in bytes) of the buffer in which $SETUAI
is to write the information. The length of the buffer varies, depending
on the item code specified in the item code field of the item
descriptor, and is given in the description of each item code. If the
value of the buffer length field is too small, $SETUAI truncates the
data.
|
|
Item code
|
A word containing a user-supplied symbolic code specifying the item of
information that $SETUAI is to set. The $UAIDEF macro defines these
codes.
|
|
Buffer address
|
A longword address of the buffer that specifies the information to be
set by $SETUAI.
|
|
Return length address
|
A longword containing the user-supplied address of a word in which
$SETUAI writes the length in bytes of the information it actually set.
|
The symbolic codes have the following format:
Item Codes
UAI$_ACCOUNT
Sets, as a blank-padded 32-character string, the account name of the
user.
An account name can include up to 8 characters. Because the account
name is a blank-filled string, however, the buffer length field of the
item descriptor should specify 32 (bytes).
UAI$_ASTLM
Sets the AST queue limit.
Because this decimal number is a word in length, the buffer length
field in the item descriptor should specify 2 (bytes).
UAI$_BATCH_ACCESS_P
Sets, as a 3-byte value, the range of times during which batch access
is permitted for primary days. Each bit set represents a 1-hour period,
from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.
The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_BATCH_ACCESS_S
Sets, as a 3-byte value, the range of times during which batch access
is permitted for secondary days. Each bit set represents a 1-hour
period, from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to
midnight.
The buffer length field in the item descriptor should specify 3 (bytes).
UAI$_BIOLM
Sets the buffered I/O count limit.
Because this decimal number is a word in length, the buffer length
field in the item descriptor should specify 2 (bytes).
UAI$_BYTLM
Sets the buffered I/O byte limit.
Because the buffered I/O count limit is a longword decimal number, the
buffer length field in the item descriptor should specify 4 (bytes).
UAI$_CLITABLES
Sets, as a character string, the name of the user-defined CLI table for
the account, if any.
Because the CLI table name can include up to 31 characters plus a
size-byte prefix, the buffer length field of the item descriptor should
specify 32 (bytes).
UAI$_CPUTIM
Sets the maximum CPU time limit (per session) for the process in
10-millisecond units.
Because the maximum CPU time limit is a longword decimal number, the
buffer length field in the item descriptor should specify 4 (bytes).
UAI$_DEFCLI
Sets, as an OpenVMS RMS file name component, the name of the command
language interpreter used to execute the specified batch job. The file
specification set assumes the device name and directory SYS$SYSTEM and
the file type .EXE.
Because a file name can include up to 31 characters plus a size-byte
prefix, the buffer length field in the item descriptor should specify
32 (bytes).
UAI$_DEFDEV
Sets, as a 1- to 31-character string, the name of the default device.
Because the device name string can include up to 31 characters plus a
size-byte prefix, the buffer length field in the item descriptor should
specify 32 (bytes).
UAI$_DEFDIR
Sets, as a 1- to 63-character string, the name of the default directory.
Because the directory name string can include up to 63 characters plus
a size-byte prefix, the buffer length field in the item descriptor
should specify 64 (bytes).
UAI$_DEF_PRIV
Sets, as a quadword value, the default privileges for the user.
Because the default privileges are set as a quadword value, the buffer
length field in the item descriptor should specify 8 (bytes).
UAI$_DFWSCNT
Sets, in pages (on VAX systems) or pagelets (on Alpha systems), the
default working set size.
Because the default working set size is a longword decimal number, the
buffer length field in the item descriptor should specify 4 (bytes).
UAI$_DIALUP_ACCESS_P
Sets, as a 3-byte value, the range of times during which dialup access
is permitted for primary days. Each bit set represents a 1-hour period,
from bit 0 as midnight to 1 a.m., to bit 23 as 11 p.m. to midnight.
|
