getpriority(3C) Standard C Library Functions getpriority(3C)NAME
getpriority, setpriority - get or set process scheduling priority
SYNOPSIS
#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 argu‐
ments. The which argument can be one of the following values:
PRIO_PROCESS, PRIO_PGRP, PRIO_USER, PRIO_GROUP, PRIO_SESSION, PRIO_LWP,
PRIO_TASK, PRIO_PROJECT, PRIO_ZONE, or PRIO_CONTRACT, indicating that
the who argument is to be interpreted as a process ID, a process group
ID, an effective user ID, an effective group ID, a session ID, an lwp
ID, a task ID, a project ID, a zone ID, or a process contract ID,
respectively. A 0 value for the who argument specifies the current
process, process group, or user. A 0 value for the who argument is
treated as valid group ID, session ID, lwp ID, task ID, project ID,
zone ID, or process contract ID. A P_MYID value for the who argument
can be used to specify the current group, session, lwp, task, project,
zone, or process contract, respectively.
If more than one process is specified, getpriority() returns the high‐
est priority (lowest numerical value) pertaining to any of the speci‐
fied processes, and setpriority() sets the priorities of all of the
specified processes to the specified value.
The default priority is 0; negative priorities cause more favorable
scheduling. The range of valid priority values is [−20, 20]. If the
value specified to setpriority() is less than the system's lowest sup‐
ported 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.
Only a process with appropriate privileges can raise its priority (that
is, assign a lower numerical priority value).
Any processes or threads using SCHED_FIFO or SCHED_RR is unaffected by
a call to setpriority(). This is not considered an error. A process
that subsequently reverts to SCHED_OTHER need not have its priority
affected by such a setpriority() call.
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.
ERRORS
The getpriority() and setpriority() functions will fail if:
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, user ID, group ID, session ID,
lwp ID, task ID, project ID, or zone ID.
In addition, setpriority() may fail if:
EPERM A process was located, but neither the real nor effec‐
tive user ID of the executing process is the privileged
user or match the effective user ID of the process
whose priority is being changed.
EACCES 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.
EXAMPLES
Example 1: Example using getpriority()
The following example returns the current scheduling priority for the
process ID returned by the call to getpid(2).
#include <sys/resource.h>
...
int which = PRIO_PROCESS;
id_t pid;
int ret;
pid = getpid();
ret = getpriority(which, pid);
Example 2: Example using setpriority()
The following example sets the priority for the current process ID to
-20.
#include <sys/resource.h>
...
int which = PRIO_PROCESS;
id_t pid;
int priority = -20;
int ret;
pid = getpid();
ret = setpriority(which, pid, priority);
USAGE
The effect of changing the scheduling priority can vary depending on
the process-scheduling algorithm in effect.
Because getpriority() can return −1 on successful completion, it is
necessary to set errno to 0 prior to a call to getpriority(). If get‐
priority() returns −1, then errno can be checked to see if an error
occurred or if the value is a legitimate priority.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Standard │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOnice(1), renice(1), fork(2), sched_get_priority_max(3RT),
sched_setscheduler(3RT), attributes(5), standards(5)SunOS 5.10 19 Jul 2004 getpriority(3C)
