Revise the documentation of simple calendar time.

This is a thorough revision of all the material relating to the
functions time, stime, gettimeofday, settimeofday, clock_gettime,
clock_getres, clock_settime, and difftime, spilling over into the
discussion of time-related data types (which now get their own
section) and touching the adjtime family as well (which deserves its
own thorough revision, but I'd have to do a bunch of research first).

Substantive changes are:

 * Document clock_gettime, clock_getres, and clock_settime.  (Only
   CLOCK_REALTIME and CLOCK_MONOTONIC are documented; the others are
   either a bit too Linux-specific, or have more to do with measuring
   CPU/processor time.  That section _also_ deserves its own thorough
   revision but again I'd have to do a bunch of research first.)

 * Present gettimeofday, settimeofday, and struct timeval as obsolete
   relative to clock_*.

 * Remove the documentation of struct timezone.  Matching POSIX,
   say that the type of the second argument to gettimeofday and
   settimeofday is [const] void *.

 * Clarify ISO C and POSIX's requirements on time_t.  Clarify the
   circumstances under which difftime is equivalent to simple
   subtraction.

 * Consolidate documentation of most of the time-related data types
   into a new section "Time Types," right after "Time Basics."  (The
   exceptions are struct tm, which stays in "Broken-down Time," and
   struct times, which stays in "Processor And CPU Time."

 * The "Elapsed Time" section is now called "Calculating Elapsed Time"
   and includes only difftime and the discussion of how to compute
   timeval differences by hand.

 * Fold the "Simple Calendar Time," "High Resolution Calendar," and
   "High Accuracy Clock" sections together into two new sections titled
   "Getting the Time" and "Setting and Adjusting the Time."

1 files changed, 1 insertions, 1 deletions

diff --git a/manual/filesys.texi b/manual/filesys.texi
index d31dbb24b4..73e630842e 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -2899,7 +2899,7 @@ which extends its resolution.  These fields are called
 @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
 each has a value between 0 and 999,999, which indicates the time in
 microseconds.  They correspond to the @code{tv_usec} field of a
-@code{timeval} structure; see @ref{High-Resolution Calendar}.
+@code{timeval} structure; see @ref{Time Types}.
 
 The @code{utimes} function is like @code{utime}, but also lets you specify
 the fractional part of the file times.  The prototype for this function is