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

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

[Mark Harris]

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>
---
 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 ()
@@ -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
 .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),
 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.
 .TP
 .BR timespec_getres ()
-- 
2.52.0

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

[Alejandro Colomar]

[-- 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 --]

[PATCH v2 1/2] man/man3/timespec_get.3: Refactor to prepare for new time bases

[Mark Harris]

Add Feature Test Macro Requirements to document functions and macros
that require ISO C11 or C23, and arrange supported time bases as a list.

Signed-off-by: Mark Harris <mark.hsj@gmail.com>
---
v2: Split into two patches, add time bases to History section

 man/man3/timespec_get.3 | 32 ++++++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 8 deletions(-)

diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
index 79bb82226..1c89865d5 100644
--- a/man/man3/timespec_get.3
+++ b/man/man3/timespec_get.3
@@ -17,6 +17,22 @@ .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 ():
+.nf
+    _ISOC23_SOURCE
+.fi
 .SH DESCRIPTION
 The
 .BR timespec_get ()
@@ -39,16 +55,18 @@ .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
 .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.
 .SH RETURN VALUE
 .BR timespec_get ()
 returns the nonzero
@@ -78,18 +96,16 @@ .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),
 POSIX.1-2024.
 .TP
 .BR timespec_getres ()
 C23.
 .SH HISTORY
 .TP
-.BR timespec_get ()
-.TQ
-.B TIME_UTC
+.BR timespec_get "(), " TIME_UTC
 C11, POSIX.1-2024, glibc 2.16, musl 1.1.10.
 .TP
 .BR timespec_getres ()
-- 
2.52.0

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

[Mark Harris]

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>
---
v2: Split into two patches, add time bases to History section

 man/man3/timespec_get.3 | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
index 1c89865d5..8c68d142d 100644
--- a/man/man3/timespec_get.3
+++ b/man/man3/timespec_get.3
@@ -29,7 +29,10 @@ .SH SYNOPSIS
     _ISOC11_SOURCE
 .fi
 .P
-.BR timespec_getres ():
+.BR timespec_getres (),
+.BR TIME_MONOTONIC ,
+.BR TIME_ACTIVE ,
+.BR TIME_THREAD_ACTIVE :
 .nf
     _ISOC23_SOURCE
 .fi
@@ -67,6 +70,37 @@ .SH DESCRIPTION
 and
 .IR clock_getres(CLOCK_REALTIME,\~tp) ,
 respectively.
+.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
@@ -110,6 +144,9 @@ .SH HISTORY
 .TP
 .BR timespec_getres ()
 C23, glibc 2.34.
+.TP
+.BR TIME_MONOTONIC ", " TIME_ACTIVE ", " TIME_THREAD_ACTIVE
+C23, glibc 2.43.
 .SH SEE ALSO
 .BR clock_gettime (2),
 .BR clock_getres (2)
-- 
2.52.0

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

[Mark Harris]

Alejandro Colomar wrote:
>
> 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?

No problem; I will send a v2.

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

Ok.

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

Previously it only listed one time base, TIME_UTC, so it was clear
that "the time epoch" referred to the starting point of the TIME_UTC
time base.  Now there are multiple time bases so "the time epoch" was
changed to "the TIME_UTC epoch".

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

Ok, added in v2.


 - Mark

>
>
> Have a lovely day!
> Alex
>
> >  .TP
> >  .BR timespec_getres ()
> > --
> > 2.52.0
> >
> >
>
> --
> <https://www.alejandro-colomar.es>

Re: [PATCH v2 1/2] man/man3/timespec_get.3: Refactor to prepare for new time bases

[Alejandro Colomar]

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

Hi Mark,

On 2026-01-28T09:33:03-0800, Mark Harris wrote:
> Add Feature Test Macro Requirements to document functions and macros
> that require ISO C11 or C23, and arrange supported time bases as a list.
> 
> Signed-off-by: Mark Harris <mark.hsj@gmail.com>
> ---
> v2: Split into two patches, add time bases to History section
> 
>  man/man3/timespec_get.3 | 32 ++++++++++++++++++++++++--------
>  1 file changed, 24 insertions(+), 8 deletions(-)

[...]
> @@ -78,18 +96,16 @@ .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),
>  POSIX.1-2024.

How about this?:

	.TP
	.BR timespec_get ()
	C23, POSIX.1-2024.
	.TQ
	.B TIME_UTC
	C23 (though ISO C doesn't specify the time epoch),
	POSIX.1-2024.

>  .TP
>  .BR timespec_getres ()
>  C23.
>  .SH HISTORY
>  .TP
> -.BR timespec_get ()
> -.TQ
> -.B TIME_UTC
> +.BR timespec_get "(), " TIME_UTC

I prefer the format with TQ.  I wouldn't change anything in HISTORY.


Have a lovely day!
Alex

>  C11, POSIX.1-2024, glibc 2.16, musl 1.1.10.
>  .TP
>  .BR timespec_getres ()
> -- 
> 2.52.0
> 

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

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

[PATCH v3 1/2] man/man3/timespec_get.3: Refactor to prepare for new time bases

[Mark Harris]

Add Feature Test Macro Requirements to document functions and macros
that require ISO C11 or C23, and arrange supported time bases as a list.

Signed-off-by: Mark Harris <mark.hsj@gmail.com>
---
v3: Use .TQ for time bases in STANDARDS and HISTORY
v2: Split into two patches, add time bases to History section

 man/man3/timespec_get.3 | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
index 79bb82226..67da4858c 100644
--- a/man/man3/timespec_get.3
+++ b/man/man3/timespec_get.3
@@ -17,6 +17,22 @@ .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 ():
+.nf
+    _ISOC23_SOURCE
+.fi
 .SH DESCRIPTION
 The
 .BR timespec_get ()
@@ -39,16 +55,18 @@ .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
 .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.
 .SH RETURN VALUE
 .BR timespec_get ()
 returns the nonzero
@@ -78,6 +96,7 @@ .SH ATTRIBUTES
 .SH STANDARDS
 .TP
 .BR timespec_get ()
+C23, POSIX.1-2024.
 .TQ
 .B TIME_UTC
 C23 (though ISO C doesn't specify the time epoch),
-- 
2.52.0

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

[Mark Harris]

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>
---
v3: Use .TQ for time bases in STANDARDS and HISTORY
v2: Split into two patches, add time bases to History section

 man/man3/timespec_get.3 | 49 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
index 67da4858c..4f0fe1a96 100644
--- a/man/man3/timespec_get.3
+++ b/man/man3/timespec_get.3
@@ -29,7 +29,10 @@ .SH SYNOPSIS
     _ISOC11_SOURCE
 .fi
 .P
-.BR timespec_getres ():
+.BR timespec_getres (),
+.BR TIME_MONOTONIC ,
+.BR TIME_ACTIVE ,
+.BR TIME_THREAD_ACTIVE :
 .nf
     _ISOC23_SOURCE
 .fi
@@ -67,6 +70,37 @@ .SH DESCRIPTION
 and
 .IR clock_getres(CLOCK_REALTIME,\~tp) ,
 respectively.
+.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
@@ -103,6 +137,12 @@ .SH STANDARDS
 POSIX.1-2024.
 .TP
 .BR timespec_getres ()
+.TQ
+.B TIME_MONOTONIC
+.TQ
+.B TIME_ACTIVE
+.TQ
+.B TIME_THREAD_ACTIVE
 C23.
 .SH HISTORY
 .TP
@@ -113,6 +153,13 @@ .SH HISTORY
 .TP
 .BR timespec_getres ()
 C23, glibc 2.34.
+.TP
+.B TIME_MONOTONIC
+.TQ
+.B TIME_ACTIVE
+.TQ
+.B TIME_THREAD_ACTIVE
+C23, glibc 2.43.
 .SH SEE ALSO
 .BR clock_gettime (2),
 .BR clock_getres (2)
-- 
2.52.0

Re: [PATCH v2 1/2] man/man3/timespec_get.3: Refactor to prepare for new time bases

[Mark Harris]

Alejandro Colomar wrote:
>
> Hi Mark,
>
> On 2026-01-28T09:33:03-0800, Mark Harris wrote:
> > Add Feature Test Macro Requirements to document functions and macros
> > that require ISO C11 or C23, and arrange supported time bases as a list.
> >
> > Signed-off-by: Mark Harris <mark.hsj@gmail.com>
> > ---
> > v2: Split into two patches, add time bases to History section
> >
> >  man/man3/timespec_get.3 | 32 ++++++++++++++++++++++++--------
> >  1 file changed, 24 insertions(+), 8 deletions(-)
>
> [...]
> > @@ -78,18 +96,16 @@ .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),
> >  POSIX.1-2024.
>
> How about this?:
>
>         .TP
>         .BR timespec_get ()
>         C23, POSIX.1-2024.
>         .TQ
>         .B TIME_UTC
>         C23 (though ISO C doesn't specify the time epoch),
>         POSIX.1-2024.

Ok.

>
> >  .TP
> >  .BR timespec_getres ()
> >  C23.
> >  .SH HISTORY
> >  .TP
> > -.BR timespec_get ()
> > -.TQ
> > -.B TIME_UTC
> > +.BR timespec_get "(), " TIME_UTC
>
> I prefer the format with TQ.  I wouldn't change anything in HISTORY.

Ok.

Changed in v3.

 - Mark

>
>
> Have a lovely day!
> Alex
>
> >  C11, POSIX.1-2024, glibc 2.16, musl 1.1.10.
> >  .TP
> >  .BR timespec_getres ()
> > --
> > 2.52.0
> >
>
> --
> <https://www.alejandro-colomar.es>

Re: [PATCH v3 1/2] man/man3/timespec_get.3: Refactor to prepare for new time bases

[Alejandro Colomar]

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

On 2026-01-29T08:52:23-0800, Mark Harris wrote:
> Add Feature Test Macro Requirements to document functions and macros
> that require ISO C11 or C23, and arrange supported time bases as a list.
> 
> Signed-off-by: Mark Harris <mark.hsj@gmail.com>

Patch applied; thanks!


Cheers,
Alex

> ---
> v3: Use .TQ for time bases in STANDARDS and HISTORY
> v2: Split into two patches, add time bases to History section
> 
>  man/man3/timespec_get.3 | 25 ++++++++++++++++++++++---
>  1 file changed, 22 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
> index 79bb82226..67da4858c 100644
> --- a/man/man3/timespec_get.3
> +++ b/man/man3/timespec_get.3
> @@ -17,6 +17,22 @@ .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 ():
> +.nf
> +    _ISOC23_SOURCE
> +.fi
>  .SH DESCRIPTION
>  The
>  .BR timespec_get ()
> @@ -39,16 +55,18 @@ .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
>  .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.
>  .SH RETURN VALUE
>  .BR timespec_get ()
>  returns the nonzero
> @@ -78,6 +96,7 @@ .SH ATTRIBUTES
>  .SH STANDARDS
>  .TP
>  .BR timespec_get ()
> +C23, POSIX.1-2024.
>  .TQ
>  .B TIME_UTC
>  C23 (though ISO C doesn't specify the time epoch),
> -- 
> 2.52.0
> 
> 

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

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

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

[Alejandro Colomar]

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

Hi Mark,

On 2026-01-29T08:52:24-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!  I've applied the patch.

> ---
> v3: Use .TQ for time bases in STANDARDS and HISTORY
> v2: Split into two patches, add time bases to History section
> 
>  man/man3/timespec_get.3 | 49 ++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 48 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
> index 67da4858c..4f0fe1a96 100644
> --- a/man/man3/timespec_get.3
> +++ b/man/man3/timespec_get.3
> @@ -29,7 +29,10 @@ .SH SYNOPSIS
>      _ISOC11_SOURCE
>  .fi
>  .P
> -.BR timespec_getres ():
> +.BR timespec_getres (),
> +.BR TIME_MONOTONIC ,
> +.BR TIME_ACTIVE ,
> +.BR TIME_THREAD_ACTIVE :
>  .nf
>      _ISOC23_SOURCE
>  .fi
> @@ -67,6 +70,37 @@ .SH DESCRIPTION
>  and
>  .IR clock_getres(CLOCK_REALTIME,\~tp) ,
>  respectively.
> +.TP
> +.BR TIME_MONOTONIC " (since glibc 2.43)"

I've removed the "(since..." part, as it's redundant with HISTORY, and
I prefer the HISTORY section.


Have a lovely night!
Alex

> +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
> @@ -103,6 +137,12 @@ .SH STANDARDS
>  POSIX.1-2024.
>  .TP
>  .BR timespec_getres ()
> +.TQ
> +.B TIME_MONOTONIC
> +.TQ
> +.B TIME_ACTIVE
> +.TQ
> +.B TIME_THREAD_ACTIVE
>  C23.
>  .SH HISTORY
>  .TP
> @@ -113,6 +153,13 @@ .SH HISTORY
>  .TP
>  .BR timespec_getres ()
>  C23, glibc 2.34.
> +.TP
> +.B TIME_MONOTONIC
> +.TQ
> +.B TIME_ACTIVE
> +.TQ
> +.B TIME_THREAD_ACTIVE
> +C23, glibc 2.43.
>  .SH SEE ALSO
>  .BR clock_gettime (2),
>  .BR clock_getres (2)
> -- 
> 2.52.0
> 
> 

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

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