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