Document resource handling and querying functions.
[kopensolaris-gnu/glibc.git] / manual / resource.texi
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
514 @section Process Priority
515 @cindex process priority
516 @cindex priority of a process
517
518 @pindex sys/resource.h
519 When several processes try to run, their respective priorities determine
520 what share of the CPU each process gets.  This section describes how you
521 can read and set the priority of a process.  All these functions and
522 macros are declared in @file{sys/resource.h}.
523
524 The range of valid priority values depends on the operating system, but
525 typically it runs from @code{-20} to @code{20}.  A lower priority value
526 means the process runs more often.  These constants describe the range of
527 priority values:
528
529 @table @code
530 @comment sys/resource.h
531 @comment BSD
532 @item PRIO_MIN
533 @vindex PRIO_MIN
534 The smallest valid priority value.
535
536 @comment sys/resource.h
537 @comment BSD
538 @item PRIO_MAX
539 @vindex PRIO_MAX
540 The largest valid priority value.
541 @end table
542
543 @comment sys/resource.h
544 @comment BSD
545 @deftypefun int getpriority (int @var{class}, int @var{id})
546 Read the priority of a class of processes; @var{class} and @var{id}
547 specify which ones (see below).  If the processes specified do not all
548 have the same priority, this returns the smallest value that any of them
549 has.
550
551 The return value is the priority value on success, and @code{-1} on
552 failure.  The following @code{errno} error condition are possible for
553 this function:
554
555 @table @code
556 @item ESRCH
557 The combination of @var{class} and @var{id} does not match any existing
558 process.
559
560 @item EINVAL
561 The value of @var{class} is not valid.
562 @end table
563
564 If the return value is @code{-1}, it could indicate failure, or it
565 could be the priority value.  The only way to make certain is to set
566 @code{errno = 0} before calling @code{getpriority}, then use @code{errno
567 != 0} afterward as the criterion for failure.
568 @end deftypefun
569
570 @comment sys/resource.h
571 @comment BSD
572 @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{priority})
573 Set the priority of a class of processes to @var{priority}; @var{class}
574 and @var{id} specify which ones (see below).
575
576 The return value is @code{0} on success and @code{-1} on failure.  The
577 following @code{errno} error condition are defined for this function:
578
579 @table @code
580 @item ESRCH
581 The combination of @var{class} and @var{id} does not match any existing
582 process.
583
584 @item EINVAL
585 The value of @var{class} is not valid.
586
587 @item EPERM
588 You tried to set the priority of some other user's process, and you
589 don't have privileges for that.
590
591 @item EACCES
592 You tried to lower the priority of a process, and you don't have
593 privileges for that.
594 @end table
595 @end deftypefun
596
597 The arguments @var{class} and @var{id} together specify a set of
598 processes in which you are interested.  These are the possible values of
599 @var{class}:
600
601 @table @code
602 @comment sys/resource.h
603 @comment BSD
604 @item PRIO_PROCESS
605 @vindex PRIO_PROCESS
606 Read or set the priority of one process.  The argument @var{id} is a
607 process ID.
608
609 @comment sys/resource.h
610 @comment BSD
611 @item PRIO_PGRP
612 @vindex PRIO_PGRP
613 Read or set the priority of one process group.  The argument @var{id} is
614 a process group ID.
615
616 @comment sys/resource.h
617 @comment BSD
618 @item PRIO_USER
619 @vindex PRIO_USER
620 Read or set the priority of one user's processes.  The argument @var{id}
621 is a user ID.
622 @end table
623
624 If the argument @var{id} is 0, it stands for the current process,
625 current process group, or the current user, according to @var{class}.
626
627 @c ??? I don't know where we should say this comes from.
628 @comment Unix
629 @comment dunno.h
630 @deftypefun int nice (int @var{increment})
631 Increment the priority of the current process by @var{increment}.
632 The return value is the same as for @code{setpriority}.
633
634 Here is an equivalent definition of @code{nice}:
635
636 @smallexample
637 int
638 nice (int increment)
639 @{
640   int old = getpriority (PRIO_PROCESS, 0);
641   return setpriority (PRIO_PROCESS, 0, old + increment);
642 @}
643 @end smallexample
644 @end deftypefun