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."
This commit is contained in:
Zack Weinberg 2019-08-19 10:31:07 -04:00 committed by Adhemerval Zanella
parent 2f2c76e1c8
commit 62193c4a3a
4 changed files with 624 additions and 484 deletions

View File

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

View File

@ -2094,11 +2094,11 @@ descriptors. The usual thing is to pass @code{FD_SETSIZE} as the value
of this argument.
The @var{timeout} specifies the maximum time to wait. If you pass a
null pointer for this argument, it means to block indefinitely until one
of the file descriptors is ready. Otherwise, you should provide the
time in @code{struct timeval} format; see @ref{High-Resolution
Calendar}. Specify zero as the time (a @code{struct timeval} containing
all zeros) if you want to find out which descriptors are ready without
null pointer for this argument, it means to block indefinitely until
one of the file descriptors is ready. Otherwise, you should provide
the time in @code{struct timeval} format; see @ref{Time Types}.
Specify zero as the time (a @code{struct timeval} containing all
zeros) if you want to find out which descriptors are ready without
waiting if none are ready.
The normal return value from @code{select} is the total number of ready file

View File

@ -128,7 +128,7 @@ function returns @math{0}; otherwise, the return value is non-zero.
least until the elapsed time pointed to by @var{time_point} has been
reached. This function does not take an absolute time, but a duration
that the thread is required to be blocked. @xref{Time Basics}, and
@ref{Elapsed Time}.
@ref{Time Types}.
The thread may wake early if a signal that is not ignored is received.
In such a case, if @code{remaining} is not NULL, the remaining time

File diff suppressed because it is too large Load Diff