Document all CLOCK_* values

The manual documents CLOCK_REALTIME and CLOCK_MONOTONIC but not other
CLOCK_* values.  Add documentation of the POSIX clocks
CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID, along with a
reference to the Linux man pages for the semantics of the
Linux-specific clocks supported (as with some other functionality
coming direct from the Linux kernel where the man pages can be
considered the main documentation).

Note: CLOCK_MONOTONIC_RAW, CLOCK_REALTIME_COARSE and
CLOCK_MONOTONIC_COARSE are also defined in the toplevel bits/time.h,
as used for Hurd.  Nevertheless, I see no sign that the Hurd code in
glibc actually has any support for those clocks, so I think it is
correct to document them as Linux-specific (and to refer only to the
Linux man pages for their semantics).

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

diff --git a/manual/time.texi b/manual/time.texi
index 6b89b8539fcecd762c2b14477179c487332666e7..7697b6ba487f45502a7c95499ee9650d6a6afd23 100644 (file)
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -529,7 +529,36 @@ Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure
 absolute time, only elapsed time.
 @end deftypevr
 
-Systems may support more than just these two POSIX clocks.
+The following clocks are defined by POSIX, but may not be supported by
+all POSIX systems:
+
+@deftypevr Macro clockid_t CLOCK_PROCESS_CPUTIME_ID
+@standards{POSIX.1, time.h}
+This POSIX clock measures the amount of CPU time used by the calling
+process.
+@end deftypevr
+
+@deftypevr Macro clockid_t CLOCK_THREAD_CPUTIME_ID
+@standards{POSIX.1, time.h}
+This POSIX clock measures the amount of CPU time used by the calling
+thread.
+@end deftypevr
+
+The following clocks are Linux extensions:
+
+@deftypevr Macro clockid_t CLOCK_MONOTONIC_RAW
+@deftypevrx Macro clockid_t CLOCK_REALTIME_COARSE
+@deftypevrx Macro clockid_t CLOCK_MONOTONIC_COARSE
+@deftypevrx Macro clockid_t CLOCK_BOOTTIME
+@deftypevrx Macro clockid_t CLOCK_REALTIME_ALARM
+@deftypevrx Macro clockid_t CLOCK_BOOTTIME_ALARM
+@deftypevrx Macro clockid_t CLOCK_TAI
+@standards{Linux, time.h}
+For details of these clocks, see the manual page
+@manpageurl{clock_gettime,2}.
+@end deftypevr
+
+Systems may support additional clocks beyond those listed here.
 
 @deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts})
 @standards{POSIX.1, time.h}