setpriority (BPX1SPY, BPX4SPY) — Set the scheduling priority of a process
Function
The setpriority callable service sets the scheduling priority of a process, process group, or user.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1SPY): | 31-bit |
AMODE (BPX4SPY): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
|
AMODE 64 callers use BPX4SPY with the same parameters.
Parameters
- Which
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains a value that indicates how the Who parameter is to be interpreted. This parameter can have one of the following values:- PRIO_PROCESS
- The Who parameter is to be interpreted as a process ID.
- PRIO_PGRP
- The Who parameter is to be interpreted as a process group ID.
- PRIO_USER
- The Who parameter is to be interpreted as a user ID.
The PRIO_ constants are defined in the BPXYCONS macro. See BPXYCONS — Constants used by services.
- Who
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains a value that indicates the exact process ID, process group ID, or user ID whose priority is to be set. The Which parameter indicates how this parameter is to be interpreted. A value of zero for this parameter specifies the current process, process group, or user ID.
- Priority
- Supplied parameter
- Type:
- Signed Integer
- Length:
- Fullword
The name of a fullword that contains a value that indicates the priority value to which the specific process or group of processes is to be set. This value can be an integer in the range of -20 to 19.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the setpriority service returns a value of zero if successful and -1 if it is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the setpriority service stores the return code. The setpriority service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The setpriority service can return one of the following values in the Return_code parameter:Return_code Explanation EACCES The priority is being changed to a lower value, and the current process does not have the appropriate privilege (see Authorization) to do so. EINVAL The value of the Which parameter was not recognized; or the value of the Who parameter is not a valid process ID, process group ID or user ID. EMVSSAF2ERR A security product internal error occurred. Consult the Reason_code parameter for the exact reason for the error. ENOSYS The system does not support this function. Your installation chose not to enable this function. EPERM A process was located, but neither the real nor the effective user ID of the calling process matches the effective user ID of the process whose priority is being changed. ESRCH No process could be located using the Which and Who parameter values that were specified. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the setpriority service stores the reason code. The setpriority service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
Usage notes
- If the supplied Who and Which values specify more than one process, each of the specified processes has its priority value set to the supplied value. If at least one of the specified processes has its priority value successfully changed, the setpriority service returns successfully.
- The priority value of a process is an integer that can be in the range of -20 to 19. If the supplied priority value is outside this range, the process's priority is set to the corresponding limit value. The default priority value for all processes is 0.
- An increase in a process's priority value results in a lower CPU priority for the process. A decrease in a process's priority value results in a higher CPU priority for the process.
- If the supplied priority value would result in a lower priority value for the specified process or processes, the caller must have appropriate privileges. Refer to Authorization for information about appropriate privileges.
- The setting of a process's priority value has a corresponding effect on its nice value because they both represent the process's relative CPU priority. For example, using the setpriority service to set the priority value of a process to its maximum value (19) has the effect of increasing its nice value to its maximum value (2*NICE_ZERO)-1, and this is reflected on the nice, getpriority, and setpriority services. The NICE_ZERO constant is defined in BPXYCONS.
- If the ENOSYS return code is received, your installation does not support this service. Contact your system administrator if you require activation of this service.
- If the supplied Who and Which values specify a process in a multiple process address space, each of the processes in the address space have their priority values set to the supplied value.
- To do the initial system setup for using this service, see Enabling nice(), setpriority(), and chpriority() support in z/OS UNIX System Services Planning.
Related services
Characteristics and restrictions
There are no restrictions on the use of the setpriority service.
Examples
For an example using this callable service, see BPX1SPY (setpriority) example.