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, 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