From 5ce8f2039b1fa51dec4ba8b12a014f77516b3ae2 Mon Sep 17 00:00:00 2001 From: Ulrich Drepper Date: Tue, 18 Apr 2000 04:27:22 +0000 Subject: Update. * manual/Makefile (chapters): Add resource. * manual/time.texi: Move section on resources to... * manual/resource.texi: ...here. New file. * manual/setjmp.texi: Adjust back reference. Patch by Bryan Henderson . --- manual/resource.texi | 644 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 644 insertions(+) create mode 100644 manual/resource.texi (limited to 'manual/resource.texi') diff --git a/manual/resource.texi b/manual/resource.texi new file mode 100644 index 0000000000..a197e28a60 --- /dev/null +++ b/manual/resource.texi @@ -0,0 +1,644 @@ +@node Resource Usage And Limitation, Non-Local Exits, Date and Time, Top +@c %MENU% Functions for examining resource usage and getting and setting limits +@chapter Resource Usage And Limitation +This chapter describes functions for examining how much of various kinds of +resources (CPU time, memory, etc.) a process has used and getting and setting +limits on future usage. + +@menu +* Resource Usage:: Measuring various resources used. +* Limits on Resources:: Specifying limits on resource usage. +* Priority:: Reading or setting process run priority. +@end menu + + +@node Resource Usage +@section Resource Usage + +@pindex sys/resource.h +The function @code{getrusage} and the data type @code{struct rusage} +are used to examine the resource usage of a process. They are declared +in @file{sys/resource.h}. + +@comment sys/resource.h +@comment BSD +@deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage}) +This function reports resource usage totals for processes specified by +@var{processes}, storing the information in @code{*@var{rusage}}. + +In most systems, @var{processes} has only two valid values: + +@table @code +@comment sys/resource.h +@comment BSD +@item RUSAGE_SELF +Just the current process. + +@comment sys/resource.h +@comment BSD +@item RUSAGE_CHILDREN +All child processes (direct and indirect) that have already terminated. +@end table + +In the GNU system, you can also inquire about a particular child process +by specifying its process ID. + +The return value of @code{getrusage} is zero for success, and @code{-1} +for failure. + +@table @code +@item EINVAL +The argument @var{processes} is not valid. +@end table +@end deftypefun + +One way of getting resource usage for a particular child process is with +the function @code{wait4}, which returns totals for a child when it +terminates. @xref{BSD Wait Functions}. + +@comment sys/resource.h +@comment BSD +@deftp {Data Type} {struct rusage} +This data type stores various resource usage statistics. It has the +following members, and possibly others: + +@table @code +@item struct timeval ru_utime +Time spent executing user instructions. + +@item struct timeval ru_stime +Time spent in operating system code on behalf of @var{processes}. + +@item long int ru_maxrss +The maximum resident set size used, in kilobytes. That is, the maximum +number of kilobytes of physical memory that @var{processes} used +simultaneously. + +@item long int ru_ixrss +An integral value expressed in kilobytes times ticks of execution, which +indicates the amount of memory used by text that was shared with other +processes. + +@item long int ru_idrss +An integral value expressed the same way, which is the amount of +unshared memory used for data. + +@item long int ru_isrss +An integral value expressed the same way, which is the amount of +unshared memory used for stack space. + +@item long int ru_minflt +The number of page faults which were serviced without requiring any I/O. + +@item long int ru_majflt +The number of page faults which were serviced by doing I/O. + +@item long int ru_nswap +The number of times @var{processes} was swapped entirely out of main memory. + +@item long int ru_inblock +The number of times the file system had to read from the disk on behalf +of @var{processes}. + +@item long int ru_oublock +The number of times the file system had to write to the disk on behalf +of @var{processes}. + +@item long int ru_msgsnd +Number of IPC messages sent. + +@item long int ru_msgrcv +Number of IPC messages received. + +@item long int ru_nsignals +Number of signals received. + +@item long int ru_nvcsw +The number of times @var{processes} voluntarily invoked a context switch +(usually to wait for some service). + +@item long int ru_nivcsw +The number of times an involuntary context switch took place (because +a time slice expired, or another process of higher priority was +scheduled). +@end table +@end deftp + +@code{vtimes} is a historical function that does some of what +@code{getrusage} does. @code{getrusage} is a better choice. + +@code{vtimes} and its @code{vtimes} data structure are declared in +@file{sys/vtimes.h}. +@pindex sys/vtimes.h +@comment vtimes.h + +@deftypefun int vtimes (struct vtimes @var{current}, struct vtimes @var{child}) + +@code{vtimes} reports resource usage totals for a process. + +If @var{current} is non-null, @code{vtimes} stores resource usage totals for +the invoking process alone in the structure to which it points. If +@var{child} is non-null, @code{vtimes} stores resource usage totals for all +past children (which have terminated) of the invoking process in the structure +to which it points. + +@deftp {Data Type} {struct vtimes} +This data type contains information about the resource usage of a process. +Each member corresponds to a member of the @code{struct rusage} data type +described above. + +@table @code +@item vm_utime +User CPU time. Analogous to @code{ru_utime} in @code{struct rusage} +@item vm_stime +System CPU time. Analogous to @code{ru_stime} in @code{struct rusage} +@item vm_idsrss +Data and stack memory. The sum of the values that would be reported as +@code{ru_idrss} and @code{ru_isrss} in @code{struct rusage} +@item vm_ixrss +Shared memory. Analogous to @code{ru_ixrss} in @code{struct rusage} +@item vm_maxrss +Maximent resident set size. Analogous to @code{ru_maxrss} in +@code{struct rusage} +@item vm_majflt +Major page faults. Analogous to @code{ru_majflt} in @code{struct rusage} +@item vm_minflt +Minor page faults. Analogous to @code{ru_minflt} in @code{struct rusage} +@item vm_nswap +Swap count. Analogous to @code{ru_nswap} in @code{struct rusage} +@item vm_inblk +Disk reads. Analogous to @code{ru_inblk} in @code{struct rusage} +@item vm_oublk +Disk writes. Analogous to @code{ru_oublk} in @code{struct rusage} +@end table +@end deftp + + +The return value is zero if the function succeeds; @code{-1} otherwise. + + + +@end deftypefun +An additional historical function for examining resource usage, +@code{vtimes}, is supported but not documented here. It is declared in +@file{sys/vtimes.h}. + +@node Limits on Resources +@section Limiting Resource Usage +@cindex resource limits +@cindex limits on resource usage +@cindex usage limits + +You can specify limits for the resource usage of a process. When the +process tries to exceed a limit, it may get a signal, or the system call +by which it tried to do so may fail, depending on the resource. Each +process initially inherits its limit values from its parent, but it can +subsequently change them. + +There are two per-process limits associated with a resource: +@cindex limit + +@table @dfn +@item current limit +The current limit is the value the system will not allow usage to +exceed. It is also called the ``soft limit'' because the process being +limited can generally raise the current limit at will. +@cindex current limit +@cindex soft limit + +@item maximum limit +The maximum limit is the maximum value to which a process is allowed to +set its current limit. It is also called the ``hard limit'' because +there is no way for a process to get around it. A process may lower +its own maximum limit, but only the superuser may increase a maximum +limit. +@cindex maximum limit +@cindex hard limit +@end table + +@pindex sys/resource.h +The symbols for use with @code{getrlimit}, @code{setrlimit}, +@code{getrlimit64}, and @code{seterlimit64} are defined in +@file{sys/resource.h}. + +@comment sys/resource.h +@comment BSD +@deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp}) +Read the current and maximum limits for the resource @var{resource} +and store them in @code{*@var{rlp}}. + +The return value is @code{0} on success and @code{-1} on failure. The +only possible @code{errno} error condition is @code{EFAULT}. + +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a +32-bit system this function is in fact @code{getrlimit64}. Thus, the +LFS interface transparently replaces the old interface. +@end deftypefun + +@comment sys/resource.h +@comment Unix98 +@deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp}) +This function is similar to @code{getrlimit} but its second parameter is +a pointer to a variable of type @code{struct rlimit64}, which allows it +to read values which wouldn't fit in the member of a @code{struct +rlimit}. + +If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a +32-bit machine, this function is available under the name +@code{getrlimit} and so transparently replaces the old interface. +@end deftypefun + +@comment sys/resource.h +@comment BSD +@deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp}) +Store the current and maximum limits for the resource @var{resource} +in @code{*@var{rlp}}. + +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error condition is possible: + +@table @code +@item EPERM +@itemize @bullet +@item +The process tried to raise a current limit beyond the maximum limit. + +@item +The process tried to raise a maximum limit, but is not superuser. +@end itemize +@end table + +When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a +32-bit system this function is in fact @code{setrlimit64}. Thus, the +LFS interface transparently replaces the old interface. +@end deftypefun + +@comment sys/resource.h +@comment Unix98 +@deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp}) +This function is similar to @code{setrlimit} but its second parameter is +a pointer to a variable of type @code{struct rlimit64} which allows it +to set values which wouldn't fit in the member of a @code{struct +rlimit}. + +If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a +32-bit machine this function is available under the name +@code{setrlimit} and so transparently replaces the old interface. +@end deftypefun + +@comment sys/resource.h +@comment BSD +@deftp {Data Type} {struct rlimit} +This structure is used with @code{getrlimit} to receive limit values, +and with @code{setrlimit} to specify limit values for a particular process +and resource. It has two fields: + +@table @code +@item rlim_t rlim_cur +The current limit + +@item rlim_t rlim_max +The maximum limit. +@end table + +For @code{getrlimit}, the structure is an output; it receives the current +values. For @code{setrlimit}, it specifies the new values. +@end deftp + +For the LFS functions a similar type is defined in @file{sys/resource.h}. + +@comment sys/resource.h +@comment Unix98 +@deftp {Data Type} {struct rlimit64} +This structure is analogous to the @code{rlimit} structure above, but +its components have wider ranges. It has two fields: + +@table @code +@item rlim64_t rlim_cur +This is analogous to @code{rlimit.rlim_cur}, but with a different type. + +@item rlim64_t rlim_max +This is analogous to @code{rlimit.rlim_max}, but with a different type. +@end table + +@end deftp + +Here is a list of resources for which you can specify a limit. Memory +and file sizes are measured in bytes. + +@table @code +@comment sys/resource.h +@comment BSD +@item RLIMIT_CPU +@vindex RLIMIT_CPU +The maximum amount of CPU time the process can use. If it runs for +longer than this, it gets a signal: @code{SIGXCPU}. The value is +measured in seconds. @xref{Operation Error Signals}. + +@comment sys/resource.h +@comment BSD +@item RLIMIT_FSIZE +@vindex RLIMIT_FSIZE +The maximum size of file the process can create. Trying to write a +larger file causes a signal: @code{SIGXFSZ}. @xref{Operation Error +Signals}. + +@comment sys/resource.h +@comment BSD +@item RLIMIT_DATA +@vindex RLIMIT_DATA +The maximum size of data memory for the process. If the process tries +to allocate data memory beyond this amount, the allocation function +fails. + +@comment sys/resource.h +@comment BSD +@item RLIMIT_STACK +@vindex RLIMIT_STACK +The maximum stack size for the process. If the process tries to extend +its stack past this size, it gets a @code{SIGSEGV} signal. +@xref{Program Error Signals}. + +@comment sys/resource.h +@comment BSD +@item RLIMIT_CORE +@vindex RLIMIT_CORE +The maximum size core file that this process can create. If the process +terminates and would dump a core file larger than this, then no core +file is created. So setting this limit to zero prevents core files from +ever being created. + +@comment sys/resource.h +@comment BSD +@item RLIMIT_RSS +@vindex RLIMIT_RSS +The maximum amount of physical memory that this process should get. +This parameter is a guide for the system's scheduler and memory +allocator; the system may give the process more memory when there is a +surplus. + +@comment sys/resource.h +@comment BSD +@item RLIMIT_MEMLOCK +The maximum amount of memory that can be locked into physical memory (so +it will never be paged out). + +@comment sys/resource.h +@comment BSD +@item RLIMIT_NPROC +The maximum number of processes that can be created with the same user ID. +If you have reached the limit for your user ID, @code{fork} will fail +with @code{EAGAIN}. @xref{Creating a Process}. + +@comment sys/resource.h +@comment BSD +@item RLIMIT_NOFILE +@vindex RLIMIT_NOFILE +@itemx RLIMIT_OFILE +@vindex RLIMIT_OFILE +The maximum number of files that the process can open. If it tries to +open more files than this, its open attempt fails with @code{errno} +@code{EMFILE}. @xref{Error Codes}. Not all systems support this limit; +GNU does, and 4.4 BSD does. + +@comment sys/resource.h +@comment Unix98 +@item RLIMIT_AS +@vindex RLIMIT_AS +The maximum size of total memory that this process should get. If the +process tries to allocate more memory beyond this amount with, for +example, @code{brk}, @code{malloc}, @code{mmap} or @code{sbrk}, the +allocation function fails. + +@comment sys/resource.h +@comment BSD +@item RLIM_NLIMITS +@vindex RLIM_NLIMITS +The number of different resource limits. Any valid @var{resource} +operand must be less than @code{RLIM_NLIMITS}. +@end table + +@comment sys/resource.h +@comment BSD +@deftypevr Constant int RLIM_INFINITY +This constant stands for a value of ``infinity'' when supplied as +the limit value in @code{setrlimit}. +@end deftypevr + + +The following are historical functions to do some of what the functions +above do. The functions above are better choices. + +@code{ulimit} and the command symbols are declared in @file{ulimit.h}. +@pindex ulimit.h +@comment ulimit.h + +@deftypefun int ulimit (int @var{cmd}, ...) + +@code{ulimit} gets the current limit or sets the current and maximum +limit for a particular resource for the calling process according to the +command @var{cmd}.a + +If you are getting a limit, the command argument is the only argument. +If you are setting a limit, there is a second argument: +@code{long int} @var{limit} which is the value to which you are setting +the limit. + +The @var{cmd} values and the operations they specify are: +@table @code + +@item GETFSIZE +Get the current limit on the size of a file, in units of 512 bytes. + +@item SETFSIZE +Set the current and maximum limit on the size of a file to @var{limit} * +512 bytes. + +@end table + +There are also some other @var{cmd} values that may do things on some +systems, but they are not supported. + +Only the superuser may increase a maximum limit. + +When you successfully get a limit, the return value of @code{ulimit} is +that limit, which is never negative. When you successfully set a limit, +the return value is zero. When the function fails, the return value is +@code{-1} and @code{errno} is set according to the reason: + +@table @code +@item EPERM +A process tried to increase a maximum limit, but is not superuser. +@end table + + +@end deftypefun + +@code{vlimit} and its resource symbols are declared in @file{sys/vlimit.h}. +@comment sys/vlimit.h +@pindex sys/vlimit.h +@comment BSD + +@deftypefun int vlimit (int @var{resource}, int @var{limit}) + +@code{vlimit} sets the current limit for a resource for a process. + +@var{resource} identifies the resource: + +@table @code +@item LIM_CPU +Maximum CPU time. Same as @code{RLIMIT_CPU} for @code{setrlimit}. +@item LIM_FSIZE +Maximum file size. Same as @code{RLIMIT_FSIZE} for @code{setrlimit}. +@item LIM_DATA +Maximum data memory. Same as @code{RLIMIT_DATA} for @code{setrlimit}. +@item LIM_STACK +Maximum stack size. Same as @code{RLIMIT_STACK} for @code{setrlimit}. +@item LIM_CORE +Maximum core file size. Same as @code{RLIMIT_COR} for @code{setrlimit}. +@item LIM_MAXRSS +Maximum physical memory. Same as @code{RLIMIT_RSS} for @code{setrlimit}. +@end table + +The return value is zero for success, and @code{-1} with @code{errno} set +accordingly for failure: + +@table @code +@item EPERM +The process tried to set its current limit beyond its maximum limit. +@end table + +@end deftypefun + +@node Priority +@section Process Priority +@cindex process priority +@cindex priority of a process + +@pindex sys/resource.h +When several processes try to run, their respective priorities determine +what share of the CPU each process gets. This section describes how you +can read and set the priority of a process. All these functions and +macros are declared in @file{sys/resource.h}. + +The range of valid priority values depends on the operating system, but +typically it runs from @code{-20} to @code{20}. A lower priority value +means the process runs more often. These constants describe the range of +priority values: + +@table @code +@comment sys/resource.h +@comment BSD +@item PRIO_MIN +@vindex PRIO_MIN +The smallest valid priority value. + +@comment sys/resource.h +@comment BSD +@item PRIO_MAX +@vindex PRIO_MAX +The largest valid priority value. +@end table + +@comment sys/resource.h +@comment BSD +@deftypefun int getpriority (int @var{class}, int @var{id}) +Read the priority of a class of processes; @var{class} and @var{id} +specify which ones (see below). If the processes specified do not all +have the same priority, this returns the smallest value that any of them +has. + +The return value is the priority value on success, and @code{-1} on +failure. The following @code{errno} error condition are possible for +this function: + +@table @code +@item ESRCH +The combination of @var{class} and @var{id} does not match any existing +process. + +@item EINVAL +The value of @var{class} is not valid. +@end table + +If the return value is @code{-1}, it could indicate failure, or it +could be the priority value. The only way to make certain is to set +@code{errno = 0} before calling @code{getpriority}, then use @code{errno +!= 0} afterward as the criterion for failure. +@end deftypefun + +@comment sys/resource.h +@comment BSD +@deftypefun int setpriority (int @var{class}, int @var{id}, int @var{priority}) +Set the priority of a class of processes to @var{priority}; @var{class} +and @var{id} specify which ones (see below). + +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error condition are defined for this function: + +@table @code +@item ESRCH +The combination of @var{class} and @var{id} does not match any existing +process. + +@item EINVAL +The value of @var{class} is not valid. + +@item EPERM +You tried to set the priority of some other user's process, and you +don't have privileges for that. + +@item EACCES +You tried to lower the priority of a process, and you don't have +privileges for that. +@end table +@end deftypefun + +The arguments @var{class} and @var{id} together specify a set of +processes in which you are interested. These are the possible values of +@var{class}: + +@table @code +@comment sys/resource.h +@comment BSD +@item PRIO_PROCESS +@vindex PRIO_PROCESS +Read or set the priority of one process. The argument @var{id} is a +process ID. + +@comment sys/resource.h +@comment BSD +@item PRIO_PGRP +@vindex PRIO_PGRP +Read or set the priority of one process group. The argument @var{id} is +a process group ID. + +@comment sys/resource.h +@comment BSD +@item PRIO_USER +@vindex PRIO_USER +Read or set the priority of one user's processes. The argument @var{id} +is a user ID. +@end table + +If the argument @var{id} is 0, it stands for the current process, +current process group, or the current user, according to @var{class}. + +@c ??? I don't know where we should say this comes from. +@comment Unix +@comment dunno.h +@deftypefun int nice (int @var{increment}) +Increment the priority of the current process by @var{increment}. +The return value is the same as for @code{setpriority}. + +Here is an equivalent definition of @code{nice}: + +@smallexample +int +nice (int increment) +@{ + int old = getpriority (PRIO_PROCESS, 0); + return setpriority (PRIO_PROCESS, 0, old + increment); +@} +@end smallexample +@end deftypefun -- cgit v1.2.3