]>
Commit | Line | Data |
---|---|---|
5ce8f203 UD |
1 | @node Resource Usage And Limitation, Non-Local Exits, Date and Time, Top |
2 | @c %MENU% Functions for examining resource usage and getting and setting limits | |
3 | @chapter Resource Usage And Limitation | |
4 | This chapter describes functions for examining how much of various kinds of | |
5 | resources (CPU time, memory, etc.) a process has used and getting and setting | |
6 | limits on future usage. | |
7 | ||
8 | @menu | |
9 | * Resource Usage:: Measuring various resources used. | |
10 | * Limits on Resources:: Specifying limits on resource usage. | |
11 | * Priority:: Reading or setting process run priority. | |
12 | @end menu | |
13 | ||
14 | ||
15 | @node Resource Usage | |
16 | @section Resource Usage | |
17 | ||
18 | @pindex sys/resource.h | |
19 | The function @code{getrusage} and the data type @code{struct rusage} | |
20 | are used to examine the resource usage of a process. They are declared | |
21 | in @file{sys/resource.h}. | |
22 | ||
23 | @comment sys/resource.h | |
24 | @comment BSD | |
25 | @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage}) | |
26 | This function reports resource usage totals for processes specified by | |
27 | @var{processes}, storing the information in @code{*@var{rusage}}. | |
28 | ||
29 | In most systems, @var{processes} has only two valid values: | |
30 | ||
31 | @table @code | |
32 | @comment sys/resource.h | |
33 | @comment BSD | |
34 | @item RUSAGE_SELF | |
35 | Just the current process. | |
36 | ||
37 | @comment sys/resource.h | |
38 | @comment BSD | |
39 | @item RUSAGE_CHILDREN | |
40 | All child processes (direct and indirect) that have already terminated. | |
41 | @end table | |
42 | ||
43 | In the GNU system, you can also inquire about a particular child process | |
44 | by specifying its process ID. | |
45 | ||
46 | The return value of @code{getrusage} is zero for success, and @code{-1} | |
47 | for failure. | |
48 | ||
49 | @table @code | |
50 | @item EINVAL | |
51 | The argument @var{processes} is not valid. | |
52 | @end table | |
53 | @end deftypefun | |
54 | ||
55 | One way of getting resource usage for a particular child process is with | |
56 | the function @code{wait4}, which returns totals for a child when it | |
57 | terminates. @xref{BSD Wait Functions}. | |
58 | ||
59 | @comment sys/resource.h | |
60 | @comment BSD | |
61 | @deftp {Data Type} {struct rusage} | |
62 | This data type stores various resource usage statistics. It has the | |
63 | following members, and possibly others: | |
64 | ||
65 | @table @code | |
66 | @item struct timeval ru_utime | |
67 | Time spent executing user instructions. | |
68 | ||
69 | @item struct timeval ru_stime | |
70 | Time spent in operating system code on behalf of @var{processes}. | |
71 | ||
72 | @item long int ru_maxrss | |
73 | The maximum resident set size used, in kilobytes. That is, the maximum | |
74 | number of kilobytes of physical memory that @var{processes} used | |
75 | simultaneously. | |
76 | ||
77 | @item long int ru_ixrss | |
78 | An integral value expressed in kilobytes times ticks of execution, which | |
79 | indicates the amount of memory used by text that was shared with other | |
80 | processes. | |
81 | ||
82 | @item long int ru_idrss | |
83 | An integral value expressed the same way, which is the amount of | |
84 | unshared memory used for data. | |
85 | ||
86 | @item long int ru_isrss | |
87 | An integral value expressed the same way, which is the amount of | |
88 | unshared memory used for stack space. | |
89 | ||
90 | @item long int ru_minflt | |
91 | The number of page faults which were serviced without requiring any I/O. | |
92 | ||
93 | @item long int ru_majflt | |
94 | The number of page faults which were serviced by doing I/O. | |
95 | ||
96 | @item long int ru_nswap | |
97 | The number of times @var{processes} was swapped entirely out of main memory. | |
98 | ||
99 | @item long int ru_inblock | |
100 | The number of times the file system had to read from the disk on behalf | |
101 | of @var{processes}. | |
102 | ||
103 | @item long int ru_oublock | |
104 | The number of times the file system had to write to the disk on behalf | |
105 | of @var{processes}. | |
106 | ||
107 | @item long int ru_msgsnd | |
108 | Number of IPC messages sent. | |
109 | ||
110 | @item long int ru_msgrcv | |
111 | Number of IPC messages received. | |
112 | ||
113 | @item long int ru_nsignals | |
114 | Number of signals received. | |
115 | ||
116 | @item long int ru_nvcsw | |
117 | The number of times @var{processes} voluntarily invoked a context switch | |
118 | (usually to wait for some service). | |
119 | ||
120 | @item long int ru_nivcsw | |
121 | The number of times an involuntary context switch took place (because | |
122 | a time slice expired, or another process of higher priority was | |
123 | scheduled). | |
124 | @end table | |
125 | @end deftp | |
126 | ||
127 | @code{vtimes} is a historical function that does some of what | |
128 | @code{getrusage} does. @code{getrusage} is a better choice. | |
129 | ||
130 | @code{vtimes} and its @code{vtimes} data structure are declared in | |
131 | @file{sys/vtimes.h}. | |
132 | @pindex sys/vtimes.h | |
133 | @comment vtimes.h | |
134 | ||
135 | @deftypefun int vtimes (struct vtimes @var{current}, struct vtimes @var{child}) | |
136 | ||
137 | @code{vtimes} reports resource usage totals for a process. | |
138 | ||
139 | If @var{current} is non-null, @code{vtimes} stores resource usage totals for | |
140 | the invoking process alone in the structure to which it points. If | |
141 | @var{child} is non-null, @code{vtimes} stores resource usage totals for all | |
142 | past children (which have terminated) of the invoking process in the structure | |
143 | to which it points. | |
144 | ||
145 | @deftp {Data Type} {struct vtimes} | |
146 | This data type contains information about the resource usage of a process. | |
147 | Each member corresponds to a member of the @code{struct rusage} data type | |
148 | described above. | |
149 | ||
150 | @table @code | |
151 | @item vm_utime | |
152 | User CPU time. Analogous to @code{ru_utime} in @code{struct rusage} | |
153 | @item vm_stime | |
154 | System CPU time. Analogous to @code{ru_stime} in @code{struct rusage} | |
155 | @item vm_idsrss | |
156 | Data and stack memory. The sum of the values that would be reported as | |
157 | @code{ru_idrss} and @code{ru_isrss} in @code{struct rusage} | |
158 | @item vm_ixrss | |
159 | Shared memory. Analogous to @code{ru_ixrss} in @code{struct rusage} | |
160 | @item vm_maxrss | |
161 | Maximent resident set size. Analogous to @code{ru_maxrss} in | |
162 | @code{struct rusage} | |
163 | @item vm_majflt | |
164 | Major page faults. Analogous to @code{ru_majflt} in @code{struct rusage} | |
165 | @item vm_minflt | |
166 | Minor page faults. Analogous to @code{ru_minflt} in @code{struct rusage} | |
167 | @item vm_nswap | |
168 | Swap count. Analogous to @code{ru_nswap} in @code{struct rusage} | |
169 | @item vm_inblk | |
170 | Disk reads. Analogous to @code{ru_inblk} in @code{struct rusage} | |
171 | @item vm_oublk | |
172 | Disk writes. Analogous to @code{ru_oublk} in @code{struct rusage} | |
173 | @end table | |
174 | @end deftp | |
175 | ||
176 | ||
177 | The return value is zero if the function succeeds; @code{-1} otherwise. | |
178 | ||
179 | ||
180 | ||
181 | @end deftypefun | |
182 | An additional historical function for examining resource usage, | |
183 | @code{vtimes}, is supported but not documented here. It is declared in | |
184 | @file{sys/vtimes.h}. | |
185 | ||
186 | @node Limits on Resources | |
187 | @section Limiting Resource Usage | |
188 | @cindex resource limits | |
189 | @cindex limits on resource usage | |
190 | @cindex usage limits | |
191 | ||
192 | You can specify limits for the resource usage of a process. When the | |
193 | process tries to exceed a limit, it may get a signal, or the system call | |
194 | by which it tried to do so may fail, depending on the resource. Each | |
195 | process initially inherits its limit values from its parent, but it can | |
196 | subsequently change them. | |
197 | ||
198 | There are two per-process limits associated with a resource: | |
199 | @cindex limit | |
200 | ||
201 | @table @dfn | |
202 | @item current limit | |
203 | The current limit is the value the system will not allow usage to | |
204 | exceed. It is also called the ``soft limit'' because the process being | |
205 | limited can generally raise the current limit at will. | |
206 | @cindex current limit | |
207 | @cindex soft limit | |
208 | ||
209 | @item maximum limit | |
210 | The maximum limit is the maximum value to which a process is allowed to | |
211 | set its current limit. It is also called the ``hard limit'' because | |
212 | there is no way for a process to get around it. A process may lower | |
213 | its own maximum limit, but only the superuser may increase a maximum | |
214 | limit. | |
215 | @cindex maximum limit | |
216 | @cindex hard limit | |
217 | @end table | |
218 | ||
219 | @pindex sys/resource.h | |
220 | The symbols for use with @code{getrlimit}, @code{setrlimit}, | |
221 | @code{getrlimit64}, and @code{seterlimit64} are defined in | |
222 | @file{sys/resource.h}. | |
223 | ||
224 | @comment sys/resource.h | |
225 | @comment BSD | |
226 | @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp}) | |
227 | Read the current and maximum limits for the resource @var{resource} | |
228 | and store them in @code{*@var{rlp}}. | |
229 | ||
230 | The return value is @code{0} on success and @code{-1} on failure. The | |
231 | only possible @code{errno} error condition is @code{EFAULT}. | |
232 | ||
233 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
234 | 32-bit system this function is in fact @code{getrlimit64}. Thus, the | |
235 | LFS interface transparently replaces the old interface. | |
236 | @end deftypefun | |
237 | ||
238 | @comment sys/resource.h | |
239 | @comment Unix98 | |
240 | @deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp}) | |
241 | This function is similar to @code{getrlimit} but its second parameter is | |
242 | a pointer to a variable of type @code{struct rlimit64}, which allows it | |
243 | to read values which wouldn't fit in the member of a @code{struct | |
244 | rlimit}. | |
245 | ||
246 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
247 | 32-bit machine, this function is available under the name | |
248 | @code{getrlimit} and so transparently replaces the old interface. | |
249 | @end deftypefun | |
250 | ||
251 | @comment sys/resource.h | |
252 | @comment BSD | |
253 | @deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp}) | |
254 | Store the current and maximum limits for the resource @var{resource} | |
255 | in @code{*@var{rlp}}. | |
256 | ||
257 | The return value is @code{0} on success and @code{-1} on failure. The | |
258 | following @code{errno} error condition is possible: | |
259 | ||
260 | @table @code | |
261 | @item EPERM | |
262 | @itemize @bullet | |
263 | @item | |
264 | The process tried to raise a current limit beyond the maximum limit. | |
265 | ||
266 | @item | |
267 | The process tried to raise a maximum limit, but is not superuser. | |
268 | @end itemize | |
269 | @end table | |
270 | ||
271 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
272 | 32-bit system this function is in fact @code{setrlimit64}. Thus, the | |
273 | LFS interface transparently replaces the old interface. | |
274 | @end deftypefun | |
275 | ||
276 | @comment sys/resource.h | |
277 | @comment Unix98 | |
278 | @deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp}) | |
279 | This function is similar to @code{setrlimit} but its second parameter is | |
280 | a pointer to a variable of type @code{struct rlimit64} which allows it | |
281 | to set values which wouldn't fit in the member of a @code{struct | |
282 | rlimit}. | |
283 | ||
284 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
285 | 32-bit machine this function is available under the name | |
286 | @code{setrlimit} and so transparently replaces the old interface. | |
287 | @end deftypefun | |
288 | ||
289 | @comment sys/resource.h | |
290 | @comment BSD | |
291 | @deftp {Data Type} {struct rlimit} | |
292 | This structure is used with @code{getrlimit} to receive limit values, | |
293 | and with @code{setrlimit} to specify limit values for a particular process | |
294 | and resource. It has two fields: | |
295 | ||
296 | @table @code | |
297 | @item rlim_t rlim_cur | |
298 | The current limit | |
299 | ||
300 | @item rlim_t rlim_max | |
301 | The maximum limit. | |
302 | @end table | |
303 | ||
304 | For @code{getrlimit}, the structure is an output; it receives the current | |
305 | values. For @code{setrlimit}, it specifies the new values. | |
306 | @end deftp | |
307 | ||
308 | For the LFS functions a similar type is defined in @file{sys/resource.h}. | |
309 | ||
310 | @comment sys/resource.h | |
311 | @comment Unix98 | |
312 | @deftp {Data Type} {struct rlimit64} | |
313 | This structure is analogous to the @code{rlimit} structure above, but | |
314 | its components have wider ranges. It has two fields: | |
315 | ||
316 | @table @code | |
317 | @item rlim64_t rlim_cur | |
318 | This is analogous to @code{rlimit.rlim_cur}, but with a different type. | |
319 | ||
320 | @item rlim64_t rlim_max | |
321 | This is analogous to @code{rlimit.rlim_max}, but with a different type. | |
322 | @end table | |
323 | ||
324 | @end deftp | |
325 | ||
326 | Here is a list of resources for which you can specify a limit. Memory | |
327 | and file sizes are measured in bytes. | |
328 | ||
329 | @table @code | |
330 | @comment sys/resource.h | |
331 | @comment BSD | |
332 | @item RLIMIT_CPU | |
333 | @vindex RLIMIT_CPU | |
334 | The maximum amount of CPU time the process can use. If it runs for | |
335 | longer than this, it gets a signal: @code{SIGXCPU}. The value is | |
336 | measured in seconds. @xref{Operation Error Signals}. | |
337 | ||
338 | @comment sys/resource.h | |
339 | @comment BSD | |
340 | @item RLIMIT_FSIZE | |
341 | @vindex RLIMIT_FSIZE | |
342 | The maximum size of file the process can create. Trying to write a | |
343 | larger file causes a signal: @code{SIGXFSZ}. @xref{Operation Error | |
344 | Signals}. | |
345 | ||
346 | @comment sys/resource.h | |
347 | @comment BSD | |
348 | @item RLIMIT_DATA | |
349 | @vindex RLIMIT_DATA | |
350 | The maximum size of data memory for the process. If the process tries | |
351 | to allocate data memory beyond this amount, the allocation function | |
352 | fails. | |
353 | ||
354 | @comment sys/resource.h | |
355 | @comment BSD | |
356 | @item RLIMIT_STACK | |
357 | @vindex RLIMIT_STACK | |
358 | The maximum stack size for the process. If the process tries to extend | |
359 | its stack past this size, it gets a @code{SIGSEGV} signal. | |
360 | @xref{Program Error Signals}. | |
361 | ||
362 | @comment sys/resource.h | |
363 | @comment BSD | |
364 | @item RLIMIT_CORE | |
365 | @vindex RLIMIT_CORE | |
366 | The maximum size core file that this process can create. If the process | |
367 | terminates and would dump a core file larger than this, then no core | |
368 | file is created. So setting this limit to zero prevents core files from | |
369 | ever being created. | |
370 | ||
371 | @comment sys/resource.h | |
372 | @comment BSD | |
373 | @item RLIMIT_RSS | |
374 | @vindex RLIMIT_RSS | |
375 | The maximum amount of physical memory that this process should get. | |
376 | This parameter is a guide for the system's scheduler and memory | |
377 | allocator; the system may give the process more memory when there is a | |
378 | surplus. | |
379 | ||
380 | @comment sys/resource.h | |
381 | @comment BSD | |
382 | @item RLIMIT_MEMLOCK | |
383 | The maximum amount of memory that can be locked into physical memory (so | |
384 | it will never be paged out). | |
385 | ||
386 | @comment sys/resource.h | |
387 | @comment BSD | |
388 | @item RLIMIT_NPROC | |
389 | The maximum number of processes that can be created with the same user ID. | |
390 | If you have reached the limit for your user ID, @code{fork} will fail | |
391 | with @code{EAGAIN}. @xref{Creating a Process}. | |
392 | ||
393 | @comment sys/resource.h | |
394 | @comment BSD | |
395 | @item RLIMIT_NOFILE | |
396 | @vindex RLIMIT_NOFILE | |
397 | @itemx RLIMIT_OFILE | |
398 | @vindex RLIMIT_OFILE | |
399 | The maximum number of files that the process can open. If it tries to | |
400 | open more files than this, its open attempt fails with @code{errno} | |
401 | @code{EMFILE}. @xref{Error Codes}. Not all systems support this limit; | |
402 | GNU does, and 4.4 BSD does. | |
403 | ||
404 | @comment sys/resource.h | |
405 | @comment Unix98 | |
406 | @item RLIMIT_AS | |
407 | @vindex RLIMIT_AS | |
408 | The maximum size of total memory that this process should get. If the | |
409 | process tries to allocate more memory beyond this amount with, for | |
410 | example, @code{brk}, @code{malloc}, @code{mmap} or @code{sbrk}, the | |
411 | allocation function fails. | |
412 | ||
413 | @comment sys/resource.h | |
414 | @comment BSD | |
415 | @item RLIM_NLIMITS | |
416 | @vindex RLIM_NLIMITS | |
417 | The number of different resource limits. Any valid @var{resource} | |
418 | operand must be less than @code{RLIM_NLIMITS}. | |
419 | @end table | |
420 | ||
421 | @comment sys/resource.h | |
422 | @comment BSD | |
423 | @deftypevr Constant int RLIM_INFINITY | |
424 | This constant stands for a value of ``infinity'' when supplied as | |
425 | the limit value in @code{setrlimit}. | |
426 | @end deftypevr | |
427 | ||
428 | ||
429 | The following are historical functions to do some of what the functions | |
430 | above do. The functions above are better choices. | |
431 | ||
432 | @code{ulimit} and the command symbols are declared in @file{ulimit.h}. | |
433 | @pindex ulimit.h | |
434 | @comment ulimit.h | |
435 | ||
436 | @deftypefun int ulimit (int @var{cmd}, ...) | |
437 | ||
438 | @code{ulimit} gets the current limit or sets the current and maximum | |
439 | limit for a particular resource for the calling process according to the | |
440 | command @var{cmd}.a | |
441 | ||
442 | If you are getting a limit, the command argument is the only argument. | |
443 | If you are setting a limit, there is a second argument: | |
444 | @code{long int} @var{limit} which is the value to which you are setting | |
445 | the limit. | |
446 | ||
447 | The @var{cmd} values and the operations they specify are: | |
448 | @table @code | |
449 | ||
450 | @item GETFSIZE | |
451 | Get the current limit on the size of a file, in units of 512 bytes. | |
452 | ||
453 | @item SETFSIZE | |
454 | Set the current and maximum limit on the size of a file to @var{limit} * | |
455 | 512 bytes. | |
456 | ||
457 | @end table | |
458 | ||
459 | There are also some other @var{cmd} values that may do things on some | |
460 | systems, but they are not supported. | |
461 | ||
462 | Only the superuser may increase a maximum limit. | |
463 | ||
464 | When you successfully get a limit, the return value of @code{ulimit} is | |
465 | that limit, which is never negative. When you successfully set a limit, | |
466 | the return value is zero. When the function fails, the return value is | |
467 | @code{-1} and @code{errno} is set according to the reason: | |
468 | ||
469 | @table @code | |
470 | @item EPERM | |
471 | A process tried to increase a maximum limit, but is not superuser. | |
472 | @end table | |
473 | ||
474 | ||
475 | @end deftypefun | |
476 | ||
477 | @code{vlimit} and its resource symbols are declared in @file{sys/vlimit.h}. | |
478 | @comment sys/vlimit.h | |
479 | @pindex sys/vlimit.h | |
480 | @comment BSD | |
481 | ||
482 | @deftypefun int vlimit (int @var{resource}, int @var{limit}) | |
483 | ||
484 | @code{vlimit} sets the current limit for a resource for a process. | |
485 | ||
486 | @var{resource} identifies the resource: | |
487 | ||
488 | @table @code | |
489 | @item LIM_CPU | |
490 | Maximum CPU time. Same as @code{RLIMIT_CPU} for @code{setrlimit}. | |
491 | @item LIM_FSIZE | |
492 | Maximum file size. Same as @code{RLIMIT_FSIZE} for @code{setrlimit}. | |
493 | @item LIM_DATA | |
494 | Maximum data memory. Same as @code{RLIMIT_DATA} for @code{setrlimit}. | |
495 | @item LIM_STACK | |
496 | Maximum stack size. Same as @code{RLIMIT_STACK} for @code{setrlimit}. | |
497 | @item LIM_CORE | |
498 | Maximum core file size. Same as @code{RLIMIT_COR} for @code{setrlimit}. | |
499 | @item LIM_MAXRSS | |
500 | Maximum physical memory. Same as @code{RLIMIT_RSS} for @code{setrlimit}. | |
501 | @end table | |
502 | ||
503 | The return value is zero for success, and @code{-1} with @code{errno} set | |
504 | accordingly for failure: | |
505 | ||
506 | @table @code | |
507 | @item EPERM | |
508 | The process tried to set its current limit beyond its maximum limit. | |
509 | @end table | |
510 | ||
511 | @end deftypefun | |
512 | ||
513 | @node Priority | |
639c6286 | 514 | @section Process CPU Priority And Scheduling |
5ce8f203 | 515 | @cindex process priority |
639c6286 | 516 | @cindex cpu priority |
5ce8f203 UD |
517 | @cindex priority of a process |
518 | ||
639c6286 UD |
519 | When multiple processes simultaneously require CPU time, the system's |
520 | scheduling policy and process CPU priorities determine which processes | |
521 | get it. This section describes how that determination is made and | |
522 | GNU C library functions to control it. | |
523 | ||
524 | It is common to refer to CPU scheduling simply as scheduling and a | |
525 | process' CPU priority simply as the process' priority, with the CPU | |
526 | resource being implied. Bear in mind, though, that CPU time is not the | |
527 | only resource a process uses or that processes contend for. In some | |
528 | cases, it is not even particularly important. Giving a process a high | |
529 | ``priority'' may have very little effect on how fast a process runs with | |
530 | respect to other processes. The priorities discussed in this section | |
531 | apply only to CPU time. | |
532 | ||
533 | CPU scheduling is a complex issue and different systems do it in wildly | |
534 | different ways. New ideas continually develop and find their way into | |
535 | the intricacies of the various systems' scheduling algorithms. This | |
536 | section discusses the general concepts, some specifics of systems | |
537 | that commonly use the GNU C library, and some standards. | |
538 | ||
539 | For simplicity, we talk about CPU contention as if there is only one CPU | |
540 | in the system. But all the same principles apply when a processor has | |
541 | multiple CPUs, and knowing that the number of processes that can run at | |
542 | any one time is equal to the number of CPUs, you can easily extrapolate | |
543 | the information. | |
544 | ||
545 | The functions described in this section are all defined by the POSIX.1 | |
546 | and POSIX.1b standards (the @code{sched...} functions are POSIX.1b). | |
547 | However, POSIX does not define any semantics for the values that these | |
548 | functions get and set. In this chapter, the semantics are based on the | |
549 | Linux kernel's implementation of the POSIX standard. As you will see, | |
550 | the Linux implementation is quite the inverse of what the authors of the | |
551 | POSIX syntax had in mind. | |
552 | ||
553 | @menu | |
554 | * Absolute Priority:: The first tier of priority. Posix | |
555 | * Realtime Scheduling:: Scheduling among the process nobility | |
556 | * Basic Scheduling Functions:: Get/set scheduling policy, priority | |
557 | * Traditional Scheduling:: Scheduling among the vulgar masses | |
558 | @end menu | |
559 | ||
560 | ||
561 | ||
562 | @node Absolute Priority | |
563 | @subsection Absolute Priority | |
564 | @cindex absolute priority | |
565 | @cindex priority, absolute | |
566 | ||
567 | Every process has an absolute priority, and it is represented by a number. | |
568 | The higher the number, the higher the absolute priority. | |
569 | ||
570 | @cindex realtime CPU scheduling | |
571 | On systems of the past, and most systems today, all processes have | |
572 | absolute priority 0 and this section is irrelevant. In that case, | |
573 | @xref{Traditional Scheduling}. Absolute priorities were invented to | |
574 | accomodate realtime systems, in which it is vital that certain processes | |
575 | be able to respond to external events happening in real time, which | |
576 | means they cannot wait around while some other process that @emph{wants | |
577 | to}, but doesn't @emph{need to} run occupies the CPU. | |
578 | ||
579 | @cindex ready to run | |
580 | @cindex preemptive scheduling | |
581 | When two processes are in contention to use the CPU at any instant, the | |
582 | one with the higher absolute priority always gets it. This is true even if the | |
583 | process with the lower priority is already using the CPU (i.e. the | |
584 | scheduling is preemptive). Of course, we're only talking about | |
585 | processes that are running or ``ready to run,'' which means they are | |
586 | ready to execute instructions right now. When a process blocks to wait | |
587 | for something like I/O, its absolute priority is irrelevant. | |
588 | ||
589 | @cindex runnable process | |
590 | @strong{Note:} The term ``runnable'' is a synonym for ``ready to run.'' | |
591 | ||
592 | When two processes are running or ready to run and both have the same | |
593 | absolute priority, it's more interesting. In that case, who gets the | |
594 | CPU is determined by the scheduling policy. If the processeses have | |
595 | absolute priority 0, the traditional scheduling policy described in | |
596 | @ref{Traditional Scheduling} applies. Otherwise, the policies described | |
597 | in @ref{Realtime Scheduling} apply. | |
598 | ||
599 | You normally give an absolute priority above 0 only to a process that | |
600 | can be trusted not to hog the CPU. Such processes are designed to block | |
601 | (or terminate) after relatively short CPU runs. | |
602 | ||
603 | A process begins life with the same absolute priority as its parent | |
604 | process. Functions described in @ref{Basic Scheduling Functions} can | |
605 | change it. | |
606 | ||
607 | Only a privileged process can change a process' absolute priority to | |
608 | something other than @code{0}. Only a privileged process or the | |
609 | target process' owner can change its absolute priority at all. | |
610 | ||
611 | POSIX requires absolute priority values used with the realtime | |
612 | scheduling policies to be consecutive with a range of at least 32. On | |
613 | Linux, they are 1 through 99. The functions | |
614 | @code{sched_get_priority_max} and @code{sched_set_priority_min} portably | |
615 | tell you what the range is on a particular system. | |
616 | ||
617 | ||
618 | @subsubsection Using Absolute Priority | |
619 | ||
620 | One thing you must keep in mind when designing real time applications is | |
621 | that having higher absolute priority than any other process doesn't | |
622 | guarantee the process can run continuously. Two things that can wreck a | |
623 | good CPU run are interrupts and page faults. | |
624 | ||
625 | Interrupt handlers live in that limbo between processes. The CPU is | |
626 | executing instructions, but they aren't part of any process. An | |
627 | interrupt will stop even the highest priority process. So you must | |
628 | allow for slight delays and make sure that no device in the system has | |
629 | an interrupt handler that could cause too long a delay between | |
630 | instructions for your process. | |
631 | ||
632 | Similarly, a page fault causes what looks like a straightforward | |
633 | sequence of instructions to take a long time. The fact that other | |
634 | processes get to run while the page faults in is of no consequence, | |
635 | because as soon as the I/O is complete, the high priority process will | |
636 | kick them out and run again, but the wait for the I/O itself could be a | |
637 | problem. To neutralize this threat, use @code{mlock} or | |
638 | @code{mlockall}. | |
639 | ||
640 | There are a few ramifications of the absoluteness of this priority on a | |
641 | single-CPU system that you need to keep in mind when you choose to set a | |
642 | priority and also when you're working on a program that runs with high | |
643 | absolute priority. Consider a process that has higher absolute priority | |
644 | than any other process in the system and due to a bug in its program, it | |
645 | gets into an infinite loop. It will never cede the CPU. You can't run | |
646 | a command to kill it because your command would need to get the CPU in | |
647 | order to run. The errant program is in complete control. It controls | |
648 | the vertical, it controls the horizontal. | |
649 | ||
650 | There are two ways to avoid this: 1) keep a shell running somewhere with | |
651 | a higher absolute priority. 2) keep a controlling terminal attached to | |
652 | the high priority process group. All the priority in the world won't | |
653 | stop an interrupt handler from running and delivering a signal to the | |
654 | process if you hit Control-C. | |
655 | ||
656 | Some systems use absolute priority as a means of allocating a fixed per | |
657 | centage of CPU time to a process. To do this, a super high priority | |
658 | privileged process constantly monitors the process' CPU usage and raises | |
659 | its absolute priority when the process isn't getting its entitled share | |
660 | and lowers it when the process is exceeding it. | |
661 | ||
662 | @strong{Note:} The absolute priority is sometimes called the ``static | |
663 | priority.'' We don't use that term in this manual because it misses the | |
664 | most important feature of the absolute priority: its absoluteness. | |
665 | ||
666 | ||
667 | @node Realtime Scheduling | |
668 | @subsection Realtime Scheduling | |
669 | @comment realtime scheduling | |
670 | ||
671 | Whenever two processes with the same absolute priority are ready to run, | |
672 | the kernel has a decision to make, because only one can run at a time. | |
673 | If the processes have absolute priority 0, the kernel makes this decision | |
674 | as described in @ref{Traditional Scheduling}. Otherwise, the decision | |
675 | is as described in this section. | |
676 | ||
677 | If two processes are ready to run but have different absolute priorities, | |
678 | the decision is much simpler, and is described in @ref{Absolute | |
679 | Priority}. | |
680 | ||
681 | Each process has a scheduling policy. For processes with absolute | |
682 | priority other than zero, there are two available: | |
683 | ||
684 | @enumerate | |
685 | @item | |
686 | First Come First Served | |
687 | @item | |
688 | Round Robin | |
689 | @end enumerate | |
690 | ||
691 | The most sensible case is where all the processes with a certain | |
692 | absolute priority have the same scheduling policy. We'll discuss that | |
693 | first. | |
694 | ||
695 | In Round Robin, processes share the CPU, each one running for a small | |
696 | quantum of time (``time slice'') and then yielding to another in a | |
697 | circular fashion. Of course, only processes that are ready to run and | |
698 | have the same absolute priority are in this circle. | |
699 | ||
700 | In First Come First Served, the process that has been waiting the | |
701 | longest to run gets the CPU, and it keeps it until it voluntarily | |
702 | relinquishes the CPU, runs out of things to do (blocks), or gets | |
703 | preempted by a higher priority process. | |
704 | ||
705 | First Come First Served, along with maximal absolute priority and | |
706 | careful control of interrupts and page faults, is the one to use when a | |
707 | process absolutely, positively has to run at full CPU speed or not at | |
708 | all. | |
709 | ||
710 | Judicious use of @code{sched_yield} function invocations by processes | |
711 | with First Come First Served scheduling policy forms a good compromise | |
712 | between Round Robin and First Come First Served. | |
713 | ||
714 | To understand how scheduling works when processes of different scheduling | |
715 | policies occupy the same absolute priority, you have to know the nitty | |
716 | gritty details of how processes enter and exit the ready to run list: | |
717 | ||
718 | In both cases, the ready to run list is organized as a true queue, where | |
719 | a process gets pushed onto the tail when it becomes ready to run and is | |
720 | popped off the head when the scheduler decides to run it. Note that | |
721 | ready to run and running are two mutually exclusive states. When the | |
722 | scheduler runs a process, that process is no longer ready to run and no | |
723 | longer in the ready to run list. When the process stops running, it | |
724 | may go back to being ready to run again. | |
725 | ||
726 | The only difference between a process that is assigned the Round Robin | |
727 | scheduling policy and a process that is assigned First Come First Serve | |
728 | is that in the former case, the process is automatically booted off the | |
729 | CPU after a certain amount of time. When that happens, the process goes | |
730 | back to being ready to run, which means it enters the queue at the tail. | |
731 | The time quantum we're talking about is small. Really small. This is | |
732 | not your father's timesharing. For example, with the Linux kernel, the | |
733 | round robin time slice is a thousand times shorter than its typical | |
734 | time slice for traditional scheduling. | |
735 | ||
736 | A process begins life with the same scheduling policy as its parent process. | |
737 | Functions described in @ref{Basic Scheduling Functions} can change it. | |
738 | ||
739 | Only a privileged process can set the scheduling policy of a process | |
740 | that has absolute priority higher than 0. | |
741 | ||
742 | @node Basic Scheduling Functions | |
743 | @subsection Basic Scheduling Functions | |
744 | ||
745 | This section describes functions in the GNU C library for setting the | |
746 | absolute priority and scheduling policy of a process. | |
747 | ||
748 | @strong{Portability Note:} On systems that have the functions in this | |
749 | section, the macro _POSIX_PRIORITY_SCHEDULING is defined in | |
750 | @file{<unistd.h>}. | |
751 | ||
752 | For the case that the scheduling policy is traditional scheduling, more | |
753 | functions to fine tune the scheduling are in @ref{Traditional Scheduling}. | |
754 | ||
755 | Don't try to make too much out of the naming and structure of these | |
756 | functions. They don't match the concepts described in this manual | |
757 | because the functions are as defined by POSIX.1b, but the implementation | |
758 | on systems that use the GNU C library is the inverse of what the POSIX | |
759 | structure contemplates. The POSIX scheme assumes that the primary | |
760 | scheduling parameter is the scheduling policy and that the priority | |
761 | value, if any, is a parameter of the scheduling policy. In the | |
762 | implementation, though, the priority value is king and the scheduling | |
763 | policy, if anything, only fine tunes the effect of that priority. | |
764 | ||
765 | The symbols in this section are declared by including file @file{sched.h}. | |
766 | ||
767 | @comment sched.h | |
768 | @comment POSIX | |
769 | @deftp {Data Type} {struct sched_param} | |
770 | This structure describes an absolute priority. | |
771 | @table @code | |
772 | @item int sched_priority | |
773 | absolute priority value | |
774 | @end table | |
775 | @end deftp | |
776 | ||
777 | @comment sched.h | |
778 | @comment POSIX | |
779 | @deftypefun int sched_setscheduler (pid_t @var{pid}, int @var{policy}, const struct sched_param *@var{param}) | |
780 | ||
781 | This function sets both the absolute priority and the scheduling policy | |
782 | for a process. | |
783 | ||
784 | It assigns the absolute priority value given by @var{param} and the | |
785 | scheduling policy @var{policy} to the process with Process ID @var{pid}, | |
786 | or the calling process if @var{pid} is zero. If @var{policy} is | |
787 | negative, @code{sched_setschedule} keeps the existing scheduling policy. | |
788 | ||
789 | The following macros represent the valid values for @var{policy}: | |
790 | ||
791 | @table @code | |
792 | @item SCHED_OTHER | |
793 | Traditional Scheduling | |
794 | @item SCHED_FIFO | |
795 | First In First Out | |
796 | @item SCHED_RR | |
797 | Round Robin | |
798 | @end table | |
799 | ||
800 | @c The Linux kernel code (in sched.c) actually reschedules the process, | |
801 | @c but it puts it at the head of the run queue, so I'm not sure just what | |
802 | @c the effect is, but it must be subtle. | |
803 | ||
804 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
805 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
806 | to this function are: | |
807 | ||
808 | @table @code | |
809 | @item EPERM | |
810 | @itemize @bullet | |
811 | @item | |
812 | The calling process does not have @code{CAP_SYS_NICE} permission and | |
813 | @var{policy} is not @code{SCHED_OTHER} (or it's negative and the | |
814 | existing policy is not @code{SCHED_OTHER}. | |
815 | ||
816 | @item | |
817 | The calling process does not have @code{CAP_SYS_NICE} permission and its | |
818 | owner is not the target process' owner. I.e. the effective uid of the | |
819 | calling process is neither the effective nor the real uid of process | |
820 | @var{pid}. | |
821 | @c We need a cross reference to the capabilities section, when written. | |
822 | @end itemize | |
823 | ||
824 | @item ESRCH | |
825 | There is no process with pid @var{pid} and @var{pid} is not zero. | |
826 | ||
827 | @item EINVAL | |
828 | @itemize @bullet | |
829 | @item | |
830 | @var{policy} does not identify an existing scheduling policy. | |
831 | ||
832 | @item | |
833 | The absolute priority value identified by *@var{param} is outside the | |
834 | valid range for the scheduling policy @var{policy} (or the existing | |
835 | scheduling policy if @var{policy} is negative) or @var{param} is | |
836 | null. @code{sched_get_priority_max} and @code{sched_get_priority_min} | |
837 | tell you what the valid range is. | |
838 | ||
839 | @item | |
840 | @var{pid} is negative. | |
841 | @end itemize | |
842 | @end table | |
843 | ||
844 | @end deftypefun | |
845 | ||
846 | ||
847 | @comment sched.h | |
848 | @comment POSIX | |
849 | @deftypefun int sched_getscheduler (pid_t @var{pid}) | |
850 | ||
851 | This function returns the scheduling policy assigned to the process with | |
852 | Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero. | |
853 | ||
854 | The return value is the scheduling policy. See | |
855 | @code{sched_setscheduler} for the possible values. | |
856 | ||
857 | If the function fails, the return value is instead @code{-1} and | |
858 | @code{errno} is set accordingly. | |
859 | ||
860 | The @code{errno} values specific to this function are: | |
861 | ||
862 | @table @code | |
863 | ||
864 | @item ESRCH | |
865 | There is no process with pid @var{pid} and it is not zero. | |
866 | ||
867 | @item EINVAL | |
868 | @var{pid} is negative. | |
869 | ||
870 | @end table | |
871 | ||
872 | Note that this function is not an exact mate to @code{sched_setscheduler} | |
873 | because while that function sets the scheduling policy and the absolute | |
874 | priority, this function gets only the scheduling policy. To get the | |
875 | absolute priority, use @code{sched_getparam}. | |
876 | ||
877 | @end deftypefun | |
878 | ||
879 | ||
880 | @comment sched.h | |
881 | @comment POSIX | |
882 | @deftypefun int sched_setparam (pid_t @var{pid}, const struct sched_param *@var{param}) | |
883 | ||
884 | This function sets a process' absolute priority. | |
885 | ||
886 | It is functionally identical to @code{sched_setscheduler} with | |
887 | @var{policy} = @code{-1}. | |
888 | ||
889 | @c in fact, that's how it's implemented in Linux. | |
890 | ||
891 | @end deftypefun | |
892 | ||
893 | @comment sched.h | |
894 | @comment POSIX | |
895 | @deftypefun int sched_getparam (pid_t @var{pid}, const struct sched_param *@var{param}) | |
896 | ||
897 | This function returns a process' absolute priority. | |
898 | ||
899 | @var{pid} is the Process ID (pid) of the process whose absolute priority | |
900 | you want to know. | |
901 | ||
902 | @var{param} is a pointer to a structure in which the function stores the | |
903 | absolute priority of the process. | |
904 | ||
905 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
906 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
907 | to this function are: | |
908 | ||
909 | @table @code | |
910 | ||
911 | @item ESRCH | |
912 | There is no process with pid @var{pid} and it is not zero. | |
913 | ||
914 | @item EINVAL | |
915 | @var{pid} is negative. | |
916 | ||
917 | @end table | |
918 | ||
919 | @end deftypefun | |
920 | ||
921 | ||
922 | @comment sched.h | |
923 | @comment POSIX | |
924 | @deftypefun int sched_get_priority_min (int *@var{policy}); | |
925 | ||
926 | This function returns the lowest absolute priority value that is | |
927 | allowable for a process with scheduling policy @var{policy}. | |
928 | ||
929 | On Linux, it is 0 for SCHED_OTHER and 1 for everything else. | |
930 | ||
931 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
932 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
933 | to this function are: | |
934 | ||
935 | @table @code | |
936 | @item EINVAL | |
937 | @var{policy} does not identify an existing scheduling policy. | |
938 | @end table | |
939 | ||
940 | @end deftypefun | |
941 | ||
942 | @comment sched.h | |
943 | @comment POSIX | |
944 | @deftypefun int sched_set_priority_max (int *@var{policy}); | |
945 | ||
946 | This function returns the highest absolute priority value that is | |
947 | allowable for a process that with scheduling policy @var{policy}. | |
948 | ||
949 | On Linux, it is 0 for SCHED_OTHER and 99 for everything else. | |
950 | ||
951 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
952 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
953 | to this function are: | |
954 | ||
955 | @table @code | |
956 | @item EINVAL | |
957 | @var{policy} does not identify an existing scheduling policy. | |
958 | @end table | |
959 | ||
960 | @end deftypefun | |
961 | ||
962 | @comment sched.h | |
963 | @comment POSIX | |
964 | @deftypefun int sched_rr_get_interval (pid_t @var{pid}, struct timespec *@var{interval}) | |
965 | ||
966 | This function returns the length of the quantum (time slice) used with | |
967 | the Round Robin scheduling policy, if it is used, for the process with | |
968 | Process ID @var{pid}. | |
969 | ||
970 | It returns the length of time as @var{interval}. | |
971 | @c We need a cross-reference to where timespec is explained. But that | |
972 | @c section doesn't exist yet, and the time chapter needs to be slightly | |
973 | @c reorganized so there is a place to put it (which will be right next | |
974 | @c to timeval, which is presently misplaced). 2000.05.07. | |
975 | ||
976 | With a Linux kernel, the round robin time slice is always 150 | |
977 | microseconds, and @var{pid} need not even be a real pid. | |
978 | ||
979 | The return value is @code{0} on success and in the pathological case | |
980 | that it fails, the return value is @code{-1} and @code{errno} is set | |
981 | accordingly. There is nothing specific that can go wrong with this | |
982 | function, so there are no specific @code{errno} values. | |
983 | ||
984 | @end deftypefun | |
985 | ||
986 | @comment sched.h | |
987 | @comment POSIX | |
988 | @deftypefun sched_yield (void) | |
989 | ||
990 | This function voluntarily gives up the process' claim on the CPU. | |
991 | ||
992 | Technically, @code{sched_yield} causes the calling process to be made | |
993 | immediately ready to run (as opposed to running, which is what it was | |
994 | before). This means that if it has absolute priority higher than 0, it | |
995 | gets pushed onto the tail of the queue of processes that share its | |
996 | absolute priority and are ready to run, and it will run again when its | |
997 | turn next arrives. If its absolute priority is 0, it is more | |
998 | complicated, but still has the effect of yielding the CPU to other | |
999 | processes. | |
1000 | ||
1001 | If there are no other processes that share the calling process' absolute | |
1002 | priority, this function doesn't have any effect. | |
1003 | ||
1004 | To the extent that the containing program is oblivious to what other | |
1005 | processes in the system are doing and how fast it executes, this | |
1006 | function appears as a no-op. | |
1007 | ||
1008 | The return value is @code{0} on success and in the pathological case | |
1009 | that it fails, the return value is @code{-1} and @code{errno} is set | |
1010 | accordingly. There is nothing specific that can go wrong with this | |
1011 | function, so there are no specific @code{errno} values. | |
1012 | ||
1013 | @end deftypefun | |
1014 | ||
1015 | @node Traditional Scheduling | |
1016 | @subsection Traditional Scheduling | |
1017 | @cindex scheduling, traditional | |
1018 | ||
1019 | This section is about the scheduling among processes whose absolute | |
1020 | priority is 0. When the system hands out the scraps of CPU time that | |
1021 | are left over after the processes with higher absolulte priority have | |
1022 | taken all they want, the scheduling described herein determines who | |
1023 | among the great unwashed processes gets them. | |
1024 | ||
1025 | @menu | |
1026 | * Traditional Scheduling Intro:: | |
1027 | * Traditional Scheduling Functions:: | |
1028 | @end menu | |
1029 | ||
1030 | @node Traditional Scheduling Intro | |
1031 | @subsubsection Introduction To Traditional Scheduling | |
1032 | ||
1033 | Long before there was absolute priority (See @ref{Absolute Priority}), | |
1034 | Unix systems were scheduling the CPU using this system. When Posix came | |
1035 | in like the Romans and imposed absolute priorities to accomodate the | |
1036 | needs of realtime processing, it left the indigenous Absolute Priority | |
1037 | Zero processes to govern themselves by their own familiar scheduling | |
1038 | policy. | |
1039 | ||
1040 | Indeed, absolute priorities higher than zero are not available on many | |
1041 | systems today and are not typically used when they are, being intended | |
1042 | mainly for computers that do realtime processing. So this section | |
1043 | describes the only scheduling many programmers need to be concerned | |
1044 | about. | |
1045 | ||
1046 | But just to be clear about the scope of this scheduling: Any time a | |
1047 | process with a absolute priority of 0 and a process with an absolute | |
1048 | priority higher than 0 are ready to run at the same time, the one with | |
1049 | absolute priority 0 does not run. If it's already running when the | |
1050 | higher priority ready-to-run process comes into existence, it stops | |
1051 | immediately. | |
1052 | ||
1053 | In addition to its absolute priority of zero, every process has another | |
1054 | priority, which we will refer to as "dynamic priority" because it changes | |
1055 | over time. The dynamic priority is meaningless for processes with | |
1056 | an absolute priority higher than zero. | |
1057 | ||
1058 | The dynamic priority sometimes determines who gets the next turn on the | |
1059 | CPU. Sometimes it determines how long turns last. Sometimes it | |
1060 | determines whether a process can kick another off the CPU. | |
1061 | ||
1062 | In Linux, the value is a combination of these things, but mostly it is | |
1063 | just determines the length of the time slice. The higher a process' | |
1064 | dynamic priority, the longer a shot it gets on the CPU when it gets one. | |
1065 | If it doesn't use up its time slice before giving up the CPU to do | |
1066 | something like wait for I/O, it is favored for getting the CPU back when | |
1067 | it's ready for it, to finish out its time slice. Other than that, | |
1068 | selection of processes for new time slices is basically round robin. | |
1069 | But the scheduler does throw a bone to the low priority processes: A | |
1070 | process' dynamic priority rises every time it is snubbed in the | |
1071 | scheduling process. In Linux, even the fat kid gets to play. | |
1072 | ||
1073 | The fluctuation of a process' dynamic priority is regulated by another | |
1074 | value: The ``nice'' value. The nice value is an integer, usually in the | |
1075 | range -20 to 20, and represents an upper limit on a process' dynamic | |
1076 | priority. The higher the nice number, the lower that limit. | |
1077 | ||
1078 | On a typical Linux system, for example, a process with a nice value of | |
1079 | 20 can get only 10 milliseconds on the CPU at a time, whereas a process | |
1080 | with a nice value of -20 can achieve a high enough priority to get 400 | |
1081 | milliseconds. | |
1082 | ||
1083 | The idea of the nice value is deferential courtesy. In the beginning, | |
1084 | in the Unix garden of Eden, all processes shared equally in the bounty | |
1085 | of the computer system. But not all processes really need the same | |
1086 | share of CPU time, so the nice value gave a courteous process the | |
1087 | ability to refuse its equal share of CPU time that others might prosper. | |
1088 | Hence, the higher a process' nice value, the nicer the process is. | |
1089 | (Then a snake came along and offered some process a negative nice value | |
1090 | and the system became the crass resource allocation system we know | |
1091 | today). | |
1092 | ||
1093 | Dynamic priorities tend upward and downward with an objective of | |
1094 | smoothing out allocation of CPU time and giving quick response time to | |
1095 | infrequent requests. But they never exceed their nice limits, so on a | |
1096 | heavily loaded CPU, the nice value effectively determines how fast a | |
1097 | process runs. | |
1098 | ||
1099 | In keeping with the socialistic heritage of Unix process priority, a | |
1100 | process begins life with the same nice value as its parent process and | |
1101 | can raise it at will. A process can also raise the nice value of any | |
1102 | other process owned by the same user (or effective user). But only a | |
1103 | privileged process can lower its nice value. A privileged process can | |
1104 | also raise or lower another process' nice value. | |
1105 | ||
1106 | GNU C Library functions for getting and setting nice values are described in | |
1107 | @xref{Traditional Scheduling Functions}. | |
1108 | ||
1109 | @node Traditional Scheduling Functions | |
1110 | @subsubsection Functions For Traditional Scheduling | |
1111 | ||
5ce8f203 | 1112 | @pindex sys/resource.h |
639c6286 UD |
1113 | This section describes how you can read and set the nice value of a |
1114 | process. All these symbols are declared in @file{sys/resource.h}. | |
1115 | ||
1116 | The function and macro names are defined by POSIX, and refer to | |
1117 | "priority," but the functions actually have to do with nice values, as | |
1118 | the terms are used both in the manual and POSIX. | |
1119 | ||
1120 | The range of valid nice values depends on the kernel, but typically it | |
1121 | runs from @code{-20} to @code{20}. A lower nice value corresponds to | |
1122 | higher priority for the process. These constants describe the range of | |
5ce8f203 UD |
1123 | priority values: |
1124 | ||
1125 | @table @code | |
1126 | @comment sys/resource.h | |
1127 | @comment BSD | |
1128 | @item PRIO_MIN | |
1129 | @vindex PRIO_MIN | |
639c6286 | 1130 | The lowest valid nice value. |
5ce8f203 UD |
1131 | |
1132 | @comment sys/resource.h | |
1133 | @comment BSD | |
1134 | @item PRIO_MAX | |
1135 | @vindex PRIO_MAX | |
639c6286 | 1136 | The highest valid nice value. |
5ce8f203 UD |
1137 | @end table |
1138 | ||
1139 | @comment sys/resource.h | |
639c6286 | 1140 | @comment BSD,POSIX |
5ce8f203 | 1141 | @deftypefun int getpriority (int @var{class}, int @var{id}) |
639c6286 | 1142 | Return the nice value of a set of processes; @var{class} and @var{id} |
5ce8f203 | 1143 | specify which ones (see below). If the processes specified do not all |
639c6286 | 1144 | have the same nice value, this returns the lowest value that any of them |
5ce8f203 UD |
1145 | has. |
1146 | ||
639c6286 UD |
1147 | On success, the return value is @code{0}. Otherwise, it is @code{-1} |
1148 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
1149 | to this function are: | |
5ce8f203 UD |
1150 | |
1151 | @table @code | |
1152 | @item ESRCH | |
1153 | The combination of @var{class} and @var{id} does not match any existing | |
1154 | process. | |
1155 | ||
1156 | @item EINVAL | |
1157 | The value of @var{class} is not valid. | |
1158 | @end table | |
1159 | ||
639c6286 UD |
1160 | If the return value is @code{-1}, it could indicate failure, or it could |
1161 | be the nice value. The only way to make certain is to set @code{errno = | |
1162 | 0} before calling @code{getpriority}, then use @code{errno != 0} | |
1163 | afterward as the criterion for failure. | |
5ce8f203 UD |
1164 | @end deftypefun |
1165 | ||
1166 | @comment sys/resource.h | |
639c6286 UD |
1167 | @comment BSD,POSIX |
1168 | @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{niceval}) | |
1169 | Set the nice value of a set of processes to @var{niceval}; @var{class} | |
5ce8f203 UD |
1170 | and @var{id} specify which ones (see below). |
1171 | ||
639c6286 UD |
1172 | The return value is the nice value on success, and @code{-1} on |
1173 | failure. The following @code{errno} error condition are possible for | |
1174 | this function: | |
5ce8f203 UD |
1175 | |
1176 | @table @code | |
1177 | @item ESRCH | |
1178 | The combination of @var{class} and @var{id} does not match any existing | |
1179 | process. | |
1180 | ||
1181 | @item EINVAL | |
1182 | The value of @var{class} is not valid. | |
1183 | ||
1184 | @item EPERM | |
639c6286 UD |
1185 | The call would set the nice value of a process which is owned by a different |
1186 | user than the calling process (i.e. the target process' real or effective | |
1187 | uid does not match the calling process' effective uid) and the calling | |
1188 | process does not have @code{CAP_SYS_NICE} permission. | |
5ce8f203 UD |
1189 | |
1190 | @item EACCES | |
639c6286 UD |
1191 | The call would lower the process' nice value and the process does not have |
1192 | @code{CAP_SYS_NICE} permission. | |
5ce8f203 | 1193 | @end table |
639c6286 | 1194 | |
5ce8f203 UD |
1195 | @end deftypefun |
1196 | ||
1197 | The arguments @var{class} and @var{id} together specify a set of | |
1198 | processes in which you are interested. These are the possible values of | |
1199 | @var{class}: | |
1200 | ||
1201 | @table @code | |
1202 | @comment sys/resource.h | |
1203 | @comment BSD | |
1204 | @item PRIO_PROCESS | |
1205 | @vindex PRIO_PROCESS | |
639c6286 | 1206 | One particular process. The argument @var{id} is a process ID (pid). |
5ce8f203 UD |
1207 | |
1208 | @comment sys/resource.h | |
1209 | @comment BSD | |
1210 | @item PRIO_PGRP | |
1211 | @vindex PRIO_PGRP | |
639c6286 UD |
1212 | All the processes in a particular process group. The argument @var{id} is |
1213 | a process group ID (pgid). | |
5ce8f203 UD |
1214 | |
1215 | @comment sys/resource.h | |
1216 | @comment BSD | |
1217 | @item PRIO_USER | |
1218 | @vindex PRIO_USER | |
639c6286 UD |
1219 | All the processes owned by a particular user (i.e. whose real uid |
1220 | indicates the user). The argument @var{id} is a user ID (uid). | |
5ce8f203 UD |
1221 | @end table |
1222 | ||
639c6286 UD |
1223 | If the argument @var{id} is 0, it stands for the calling process, its |
1224 | process group, or its owner (real uid), according to @var{class}. | |
5ce8f203 UD |
1225 | |
1226 | @c ??? I don't know where we should say this comes from. | |
1227 | @comment Unix | |
1228 | @comment dunno.h | |
1229 | @deftypefun int nice (int @var{increment}) | |
639c6286 | 1230 | Increment the nice value of the calling process by @var{increment}. |
5ce8f203 UD |
1231 | The return value is the same as for @code{setpriority}. |
1232 | ||
1233 | Here is an equivalent definition of @code{nice}: | |
1234 | ||
1235 | @smallexample | |
1236 | int | |
1237 | nice (int increment) | |
1238 | @{ | |
1239 | int old = getpriority (PRIO_PROCESS, 0); | |
1240 | return setpriority (PRIO_PROCESS, 0, old + increment); | |
1241 | @} | |
1242 | @end smallexample | |
1243 | @end deftypefun | |
639c6286 | 1244 |