]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1980, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
a9cd9cb7 | 4 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
14 | .\" must display the following acknowledgement: | |
15 | .\" This product includes software developed by the University of | |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
8c9302dc | 32 | .\" %%%LICENSE_END |
fea681da MK |
33 | .\" |
34 | .\" @(#)getpriority.2 6.9 (Berkeley) 3/10/91 | |
35 | .\" | |
36 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
37 | .\" Modified 1996-07-01 by Andries Brouwer <aeb@cwi.nl> | |
38 | .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com> | |
c11b1abf | 39 | .\" Modified 2001-10-21 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 40 | .\" Corrected statement under EPERM to clarify privileges required |
c11b1abf | 41 | .\" Modified 2002-06-21 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 42 | .\" Clarified meaning of 0 value for 'who' argument |
c11b1abf | 43 | .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 44 | .\" |
6f52c9d4 MK |
45 | .\" FIXME Oct 2008: Denys Vlasenko is working on a PRIO_THREAD feature that |
46 | .\" is likely to get included in mainline; this will need to be documented. | |
47 | .\" | |
96d1766a | 48 | .TH GETPRIORITY 2 2013-02-12 "Linux" "Linux Programmer's Manual" |
fea681da MK |
49 | .SH NAME |
50 | getpriority, setpriority \- get/set program scheduling priority | |
51 | .SH SYNOPSIS | |
52 | .B #include <sys/time.h> | |
53 | .br | |
54 | .B #include <sys/resource.h> | |
55 | .sp | |
56 | .BI "int getpriority(int " which ", int " who ); | |
57 | .br | |
58 | .BI "int setpriority(int " which ", int " who ", int " prio ); | |
59 | .SH DESCRIPTION | |
60 | The scheduling priority of the process, process group, or user, as | |
61 | indicated by | |
62 | .I which | |
63 | and | |
64 | .I who | |
65 | is obtained with the | |
e511ffb6 | 66 | .BR getpriority () |
fea681da | 67 | call and set with the |
e511ffb6 | 68 | .BR setpriority () |
fea681da MK |
69 | call. |
70 | ||
71 | The value | |
72 | .I which | |
73 | is one of | |
74 | .BR PRIO_PROCESS , | |
75 | .BR PRIO_PGRP , | |
76 | or | |
77 | .BR PRIO_USER , | |
c13182ef | 78 | and |
fea681da | 79 | .I who |
c13182ef | 80 | is interpreted relative to |
fea681da MK |
81 | .I which |
82 | (a process identifier for | |
83 | .BR PRIO_PROCESS , | |
84 | process group | |
85 | identifier for | |
86 | .BR PRIO_PGRP , | |
87 | and a user ID for | |
88 | .BR PRIO_USER ). | |
89 | A zero value for | |
90 | .I who | |
91 | denotes (respectively) the calling process, the process group of the | |
92 | calling process, or the real user ID of the calling process. | |
93 | .I Prio | |
ee6573b9 | 94 | is a value in the range \-20 to 19 (but see the Notes below). |
fea681da MK |
95 | The default priority is 0; |
96 | lower priorities cause more favorable scheduling. | |
97 | ||
98 | The | |
e511ffb6 | 99 | .BR getpriority () |
fea681da | 100 | call returns the highest priority (lowest numerical value) |
c13182ef MK |
101 | enjoyed by any of the specified processes. |
102 | The | |
e511ffb6 | 103 | .BR setpriority () |
fea681da | 104 | call sets the priorities of all of the specified processes |
c13182ef MK |
105 | to the specified value. |
106 | Only the superuser may lower priorities. | |
47297adb | 107 | .SH RETURN VALUE |
fea681da | 108 | Since |
e511ffb6 | 109 | .BR getpriority () |
fea681da MK |
110 | can legitimately return the value \-1, it is necessary |
111 | to clear the external variable | |
112 | .I errno | |
113 | prior to the | |
5fab2e7c | 114 | call, then check it afterward to determine |
84811e86 | 115 | if \-1 is an error or a legitimate value. |
fea681da | 116 | The |
e511ffb6 | 117 | .BR setpriority () |
fea681da MK |
118 | call returns 0 if there is no error, or |
119 | \-1 if there is. | |
120 | .SH ERRORS | |
121 | .TP | |
122 | .B EINVAL | |
123 | .I which | |
124 | was not one of | |
125 | .BR PRIO_PROCESS , | |
126 | .BR PRIO_PGRP , | |
127 | or | |
128 | .BR PRIO_USER . | |
129 | .TP | |
130 | .B ESRCH | |
c13182ef | 131 | No process was located using the |
fea681da MK |
132 | .I which |
133 | and | |
134 | .I who | |
135 | values specified. | |
136 | .PP | |
137 | In addition to the errors indicated above, | |
e511ffb6 | 138 | .BR setpriority () |
fea681da MK |
139 | may fail if: |
140 | .TP | |
fea681da | 141 | .B EACCES |
d818502d MK |
142 | The caller attempted to lower a process priority, but did not |
143 | have the required privilege (on Linux: did not have the | |
144 | .B CAP_SYS_NICE | |
145 | capability). | |
23b1b9bc | 146 | Since Linux 2.6.12, this error only occurs if the caller attempts |
c13182ef | 147 | to set a process priority outside the range of the |
23b1b9bc | 148 | .B RLIMIT_NICE |
614f40af | 149 | soft resource limit of the target process; see |
23b1b9bc MK |
150 | .BR getrlimit (2) |
151 | for details. | |
eab64696 MK |
152 | .TP |
153 | .B EPERM | |
154 | A process was located, but its effective user ID did not match | |
155 | either the effective or the real user ID of the caller, | |
156 | and was not privileged (on Linux: did not have the | |
157 | .B CAP_SYS_NICE | |
158 | capability). | |
159 | But see NOTES below. | |
47297adb | 160 | .SH CONFORMING TO |
a1d5f77c MK |
161 | SVr4, 4.4BSD (these function calls first appeared in 4.2BSD), |
162 | POSIX.1-2001. | |
fea681da | 163 | .SH NOTES |
2cab31c6 MK |
164 | A child created by |
165 | .BR fork (2) | |
166 | inherits its parent's nice value. | |
c13182ef MK |
167 | The nice value is preserved across |
168 | .BR execve (2). | |
2cab31c6 | 169 | |
a522769f | 170 | The degree to which their relative nice value affects the scheduling of |
008f1ecc | 171 | processes varies across UNIX systems, and, |
a522769f MK |
172 | on Linux, across kernel versions. |
173 | Starting with kernel 2.6.23, Linux adopted an algorithm that causes | |
174 | relative differences in nice values to have a much stronger effect. | |
175 | This causes very low nice values (+19) to truly provide little CPU | |
176 | to a process whenever there is any other | |
177 | higher priority load on the system, | |
178 | and makes high nice values (\-20) deliver most of the CPU to applications | |
179 | that require it (e.g., some audio applications). | |
180 | ||
682edefb | 181 | The details on the condition for |
0daa9e92 | 182 | .B EPERM |
682edefb | 183 | depend on the system. |
97c1eac8 | 184 | The above description is what POSIX.1-2001 says, and seems to be followed on |
80b50848 | 185 | all System V-like systems. |
c13182ef | 186 | Linux kernels before 2.6.12 required the real or |
614f40af | 187 | effective user ID of the caller to match |
fea681da | 188 | the real user of the process \fIwho\fP (instead of its effective user ID). |
614f40af | 189 | Linux 2.6.12 and later require |
fea681da MK |
190 | the effective user ID of the caller to match |
191 | the real or effective user ID of the process \fIwho\fP. | |
614f40af | 192 | All BSD-like systems (SunOS 4.1.3, Ultrix 4.2, |
c13182ef | 193 | 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same |
74aace8a | 194 | manner as Linux 2.6.12 and later. |
fea681da MK |
195 | .LP |
196 | The actual priority range varies between kernel versions. | |
d818502d | 197 | Linux before 1.3.36 had \-infinity..15. |
4c111639 | 198 | Since kernel 1.3.43 Linux has the range \-20..19. |
d818502d MK |
199 | Within the kernel, nice values are actually represented |
200 | using the corresponding range 40..1 | |
201 | (since negative numbers are error codes) and these are the values | |
202 | employed by the | |
e511ffb6 | 203 | .BR setpriority () |
d818502d | 204 | and |
e511ffb6 | 205 | .BR getpriority () |
d818502d MK |
206 | system calls. |
207 | The glibc wrapper functions for these system calls handle the | |
208 | translations between the user-land and kernel representations | |
209 | of the nice value according to the formula | |
210 | .IR "unice\ =\ 20\ \-\ knice" . | |
fea681da | 211 | .LP |
7f185ad2 MK |
212 | On some systems, the range of nice values is \-20..20. |
213 | .LP | |
fea681da MK |
214 | Including |
215 | .I <sys/time.h> | |
216 | is not required these days, but increases portability. | |
217 | (Indeed, | |
218 | .I <sys/resource.h> | |
219 | defines the | |
220 | .I rusage | |
221 | structure with fields of type | |
222 | .I struct timeval | |
223 | defined in | |
224 | .IR <sys/time.h> .) | |
24936448 MK |
225 | .SH BUGS |
226 | According to POSIX, the nice value is a per-process setting. | |
227 | However, under the current Linux/NPTL implementation of POSIX threads, | |
228 | the nice value is a per-thread attribute: | |
229 | different threads in the same process can have different nice values. | |
230 | Portable applications should avoid relying on the Linux behavior, | |
231 | which may be made standards conformant in the future. | |
47297adb | 232 | .SH SEE ALSO |
fea681da | 233 | .BR nice (1), |
3e5c319e | 234 | .BR renice (1), |
fea681da | 235 | .BR fork (2), |
3e5c319e | 236 | .BR capabilities (7) |
173fe7e7 | 237 | |
a522769f | 238 | .I Documentation/scheduler/sched-nice-design.txt |
173fe7e7 | 239 | in the Linux kernel source tree (since Linux 2.6.23) |