| blob | 6079318e7a19c147c292225299f5865e5a2d8ec4 |
1 .\" Copyright (c) 1980, 1991 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
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>
11 .\" Modified 2001-10-21 by Michael Kerrisk <mtk.manpages@gmail.com>
12 .\" Corrected statement under EPERM to clarify privileges required
13 .\" Modified 2002-06-21 by Michael Kerrisk <mtk.manpages@gmail.com>
14 .\" Clarified meaning of 0 value for 'who' argument
15 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
16 .\"
17 .TH GETPRIORITY 2 2022-09-09 "Linux man-pages (unreleased)"
18 .SH NAME
19 getpriority, setpriority \- get/set program scheduling priority
20 .SH LIBRARY
21 Standard C library
22 .RI ( libc ", " \-lc )
23 .SH SYNOPSIS
24 .nf
25 .B #include <sys/resource.h>
26 .PP
27 .BI "int getpriority(int " which ", id_t " who );
28 .BI "int setpriority(int " which ", id_t " who ", int " prio );
29 .fi
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
37 .BR getpriority ()
38 call and set with the
39 .BR setpriority ()
40 call.
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).
44 .PP
45 The value
46 .I which
47 is one of
48 .BR PRIO_PROCESS ,
49 .BR PRIO_PGRP ,
50 or
51 .BR PRIO_USER ,
52 and
53 .I who
54 is interpreted relative to
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.
67 .PP
68 The
69 .I prio
70 argument is a value in the range \-20 to 19 (but see NOTES below),
71 with \-20 being the highest priority and 19 being the lowest priority.
72 Attempts to set a priority outside this range
73 are silently clamped to the range.
74 The default priority is 0;
75 lower values give a process a higher scheduling priority.
76 .PP
77 The
78 .BR getpriority ()
79 call returns the highest priority (lowest numerical value)
80 enjoyed by any of the specified processes.
81 The
82 .BR setpriority ()
83 call sets the priorities of all of the specified processes
84 to the specified value.
85 .PP
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
90 .B RLIMIT_NICE
91 soft limit; see
92 .BR getrlimit (2)
93 for details.
94 .SH RETURN VALUE
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
100 to indicate the error.
101 .PP
102 Since a successful call to
103 .BR getpriority ()
104 can legitimately return the value \-1, it is necessary
105 to clear
106 .I errno
107 prior to the
108 call, then check
109 .I errno
110 afterward to determine
111 if \-1 is an error or a legitimate value.
112 .PP
113 .BR setpriority ()
114 returns 0 on success.
115 On failure, it returns \-1 and sets
116 .I errno
117 to indicate the error.
118 .SH ERRORS
119 .TP
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
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
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.
142 .TP
143 .B ESRCH
144 No process was located using the
145 .I which
146 and
147 .I who
148 values specified.
149 .SH STANDARDS
150 POSIX.1-2001, POSIX.1-2008,
151 SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
152 .SH NOTES
153 For further details on the nice value, see
154 .BR sched (7).
155 .PP
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).
161 .PP
162 A child created by
163 .BR fork (2)
164 inherits its parent's nice value.
165 The nice value is preserved across
166 .BR execve (2).
167 .PP
168 The details on the condition for
169 .B EPERM
170 depend on the system.
171 The above description is what POSIX.1-2001 says, and seems to be followed on
172 all System\ V-like systems.
173 Linux kernels before 2.6.12 required the real or
174 effective user ID of the caller to match
175 the real user of the process \fIwho\fP (instead of its effective user ID).
176 Linux 2.6.12 and later require
177 the effective user ID of the caller to match
178 the real or effective user ID of the process \fIwho\fP.
179 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
180 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
181 manner as Linux 2.6.12 and later.
182 .\"
183 .SS C library/kernel differences
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.
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).
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.
199 .SH SEE ALSO
200 .BR nice (1),
201 .BR renice (1),
202 .BR fork (2),
203 .BR capabilities (7),
204 .BR sched (7)
205 .PP
206 .I Documentation/scheduler/sched\-nice\-design.txt
207 in the Linux kernel source tree (since Linux 2.6.23)