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 <bryanh@giraffe-data.com>.

1 files changed, 644 insertions, 0 deletions

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