diff options
Diffstat (limited to 'manual/time.texi')
| -rw-r--r-- | manual/time.texi | 487 |
1 files changed, 5 insertions, 482 deletions
diff --git a/manual/time.texi b/manual/time.texi index 349c890..d292d1c 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -1,4 +1,4 @@ -@node Date and Time, Non-Local Exits, Arithmetic, Top +@node Date and Time, Resource Usage And Limitation, Arithmetic, Top @c %MENU% Functions for getting the date and time and formatting them nicely @chapter Date and Time @@ -29,11 +29,12 @@ an Alarm}. time. * Setting an Alarm:: Sending a signal after a specified time. * Sleeping:: Waiting for a period of time. -* Resource Usage:: Measuring various resources used. -* Limits on Resources:: Specifying limits on resource usage. -* Priority:: Reading or setting process run priority. @end menu +For functions to examine and control a process' CPU time, see +@xref{Resource Usage And Limitation}. + + @node Processor Time @section Processor Time @@ -2263,481 +2264,3 @@ be protected using cancellation handlers. The @code{nanosleep} function is declared in @file{time.h}. @end deftypefun -@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 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 - -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 given limit, it may get a signal, or the system call -by which it tried to do so may fail, depending on the limit in question. Each -process initially inherits its limit values from its parent, but it can -subsequently change them. - -@pindex sys/resource.h -The symbols in this section 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 value and the maximum value of 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}, -allowing 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 value and the maximum value of 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 -You tried to change the maximum permissible limit value, -but you don't have privileges to do so. -@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}, allowing 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. It has two fields: - -@table @code -@item rlim_t rlim_cur -The current value of the limit in question. -This is also called the ``soft limit''. -@cindex soft limit - -@item rlim_t rlim_max -The maximum permissible value of the limit in question. You cannot set -the current value of the limit to a larger number than this maximum. -Only the super-user can change the maximum permissible value. -This is also called the ``hard limit''. -@cindex hard limit -@end table - -For @code{getrlimit}, the structure is an output; it receives the current -value. With @code{setrlimit} it specifies the new value. -@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 used with @code{getrlimit64} to receive limit values, -and with @code{setrlimit64} to specify limit values. It has two fields: - -@table @code -@item rlim64_t rlim_cur -The current value of the limit in question. -This is also called the ``soft limit''. - -@item rlim64_t rlim_max -The maximum permissible value of the limit in question. You cannot set -the current value of the limit to a larger number than this maximum. -Only the super-user can change the maximum permissible value. -This is also called the ``hard limit''. -@end table - -For @code{getrlimit64}, the structure is an output; it receives the current -value. With @code{setrlimit64} it specifies the new value. -@end deftp - -Here is a list of resources that you can specify a limit for. -Memory 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, it gets the error code @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 - -@c ??? Someone want to finish these? -Two historical functions for setting resource limits, @code{ulimit} and -@code{vlimit}, are not documented here. The latter is declared in -@file{sys/vlimit.h} and comes from BSD. - -@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 you are interested in. 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 |