chpriority() — Change the scheduling priority of a process

Standards

Standards / Extensions C or C++ Dependencies
z/OS® UNIX both  

Format

#define _OPEN_SOURCE 2
#include <sys/resource.h>

int chpriority(int which, id_t who, int prioritytype, int priority);

General description

The chpriority() function changes the scheduling priority of a process, process group or user.

Processes are specified by the values of the which and who arguments. The which argument may be one of the following values: PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, indicating that the who argument is to be interpreted as a process ID, a process group ID, or a user ID, respectively. A 0 (zero) value for the who argument specifies the current process, process group or user ID.

If more than one process is specified, the chpriority() function changes the priorities of all of the specified processes.

The default priority is 0; negative priorities cause more favorable scheduling. The range of legal priority values is -20 to 19. If the CPRIO_ABSOLUTE value is specified for the prioritytype argument and the priority value specified to chpriority() is less than the system's lowest supported priority value, the system's lowest supported value is used; if it is greater than the system's highest supported value, the system's highest supported value is used. If the CPRIO_RELATIVE value is specified on the prioritytype argument, request for values above or below the legal limits result in the priority value being set to the corresponding limit.

The changing of a process's scheduling priority value has the equivalent effect of a process's nice value, since they both represent the process's relative CPU priority. For example, changing one's scheduling priority value using the chpriority() function to its maximum value (19) has the equivalent effect of increasing one's nice value to its maximum value 2*{NZERO}-1, and will be reflected on the nice(), getpriority(), chpriority(), and setpriority() functions.

Only a process with appropriate privilege can lower its priority. In addition to lowering the priority value, a process with appropriate privilege has the ability to change the priority of any process regardless of the process's saved set-user-ID value.

Returned value

If successful, chpriority() returns 0.

If unsuccessful, chpriority() returns -1 and sets errno to one of the following values:
Error Code
Description
EACCES
The priority is being changed to a lower value and the current process does not have the appropriate privilege.
EINVAL
The value of the which argument was not recognized, or the value of the who argument is not a valid process ID, process group ID or user ID, or the value of the prioritytype argument was not recognized.
ENOSYS
The system does not support this function.
EPERM
A process was located, but the save set-user-ID of the executing process does not match the saved set-user-ID of the process whose priority is to be changed.
ESRCH
No process could be located using the which and who argument values specified.

Related information