initial import

1 files changed, 1574 insertions, 0 deletions

diff --git a/manual/time.texi b/manual/time.texi
new file mode 100644
index 0000000000..767c318a42
--- /dev/null
+++ b/manual/time.texi
@@ -0,0 +1,1574 @@
+@node Date and Time, Non-Local Exits, Arithmetic, Top
+@chapter Date and Time
+
+This chapter describes functions for manipulating dates and times,
+including functions for determining what the current time is and
+conversion between different time representations.
+
+The time functions fall into three main categories:
+
+@itemize @bullet
+@item 
+Functions for measuring elapsed CPU time are discussed in @ref{Processor
+Time}.
+
+@item
+Functions for measuring absolute clock or calendar time are discussed in
+@ref{Calendar Time}.
+
+@item
+Functions for setting alarms and timers are discussed in @ref{Setting
+an Alarm}.
+@end itemize
+
+@menu
+* Processor Time::              Measures processor time used by a program.
+* Calendar Time::               Manipulation of ``real'' dates and times.
+* 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
+
+@node Processor Time
+@section Processor Time
+
+If you're trying to optimize your program or measure its efficiency, it's
+very useful to be able to know how much @dfn{processor time} or @dfn{CPU
+time} it has used at any given point.  Processor time is different from
+actual wall clock time because it doesn't include any time spent waiting
+for I/O or when some other process is running.  Processor time is
+represented by the data type @code{clock_t}, and is given as a number of
+@dfn{clock ticks} relative to an arbitrary base time marking the beginning
+of a single program invocation.
+@cindex CPU time
+@cindex processor time
+@cindex clock ticks
+@cindex ticks, clock
+@cindex time, elapsed CPU
+
+@menu
+* Basic CPU Time::              The @code{clock} function.
+* Detailed CPU Time::           The @code{times} function.
+@end menu
+
+@node Basic CPU Time
+@subsection Basic CPU Time Inquiry
+
+To get the elapsed CPU time used by a process, you can use the
+@code{clock} function.  This facility is declared in the header file
+@file{time.h}.
+@pindex time.h
+
+In typical usage, you call the @code{clock} function at the beginning and
+end of the interval you want to time, subtract the values, and then divide
+by @code{CLOCKS_PER_SEC} (the number of clock ticks per second), like this:
+
+@smallexample
+@group
+#include <time.h>
+
+clock_t start, end;
+double elapsed;
+
+start = clock();
+@dots{} /* @r{Do the work.} */
+end = clock();
+elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
+@end group
+@end smallexample
+
+Different computers and operating systems vary wildly in how they keep
+track of processor time.  It's common for the internal processor clock
+to have a resolution somewhere between hundredths and millionths of a
+second.
+
+In the GNU system, @code{clock_t} is equivalent to @code{long int} and
+@code{CLOCKS_PER_SEC} is an integer value.  But in other systems, both
+@code{clock_t} and the type of the macro @code{CLOCKS_PER_SEC} can be
+either integer or floating-point types.  Casting processor time values
+to @code{double}, as in the example above, makes sure that operations
+such as arithmetic and printing work properly and consistently no matter
+what the underlying representation is.
+
+@comment time.h
+@comment ANSI
+@deftypevr Macro int CLOCKS_PER_SEC
+The value of this macro is the number of clock ticks per second measured
+by the @code{clock} function.
+@end deftypevr
+
+@comment time.h
+@comment POSIX.1
+@deftypevr Macro int CLK_TCK
+This is an obsolete name for @code{CLOCKS_PER_SEC}.  
+@end deftypevr
+
+@comment time.h
+@comment ANSI
+@deftp {Data Type} clock_t
+This is the type of the value returned by the @code{clock} function.
+Values of type @code{clock_t} are in units of clock ticks.
+@end deftp
+
+@comment time.h
+@comment ANSI
+@deftypefun clock_t clock (void)
+This function returns the elapsed processor time.  The base time is
+arbitrary but doesn't change within a single process.  If the processor
+time is not available or cannot be represented, @code{clock} returns the
+value @code{(clock_t)(-1)}.
+@end deftypefun
+
+
+@node Detailed CPU Time
+@subsection Detailed Elapsed CPU Time Inquiry
+
+The @code{times} function returns more detailed information about
+elapsed processor time in a @w{@code{struct tms}} object.  You should
+include the header file @file{sys/times.h} to use this facility.
+@pindex sys/times.h
+
+@comment sys/times.h
+@comment POSIX.1
+@deftp {Data Type} {struct tms}
+The @code{tms} structure is used to return information about process
+times.  It contains at least the following members:
+
+@table @code
+@item clock_t tms_utime
+This is the CPU time used in executing the instructions of the calling
+process.
+
+@item clock_t tms_stime
+This is the CPU time used by the system on behalf of the calling process.
+
+@item clock_t tms_cutime
+This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
+values of all terminated child processes of the calling process, whose
+status has been reported to the parent process by @code{wait} or
+@code{waitpid}; see @ref{Process Completion}.  In other words, it
+represents the total CPU time used in executing the instructions of all
+the terminated child processes of the calling process, excluding child
+processes which have not yet been reported by @code{wait} or
+@code{waitpid}.
+
+@item clock_t tms_cstime
+This is similar to @code{tms_cutime}, but represents the total CPU time
+used by the system on behalf of all the terminated child processes of the
+calling process.
+@end table
+
+All of the times are given in clock ticks.  These are absolute values; in a
+newly created process, they are all zero.  @xref{Creating a Process}.
+@end deftp
+
+@comment sys/times.h
+@comment POSIX.1
+@deftypefun clock_t times (struct tms *@var{buffer})
+The @code{times} function stores the processor time information for
+the calling process in @var{buffer}.
+
+The return value is the same as the value of @code{clock()}: the elapsed
+real time relative to an arbitrary base.  The base is a constant within a
+particular process, and typically represents the time since system
+start-up.  A value of @code{(clock_t)(-1)} is returned to indicate failure.
+@end deftypefun
+
+@strong{Portability Note:} The @code{clock} function described in
+@ref{Basic CPU Time}, is specified by the ANSI C standard.  The
+@code{times} function is a feature of POSIX.1.  In the GNU system, the
+value returned by the @code{clock} function is equivalent to the sum of
+the @code{tms_utime} and @code{tms_stime} fields returned by
+@code{times}.
+
+@node Calendar Time
+@section Calendar Time
+
+This section describes facilities for keeping track of dates and times
+according to the Gregorian calendar.
+@cindex Gregorian calendar
+@cindex time, calendar
+@cindex date and time
+
+There are three representations for date and time information:
+
+@itemize @bullet
+@item 
+@dfn{Calendar time} (the @code{time_t} data type) is a compact 
+representation, typically giving the number of seconds elapsed since
+some implementation-specific base time.
+@cindex calendar time
+
+@item
+There is also a @dfn{high-resolution time} representation (the @code{struct
+timeval} data type) that includes fractions of a second.  Use this time
+representation instead of ordinary calendar time when you need greater
+precision.
+@cindex high-resolution time
+
+@item
+@dfn{Local time} or @dfn{broken-down time} (the @code{struct
+tm} data type) represents the date and time as a set of components
+specifying the year, month, and so on, for a specific time zone.
+This time representation is usually used in conjunction with formatting
+date and time values.
+@cindex local time
+@cindex broken-down time
+@end itemize
+
+@menu
+* Simple Calendar Time::        Facilities for manipulating calendar time.
+* High-Resolution Calendar::    A time representation with greater precision.
+* Broken-down Time::            Facilities for manipulating local time.
+* Formatting Date and Time::    Converting times to strings.
+* TZ Variable::                 How users specify the time zone.
+* Time Zone Functions::         Functions to examine or specify the time zone. 
+* Time Functions Example::      An example program showing use of some of
+				 the time functions.
+@end menu
+
+@node Simple Calendar Time
+@subsection Simple Calendar Time
+
+This section describes the @code{time_t} data type for representing
+calendar time, and the functions which operate on calendar time objects.
+These facilities are declared in the header file @file{time.h}.
+@pindex time.h
+
+@cindex epoch
+@comment time.h
+@comment ANSI
+@deftp {Data Type} time_t
+This is the data type used to represent calendar time.  In the GNU C
+library and other POSIX-compliant implementations, @code{time_t} is
+equivalent to @code{long int}.  When interpreted as an absolute time
+value, it represents the number of seconds elapsed since 00:00:00 on
+January 1, 1970, Coordinated Universal Time.  (This date is sometimes
+referred to as the @dfn{epoch}.)
+
+In other systems, @code{time_t} might be either an integer or
+floating-point type.
+@end deftp
+
+@comment time.h
+@comment ANSI
+@deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
+The @code{difftime} function returns the number of seconds elapsed
+between time @var{time1} and time @var{time0}, as a value of type
+@code{double}.  
+
+In the GNU system, you can simply subtract @code{time_t} values.  But on
+other systems, the @code{time_t} data type might use some other encoding
+where subtraction doesn't work directly.
+@end deftypefun
+
+@comment time.h
+@comment ANSI
+@deftypefun time_t time (time_t *@var{result})
+The @code{time} function returns the current time as a value of type
+@code{time_t}.  If the argument @var{result} is not a null pointer, the
+time value is also stored in @code{*@var{result}}.  If the calendar 
+time is not available, the value @w{@code{(time_t)(-1)}} is returned.
+@end deftypefun
+
+
+@node High-Resolution Calendar
+@subsection High-Resolution Calendar
+
+The @code{time_t} data type used to represent calendar times has a 
+resolution of only one second.  Some applications need more precision.
+
+So, the GNU C library also contains functions which are capable of
+representing calendar times to a higher resolution than one second.  The
+functions and the associated data types described in this section are
+declared in @file{sys/time.h}.
+@pindex sys/time.h
+
+@comment sys/time.h
+@comment BSD
+@deftp {Data Type} {struct timeval}
+The @code{struct timeval} structure represents a calendar time.  It
+has the following members:
+
+@table @code
+@item long int tv_sec
+This represents the number of seconds since the epoch.  It is equivalent
+to a normal @code{time_t} value.
+
+@item long int tv_usec
+This is the fractional second value, represented as the number of
+microseconds.
+
+Some times struct timeval values are used for time intervals.  Then the
+@code{tv_sec} member is the number of seconds in the interval, and
+@code{tv_usec} is the number of additional microseconds.
+@end table
+@end deftp
+
+@comment sys/time.h
+@comment BSD
+@deftp {Data Type} {struct timezone}
+The @code{struct timezone} structure is used to hold minimal information
+about the local time zone.  It has the following members:
+
+@table @code
+@item int tz_minuteswest
+This is the number of minutes west of GMT.
+
+@item int tz_dsttime
+If nonzero, daylight savings time applies during some part of the year.
+@end table
+
+The @code{struct timezone} type is obsolete and should never be used.
+Instead, use the facilities described in @ref{Time Zone Functions}.
+@end deftp
+
+It is often necessary to subtract two values of type @w{@code{struct
+timeval}}.  Here is the best way to do this.  It works even on some
+peculiar operating systems where the @code{tv_sec} member has an
+unsigned type.
+
+@smallexample
+/* @r{Subtract the `struct timeval' values X and Y,}
+   @r{storing the result in RESULT.}
+   @r{Return 1 if the difference is negative, otherwise 0.}  */
+
+int
+timeval_subtract (result, x, y)
+     struct timeval *result, *x, *y;
+@{
+  /* @r{Perform the carry for the later subtraction by updating @var{y}.} */
+  if (x->tv_usec < y->tv_usec) @{
+    int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
+    y->tv_usec -= 1000000 * nsec;
+    y->tv_sec += nsec;
+  @}
+  if (x->tv_usec - y->tv_usec > 1000000) @{
+    int nsec = (y->tv_usec - x->tv_usec) / 1000000;
+    y->tv_usec += 1000000 * nsec;
+    y->tv_sec -= nsec;
+  @}
+
+  /* @r{Compute the time remaining to wait.}
+     @r{@code{tv_usec} is certainly positive.} */
+  result->tv_sec = x->tv_sec - y->tv_sec;
+  result->tv_usec = x->tv_usec - y->tv_usec;
+
+  /* @r{Return 1 if result is negative.} */
+  return x->tv_sec < y->tv_sec;
+@}
+@end smallexample
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
+The @code{gettimeofday} function returns the current date and time in the
+@code{struct timeval} structure indicated by @var{tp}.  Information about the
+time zone is returned in the structure pointed at @var{tzp}.  If the @var{tzp}
+argument is a null pointer, time zone information is ignored.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is defined for this function:
+
+@table @code
+@item ENOSYS
+The operating system does not support getting time zone information, and
+@var{tzp} is not a null pointer.  The GNU operating system does not
+support using @w{@code{struct timezone}} to represent time zone
+information; that is an obsolete feature of 4.3 BSD.
+Instead, use the facilities described in @ref{Time Zone Functions}.
+@end table
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
+The @code{settimeofday} function sets the current date and time
+according to the arguments.  As for @code{gettimeofday}, time zone
+information is ignored if @var{tzp} is a null pointer.
+
+You must be a privileged user in order to use @code{settimeofday}.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EPERM
+This process cannot set the time because it is not privileged.
+
+@item ENOSYS
+The operating system does not support setting time zone information, and
+@var{tzp} is not a null pointer.
+@end table
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
+This function speeds up or slows down the system clock in order to make
+gradual adjustments in the current time.  This ensures that the time
+reported by the system clock is always monotonically increasing, which
+might not happen if you simply set the current time.
+
+The @var{delta} argument specifies a relative adjustment to be made to
+the current time.  If negative, the system clock is slowed down for a
+while until it has lost this much time.  If positive, the system clock
+is speeded up for a while.
+
+If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
+function returns information about any previous time adjustment that
+has not yet completed.
+
+This function is typically used to synchronize the clocks of computers
+in a local network.  You must be a privileged user to use it.
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EPERM
+You do not have privilege to set the time.
+@end table
+@end deftypefun
+
+@strong{Portability Note:}  The @code{gettimeofday}, @code{settimeofday},
+and @code{adjtime} functions are derived from BSD.  
+
+
+@node Broken-down Time
+@subsection Broken-down Time
+@cindex broken-down time
+@cindex calendar time and broken-down time
+
+Calendar time is represented as a number of seconds.  This is convenient
+for calculation, but has no resemblance to the way people normally
+represent dates and times.  By contrast, @dfn{broken-down time} is a binary
+representation separated into year, month, day, and so on.  Broken down
+time values are not useful for calculations, but they are useful for
+printing human readable time.
+
+A broken-down time value is always relative to a choice of local time
+zone, and it also indicates which time zone was used.
+
+The symbols in this section are declared in the header file @file{time.h}.
+
+@comment time.h
+@comment ANSI
+@deftp {Data Type} {struct tm}
+This is the data type used to represent a broken-down time.  The structure
+contains at least the following members, which can appear in any order:
+
+@table @code
+@item int tm_sec
+This is the number of seconds after the minute, normally in the range
+@code{0} to @code{59}.  (The actual upper limit is @code{61}, to allow
+for ``leap seconds''.)
+@cindex leap second
+
+@item int tm_min
+This is the number of minutes after the hour, in the range @code{0} to
+@code{59}.
+
+@item int tm_hour
+This is the number of hours past midnight, in the range @code{0} to
+@code{23}.
+
+@item int tm_mday
+This is the day of the month, in the range @code{1} to @code{31}.
+
+@item int tm_mon
+This is the number of months since January, in the range @code{0} to
+@code{11}.
+
+@item int tm_year
+This is the number of years since @code{1900}.
+
+@item int tm_wday
+This is the number of days since Sunday, in the range @code{0} to @code{6}.
+
+@item int tm_yday
+This is the number of days since January 1, in the range @code{0} to
+@code{365}.
+
+@item int tm_isdst
+@cindex Daylight Saving Time
+@cindex summer time
+This is a flag that indicates whether Daylight Saving Time is (or was, or
+will be) in effect at the time described.  The value is positive if
+Daylight Saving Time is in effect, zero if it is not, and negative if the
+information is not available.
+
+@item long int tm_gmtoff
+This field describes the time zone that was used to compute this
+broken-down time value; it is the amount you must add to the local time
+in that zone to get GMT, in units of seconds.  The value is like that of
+the variable @code{timezone} (@pxref{Time Zone Functions}).  You can
+also think of this as the ``number of seconds west'' of GMT.  The
+@code{tm_gmtoff} field is a GNU library extension.
+
+@item const char *tm_zone
+This field is the three-letter name for the time zone that was used to
+compute this broken-down time value.  It is a GNU library extension.
+@end table
+@end deftp
+
+@comment time.h
+@comment ANSI
+@deftypefun {struct tm *} localtime (const time_t *@var{time})
+The @code{localtime} function converts the calendar time pointed to by
+@var{time} to broken-down time representation, expressed relative to the
+user's specified time zone.
+
+The return value is a pointer to a static broken-down time structure, which
+might be overwritten by subsequent calls to any of the date and time
+functions.  (But no other library function overwrites the contents of this
+object.)
+
+Calling @code{localtime} has one other effect: it sets the variable
+@code{tzname} with information about the current time zone.  @xref{Time
+Zone Functions}.
+@end deftypefun
+
+@comment time.h
+@comment ANSI
+@deftypefun {struct tm *} gmtime (const time_t *@var{time})
+This function is similar to @code{localtime}, except that the broken-down
+time is expressed as Coordinated Universal Time (UTC)---that is, as
+Greenwich Mean Time (GMT) rather than relative to the local time zone.
+
+Recall that calendar times are @emph{always} expressed in coordinated
+universal time.
+@end deftypefun
+
+@comment time.h
+@comment ANSI
+@deftypefun time_t mktime (struct tm *@var{brokentime})
+The @code{mktime} function is used to convert a broken-down time structure
+to a calendar time representation.  It also ``normalizes'' the contents of
+the broken-down time structure, by filling in the day of week and day of
+year based on the other date and time components.
+
+The @code{mktime} function ignores the specified contents of the
+@code{tm_wday} and @code{tm_yday} members of the broken-down time
+structure.  It uses the values of the other components to compute the
+calendar time; it's permissible for these components to have
+unnormalized values outside of their normal ranges.  The last thing that
+@code{mktime} does is adjust the components of the @var{brokentime}
+structure (including the @code{tm_wday} and @code{tm_yday}).
+
+If the specified broken-down time cannot be represented as a calendar time,
+@code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
+the contents of @var{brokentime}.
+
+Calling @code{mktime} also sets the variable @code{tzname} with
+information about the current time zone.  @xref{Time Zone Functions}.
+@end deftypefun
+
+@node Formatting Date and Time
+@subsection Formatting Date and Time
+
+The functions described in this section format time values as strings.
+These functions are declared in the header file @file{time.h}.
+@pindex time.h
+
+@comment time.h
+@comment ANSI
+@deftypefun {char *} asctime (const struct tm *@var{brokentime})
+The @code{asctime} function converts the broken-down time value that
+@var{brokentime} points to into a string in a standard format:
+
+@smallexample
+"Tue May 21 13:46:22 1991\n"
+@end smallexample
+
+The abbreviations for the days of week are: @samp{Sun}, @samp{Mon},
+@samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}.
+
+The abbreviations for the months are: @samp{Jan}, @samp{Feb},
+@samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug},
+@samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}.
+
+The return value points to a statically allocated string, which might be
+overwritten by subsequent calls to any of the date and time functions.
+(But no other library function overwrites the contents of this
+string.)
+@end deftypefun
+
+@comment time.h
+@comment ANSI
+@deftypefun {char *} ctime (const time_t *@var{time})
+The @code{ctime} function is similar to @code{asctime}, except that the
+time value is specified as a @code{time_t} calendar time value rather
+than in broken-down local time format.  It is equivalent to
+
+@smallexample
+asctime (localtime (@var{time}))
+@end smallexample
+
+@code{ctime} sets the variable @code{tzname}, because @code{localtime}
+does so.  @xref{Time Zone Functions}.
+@end deftypefun
+
+@comment time.h
+@comment ANSI
+@deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
+This function is similar to the @code{sprintf} function (@pxref{Formatted
+Input}), but the conversion specifications that can appear in the format
+template @var{template} are specialized for printing components of the date
+and time @var{brokentime} according to the locale currently specified for
+time conversion (@pxref{Locales}).
+
+Ordinary characters appearing in the @var{template} are copied to the
+output string @var{s}; this can include multibyte character sequences.
+Conversion specifiers are introduced by a @samp{%} character, and are
+replaced in the output string as follows:
+
+@table @code
+@item %a
+The abbreviated weekday name according to the current locale.
+
+@item %A
+The full weekday name according to the current locale.
+
+@item %b
+The abbreviated month name according to the current locale.
+
+@item %B
+The full month name according to the current locale.
+
+@item %c
+The preferred date and time representation for the current locale.
+
+@item %d
+The day of the month as a decimal number (range @code{01} to @code{31}).
+
+@item %H
+The hour as a decimal number, using a 24-hour clock (range @code{00} to
+@code{23}).
+
+@item %I
+The hour as a decimal number, using a 12-hour clock (range @code{01} to
+@code{12}).
+
+@item %j
+The day of the year as a decimal number (range @code{001} to @code{366}).
+
+@item %m
+The month as a decimal number (range @code{01} to @code{12}).
+
+@item %M
+The minute as a decimal number.
+
+@item %p
+Either @samp{am} or @samp{pm}, according to the given time value; or the
+corresponding strings for the current locale.
+
+@item %S
+The second as a decimal number.
+
+@item %U
+The week number of the current year as a decimal number, starting with
+the first Sunday as the first day of the first week.
+
+@item %W
+The week number of the current year as a decimal number, starting with
+the first Monday as the first day of the first week.
+
+@item %w
+The day of the week as a decimal number, Sunday being @code{0}.
+
+@item %x
+The preferred date representation for the current locale, but without the
+time.
+
+@item %X
+The preferred time representation for the current locale, but with no date.
+
+@item %y
+The year as a decimal number, but without a century (range @code{00} to
+@code{99}).
+
+@item %Y
+The year as a decimal number, including the century.
+
+@item %Z
+The time zone or name or abbreviation (empty if the time zone can't be
+determined).
+
+@item %%
+A literal @samp{%} character.
+@end table
+
+The @var{size} parameter can be used to specify the maximum number of
+characters to be stored in the array @var{s}, including the terminating
+null character.  If the formatted time requires more than @var{size}
+characters, the excess characters are discarded.  The return value from
+@code{strftime} is the number of characters placed in the array @var{s},
+not including the terminating null character.  If the value equals
+@var{size}, it means that the array @var{s} was too small; you should
+repeat the call, providing a bigger array.
+
+If @var{s} is a null pointer, @code{strftime} does not actually write
+anything, but instead returns the number of characters it would have written.
+
+For an example of @code{strftime}, see @ref{Time Functions Example}.
+@end deftypefun
+
+@node TZ Variable
+@subsection Specifying the Time Zone with @code{TZ}
+
+In POSIX systems, a user can specify the time zone by means of the
+@code{TZ} environment variable.  For information about how to set
+environment variables, see @ref{Environment Variables}.  The functions
+for accessing the time zone are declared in @file{time.h}.
+@pindex time.h
+@cindex time zone
+
+You should not normally need to set @code{TZ}.  If the system is
+configured properly, the default timezone will be correct.  You might
+set @code{TZ} if you are using a computer over the network from a
+different timezone, and would like times reported to you in the timezone
+that local for you, rather than what is local for the computer.
+
+In POSIX.1 systems the value of the @code{TZ} variable can be of one of
+three formats.  With the GNU C library, the most common format is the
+last one, which can specify a selection from a large database of time
+zone information for many regions of the world.  The first two formats
+are used to describe the time zone information directly, which is both
+more cumbersome and less precise.  But the POSIX.1 standard only
+specifies the details of the first two formats, so it is good to be
+familiar with them in case you come across a POSIX.1 system that doesn't
+support a time zone information database.
+
+The first format is used when there is no Daylight Saving Time (or
+summer time) in the local time zone:
+
+@smallexample
+@r{@var{std} @var{offset}}
+@end smallexample
+
+The @var{std} string specifies the name of the time zone.  It must be
+three or more characters long and must not contain a leading colon or
+embedded digits, commas, or plus or minus signs.  There is no space
+character separating the time zone name from the @var{offset}, so these
+restrictions are necessary to parse the specification correctly.
+
+The @var{offset} specifies the time value one must add to the local time
+to get a Coordinated Universal Time value.  It has syntax like
+[@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]].  This
+is positive if the local time zone is west of the Prime Meridian and
+negative if it is east.  The hour must be between @code{0} and
+@code{24}, and the minute and seconds between @code{0} and @code{59}.
+
+For example, here is how we would specify Eastern Standard Time, but
+without any daylight savings time alternative:
+
+@smallexample
+EST+5
+@end smallexample
+
+The second format is used when there is Daylight Saving Time:
+
+@smallexample
+@r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
+@end smallexample
+
+The initial @var{std} and @var{offset} specify the standard time zone, as
+described above.  The @var{dst} string and @var{offset} specify the name
+and offset for the corresponding daylight savings time time zone; if the
+@var{offset} is omitted, it defaults to one hour ahead of standard time.
+
+The remainder of the specification describes when daylight savings time is
+in effect.  The @var{start} field is when daylight savings time goes into
+effect and the @var{end} field is when the change is made back to standard
+time.  The following formats are recognized for these fields:
+
+@table @code
+@item J@var{n}
+This specifies the Julian day, with @var{n} between @code{1} and @code{365}.
+February 29 is never counted, even in leap years.
+
+@item @var{n}
+This specifies the Julian day, with @var{n} between @code{0} and @code{365}.
+February 29 is counted in leap years.
+
+@item M@var{m}.@var{w}.@var{d}
+This specifies day @var{d} of week @var{w} of month @var{m}.  The day
+@var{d} must be between @code{0} (Sunday) and @code{6}.  The week
+@var{w} must be between @code{1} and @code{5}; week @code{1} is the
+first week in which day @var{d} occurs, and week @code{5} specifies the
+@emph{last} @var{d} day in the month.  The month @var{m} should be
+between @code{1} and @code{12}.
+@end table
+
+The @var{time} fields specify when, in the local time currently in
+effect, the change to the other time occurs.  If omitted, the default is
+@code{02:00:00}.
+
+For example, here is how one would specify the Eastern time zone in the
+United States, including the appropriate daylight saving time and its dates
+of applicability.  The normal offset from GMT is 5 hours; since this is
+west of the prime meridian, the sign is positive.  Summer time begins on
+the first Sunday in April at 2:00am, and ends on the last Sunday in October
+at 2:00am.
+
+@smallexample
+EST+5EDT,M4.1.0/M10.5.0
+@end smallexample
+
+The schedule of daylight savings time in any particular jurisdiction has
+changed over the years.  To be strictly correct, the conversion of dates
+and times in the past should be based on the schedule that was in effect
+then.  However, this format has no facilities to let you specify how the
+schedule has changed from year to year.  The most you can do is specify
+one particular schedule---usually the present day schedule---and this is
+used to convert any date, no matter when.  For precise time zone
+specifications, it is best to use the time zone information database
+(see below).
+
+The third format looks like this:
+
+@smallexample
+:@var{characters}
+@end smallexample
+
+Each operating system interprets this format differently; in the GNU C
+library, @var{characters} is the name of a file which describes the time
+zone.
+
+@pindex /etc/localtime
+@pindex localtime
+If the @code{TZ} environment variable does not have a value, the
+operation chooses a time zone by default.  In the GNU C library, the
+default time zone is like the specification @samp{TZ=:/etc/localtime}
+(or @samp{TZ=:/usr/local/etc/localtime}, depending on how GNU C library
+was configured; @pxref{Installation}).  Other C libraries use their own
+rule for choosing the default time zone, so there is little we can say
+about them.
+
+@cindex time zone database
+@pindex /share/lib/zoneinfo
+@pindex zoneinfo
+If @var{characters} begins with a slash, it is an absolute file name;
+otherwise the library looks for the file
+@w{@file{/share/lib/zoneinfo/@var{characters}}}.  The @file{zoneinfo}
+directory contains data files describing local time zones in many
+different parts of the world.  The names represent major cities, with
+subdirectories for geographical areas; for example,
+@file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}.
+These data files are installed by the system administrator, who also
+sets @file{/etc/localtime} to point to the data file for the local time
+zone.  The GNU C library comes with a large database of time zone
+information for most regions of the world, which is maintained by a
+community of volunteers and put in the public domain.
+
+@node Time Zone Functions
+@subsection Functions and Variables for Time Zones
+
+@comment time.h
+@comment POSIX.1
+@deftypevar char * tzname [2]
+The array @code{tzname} contains two strings, which are the standard
+three-letter names of the pair of time zones (standard and daylight
+savings) that the user has selected.  @code{tzname[0]} is the name of
+the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
+is the name for the time zone when daylight savings time is in use (for
+example, @code{"EDT"}).  These correspond to the @var{std} and @var{dst}
+strings (respectively) from the @code{TZ} environment variable.
+
+The @code{tzname} array is initialized from the @code{TZ} environment
+variable whenever @code{tzset}, @code{ctime}, @code{strftime},
+@code{mktime}, or @code{localtime} is called.
+@end deftypevar
+
+@comment time.h
+@comment POSIX.1
+@deftypefun void tzset (void)
+The @code{tzset} function initializes the @code{tzname} variable from
+the value of the @code{TZ} environment variable.  It is not usually
+necessary for your program to call this function, because it is called
+automatically when you use the other time conversion functions that
+depend on the time zone.
+@end deftypefun
+
+The following variables are defined for compatibility with System V
+Unix.  These variables are set by calling @code{localtime}.
+
+@comment time.h
+@comment SVID
+@deftypevar {long int} timezone
+This contains the difference between GMT and local standard time, in
+seconds.  For example, in the U.S. Eastern time zone, the value is
+@code{5*60*60}.
+@end deftypevar
+
+@comment time.h
+@comment SVID
+@deftypevar int daylight
+This variable has a nonzero value if the standard U.S. daylight savings
+time rules apply.
+@end deftypevar
+
+@node Time Functions Example
+@subsection Time Functions Example
+
+Here is an example program showing the use of some of the local time and
+calendar time functions.
+
+@smallexample
+@include strftim.c.texi
+@end smallexample
+
+It produces output like this:
+
+@smallexample
+Wed Jul 31 13:02:36 1991
+Today is Wednesday, July 31.
+The time is 01:02 PM.
+@end smallexample
+
+
+@node Setting an Alarm
+@section Setting an Alarm
+
+The @code{alarm} and @code{setitimer} functions provide a mechanism for a
+process to interrupt itself at some future time.  They do this by setting a
+timer; when the timer expires, the process receives a signal.
+
+@cindex setting an alarm
+@cindex interval timer, setting
+@cindex alarms, setting
+@cindex timers, setting
+Each process has three independent interval timers available:
+
+@itemize @bullet
+@item 
+A real-time timer that counts clock time.  This timer sends a
+@code{SIGALRM} signal to the process when it expires.
+@cindex real-time timer
+@cindex timer, real-time
+
+@item 
+A virtual timer that counts CPU time used by the process.  This timer
+sends a @code{SIGVTALRM} signal to the process when it expires.
+@cindex virtual timer
+@cindex timer, virtual
+
+@item 
+A profiling timer that counts both CPU time used by the process, and CPU
+time spent in system calls on behalf of the process.  This timer sends a
+@code{SIGPROF} signal to the process when it expires.
+@cindex profiling timer
+@cindex timer, profiling
+
+This timer is useful for profiling in interpreters.  The interval timer
+mechanism does not have the fine granularity necessary for profiling
+native code.
+@c @xref{profil} !!!
+@end itemize
+
+You can only have one timer of each kind set at any given time.  If you
+set a timer that has not yet expired, that timer is simply reset to the
+new value.
+
+You should establish a handler for the appropriate alarm signal using
+@code{signal} or @code{sigaction} before issuing a call to @code{setitimer}
+or @code{alarm}.  Otherwise, an unusual chain of events could cause the
+timer to expire before your program establishes the handler, and in that
+case it would be terminated, since that is the default action for the alarm
+signals.  @xref{Signal Handling}.
+
+The @code{setitimer} function is the primary means for setting an alarm.
+This facility is declared in the header file @file{sys/time.h}.  The
+@code{alarm} function, declared in @file{unistd.h}, provides a somewhat
+simpler interface for setting the real-time timer.
+@pindex unistd.h
+@pindex sys/time.h
+
+@comment sys/time.h
+@comment BSD
+@deftp {Data Type} {struct itimerval}
+This structure is used to specify when a timer should expire.  It contains
+the following members:
+@table @code
+@item struct timeval it_interval
+This is the interval between successive timer interrupts.  If zero, the
+alarm will only be sent once.
+
+@item struct timeval it_value
+This is the interval to the first timer interrupt.  If zero, the alarm is
+disabled.
+@end table
+
+The @code{struct timeval} data type is described in @ref{High-Resolution
+Calendar}.
+@end deftp
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int setitimer (int @var{which}, struct itimerval *@var{new}, struct itimerval *@var{old})
+The @code{setitimer} function sets the timer specified by @var{which} 
+according to @var{new}.  The @var{which} argument can have a value of
+@code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}.
+
+If @var{old} is not a null pointer, @code{setitimer} returns information
+about any previous unexpired timer of the same kind in the structure it
+points to.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The timer interval was too large.
+@end table
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
+The @code{getitimer} function stores information about the timer specified
+by @var{which} in the structure pointed at by @var{old}.
+
+The return value and error conditions are the same as for @code{setitimer}.
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@table @code
+@item ITIMER_REAL
+@findex ITIMER_REAL
+This constant can be used as the @var{which} argument to the
+@code{setitimer} and @code{getitimer} functions to specify the real-time
+timer.
+
+@comment sys/time.h
+@comment BSD
+@item ITIMER_VIRTUAL
+@findex ITIMER_VIRTUAL
+This constant can be used as the @var{which} argument to the
+@code{setitimer} and @code{getitimer} functions to specify the virtual
+timer.
+
+@comment sys/time.h
+@comment BSD
+@item ITIMER_PROF
+@findex ITIMER_PROF
+This constant can be used as the @var{which} argument to the
+@code{setitimer} and @code{getitimer} functions to specify the profiling
+timer.
+@end table
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {unsigned int} alarm (unsigned int @var{seconds})
+The @code{alarm} function sets the real-time timer to expire in
+@var{seconds} seconds.  If you want to cancel any existing alarm, you
+can do this by calling @code{alarm} with a @var{seconds} argument of
+zero.
+
+The return value indicates how many seconds remain before the previous
+alarm would have been sent.  If there is no previous alarm, @code{alarm}
+returns zero.
+@end deftypefun
+
+The @code{alarm} function could be defined in terms of @code{setitimer}
+like this:
+
+@smallexample
+unsigned int
+alarm (unsigned int seconds)
+@{
+  struct itimerval old, new;
+  new.it_interval.tv_usec = 0;
+  new.it_interval.tv_sec = 0;
+  new.it_value.tv_usec = 0;
+  new.it_value.tv_sec = (long int) seconds;
+  if (setitimer (ITIMER_REAL, &new, &old) < 0)
+    return 0;
+  else
+    return old.it_value.tv_sec;
+@}
+@end smallexample
+
+There is an example showing the use of the @code{alarm} function in
+@ref{Handler Returns}.
+
+If you simply want your process to wait for a given number of seconds,
+you should use the @code{sleep} function.  @xref{Sleeping}.
+
+You shouldn't count on the signal arriving precisely when the timer
+expires.  In a multiprocessing environment there is typically some
+amount of delay involved.
+
+@strong{Portability Note:} The @code{setitimer} and @code{getitimer}
+functions are derived from BSD Unix, while the @code{alarm} function is
+specified by the POSIX.1 standard.  @code{setitimer} is more powerful than
+@code{alarm}, but @code{alarm} is more widely used.
+
+@node Sleeping
+@section Sleeping
+
+The function @code{sleep} gives a simple way to make the program wait
+for short periods of time.  If your program doesn't use signals (except
+to terminate), then you can expect @code{sleep} to wait reliably for
+the specified amount of time.  Otherwise, @code{sleep} can return sooner
+if a signal arrives; if you want to wait for a given period regardless
+of signals, use @code{select} (@pxref{Waiting for I/O}) and don't
+specify any descriptors to wait for.
+@c !!! select can get EINTR; using SA_RESTART makes sleep win too.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {unsigned int} sleep (unsigned int @var{seconds})
+The @code{sleep} function waits for @var{seconds} or until a signal
+is delivered, whichever happens first.  
+
+If @code{sleep} function returns because the requested time has
+elapsed, it returns a value of zero.  If it returns because of delivery
+of a signal, its return value is the remaining time in the sleep period.
+
+The @code{sleep} function is declared in @file{unistd.h}.
+@end deftypefun
+
+Resist the temptation to implement a sleep for a fixed amount of time by
+using the return value of @code{sleep}, when nonzero, to call
+@code{sleep} again.  This will work with a certain amount of accuracy as
+long as signals arrive infrequently.  But each signal can cause the
+eventual wakeup time to be off by an additional second or so.  Suppose a
+few signals happen to arrive in rapid succession by bad luck---there is
+no limit on how much this could shorten or lengthen the wait.
+
+Instead, compute the time at which the program should stop waiting, and
+keep trying to wait until that time.  This won't be off by more than a
+second.  With just a little more work, you can use @code{select} and
+make the waiting period quite accurate.  (Of course, heavy system load
+can cause unavoidable additional delays---unless the machine is 
+dedicated to one application, there is no way you can avoid this.)
+
+On some systems, @code{sleep} can do strange things if your program uses
+@code{SIGALRM} explicitly.  Even if @code{SIGALRM} signals are being
+ignored or blocked when @code{sleep} is called, @code{sleep} might
+return prematurely on delivery of a @code{SIGALRM} signal.  If you have
+established a handler for @code{SIGALRM} signals and a @code{SIGALRM}
+signal is delivered while the process is sleeping, the action taken
+might be just to cause @code{sleep} to return instead of invoking your
+handler.  And, if @code{sleep} is interrupted by delivery of a signal
+whose handler requests an alarm or alters the handling of @code{SIGALRM},
+this handler and @code{sleep} will interfere.
+
+On the GNU system, it is safe to use @code{sleep} and @code{SIGALRM} in
+the same program, because @code{sleep} does not work by means of
+@code{SIGALRM}.
+
+@node Resource Usage
+@section Resource Usage
+
+@pindex sys/resource.h
+The function @code{getrusage} and the data type @code{struct rusage}
+are used for examining the usage figures 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 the 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 terminated already.
+@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 usage figures 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 records a collection usage amounts for various sorts of
+resources.  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 that @var{processes} used in real memory 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 in data.
+
+@item long int ru_isrss
+An integral value expressed the same way, which is the amount of
+unshared memory used in 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
+the time slice expired, or another process of higher priority became
+runnable).
+@end table
+@end deftp
+
+An additional historical function for examining usage figures,
+@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 limit.  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}.
+@end deftypefun
+
+@comment sys/resource.h
+@comment BSD
+@deftypefun int setrlimit (int @var{resource}, 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
+@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_cur
+The current value of the limit in question.
+This is also called the ``soft limit''.
+@cindex soft limit
+
+@item 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
+
+In @code{getrlimit}, the structure is an output; it receives the current
+values.  In @code{setrlimit}, it specifies the new values.
+@end deftp
+
+Here is a list of resources that you can specify a limit for.
+Those that are 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 maximum size,
+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 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 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
+@defvr Constant int RLIM_INFINITY
+This constant stands for a value of ``infinity'' when supplied as
+the limit value in @code{setrlimit}.
+@end defvr
+
+@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 smallest 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
+
+When 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 for
+@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 for @code{nice}:
+
+@smallexample
+int
+nice (int increment)
+@{
+  int old = getpriority (PRIO_PROCESS, 0);
+  return setpriority (PRIO_PROCESS, 0, old + increment);
+@}
+@end smallexample
+@end deftypefun