Document all CLOCK_* values

[Carlos O'Donell]

On 5/9/25 5:46 PM, Joseph Myers wrote:
> 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).

Agreed.

> 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).

LGTM.

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


-- 
Cheers,
Carlos.