Re: [PATCH] man/man3/timespec_get.3: Add ISO C23 time bases

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 4100 bytes --]

Hi Mark,

On 2026-01-27T22:42:21-0800, Mark Harris wrote:
> Document new time bases TIME_MONOTONIC, TIME_ACTIVE, and
> TIME_THREAD_ACTIVE, introduced in ISO C23 and supported by
> glibc 2.43.[1]
> 
> [1] <https://sourceware.org/git/?p=glibc.git;a=commit;h=f28a11e43f40>
> 
> Signed-off-by: Mark Harris <mark.hsj@gmail.com>

Thanks!

> ---
>  man/man3/timespec_get.3 | 64 ++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 57 insertions(+), 7 deletions(-)
> 
> diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
> index 79bb82226..d2be50fd4 100644
> --- a/man/man3/timespec_get.3
> +++ b/man/man3/timespec_get.3
> @@ -17,6 +17,25 @@ .SH SYNOPSIS
>  .BI "int timespec_get(struct timespec *" res ", int " base );
>  .BI "int timespec_getres(struct timespec *" tp ", int " base );
>  .fi
> +.P
> +.RS -4
> +Feature Test Macro Requirements for glibc (see
> +.BR feature_test_macros (7)):
> +.RE
> +.P
> +.BR timespec_get (),
> +.BR TIME_UTC :
> +.nf
> +    _ISOC11_SOURCE
> +.fi
> +.P
> +.BR timespec_getres (),
> +.BR TIME_MONOTONIC ,
> +.BR TIME_ACTIVE ,
> +.BR TIME_THREAD_ACTIVE :
> +.nf
> +    _ISOC23_SOURCE
> +.fi
>  .SH DESCRIPTION
>  The
>  .BR timespec_get ()

LGTM.  But would you mind separating the patch into one that reformats
the page without adding the new time bases, and then one patch that adds
the new time bases?

> @@ -39,16 +58,49 @@ .SH DESCRIPTION
>  For a particular time base,
>  the resolution is constant for the lifetime of the calling process.
>  .P
> +The time base
> +.I base
> +is one of the following:
> +.TP

Same here.  I'd like this to be part of a pre-patch.

>  .B TIME_UTC
> -is always a supported time base,
> -and is the only time base supported on Linux.
> +A system-wide time base that measures real (i.e., wall-clock) time.
>  The time and resolution in this time base
>  are the same as those retrieved by
>  .I clock_gettime(CLOCK_REALTIME,\~res)
>  and
>  .IR clock_getres(CLOCK_REALTIME,\~tp) ,
>  respectively.
> -Other systems may support additional time bases.
> +.TP
> +.BR TIME_MONOTONIC " (since glibc 2.43)"
> +A time base that measures time since an unspecified point in the past,
> +where the time within a process will not decrease even if the
> +system's real time clock is set or adjusted.
> +The time and resolution in this time base
> +are the same as those retrieved by
> +.I clock_gettime(CLOCK_MONOTONIC,\~res)
> +and
> +.IR clock_getres(CLOCK_MONOTONIC,\~tp) ,
> +respectively.
> +.TP
> +.BR TIME_ACTIVE " (since glibc 2.43)"
> +A process-specific time base that measures CPU time consumed by
> +the calling process.
> +The time and resolution in this time base
> +are the same as those retrieved by
> +.I clock_gettime(CLOCK_PROCESS_CPUTIME_ID,\~res)
> +and
> +.IR clock_getres(CLOCK_PROCESS_CPUTIME_ID,\~tp) ,
> +respectively.
> +.TP
> +.BR TIME_THREAD_ACTIVE " (since glibc 2.43)"
> +A thread-specific time base that measures CPU time consumed by
> +the calling thread.
> +The time and resolution in this time base
> +are the same as those retrieved by
> +.I clock_gettime(CLOCK_THREAD_CPUTIME_ID,\~res)
> +and
> +.IR clock_getres(CLOCK_THREAD_CPUTIME_ID,\~tp) ,
> +respectively.
>  .SH RETURN VALUE
>  .BR timespec_get ()
>  returns the nonzero
> @@ -78,9 +130,9 @@ .SH ATTRIBUTES
>  .SH STANDARDS
>  .TP
>  .BR timespec_get ()
> -.TQ
> +C23 (though ISO C doesn't specify the
>  .B TIME_UTC
> -C23 (though ISO C doesn't specify the time epoch),
> +epoch),

I don't understand this change.  Could you please clarify?

>  POSIX.1-2024.
>  .TP
>  .BR timespec_getres ()
> @@ -88,8 +140,6 @@ .SH STANDARDS
>  .SH HISTORY
>  .TP
>  .BR timespec_get ()
> -.TQ
> -.B TIME_UTC
>  C11, POSIX.1-2024, glibc 2.16, musl 1.1.10.

I'd like to have the new bases documented in HISTORY, which will allow
documenting also support in musl and other libraries.


Have a lovely day!
Alex

>  .TP
>  .BR timespec_getres ()
> -- 
> 2.52.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]