setpriority(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 set-
priority() function sets the scheduling priority of a pro-
cess, 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, PRIO_USER,
PRIO_GROUP, PRIO_SESSION, PRIO_LWP, PRIO_LWP, or
PRIO_PROJECT, indicating that the who argument is to be
interpreted as a process ID, a process group ID, a user ID,
a group ID, a session ID, an lwp ID, a task ID, or a project
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, or project ID. A P_MYID value for the who
argument can be used to specify the current group, session,
lwp, task, or project, respectively.
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 speci-
fied value.
The default priority is 0; negative priorities cause more
favorable scheduling. While the range of valid priority
values is [-20, 20], implementations may enforce more res-
trictive limits. If the value specified to setpriority() 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.
Only a process with appropriate privileges can raise its
priority (that is, 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. Other-
wise, -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, or project 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.
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 comple-
tion, it is necessary to set errno to 0 prior to a call to
getpriority(). If getpriority() 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 attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Standard |
|_____________________________|_____________________________|
SEE ALSO
nice(1), renice(1), fork(2), attributes(5)
Man(1) output converted with
man2html