From: Joseph Myers <josmyers@redhat.com>
Date: Mon, 12 May 2025 14:56:07 +0000 (+0000)
Subject: Document all CLOCK_* values
X-Git-Tag: glibc-2.42~262
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f451a02a8c3c0bc6b41dac5e9e6ad49dd1c9529c;p=thirdparty%2Fglibc.git

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 6b89b8539f..7697b6ba48 100644
--- 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}