1GETPRIORITY(P) POSIX Programmer's Manual GETPRIORITY(P)
2
6 getpriority, setpriority - get and set the nice value
7
9 #include <sys/resource.h>
10 int getpriority(int which, id_t who);
12 int setpriority(int which, id_t who, int value);
13
16 The getpriority() function shall obtain the nice value of a process,
17 process group, or user. The setpriority() function shall set the nice
18 value of a process, process group, or user to value+ {NZERO}.
19 Target processes are specified by the values of the which and who argu‐
21 ments. The which argument may be one of the following values:
22 PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, indicating that the who argument
23 is to be interpreted as a process ID, a process group ID, or an effec‐
24 tive user ID, respectively. A 0 value for the who argument specifies
25 the current process, process group, or user.
26 The nice value set with setpriority() shall be applied to the process.
28 If the process is multi-threaded, the nice value shall affect all sys‐
29 tem scope threads in the process.
30 If more than one process is specified, getpriority() shall return value
32 {NZERO} less than the lowest nice value pertaining to any of the speci‐
33 fied processes, and setpriority() shall set the nice values of all of
34 the specified processes to value+ {NZERO}.
35 The default nice value is {NZERO}; lower nice values shall cause more
37 favorable scheduling. While the range of valid nice values is
38 [0,{NZERO}*2-1], implementations may enforce more restrictive limits.
39 If value+ {NZERO} is less than the system's lowest supported nice
40 value, setpriority() shall set the nice value to the lowest supported
41 value; if value+ {NZERO} is greater than the system's highest supported
42 nice value, setpriority() shall set the nice value to the highest sup‐
43 ported value.
44 Only a process with appropriate privileges can lower its nice value.
46 Any processes or threads using SCHED_FIFO or SCHED_RR shall be unaf‐
48 fected by a call to setpriority(). This is not considered an error. A
49 process which subsequently reverts to SCHED_OTHER need not have its
50 priority affected by such a setpriority() call.
51 The effect of changing the nice value may vary depending on the
53 process-scheduling algorithm in effect.
54 Since getpriority() can return the value -1 on successful completion,
56 it is necessary to set errno to 0 prior to a call to getpriority(). If
57 getpriority() returns the value -1, then errno can be checked to see if
58 an error occurred or if the value is a legitimate nice value.
59
61 Upon successful completion, getpriority() shall return an integer in
62 the range -{NZERO} to {NZERO}-1. Otherwise, -1 shall be returned and
63 errno set to indicate the error.
64 Upon successful completion, setpriority() shall return 0; otherwise, -1
66 shall be returned and errno set to indicate the error.
67
69 The getpriority() and setpriority() functions shall fail if:
70 ESRCH No process could be located using the which and who argument
72 values specified.
73 EINVAL The value of the which argument was not recognized, or the value
75 of the who argument is not a valid process ID, process group ID,
76 or user ID.
77 In addition, setpriority() may fail if:
80 EPERM A process was located, but neither the real nor effective user
82 ID of the executing process match the effective user ID of the
83 process whose nice value is being changed.
84 EACCES A request was made to change the nice value to a lower numeric
86 value and the current process does not have appropriate privi‐
87 leges.
88 The following sections are informative.
91
93 Using getpriority()
94 The following example returns the current scheduling priority for the
95 process ID returned by the call to getpid().
96 #include <sys/resource.h>
99 ...
100 int which = PRIO_PROCESS;
101 id_t pid;
102 int ret;
103 pid = getpid();
106 ret = getpriority(which, pid);
107 Using setpriority()
109 The following example sets the priority for the current process ID to
110 -20.
111 #include <sys/resource.h>
114 ...
115 int which = PRIO_PROCESS;
116 id_t pid;
117 int priority = -20;
118 int ret;
119 pid = getpid();
122 ret = setpriority(which, pid, priority);
123
125 The getpriority() and setpriority() functions work with an offset nice
126 value (nice value -{NZERO}). The nice value is in the range
127 [0,2*{NZERO} -1], while the return value for getpriority() and the
128 third parameter for setpriority() are in the range [-{NZERO},{NZERO}
129 -1].
130
132 None.
133
135 None.
136
138 nice() , sched_get_priority_max() , sched_setscheduler() , the Base
139 Definitions volume of IEEE Std 1003.1-2001, <sys/resource.h>
140
142 Portions of this text are reprinted and reproduced in electronic form
143 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
144 -- Portable Operating System Interface (POSIX), The Open Group Base
145 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
146 Electrical and Electronics Engineers, Inc and The Open Group. In the
147 event of any discrepancy between this version and the original IEEE and
148 The Open Group Standard, the original IEEE and The Open Group Standard
149 is the referee document. The original Standard can be obtained online
150 at http://www.opengroup.org/unix/online.html .
151IEEE/The Open Group 2003 GETPRIORITY(P)