]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1980, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
47009d5e | 4 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
5 | .\" |
6 | .\" @(#)getpriority.2 6.9 (Berkeley) 3/10/91 | |
7 | .\" | |
8 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
9 | .\" Modified 1996-07-01 by Andries Brouwer <aeb@cwi.nl> | |
10 | .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com> | |
c11b1abf | 11 | .\" Modified 2001-10-21 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 12 | .\" Corrected statement under EPERM to clarify privileges required |
c11b1abf | 13 | .\" Modified 2002-06-21 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 14 | .\" Clarified meaning of 0 value for 'who' argument |
c11b1abf | 15 | .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 16 | .\" |
45186a5d | 17 | .TH GETPRIORITY 2 2021-08-27 "Linux man-pages (unreleased)" |
fea681da MK |
18 | .SH NAME |
19 | getpriority, setpriority \- get/set program scheduling priority | |
a29a8b6a AC |
20 | .SH LIBRARY |
21 | Standard C library | |
8fc3b2cf | 22 | .RI ( libc ", " \-lc ) |
fea681da | 23 | .SH SYNOPSIS |
c7db92b9 | 24 | .nf |
fea681da | 25 | .B #include <sys/resource.h> |
68e4db0a | 26 | .PP |
9f9bbc5a | 27 | .BI "int getpriority(int " which ", id_t " who ); |
9f9bbc5a | 28 | .BI "int setpriority(int " which ", id_t " who ", int " prio ); |
c7db92b9 | 29 | .fi |
fea681da MK |
30 | .SH DESCRIPTION |
31 | The scheduling priority of the process, process group, or user, as | |
32 | indicated by | |
33 | .I which | |
34 | and | |
35 | .I who | |
36 | is obtained with the | |
e511ffb6 | 37 | .BR getpriority () |
fea681da | 38 | call and set with the |
e511ffb6 | 39 | .BR setpriority () |
fea681da | 40 | call. |
653c1fe2 MK |
41 | The process attribute dealt with by these system calls is |
42 | the same attribute (also known as the "nice" value) that is dealt with by | |
43 | .BR nice (2). | |
efeece04 | 44 | .PP |
fea681da MK |
45 | The value |
46 | .I which | |
47 | is one of | |
48 | .BR PRIO_PROCESS , | |
49 | .BR PRIO_PGRP , | |
50 | or | |
51 | .BR PRIO_USER , | |
c13182ef | 52 | and |
fea681da | 53 | .I who |
c13182ef | 54 | is interpreted relative to |
fea681da MK |
55 | .I which |
56 | (a process identifier for | |
57 | .BR PRIO_PROCESS , | |
58 | process group | |
59 | identifier for | |
60 | .BR PRIO_PGRP , | |
61 | and a user ID for | |
62 | .BR PRIO_USER ). | |
63 | A zero value for | |
64 | .I who | |
65 | denotes (respectively) the calling process, the process group of the | |
66 | calling process, or the real user ID of the calling process. | |
efeece04 | 67 | .PP |
b17796b9 MK |
68 | The |
69 | .I prio | |
03659d7d | 70 | argument is a value in the range \-20 to 19 (but see NOTES below), |
40fcb004 | 71 | with \-20 being the highest priority and 19 being the lowest priority. |
26ea000d MK |
72 | Attempts to set a priority outside this range |
73 | are silently clamped to the range. | |
fea681da | 74 | The default priority is 0; |
b8bc577b | 75 | lower values give a process a higher scheduling priority. |
efeece04 | 76 | .PP |
fea681da | 77 | The |
e511ffb6 | 78 | .BR getpriority () |
fea681da | 79 | call returns the highest priority (lowest numerical value) |
c13182ef MK |
80 | enjoyed by any of the specified processes. |
81 | The | |
e511ffb6 | 82 | .BR setpriority () |
fea681da | 83 | call sets the priorities of all of the specified processes |
c13182ef | 84 | to the specified value. |
efeece04 | 85 | .PP |
f69c2584 MK |
86 | Traditionally, only a privileged process could lower the nice value |
87 | (i.e., set a higher priority). | |
88 | However, since Linux 2.6.12, an unprivileged process can decrease | |
89 | the nice value of a target process that has a suitable | |
1ae6b2c7 | 90 | .B RLIMIT_NICE |
f69c2584 MK |
91 | soft limit; see |
92 | .BR getrlimit (2) | |
93 | for details. | |
47297adb | 94 | .SH RETURN VALUE |
268c2817 MK |
95 | On success, |
96 | .BR getpriority () | |
97 | returns the calling thread's nice value, which may be a negative number. | |
98 | On error, it returns \-1 and sets | |
99 | .I errno | |
855d489a | 100 | to indicate the error. |
fe276432 | 101 | .PP |
268c2817 | 102 | Since a successful call to |
e511ffb6 | 103 | .BR getpriority () |
fea681da | 104 | can legitimately return the value \-1, it is necessary |
ba50f49c | 105 | to clear |
fea681da MK |
106 | .I errno |
107 | prior to the | |
61d6b66a MK |
108 | call, then check |
109 | .I errno | |
110 | afterward to determine | |
84811e86 | 111 | if \-1 is an error or a legitimate value. |
efeece04 | 112 | .PP |
e511ffb6 | 113 | .BR setpriority () |
a6bdf7ee | 114 | returns 0 on success. |
cb6a894e | 115 | On failure, it returns \-1 and sets |
a6bdf7ee | 116 | .I errno |
cb6a894e | 117 | to indicate the error. |
fea681da MK |
118 | .SH ERRORS |
119 | .TP | |
18ce9c4a MK |
120 | .B EACCES |
121 | The caller attempted to set a lower nice value | |
122 | (i.e., a higher process priority), but did not | |
123 | have the required privilege (on Linux: did not have the | |
124 | .B CAP_SYS_NICE | |
125 | capability). | |
126 | .TP | |
fea681da MK |
127 | .B EINVAL |
128 | .I which | |
129 | was not one of | |
130 | .BR PRIO_PROCESS , | |
131 | .BR PRIO_PGRP , | |
132 | or | |
133 | .BR PRIO_USER . | |
134 | .TP | |
eab64696 MK |
135 | .B EPERM |
136 | A process was located, but its effective user ID did not match | |
137 | either the effective or the real user ID of the caller, | |
138 | and was not privileged (on Linux: did not have the | |
139 | .B CAP_SYS_NICE | |
140 | capability). | |
141 | But see NOTES below. | |
18ce9c4a MK |
142 | .TP |
143 | .B ESRCH | |
144 | No process was located using the | |
145 | .I which | |
146 | and | |
147 | .I who | |
148 | values specified. | |
3113c7f3 | 149 | .SH STANDARDS |
226acd20 | 150 | POSIX.1-2001, POSIX.1-2008, |
893922a2 | 151 | SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). |
fea681da | 152 | .SH NOTES |
45fcd0e2 MK |
153 | For further details on the nice value, see |
154 | .BR sched (7). | |
efeece04 | 155 | .PP |
ccc12700 MK |
156 | .IR Note : |
157 | the addition of the "autogroup" feature in Linux 2.6.38 means that | |
158 | the nice value no longer has its traditional effect in many circumstances. | |
159 | For details, see | |
160 | .BR sched (7). | |
efeece04 | 161 | .PP |
2cab31c6 MK |
162 | A child created by |
163 | .BR fork (2) | |
164 | inherits its parent's nice value. | |
c13182ef MK |
165 | The nice value is preserved across |
166 | .BR execve (2). | |
efeece04 | 167 | .PP |
682edefb | 168 | The details on the condition for |
0daa9e92 | 169 | .B EPERM |
682edefb | 170 | depend on the system. |
97c1eac8 | 171 | The above description is what POSIX.1-2001 says, and seems to be followed on |
efbfd7ec | 172 | all System\ V-like systems. |
c13182ef | 173 | Linux kernels before 2.6.12 required the real or |
614f40af | 174 | effective user ID of the caller to match |
fea681da | 175 | the real user of the process \fIwho\fP (instead of its effective user ID). |
614f40af | 176 | Linux 2.6.12 and later require |
fea681da MK |
177 | the effective user ID of the caller to match |
178 | the real or effective user ID of the process \fIwho\fP. | |
614f40af | 179 | All BSD-like systems (SunOS 4.1.3, Ultrix 4.2, |
c13182ef | 180 | 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same |
74aace8a | 181 | manner as Linux 2.6.12 and later. |
0ebe771f | 182 | .\" |
0722a578 | 183 | .SS C library/kernel differences |
7745313f TD |
184 | The getpriority system call returns nice values translated to the range 40..1, |
185 | since a negative return value would be interpreted as an error. | |
e89f125d AC |
186 | The glibc wrapper function for |
187 | .BR getpriority () | |
188 | translates the value back according to the formula | |
189 | .I unice\~=\~20\~\-\~knice | |
190 | (thus, the 40..1 range returned by the kernel | |
191 | corresponds to the range \-20..19 as seen by user space). | |
24936448 MK |
192 | .SH BUGS |
193 | According to POSIX, the nice value is a per-process setting. | |
194 | However, under the current Linux/NPTL implementation of POSIX threads, | |
195 | the nice value is a per-thread attribute: | |
196 | different threads in the same process can have different nice values. | |
197 | Portable applications should avoid relying on the Linux behavior, | |
198 | which may be made standards conformant in the future. | |
47297adb | 199 | .SH SEE ALSO |
fea681da | 200 | .BR nice (1), |
3e5c319e | 201 | .BR renice (1), |
fea681da | 202 | .BR fork (2), |
645e6d64 MK |
203 | .BR capabilities (7), |
204 | .BR sched (7) | |
efeece04 | 205 | .PP |
b49c2acb | 206 | .I Documentation/scheduler/sched\-nice\-design.txt |
173fe7e7 | 207 | in the Linux kernel source tree (since Linux 2.6.23) |