getpriority (BPX1GPY, BPX4GPY) — Get the scheduling priority of a process

Function

The getpriority callable service gets the scheduling priority of a specific process or group of processes.

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 = Indicates that the Who parameter is to be interpreted as a process ID
• PRIO_PGRP = Indicates that the Who parameter is to be interpreted as a process group ID
• PRIO_USER = Indicates that 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 obtained. 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.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the getpriority service returns the priority value of the specified process, or -1 if it is not successful.

Because the getpriority service can return the value -1 on successful completion, it is necessary to set the Return_code parameter to 0 before a call to the getpriority service. If getpriority returns the value -1, the Return_code parameter can be checked to see if the service was successful, or if an error occurred.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the getpriority service stores the return code. The getpriority 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 getpriority service can return one of the following values in the Return_code parameter:

Return_code	Explanation
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.
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 getpriority service stores the reason code. The getpriority 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, the lowest priority value found among the specified processes is returned.
2. The setting of a process's priority value has an equivalent effect on a process's nice value, as they both represent the process's relative CPU priority. For example, setting the priority value of a process via the setpriority service to its maximum value (19) has the effect of increasing its nice value to its maximum value (2*NICE_ZERO)-1, and is reflected on the nice, getpriority and setpriority services. The NICE_ZERO constant is defined in BPXYCONS. (See BPXYCONS — Constants used by services.)

Related services

• setpriority (BPX1SPY, BPX4SPY) — Set the scheduling priority of a process
• nice (BPX1NIC, BPX4NIC) — Change the nice value of a process

Characteristics and restrictions

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