Update.

2000-05-21  Ulrich Drepper  <drepper@redhat.com>

	* manual/memory.texi: Document memory handling functions.
	* manual/time.texi: Document timespec and friends.
	* manual/conf.texi: Fix references.
	* manual/ctype.texi: Likewise.
	* manual/errno.texi: Likewise.
	* manual/intro.texi: Likewise.
	* manual/locale.texi: Likewise.
	* manual/sysinfo.texi: Likewise.
	Patches by Bryan Henderson <bryanh@giraffe-data.com>.

1 files changed, 410 insertions, 294 deletions

diff --git a/manual/time.texi b/manual/time.texi
index 1a1cddd..154b667 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -3,106 +3,263 @@
 @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
+including functions for determining what time it is and conversion
+between different time representations.
 
 @menu
-* Processor Time::              Measures processor time used by a program.
+* Time Basics::                 Concepts and definitions.
+* Elapsed Time::                Data types to represent elapsed times
+* Processor And CPU Time::      Time a program has spent executing.
 * 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.
 @end menu
 
-For functions to examine and control a process' CPU time, see
-@xref{Resource Usage And Limitation}.
 
+@node Time Basics
+@section Time Basics
+@cindex time
 
-@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.
+Discussing time in a technical manual can be difficult because the word
+``time'' in English refers to lots of different things.  In this manual,
+we use a rigorous terminology to avoid confusion, and the only thing we
+use the simple word ``time'' for is to talk about the abstract concept.
+
+A @dfn{calendar time} is a point in the time continuum, for example
+November 4, 1990 at 18:02.5 UTC.  Sometimes this is called ``absolute
+time''.
+@cindex calendar time
+
+We don't speak of a ``date'', because that is inherent in a calendar
+time.
+@cindex date
+
+An @dfn{interval} is a contiguous part of the time continuum between two
+calendar times, for example the hour between 9:00 and 10:00 on July 4,
+1980.
+@cindex interval
+
+An @dfn{elapsed time} is the length of an interval, for example, 35
+minutes.  People sometimes sloppily use the word ``interval'' to refer
+to the elapsed time of some interval.
+@cindex elapsed time
+@cindex time, elapsed
+
+An @dfn{amount of time} is a sum of elapsed times, which need not be of
+any specific intervals.  For example, the amount of time it takes to
+read a book might be 9 hours, independently of when and in how many
+sittings it is read.
+
+A @dfn{period} is the elapsed time of an interval between two events,
+especially when they are part of a sequence of regularly repeating
+events.
+@cindex period of time
+
+@dfn{CPU time} is like calendar time, except that it is based on the
+subset of the time continuum when a particular process is actively
+using a CPU.  CPU time is, therefore, relative to a process.
 @cindex CPU time
+
+@dfn{Processor time} is an amount of time that a CPU is in use.  In
+fact, it's a basic system resource, since there's a limit to how much
+can exist in any given interval (that limit is the elapsed time of the
+interval times the number of CPUs in the processor).  People often call
+this CPU time, but we reserve the latter term in this manual for the
+definition above.
 @cindex processor time
+
+@node Elapsed Time
+@section Elapsed Time
+@cindex elapsed time
+
+One way to represent an elapsed time is with a simple arithmetic data
+type, as with the following function to compute the elapsed time between
+two calendar times.  This function is declared in @file{time.h}.
+
+@comment time.h
+@comment ISO
+@deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
+The @code{difftime} function returns the number of seconds of elapsed
+time between calendar time @var{time1} and calendar time @var{time0}, as
+a value of type @code{double}.  The difference ignores leap seconds
+unless leap second support is enabled.
+
+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
+
+The GNU C library provides two data types specifically for representing
+an elapsed time.  They are used by various GNU C library functions, and
+you can use them for your own purposes too.  They're exactly the same
+except that one has a resolution in microseconds, and the other, newer
+one, is in nanoseconds.
+
+@comment sys/time.h
+@comment BSD
+@deftp {Data Type} {struct timeval}
+@cindex timeval
+The @code{struct timeval} structure represents an elapsed time.  It is
+declared in @file{sys/time.h} and has the following members:
+
+@table @code
+@item long int tv_sec
+This represents the number of whole seconds of elapsed time.
+
+@item long int tv_usec
+This is the rest of the elapsed time (a fraction of a second),
+represented as the number of microseconds.  It is always less than one
+million.
+
+@end table
+@end deftp
+
+@comment sys/time.h
+@comment POSIX.1
+@deftp {Data Type} {struct timespec}
+@cindex timespec
+The @code{struct timespec} structure represents an elapsed time.  It is
+declared in @file{time.h} and has the following members:
+
+@table @code
+@item long int tv_sec
+This represents the number of whole seconds of elapsed time.
+
+@item long int tv_nsec
+This is the rest of the elapsed time (a fraction of a second),
+represented as the number of nanoseconds.  It is always less than one
+billion.
+
+@end table
+@end deftp
+
+It is often necessary to subtract two values of type @w{@code{struct
+timeval}} or @w{@code{struct timespec}}.  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 = (x->tv_usec - y->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
+
+Common functions that use @code{struct timeval} are @code{gettimeofday} 
+and @code{settimeofday}.
+
+
+There are no GNU C library functions specifically oriented toward
+dealing with elapsed times, but the calendar time, processor time, and
+alarm and sleeping functions have a lot to do with them.
+
+
+@node Processor And CPU Time
+@section Processor And CPU Time
+
+If you're trying to optimize your program or measure its efficiency,
+it's very useful to know how much processor time it uses.  For that,
+calendar time and elapsed times are useless because a process may spend
+time waiting for I/O or for other processes to use the CPU.  However,
+you can get the information with the functions in this section.
+
+CPU time (@pxref{Time Basics}) is represented by the data type
+@code{clock_t}, which is a number of @dfn{clock ticks}.  It gives the
+total amount of time a process has actively used a CPU since some
+arbitrary event.  On the GNU system, that event is the creation of the
+process.  While arbitrary in general, the event is always the same event
+for any particular process, so you can always measure how much time on
+the CPU a particular computation takes by examinining the process' CPU
+time before and after the computation.
+@cindex CPU time
 @cindex clock ticks
 @cindex ticks, clock
-@cindex time, elapsed CPU
+
+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 macro @code{CLOCKS_PER_SEC} can be either integer
+or floating-point types.  Casting CPU 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.
+
+Note that the clock can wrap around.  On a 32bit system with
+@code{CLOCKS_PER_SEC} set to one million this function will return the
+same value approximately every 72 minutes.
+
+For additional functions to examine a process' use of processor time,
+and to control it, @xref{Resource Usage And Limitation}.
+
 
 @menu
-* Basic CPU Time::              The @code{clock} function.
-* Detailed CPU Time::           The @code{times} function.
+* CPU Time::                    The @code{clock} function.
+* Processor Time::              The @code{times} function.
 @end menu
 
-@node Basic CPU Time
-@subsection Basic CPU Time Inquiry
+@node CPU Time
+@subsection 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}.
+To get a process' CPU time, 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:
+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)
+to get processor time, like this:
 
 @smallexample
 @group
 #include <time.h>
 
 clock_t start, end;
-double elapsed;
+double cpu_time_used;
 
 start = clock();
 @dots{} /* @r{Do the work.} */
 end = clock();
-elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
+cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
 @end group
 @end smallexample
 
+Do not use a single CPU time as an amount of time; it doesn't work that
+way.  Either do a subtraction as shown above or query processor time
+directly.  @xref{Processor Time}.
+
 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 hundredth and millionth of a
+track of CPU time.  It's common for the internal processor clock
+to have a resolution somewhere between a hundredth and millionth 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.
-
-Note that the clock can wrap around.  On a 32bit system with
-@code{CLOCKS_PER_SEC} set to one million this function will return the
-same value approximately every 72 minutes.
-
 @comment time.h
 @comment ISO
 @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.  POSIX requires that this value is one
+by the @code{clock} function.  POSIX requires that this value be one
 million independent of the actual resolution.
 @end deftypevr
 
@@ -116,25 +273,27 @@ This is an obsolete name for @code{CLOCKS_PER_SEC}.
 @comment ISO
 @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.
+Values of type @code{clock_t} are numbers of clock ticks.
 @end deftp
 
 @comment time.h
 @comment ISO
 @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
+This function returns the calling process' current CPU time.  If the CPU
 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
+@node Processor Time
+@subsection Processor Time Inquiry
 
-The @code{times} function returns more detailed information about
-elapsed processor time in a @w{@code{struct tms}} object.  You should
+The @code{times} function returns information about a process'
+consumption of processor time in a @w{@code{struct tms}} object, in
+addition to the process' CPU time.  @xref{Time Basics}.  You should
 include the header file @file{sys/times.h} to use this facility.
+@cindex processor time
+@cindex CPU time
 @pindex sys/times.h
 
 @comment sys/times.h
@@ -145,30 +304,33 @@ 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.
+This is the total processor time the calling process has used in
+executing the instructions of its program.
 
 @item clock_t tms_stime
-This is the CPU time used by the system on behalf of the calling process.
+This is the processor time the system has used 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
+represents the total processor 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}.
+@cindex child process
 
 @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.
+This is similar to @code{tms_cutime}, but represents the total processor
+time system has used 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}.
+All of the times are given in numbers of clock ticks.  Unlike CPU time,
+these are the actual amounts of time; not relative to any event.
+@xref{Creating a Process}.
 @end deftp
 
 @comment sys/times.h
@@ -177,50 +339,46 @@ newly created process, they are all zero.  @xref{Creating a Process}.
 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.
+The return value is the calling process' CPU time (the same value you
+get from @code{clock()}.  @code{times} returns @code{(clock_t)(-1)} to
+indicate failure.
 @end deftypefun
 
 @strong{Portability Note:} The @code{clock} function described in
-@ref{Basic CPU Time}, is specified by the @w{ISO C} standard.  The
+@ref{CPU Time} is specified by the @w{ISO 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}.
+CPU time is defined to be 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 points in time.
-This is called calendar time and sometimes absolute time.
-@cindex time, absolute
-@cindex time, calendar
-@cindex date and time
+This section describes facilities for keeping track of calendar time.
+@xref{Time Basics}.
 
 The GNU C library represents calendar time three ways:
 
 @itemize @bullet
 @item
 @dfn{Simple time} (the @code{time_t} data type) is a compact
-representation, typically giving the number of seconds elapsed since
-some implementation-specific base time.
+representation, typically giving the number of seconds of elapsed time
+since some implementation-specific base time.
 @cindex simple 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 simple time when you need greater
-precision.
+There is also a "high-resolution time" representation.  Like simple
+time, this represents a calendar time as an elapsed time since a base
+time, but instead of measuring in whole seconds, it uses a @code{struct
+timeval} data type, which includes fractions of a second.  Use this time
+representation instead of simple 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
+type) represents a calendar time as a set of components specifying the
 year, month, and so on in the Gregorian calendar, for a specific time
-zone.  This time representation is usually used only to communicate with
-people.
+zone.  This calendar time representation is usually used only to
+communicate with people.
 @cindex local time
 @cindex broken-down time
 @cindex Gregorian calendar
@@ -232,7 +390,7 @@ people.
 * High-Resolution Calendar::    A time representation with greater precision.
 * Broken-down Time::            Facilities for manipulating local time.
 * High Accuracy Clock::         Maintaining a high accuracy system clock.
-* Formatting Date and Time::    Converting times to strings.
+* Formatting Calendar Time::    Converting times to strings.
 * Parsing Date and Time::       Convert textual time and date information back
                                  into broken-down time values.
 * TZ Variable::                 How users specify the time zone.
@@ -254,43 +412,34 @@ These facilities are declared in the header file @file{time.h}.
 @comment ISO
 @deftp {Data Type} time_t
 This is the data type used to represent simple time.  Sometimes, it also
-represents an elapsed time.
-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 time is sometimes
-referred to as the @dfn{epoch}.)  POSIX requires that this count
-not include leap seconds, but on some hosts this count includes leap seconds
+represents an elapsed time.  When interpreted as a calendar time value,
+it represents the number of seconds elapsed since 00:00:00 on January 1,
+1970, Coordinated Universal Time.  (This calendar time is sometimes
+referred to as the @dfn{epoch}.)  POSIX requires that this count not
+include leap seconds, but on some systems this count includes leap seconds
 if you set @code{TZ} to certain values (@pxref{TZ Variable}).
 
-Note that a simple time has no concept of local time zone.  Time @var{N}
-is the same instant in time regardless of where on the globe the
-computer is.
+Note that a simple time has no concept of local time zone.  Calendar
+Time @var{T} is the same instant in time regardless of where on the
+globe the computer is.
 
 In the GNU C library, @code{time_t} is equivalent to @code{long int}.
 In other systems, @code{time_t} might be either an integer or
 floating-point type.
 @end deftp
 
-@comment time.h
-@comment ISO
-@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}.  The difference ignores leap seconds unless leap
-second support is enabled.
-
-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
+The function @code{difftime} tells you the elapsed time between two
+simple calendar times, which is not always as easy to compute as just
+subtracting.  @xref{Elapsed Time}.
 
 @comment time.h
 @comment ISO
 @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.
+The @code{time} function returns the current calendar time as a value of
+type @code{time_t}.  If the argument @var{result} is not a null pointer,
+the calendar time value is also stored in @code{*@var{result}}.  If the
+current calendar time is not available, the value
+@w{@code{(time_t)(-1)}} is returned.
 @end deftypefun
 
 @c The GNU C library implements stime() with a call to settimeofday() on
@@ -299,7 +448,7 @@ time is not available, the value @w{@code{(time_t)(-1)}} is returned.
 @comment SVID, XPG
 @deftypefun int stime (time_t *@var{newtime})
 @code{stime} sets the system clock, i.e.  it tells the system that the
-present absolute time is @var{newtime}, where @code{newtime} is
+current calendar time is @var{newtime}, where @code{newtime} is
 interpreted as described in the above definition of @code{time_t}.
 
 @code{settimeofday} is a newer function which sets the system clock to
@@ -333,27 +482,6 @@ declared in @file{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:
@@ -370,49 +498,15 @@ 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 = (x->tv_usec - y->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 @code{gettimeofday} function returns the current calendar time as
+the elapsed time since the epoch in the @code{struct timeval} structure
+indicated by @var{tp}.  (@pxref{Elapsed Time} for a description of
+@code{struct timespec}).  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:
@@ -430,15 +524,17 @@ Instead, use the facilities described in @ref{Time Zone Functions}.
 @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.
+The @code{settimeofday} function sets the current calendar time in the
+system clock according to the arguments.  As for @code{gettimeofday},
+the calendar time is represented as the elapsed time since the epoch.
+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}.
 
 Some kernels automatically set the system clock from some source such as
 a hardware clock when they start up.  Others, including Linux, place the
-system clock in an ``invalid'' state (in which attempts to read the time
+system clock in an ``invalid'' state (in which attempts to read the clock
 fail).  A call of @code{stime} removes the system clock from an invalid
 state, and system startup scripts typically run a program that calls
 @code{stime}.
@@ -457,7 +553,7 @@ 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.
+This process cannot set the clock because it is not privileged.
 
 @item ENOSYS
 The operating system does not support setting time zone information, and
@@ -470,14 +566,14 @@ The operating system does not support setting time zone information, and
 @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.
+a gradual adjustment.  This ensures that the calendar time reported by
+the system clock is always monotonically increasing, which might not
+happen if you simply set the clock.
 
 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.
+the clock time.  If negative, the system clock is slowed down for a
+while until it has lost this much elapsed 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
@@ -520,15 +616,16 @@ This function is present only with a Linux kernel.
 @cindex broken-down time
 @cindex calendar time and broken-down time
 
-Calendar time is represented as an amount of time since a fixed base
-time.  This is convenient for calculation, but has no relation to the
-way people normally think of 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.
+Calendar time is represented by the usual GNU C library functions as an
+elapsed time since a fixed base calendar time.  This is convenient for
+computation, but has no relation to the way people normally think of
+calendar time.  By contrast, @dfn{broken-down time} is a binary
+representation of calendar time 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 information.
 
 A broken-down time value is always relative to a choice of time
-zone, and it also indicates which time zone was used.
+zone, and it also indicates which time zone that is.
 
 The symbols in this section are declared in the header file @file{time.h}.
 
@@ -536,40 +633,44 @@ The symbols in this section are declared in the header file @file{time.h}.
 @comment ISO
 @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:
+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} through @code{59}.  (The actual upper limit is @code{60}, to allow
-for leap seconds if leap second support is available.)
+This is the number of full seconds since the top of the minute (normally
+in the range @code{0} through @code{59}, but the actual upper limit is
+@code{60}, to allow for leap seconds if leap second support is
+available).
 @cindex leap second
 
 @item int tm_min
-This is the number of minutes after the hour, in the range @code{0} through
-@code{59}.
+This is the number of full minutes since the top of the hour (in the
+range @code{0} through @code{59}).
 
 @item int tm_hour
-This is the number of hours past midnight, in the range @code{0} through
-@code{23}.
+This is the number of full hours past midnight (in the range @code{0} through
+@code{23}).
 
 @item int tm_mday
-This is the day of the month, in the range @code{1} through @code{31}.
+This is the ordinal day of the month (in the range @code{1} through @code{31}).
+Watch out for this one!  As the only ordinal number in the structure, it is
+inconsistent with the rest of the structure.
 
 @item int tm_mon
-This is the number of months since January, in the range @code{0} through
-@code{11}.
+This is the number of full calendar months since the beginning of the
+year (in the range @code{0} through @code{11}).  Watch out for this one!
+People usually use ordinal numbers for month-of-year (where January = 1).
 
 @item int tm_year
-This is the number of years since @code{1900}.
+This is the number of full calendar years since 1900.
 
 @item int tm_wday
-This is the number of days since Sunday, in the range @code{0} through
-@code{6}.
+This is the number of full days since Sunday (in the range @code{0} through
+@code{6}).
 
 @item int tm_yday
-This is the number of days since January 1, in the range @code{0} through
-@code{365}.
+This is the number of full days since the beginning of the year (in the
+range @code{0} through @code{365}).
 
 @item int tm_isdst
 @cindex Daylight Saving Time
@@ -595,6 +696,7 @@ GNU extension, and is not visible in a strict @w{ISO C} environment.
 @end table
 @end deftp
 
+
 @comment time.h
 @comment ISO
 @deftypefun {struct tm *} localtime (const time_t *@var{time})
@@ -738,12 +840,13 @@ These functions are declared in @file{sys/timex.h}.
 
 @tindex struct ntptimeval
 @deftp {Data Type} {struct ntptimeval}
-This structure is used to monitor kernel time.  It contains the
-following members:
+This structure is used for information about the system clock.  It
+contains the following members:
 @table @code
 @item struct timeval time
-This is the current time.  The @code{struct timeval} data type is
-described in @ref{High-Resolution Calendar}.
+This is the current calendar time, expressed as the elapsed time since
+the epoch.  The @code{struct timeval} data type is described in
+@ref{Elapsed Time}.
 
 @item long int maxerror
 This is the maximum error, measured in microseconds.  Unless updated
@@ -753,7 +856,7 @@ platform-specific maximum value.
 @item long int esterror
 This is the estimated error, measured in microseconds.  This value can
 be set by @code{ntp_adjtime} to indicate the estimated offset of the
-local clock against the true time.
+system clock from the true calendar time.
 @end table
 @end deftp
 
@@ -788,18 +891,19 @@ symbolic constants have to be combined with @emph{binary or} to specify
 the effective mode.  These constants start with @code{MOD_}.
 
 @item long int offset
-This value indicates the current offset of the local clock from the true
-time.  The value is given in microseconds.  If bit @code{MOD_OFFSET} is
-set in @code{modes}, the offset (and possibly other dependent values) can
-be set.  The offset's absolute value must not exceed @code{MAXPHASE}.
+This value indicates the current offset of the system clock from the true
+calendar time.  The value is given in microseconds.  If bit
+@code{MOD_OFFSET} is set in @code{modes}, the offset (and possibly other
+dependent values) can be set.  The offset's absolute value must not
+exceed @code{MAXPHASE}.
 
 
 @item long int frequency
-This value indicates the difference in frequency between the true time
-and the local clock.  The value is expressed as scaled PPM (parts per
-million, 0.0001%).  The scaling is @code{1 << SHIFT_USEC}.  The value
-can be set with bit @code{MOD_FREQUENCY}, but the absolute value must
-not exceed @code{MAXFREQ}.
+This value indicates the difference in frequency between the true
+calendar time and the system clock.  The value is expressed as scaled
+PPM (parts per million, 0.0001%).  The scaling is @code{1 <<
+SHIFT_USEC}.  The value can be set with bit @code{MOD_FREQUENCY}, but
+the absolute value must not exceed @code{MAXFREQ}.
 
 @item long int maxerror
 This is the maximum error, measured in microseconds.  A new value can be
@@ -832,17 +936,17 @@ scaled PPM.  This value is used to increase the @code{maxerror} every
 second.
 
 @item struct timeval time
-The current time.
+The current calendar time.
 
 @item long int tick
-The time between clock ticks in microseconds.  A clock tick is a
+The elapsed time between clock ticks in microseconds.  A clock tick is a
 periodic timer interrupt on which the system clock is based.
 
 @item long int ppsfreq
 This is the first of a few optional variables that are present only if
 the system clock can use a PPS (pulse per second) signal to discipline
-the local clock.  The value is expressed in scaled PPM and it denotes
-the difference in frequency between the local clock and the PPS signal.
+the system clock.  The value is expressed in scaled PPM and it denotes
+the difference in frequency between the system clock and the PPS signal.
 
 @item long int jitter
 This value expresses a median filtered average of the PPS signal's
@@ -920,11 +1024,11 @@ have this function but did have the synonymous @code{adjtimex}.
 @end deftypefun
 
 
-@node Formatting Date and Time
-@subsection Formatting Date and Time
+@node Formatting Calendar Time
+@subsection Formatting Calendar Time
 
-The functions described in this section format time values as strings.
-These functions are declared in the header file @file{time.h}.
+The functions described in this section format calendar time values as
+strings.  These functions are declared in the header file @file{time.h}.
 @pindex time.h
 
 @comment time.h
@@ -967,9 +1071,9 @@ return @code{NULL}.
 @comment time.h
 @comment ISO
 @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} simple time value rather
-than in broken-down local time format.  It is equivalent to
+The @code{ctime} function is similar to @code{asctime}, except that you
+specify the calendar time argument as a @code{time_t} simple time value
+rather than in broken-down local time format.  It is equivalent to
 
 @smallexample
 asctime (localtime (@var{time}))
@@ -982,9 +1086,9 @@ does so.  @xref{Time Zone Functions}.
 @comment time.h
 @comment POSIX.1c
 @deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer})
-This function is similar to @code{ctime}, only that it places the result
-in the string pointed to by @var{buffer}.  It is equivalent to (written
-using gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}):
+This function is similar to @code{ctime}, but places the result in the
+string pointed to by @var{buffer}.  It is equivalent to (written using
+gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}):
 
 @smallexample
 (@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @})
@@ -1075,7 +1179,7 @@ The abbreviated month name according to the current locale.
 The full month name according to the current locale.
 
 @item %c
-The preferred date and time representation for the current locale.
+The preferred calendar time representation for the current locale.
 
 @item %C
 The century of the year.  This is equivalent to the greatest integer not
@@ -1178,7 +1282,7 @@ This format was introduced in @w{ISO C99} but was previously available
 as a GNU extension.
 
 @item %r
-The complete time using the AM/PM format of the current locale.
+The complete calendar time using the AM/PM format of the current locale.
 
 This format is a POSIX.2 extension and also appears in @w{ISO C99}.
 
@@ -1203,7 +1307,7 @@ A single @samp{\t} (tabulator) character.
 This format is a POSIX.2 extension and also appears in @w{ISO C99}.
 
 @item %T
-The time using decimal numbers using the format @code{%H:%M:%S}.
+The time of day using decimal numbers using the format @code{%H:%M:%S}.
 
 This format is a POSIX.2 extension.
 
@@ -1243,11 +1347,10 @@ the first week.  All days preceding the first Monday in the year are
 considered to be in week @code{00}.
 
 @item %x
-The preferred date representation for the current locale, but without the
-time.
+The preferred date representation for the current locale.
 
 @item %X
-The preferred time representation for the current locale, but with no date.
+The preferred time of day representation for the current locale.
 
 @item %y
 The year without a century as a decimal number (range @code{00} through
@@ -1532,13 +1635,14 @@ Leap seconds are not counted unless leap second support is available.
 @code{%s} is a GNU extension following a GNU extension to @code{strftime}.
 
 @item %S
-The seconds as a decimal number (range @code{0} through @code{61}).
+The seconds as a decimal number (range @code{0} through @code{60}).
 
 Leading zeroes are permitted but not required.
 
-Note the nonsense with @code{61}, as given in the Unix specification.
-This is a result of a decision to allow double leap seconds.  These do
-not in fact exist but the myth persists.
+@strong{Note:} The Unix specification says the upper bound on this value
+is @code{61}, a result of a decision to allow double leap seconds.  You
+will not see the value @code{61} because no minute has more than one
+leap second, but the myth persists.
 
 @item %OS
 Same as @code{%S} but using the locale's alternative numeric symbols.
@@ -2135,7 +2239,7 @@ The time is 01:02 PM.
 @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
+process to interrupt itself in the future.  They do this by setting a
 timer; when the timer expires, the process receives a signal.
 
 @cindex setting an alarm
@@ -2146,21 +2250,21 @@ Each process has three independent interval timers available:
 
 @itemize @bullet
 @item
-A real-time timer that counts clock time.  This timer sends a
+A real-time timer that counts elapsed 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
+A virtual timer that counts processor 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.
+A profiling timer that counts both processor time used by the process,
+and processor 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
 
@@ -2195,16 +2299,15 @@ 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
+This is the period 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.
+This is the period between now and 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}.
+The @code{struct timeval} data type is described in @ref{Elapsed Time}.
 @end deftp
 
 @comment sys/time.h
@@ -2223,7 +2326,7 @@ following @code{errno} error conditions are defined for this function:
 
 @table @code
 @item EINVAL
-The timer interval was too large.
+The timer period is too large.
 @end table
 @end deftypefun
 
@@ -2313,12 +2416,12 @@ specified by the POSIX.1 standard.  @code{setitimer} is more powerful than
 @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.
+for a short interval.  If your program doesn't use signals (except to
+terminate), then you can expect @code{sleep} to wait reliably throughout
+the specified interval.  Otherwise, @code{sleep} can return sooner if a
+signal arrives; if you want to wait for a given interval 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
@@ -2327,9 +2430,9 @@ specify any descriptors to wait for.
 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.
+If @code{sleep} function returns because the requested interval is over,
+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 interval.
 
 The @code{sleep} function is declared in @file{unistd.h}.
 @end deftypefun
@@ -2342,12 +2445,13 @@ 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 additional unavoidable delays---unless the machine is
-dedicated to one application, there is no way you can avoid this.)
+Instead, compute the calendar time at which the program should stop
+waiting, and keep trying to wait until that calendar 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 additional unavoidable 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
@@ -2367,13 +2471,22 @@ the same program, because @code{sleep} does not work by means of
 @comment time.h
 @comment POSIX.1
 @deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
-If resolution to seconds is not enough the @code{nanosleep} function
-can be used.  As the name suggests the sleeping period can be specified
-in nanoseconds.  The actual period of waiting time might be longer since
-the requested time in the @var{requested_time} parameter is rounded up
-to the next integer multiple of the actual resolution of the system.
+If resolution to seconds is not enough the @code{nanosleep} function can
+be used.  As the name suggests the sleep interval can be specified in
+nanoseconds.  The actual elapsed time of the sleep interval might be
+longer since the system rounds the elapsed time you request up to the
+next integer multiple of the actual resolution the system can deliver.
 
-If the function returns because the time has elapsed the return value is
+*@code{requested_time} is the elapsed time of the interval you want to
+sleep.
+
+The function returns as *@code{remaining} the elapsed time left in the
+interval for which you requested to sleep.  If the interval completed
+without getting interrupted by a signal, this is zero.
+
+@code{struct timespec} is described in @xref{Elapsed Time}.    
+
+If the function returns because the interval is over the return value is
 zero.  If the function returns @math{-1} the global variable @var{errno}
 is set to the following values:
 
@@ -2381,7 +2494,8 @@ is set to the following values:
 @item EINTR
 The call was interrupted because a signal was delivered to the thread.
 If the @var{remaining} parameter is not the null pointer the structure
-pointed to by @var{remaining} is updated to contain the remaining time.
+pointed to by @var{remaining} is updated to contain the remaining
+elapsed time.
 
 @item EINVAL
 The nanosecond value in the @var{requested_time} parameter contains an
@@ -2399,3 +2513,5 @@ be protected using cancellation handlers.
 
 The @code{nanosleep} function is declared in @file{time.h}.
 @end deftypefun
+
+