getpriority(3C)

getpriority, setpriority -- get or set program scheduling priority

Synopsis

   #include <sys/time.h>
   #include <sys/resource.h>
   
   int getpriority(int which, id_t who);
   

   int setpriority(int which, id_t who, int priority);

Description

The getpriority function obtains the current scheduling priority of a process, process group, or user. The setpriority function sets the scheduling priority of a process, process group, or user.

Target 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 value for the who argument specifies the current process, process group, or user.

If more than one process is specified, getpriority returns the highest priority (lowest numerical value) pertaining to any of the specified processes, and setpriority sets the priorities of all of the specified processes to the specified priority value.

The default priority is 0; negative priorities cause more favorable scheduling. If priority is less than -20, a value of -20 is used; if it is greater than 20, a value of 20 is used.

Only a process with appropriate privileges can raise its priority (ie. assign a lower numerical priority value).

Return values

Upon successful completion, getpriority returns an integer in the range from -20 to 20. Otherwise, -1 is returned and errno is set to indicate the error.

Upon successful completion, setpriority returns 0. Otherwise, -1 is returned and errno is set to indicate the error.

Since getpriority can legitimately return the value -1, it is necessary to clear the external variable errno prior to the call, then check it afterward to determine if a -1 return is an error or a legitimate value.

Errors

getpriority and setpriority may return one of the following errors:

ESRCH: No process could be located using the which and who argument values specified.
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.

In addition, setpriority may fail if:

EPERM: A process was located, but neither the real nor effective user ID of the executing process match the effective user ID of the process whose priority is being changed.
EACCESS: A request was made to change the priority to a lower numeric value (that is, to a higher priority) and the current process does not have appropriate privileges

References

fork(2), nice(1), renice(1), renice(1Mbsd)

Notices

It is not possible for the process executing setpriority to lower any other process down to its current priority, without requiring privileged user privileges. getpriority, setpriority

Standards conformance

These routines conform to X/Open System Interfaces and Headers, Issue 4, Version 2.