Debian Codegraph @

upstream/debian-unstable/man2/getpriority.2

raw
1 .\" Copyright 1980-1991, The Regents of the University of California.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .TH getpriority 2 2026-01-23 "Linux man-pages 6.18"
7 .SH NAME
8 getpriority, setpriority \- get/set program scheduling priority
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/resource.h>
15 .P
16 .BI "int getpriority(int " which ", id_t " who );
17 .BI "int setpriority(int " which ", id_t " who ", int " prio );
18 .fi
19 .SH DESCRIPTION
20 The scheduling priority of the process, process group, or user, as
21 indicated by
22 .I which
23 and
24 .I who
25 is obtained with the
26 .BR getpriority ()
27 call and set with the
28 .BR setpriority ()
29 call.
30 The process attribute dealt with by these system calls is
31 the same attribute (also known as the "nice" value) that is dealt with by
32 .BR nice (2).
33 .P
34 The value
35 .I which
36 is one of
37 .BR PRIO_PROCESS ,
38 .BR PRIO_PGRP ,
39 or
40 .BR PRIO_USER ,
41 and
42 .I who
43 is interpreted relative to
44 .I which
45 (a process identifier for
46 .BR PRIO_PROCESS ,
47 process group
48 identifier for
49 .BR PRIO_PGRP ,
50 and a user ID for
51 .BR PRIO_USER ).
52 A zero value for
53 .I who
54 denotes (respectively) the calling process, the process group of the
55 calling process, or the real user ID of the calling process.
56 .P
57 The
58 .I prio
59 argument is a value in the range \-20 to 19 (but see NOTES below),
60 with \-20 being the highest priority and 19 being the lowest priority.
61 Attempts to set a priority outside this range
62 are silently clamped to the range.
63 The default priority is 0;
64 lower values give a process a higher scheduling priority.
65 .P
66 The
67 .BR getpriority ()
68 call returns the highest priority (lowest numerical value)
69 enjoyed by any of the specified processes.
70 The
71 .BR setpriority ()
72 call sets the priorities of all of the specified processes
73 to the specified value.
74 .P
75 Traditionally, only a privileged process could lower the nice value
76 (i.e., set a higher priority).
77 However, since Linux 2.6.12, an unprivileged process can decrease
78 the nice value of a target process that has a suitable
79 .B RLIMIT_NICE
80 soft limit;
81 see
82 .BR getrlimit (2)
83 for details.
84 .SH RETURN VALUE
85 On success,
86 .BR getpriority ()
87 returns the calling thread's nice value, which may be a negative number.
88 On error, it returns \-1 and sets
89 .I errno
90 to indicate the error.
91 .P
92 Since a successful call to
93 .BR getpriority ()
94 can legitimately return the value \-1, it is necessary
95 to clear
96 .I errno
97 prior to the
98 call, then check
99 .I errno
100 afterward to determine
101 if \-1 is an error or a legitimate value.
102 .P
103 .BR setpriority ()
104 returns 0 on success.
105 On failure, it returns \-1 and sets
106 .I errno
107 to indicate the error.
108 .SH ERRORS
109 .TP
110 .B EACCES
111 The caller attempted to set a lower nice value
112 (i.e., a higher process priority), but did not
113 have the required privilege (on Linux: did not have the
114 .B CAP_SYS_NICE
115 capability).
116 .TP
117 .B EINVAL
118 .I which
119 was not one of
120 .BR PRIO_PROCESS ,
121 .BR PRIO_PGRP ,
122 or
123 .BR PRIO_USER .
124 .TP
125 .B EPERM
126 A process was located, but its effective user ID did not match
127 either the effective or the real user ID of the caller,
128 and was not privileged (on Linux: did not have the
129 .B CAP_SYS_NICE
130 capability).
131 But see HISTORY below.
132 .TP
133 .B ESRCH
134 No process was located using the
135 .I which
136 and
137 .I who
138 values specified.
139 .SH STANDARDS
140 POSIX.1-2024.
141 .SH HISTORY
142 4.2BSD,
143 SVr4,
144 SUSv1,
145 POSIX.1-2001 XSI.
146 .P
147 The details on the condition for
148 .B EPERM
149 depend on the system.
150 The above description is what POSIX.1-2001 says, and seems to be followed on
151 all System\ V-like systems.
152 Linux kernels before Linux 2.6.12 required the real or
153 effective user ID of the caller to match
154 the real user of the process
155 .I who
156 (instead of its effective user ID).
157 Linux 2.6.12 and later require
158 the effective user ID of the caller to match
159 the real or effective user ID of the process
160 .IR who .
161 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
162 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
163 manner as Linux 2.6.12 and later.
164 .\"
165 .SH NOTES
166 For further details on the nice value, see
167 .BR sched (7).
168 .P
169 .IR Note :
170 the addition of the "autogroup" feature in Linux 2.6.38 means that
171 the nice value no longer has its traditional effect in many circumstances.
172 For details, see
173 .BR sched (7).
174 .P
175 A child created by
176 .BR fork (2)
177 inherits its parent's nice value.
178 The nice value is preserved across
179 .BR execve (2).
180 .SS C library/kernel differences
181 The getpriority system call returns nice values translated to the range 40..1,
182 since a negative return value would be interpreted as an error.
183 The glibc wrapper function for
184 .BR getpriority ()
185 translates the value back according to the formula
186 .I unice\~=\~20\~\-\~knice
187 (thus, the 40..1 range returned by the kernel
188 corresponds to the range \-20..19 as seen by user space).
189 .SH BUGS
190 According to POSIX, the nice value is a per-process setting.
191 However, under the current Linux/NPTL implementation of POSIX threads,
192 the nice value is a per-thread attribute:
193 different threads in the same process can have different nice values.
194 Portable applications should avoid relying on the Linux behavior,
195 which may be made standards conformant in the future.
196 .SH SEE ALSO
197 .BR nice (1),
198 .BR renice (1),
199 .BR fork (2),
200 .BR capabilities (7),
201 .BR sched (7)
202 .P
203 .I Documentation/scheduler/sched\-nice\-design.rst
204 in the Linux kernel source tree (since Linux 2.6.23)