Debian Codegraph @

upstream/debian-trixie/man2/getpriority.2

raw
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 <[email protected]>
9 .\" Modified 1996-07-01 by Andries Brouwer <[email protected]>
10 .\" Modified 1996-11-06 by Eric S. Raymond <[email protected]>
11 .\" Modified 2001-10-21 by Michael Kerrisk <[email protected]>
12 .\" Corrected statement under EPERM to clarify privileges required
13 .\" Modified 2002-06-21 by Michael Kerrisk <[email protected]>
14 .\" Clarified meaning of 0 value for 'who' argument
15 .\" Modified 2004-05-27 by Michael Kerrisk <[email protected]>
16 .\"
17 .TH getpriority 2 2024-05-02 "Linux man-pages 6.9.1"
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 .P
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 .P
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 .P
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 .P
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 .P
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 .P
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 .P
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-2008.
151 .SH HISTORY
152 POSIX.1-2001,
153 SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
154 .SH NOTES
155 For further details on the nice value, see
156 .BR sched (7).
157 .P
158 .IR Note :
159 the addition of the "autogroup" feature in Linux 2.6.38 means that
160 the nice value no longer has its traditional effect in many circumstances.
161 For details, see
162 .BR sched (7).
163 .P
164 A child created by
165 .BR fork (2)
166 inherits its parent's nice value.
167 The nice value is preserved across
168 .BR execve (2).
169 .P
170 The details on the condition for
171 .B EPERM
172 depend on the system.
173 The above description is what POSIX.1-2001 says, and seems to be followed on
174 all System\ V-like systems.
175 Linux kernels before Linux 2.6.12 required the real or
176 effective user ID of the caller to match
177 the real user of the process \fIwho\fP (instead of its effective user ID).
178 Linux 2.6.12 and later require
179 the effective user ID of the caller to match
180 the real or effective user ID of the process \fIwho\fP.
181 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
182 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
183 manner as Linux 2.6.12 and later.
184 .\"
185 .SS C library/kernel differences
186 The getpriority system call returns nice values translated to the range 40..1,
187 since a negative return value would be interpreted as an error.
188 The glibc wrapper function for
189 .BR getpriority ()
190 translates the value back according to the formula
191 .I unice\~=\~20\~\-\~knice
192 (thus, the 40..1 range returned by the kernel
193 corresponds to the range \-20..19 as seen by user space).
194 .SH BUGS
195 According to POSIX, the nice value is a per-process setting.
196 However, under the current Linux/NPTL implementation of POSIX threads,
197 the nice value is a per-thread attribute:
198 different threads in the same process can have different nice values.
199 Portable applications should avoid relying on the Linux behavior,
200 which may be made standards conformant in the future.
201 .SH SEE ALSO
202 .BR nice (1),
203 .BR renice (1),
204 .BR fork (2),
205 .BR capabilities (7),
206 .BR sched (7)
207 .P
208 .I Documentation/scheduler/sched\-nice\-design.txt
209 in the Linux kernel source tree (since Linux 2.6.23)