 |
HP OpenVMS System Services Reference Manual
$SETPRI
Changes the base priority of the process. The base priority is used to
determine the order in which executable processes are to run.
Format
SYS$SETPRI [pidadr] ,[prcnam] ,pri ,[prvpri] ,[nullarg] ,[nullarg]
C Prototype
int sys$setpri (unsigned int *pidadr, void *prcnam, unsigned int pri,
unsigned int *prvpri, unsigned int *pol, unsigned int *prvpol);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process whose priority is to be
set. The pidadr argument is the address of the PID.
The pidadr argument can refer to a process running on
the local node or a process running on another node in the cluster.
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 whose priority is to be changed. The
prcnam argument is the address of a character string
descriptor pointing to the process name.
A process running on the local node can be identified with a 1- to
15-character string. To identify a process on a particular node on a
cluster, specify the full process name, which includes the node name as
well as the process name. The full process name can contain up to 23
characters.
You can use the prcnam argument only on behalf of
processes in the same UIC group as the calling process. To set the
priority for processes in other groups, you must specify the
pidadr argument.
pri
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
New base priority to be established for the process. The
pri argument is a longword value containing the new
priority. Priorities that are not real time are in the range 0 through
15; real-time priorities are in the range 16 through 31.
If the specified priority is higher than the base priority of the
target process, and if the caller does not have ALTPRI privilege, then
the base priority of the target process is used.
prvpri
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Base priority of the process before the call to $SETPRI. The
prvpri argument is the address of a longword into
which $SETPRI writes the previous base priority of the process.
policy
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
On Alpha and Integrity server systems, address of a longword containing
the new scheduling policy for the process.
The $JPIDEF macro defines the following symbols for the
policy argument:
| Symbol |
Meaning |
|
JPI$K_DEFAULT_POLICY
|
The normal scheduling policy. The priority interval for this policy is
defined as [0..
n], such that priorities [0..15] are interactive and
priorities [16..
n] are real time.
|
|
JPI$K_PSX_FIFO_POLICY
|
POSIX FIFO scheduling policy. The priority interval for this policy is
defined as [
n..
m] real-time priorities.
|
|
JPI$K_PSX_RR_POLICY
|
POSIX round-robin policy. The priority interval for this policy is
defined as [
n..
m] real-time priorities.
|
prvpol
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
On Alpha and Integrity server systems, address of a longword into which
the previous scheduling policy for the process is written. If the
policy argument is null, no change in policy is
requested and prvpol returns the current policy.
The valid priority intervals for specific scheduling policies might
change in the future. Applications should, therefore, not use embedded
numeric constants for scheduling priority, but should use the
appropriate $GETSYI item codes to fetch the legal priority intervals.
The application can then dynamically select a priority value that is
within the interval. The $GETSYI item codes are:
- SYI$_DEF_PRIO_MAX, SYI$_DEF_PRIO_MIN
- SYI$_PSXFIFO_PRIO_MAX, SYI$_PSXFIFO_PRIO_MIN
- SYI$_PSXRR_PRIO_MAX, SYI$_PSXRR_PRIO_MIN
See the Item Codes section of the $GETSYI service description for more
information about these item codes.
nullarg
| OpenVMS usage: |
null_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Placeholding argument reserved to HP.
Description
The Set Priority service changes the base priority of the process or,
optionally, changes the scheduling policy of the process. The base
priority is used to determine the order in which executable processes
are to run.
The scheduling policy denotes the following:
- The basic scheduling discipline (FIFO, round-robin, and so forth).
- The preemption/compensation rules by which a running process is
descheduled in favor of another process and, ultimately, rescheduled.
A source process can modify the priority or scheduling policy of a
target process if any of the following are true:
- The source and target processes are in the same job tree.
- The source and target processes have the same UIC.
- The source process has WORLD privilege enabled.
- The source and target processes are in the same process group.
The value to which the priority of a process can be set can be subject
to limitations. If the source has ALTPRI privilege enabled, the target
can be set to any valid priority. Otherwise, the priority value
specified by the source process is compared to the authorized priority
of the target process and the smaller of the two values is used as the
new base priority of the target process.
If you specify neither the pidadr nor the
prcnam argument, $SETPRI sets the base priority of the
calling process.
If the longword at address pidadr is the value 0, the
PID of the target process is returned.
The base priority of a process remains in effect until specifically
changed or until the process is deleted.
To determine the priority set by the $SETPRI service, use the Get
Job/Process Information ($GETJPI) service.
Required Access or Privileges
Depending on the operation, the calling process might need one of the
following privileges to use $SETPRI:
- GROUP privilege to change the priority of a process in the same
group, unless the target process has the same UIC as the calling
process.
- WORLD privilege to change the priority of any other process in the
system.
- ALTPRI privilege to set any process's priority to a value greater
than the target process's initial base priority. If a process does not
have ALTPRI privilege, the priority value specified by the source
process is compared to the authorized priority of the target process
and the smaller of the two values is used as the new base priority of
the target process.
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,
$HIBER, $PROCESS_SCAN, $RESUME, $SETPRN, $SETPRV, $SETRWM, $SUSPND,
$WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The process name string or string descriptor cannot be read by the
caller, or the process identification or previous priority longword
cannot be written by the caller.
|
|
SS$_ILLPOLICY
|
An invalid scheduling policy was specified.
|
|
SS$_ILLPRIPOL
|
Setting the process to the specified priority and/or policy would
result in an illegal policy/priority combination. The illegal
combination can occur between the SETPRI policy and priority parameters
themselves, or it can occur between either of the parameters and the
current policy and/or priority of the target process.
|
|
SS$_INCOMPAT
|
The remote node is running an incompatible version of the operating
system.
|
|
SS$_IVLOGNAM
|
The process name string has a length of 0 or has more than 15
characters.
|
|
SS$_NONEXPR
|
The specified process does not exist, or an invalid process
identification was specified.
|
|
SS$_NOPRIV
|
The process does not have the privilege to affect other processes.
|
|
SS$_NOSUCHNODE
|
The process name refers to a node that is not currently recognized as
part of the cluster.
|
|
SS$_REMRSRC
|
The remote node has insufficient resources to respond to the request.
(Bring this error to the attention of your system manager.)
|
|
SS$_UNREACHABLE
|
The remote node is a member of the cluster but is not accepting
requests. (This is normal for a brief period early in the system boot
process.)
|
$SETPRN
Allows a process to establish or to change its own process name.
Format
SYS$SETPRN [prcnam]
C Prototype
int sys$setprn (void *prcnam);
Argument
prcnam
| OpenVMS usage: |
process_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Process name to be given to the calling process. The
prcnam argument is the address of a character string
descriptor pointing to a 1- to 15-character process name string. If you
do not specify prcnam, the calling process is given no
name.
Description
The Set Process Name service allows a process to establish or to change
its own process name, which remains in effect until you change it
(using $SETPRN) or until the process is deleted. Process names provide
an identification mechanism for processes executing with the same group
number. A process can also be identified by its process identification
(PID).
Required Access or Privileges
None
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,
$HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRV, $SETRWM, $SUSPND,
$WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The process name string or string descriptor cannot be read by the
caller.
|
|
SS$_DUPLNAM
|
The specified process name duplicates one already specified within that
group.
|
|
SS$_IVLOGNAM
|
The specified process name has a length of 0 or has more than 15
characters.
|
$SETPRT
Allows a process to change the protection on a page or range of pages.
Format
SYS$SETPRT inadr ,[retadr] ,[acmode] ,prot ,[prvprt]
C Prototype
int sys$setprt (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode, unsigned int prot, unsigned char *prvprt);
Arguments
inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Starting and ending virtual addresses of the range of pages whose
protection is to be changed. The inadr argument is the
address of a 2-longword array containing, in order, the starting and
ending process virtual addresses.
Addresses are adjusted up or down to fall on CPU-specific page
boundaries. Only the virtual page number portion of each virtual
address is used; the low-order byte-within-page bits are ignored.
If the starting and ending virtual addresses are the same, the
protection is changed for a single page.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference---array reference or descriptor |
Starting and ending virtual addresses of the range of pages whose
protection was actually changed by $SETPRT. The retadr
argument is the address of a 2-longword array containing, in order, the
starting and ending process virtual addresses.
If an error occurs while the protection is being changed, $SETPRT
writes into retadr the range of pages that were
successfully changed before the error occurred. If no pages were
affected before the error occurred, $SETPRT writes the value --1 into
each longword of the 2-longword array.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the call to $SETPRT. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines symbols for the access modes.
The $SETPRT service uses whichever of the following two access modes is
least privileged: (1) the access mode specified by
acmode or (2) the access mode of the caller. To change
the protection of any page in the specified range, the resultant access
mode must be equal to or more privileged than the access mode of the
owner of that page.
prot
| OpenVMS usage: |
page_protection |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Page protection to be assigned to the specified pages. The
prot argument is a longword value containing the
protection code. Only bits 0 to 3 are used; bits 4 to 31 are ignored.
The $PRTDEF macro defines the following symbolic names for the
protection codes:
| Symbol |
Description |
|
PRT$C_NA
|
No access
|
|
PRT$C_KR
|
Kernel read only
|
|
PRT$C_KW
|
Kernel write
|
|
PRT$C_ER
|
Executive read only
|
|
PRT$C_EW
|
Executive write
|
|
PRT$C_SR
|
Supervisor read only
|
|
PRT$C_SW
|
Supervisor write
|
|
PRT$C_UR
|
User read only
|
|
PRT$C_UW
|
User write
|
|
PRT$C_ERKW
|
Executive read; kernel write
|
|
PRT$C_SRKW
|
Supervisor read; kernel write
|
|
PRT$C_SREW
|
Supervisor read; executive write
|
|
PRT$C_URKW
|
User read; kernel write
|
|
PRT$C_UREW
|
User read; executive write
|
|
PRT$C_URSW
|
User read; supervisor write
|
OpenVMS Alpha and Integrity server systems convert PRT$C_NA to the next
highest protection, kernel-read.
If you specify the protection as the value 0, the protection defaults
to kernel read only.
prvprt
| OpenVMS usage: |
page_protection |
| type: |
byte (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Protection previously assigned to the last page in the range. The
prvprt argument is the address of a byte into which
$SETPRT writes the protection of this page. The prvprt
argument is useful only when protection for a single page is being
changed.
Description
The Set Protection on Pages service allows a process to change the
protection on a page or range of pages.
Required Access or Privileges
None
Required Quota
If a process changes the protection for any pages in a private section
from read only to read/write, $SETPRT uses the paging file (PGFLQUOTA)
quota of the process.
For pages in global sections, the new protection can alter only
copy-on-reference pages.
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,
$LKWSET, $MGBLSC, $PURGWS, $SETSTK, $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 output
address array or the byte to receive the previous protection cannot be
written by the caller; or an attempt was made to change the protection
of a nonexistent page.
|
|
SS$_EXQUOTA
|
The process exceeded its paging file quota while changing a page in a
read-only private section to a read/write page.
|
|
SS$_IVPROTECT
|
The specified protection code has a numeric value of 1, less than 0, or
greater than 15.
|
|
SS$_LENVIO
|
A page in the specified range is beyond the end of the program or
control region.
|
|
SS$_NOPRIV
|
A page in the specified range is in the system address space; an
attempt was made to change the protection of a valid global page, of an
invalid global noncopy-on-reference page, or a PFN global or private
page.
|
|
SS$_PAGOWNVIO
|
The process attempted to change the protection on a page owned by a
more privileged access mode.
|
$SETPRT_64 (Alpha and Integrity servers)
On Alpha and Integrity server systems, allows a process to change the
protection on a page or range of pages.
This service accepts 64-bit addresses.
Format
SYS$SETPRT_64 start_va_64 ,length_64 ,acmode ,prot ,return_va_64
,return_length_64 ,return_prot_64
C Prototype
int sys$setprt_64 (void *start_va_64, unsigned __int64 length_64,
unsigned int acmode, unsigned int prot, void *(*(return_va_64)),
unsigned __int64 *return_length_64, unsigned int *return_prot_64);
Arguments
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address of the range of pages whose protection is
to be changed. The specified virtual address will be rounded down to a
CPU-specific boundary.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space whose protection is to be changed.
The specified length will be rounded up to a CPU-specific page boundary
so that it includes all CPU-specific pages in the requested range.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the call to $SETPRT_64. The
acmode argument is a longword containing the access
mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values for the
four access modes:
| Value |
Symbolic Name |
Access Mode |
|
0
|
PSL$C_KERNEL
|
Kernel
|
|
1
|
PSL$C_EXEC
|
Executive
|
|
2
|
PSL$C_SUPER
|
Supervisor
|
|
3
|
PSL$C_USER
|
User
|
The most privileged access mode used is the access mode of the caller.
To change the protection of any page in the specified range, the
resultant access mode must be equal to or more privileged than the
access mode of the owner of that page.
prot
| OpenVMS usage: |
page_protection |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Page protection to be assigned to the specified pages. The
prot argument is a longword value containing the
protection code. Only bits 0 to 3 are used; bits 4 to 31 are ignored.
The $PRTDEF macro for MACRO-32 and the include file PRTDEF.H for C
define the symbolic names for the protection codes.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The lowest process virtual address of the range of pages whose
protection was actually changed. The return_va_64
argument is the 32- or 64-bit virtual address of a naturally aligned
quadword into which the service returns the virtual address.
return_length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The length of the virtual address range whose protection was actually
changed. The return_length_64 argument is the 32- or
64-bit virtual address of a naturally aligned quadword into which the
service returns the length of the virtual address range in bytes.
return_prot_64
| OpenVMS usage: |
page_protection |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
Protection previously assigned to the last page in the range. The
return_prot_64 argument is the 32- or 64-bit virtual
address of a naturally aligned longword into which $SETPRT_64 writes
the protection of this page. The return_prot_64
argument is useful only when protection for a single page is being
changed.
Description
The Set Protection on Pages service allows a process to change the
protection on a page or range of pages. For pages in a global section,
the new protection can alter only copy-on-reference pages.
|
