]>
Commit | Line | Data |
---|---|---|
1 | .\" $NetBSD: getpriority.2,v 1.4 1995/02/27 12:33:15 cgd Exp $ | |
2 | .\" | |
3 | .\" Copyright (c) 1980, 1991, 1993 | |
4 | .\" The Regents of the University of California. All rights reserved. | |
5 | .\" | |
6 | .\" Redistribution and use in source and binary forms, with or without | |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" 1. Redistributions of source code must retain the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer. | |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer in the | |
13 | .\" documentation and/or other materials provided with the distribution. | |
14 | .\" 3. All advertising materials mentioning features or use of this software | |
15 | .\" must display the following acknowledgement: | |
16 | .\" This product includes software developed by the University of | |
17 | .\" California, Berkeley and its contributors. | |
18 | .\" 4. Neither the name of the University nor the names of its contributors | |
19 | .\" may be used to endorse or promote products derived from this software | |
20 | .\" without specific prior written permission. | |
21 | .\" | |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
32 | .\" SUCH DAMAGE. | |
33 | .\" | |
34 | .\" @(#)getpriority.2 8.1 (Berkeley) 6/4/93 | |
35 | .\" | |
36 | .Dd June 4, 1993 | |
37 | .Dt GETPRIORITY 2 | |
38 | .Os BSD 4 | |
39 | .Sh NAME | |
40 | .Nm getpriority , | |
41 | .Nm setpriority | |
42 | .Nd get/set program scheduling priority | |
43 | .Sh SYNOPSIS | |
44 | .Fd #include <sys/resource.h> | |
45 | .Ft int | |
46 | .Fo getpriority | |
47 | .Fa "int which" | |
48 | .Fa "id_t who" | |
49 | .Fc | |
50 | .Ft int | |
51 | .Fo setpriority | |
52 | .Fa "int which" | |
53 | .Fa "id_t who" | |
54 | .Fa "int prio" | |
55 | .Fc | |
56 | .Sh DESCRIPTION | |
57 | The scheduling priority of the process, process group, or user as indicated by | |
58 | .Fa which | |
59 | and | |
60 | .Fa who | |
61 | is obtained with the | |
62 | .Fn getpriority | |
63 | call and set with the | |
64 | .Fn setpriority | |
65 | call. | |
66 | .Fa Which | |
67 | is one of | |
68 | .Dv PRIO_PROCESS , | |
69 | .Dv PRIO_PGRP , | |
70 | or | |
71 | .Dv PRIO_USER , | |
72 | and | |
73 | .Fa who | |
74 | is interpreted relative to | |
75 | .Fa which | |
76 | (a process identifier for | |
77 | .Dv PRIO_PROCESS , | |
78 | process group | |
79 | identifier for | |
80 | .Dv PRIO_PGRP , | |
81 | and a user ID for | |
82 | .Dv PRIO_USER ) . | |
83 | A zero value of | |
84 | .Fa who | |
85 | denotes the current process, process group, or user. | |
86 | .Fa prio | |
87 | is a value in the range -20 to 20. The default priority is 0; | |
88 | lower priorities cause more favorable scheduling. | |
89 | .Pp | |
90 | The | |
91 | .Fn getpriority | |
92 | call returns the highest priority (lowest numerical value) | |
93 | enjoyed by any of the specified processes. | |
94 | The | |
95 | .Fn setpriority | |
96 | call sets the priorities of all of the specified processes | |
97 | to the specified value. Only the super-user may lower priorities. | |
98 | .Pp | |
99 | Additionally, the current thread or process can be placed in a background state | |
100 | by specifying PRIO_DARWIN_THREAD or PRIO_DARWIN_PROCESS for | |
101 | .Fa which . | |
102 | Only a value of zero (the current thread or process) is supported for | |
103 | .Fa who | |
104 | when setting or getting background state. | |
105 | .Fa prio | |
106 | is either 0 (to remove current thread from background status) or PRIO_DARWIN_BG | |
107 | (to set current thread into background state). | |
108 | When a thread or process is in a background state the scheduling priority is set | |
109 | to the lowest value, disk IO is throttled (with behavior similar to using | |
110 | .Xr setiopolicy_np 3 | |
111 | to set a throttleable policy), and network IO is throttled for | |
112 | any sockets opened after going into background state. Any previously opened | |
113 | sockets are not affected. | |
114 | The | |
115 | .Fn getpriority | |
116 | call returns 0 when current thread or process is not in background state or 1 | |
117 | when the current thread is in background state. Any thread or process can set | |
118 | itself into background state. | |
119 | .Sh RETURN VALUES | |
120 | Since | |
121 | .Fn getpriority | |
122 | can legitimately return the value -1, it is necessary | |
123 | to clear the external variable | |
124 | .Va errno | |
125 | prior to the | |
126 | call, then check it afterward to determine | |
127 | if a -1 is an error or a legitimate value. | |
128 | The | |
129 | .Fn setpriority | |
130 | call returns 0 if there is no error, or | |
131 | -1 if there is. | |
132 | .Sh ERRORS | |
133 | .Fn Getpriority | |
134 | and | |
135 | .Fn setpriority | |
136 | will fail if: | |
137 | .Bl -tag -width Er | |
138 | .\" ========== | |
139 | .It Bq Er EINVAL | |
140 | .Fa Which | |
141 | is not one of | |
142 | .Dv PRIO_PROCESS , | |
143 | .Dv PRIO_PGRP , | |
144 | .Dv PRIO_USER , | |
145 | .Dv PRIO_DARWIN_THREAD , | |
146 | or | |
147 | .Dv PRIO_DARWIN_PROCESS . | |
148 | .\" ========== | |
149 | .It Bq Er EINVAL | |
150 | .Fa Who | |
151 | is not a valid process, process group, or user ID. | |
152 | .\" ========== | |
153 | .It Bq Er EINVAL | |
154 | .Fa Who | |
155 | is not 0 when | |
156 | .Fa which | |
157 | is | |
158 | .Dv PRIO_DARWIN_THREAD | |
159 | or | |
160 | .Dv PRIO_DARWIN_PROCESS . | |
161 | .\" ========== | |
162 | .It Bq Er ESRCH | |
163 | No process can be located using the | |
164 | .Fa which | |
165 | and | |
166 | .Fa who | |
167 | values specified. | |
168 | .El | |
169 | .Pp | |
170 | .Bl -tag -width Er | |
171 | In addition to the errors indicated above, | |
172 | .Fn setpriority | |
173 | will fail if: | |
174 | .\" ========== | |
175 | .It Bq Er EACCES | |
176 | A non super-user attempts to lower a process priority. | |
177 | .\" ========== | |
178 | .It Bq Er EPERM | |
179 | A process is located, | |
180 | but neither its effective nor real user ID | |
181 | matches the effective user ID of the caller. | |
182 | .El | |
183 | .Sh LEGACY SYNOPSIS | |
184 | .Fd #include <sys/types.h> | |
185 | .Fd #include <sys/resource.h> | |
186 | .Pp | |
187 | The include file | |
188 | .In sys/types.h | |
189 | is necessary. | |
190 | .Pp | |
191 | .Ft int | |
192 | .br | |
193 | .Fo getpriority | |
194 | .Fa "int which" | |
195 | .Fa "int who" | |
196 | .Fc ; | |
197 | .Pp | |
198 | .Ft int | |
199 | .br | |
200 | .Fo setpriority | |
201 | .Fa "int which" | |
202 | .Fa "int who" | |
203 | .Fa "int value" | |
204 | .Fc ; | |
205 | .Pp | |
206 | The type of | |
207 | .Fa who | |
208 | has changed. | |
209 | .Sh SEE ALSO | |
210 | .Xr nice 1 , | |
211 | .Xr fork 2 , | |
212 | .Xr setiopolicy_np 3 , | |
213 | .Xr compat 5 , | |
214 | .Xr renice 8 | |
215 | .Sh HISTORY | |
216 | The | |
217 | .Fn getpriority | |
218 | function call appeared in | |
219 | .Bx 4.2 . |