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

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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

• nice (BPX1NIC, BPX4NIC) — Change the nice value of a process
• getpriority (BPX1GPY, BPX4GPY) — Get the scheduling priority of a process

Characteristics and restrictions

There are no restrictions on the use of the setpriority service.