- 0, not -1, is returned for an unsupported time base or error (C23 7.29.2.6, 7.29.2.7; POSIX.1-2024 line 74358). - Clarify that any supported value of base is always nonzero (i.e., there is no overlap between the two return value cases that may require errno or some other source to disambiguate) (C23 7.29.2.6, 7.29.2.7; POSIX.1-2024 line 74357). - Clarify that timespec_getres(NULL, base) is a valid call to check whether the specified time base is supported (C23 7.29.2.7). - Clarify that the resolution for a particular time base is constant for the lifetime of the process (i.e., there is no need to retrieve it repeatedly) (C23 7.29.2.7). - Calls to these functions are not technically equivalent to any clock_* function call; at least the return value will be different. - The ERRORS section is removed, because it states only what is true for every function that does not state otherwise (i.e., errno might be affected by underlying system calls). Signed-off-by: Mark Harris <mark.hsj@xxxxxxxxx> --- man/man3/timespec_get.3 | 62 ++++++++++++++++++++++++----------------- 1 file changed, 36 insertions(+), 26 deletions(-) diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3 index 8c8d45d33..7993e138a 100644 --- a/man/man3/timespec_get.3 +++ b/man/man3/timespec_get.3 @@ -18,37 +18,47 @@ .SH SYNOPSIS .BI "int timespec_getres(struct timespec *" tp ", int " base ); .fi .SH DESCRIPTION -.I timespec_get(tp, TIME_UTC) -is defined as -.IR "clock_gettime(CLOCK_REALTIME, tp)" . +The +.BR timespec_get () +function stores the current time, based on the specified time base, in the +.I struct timespec +pointed to by +.IR res . .P -.I timespec_getres(res, TIME_UTC) -is equivalent to -.IR "clock_getres(CLOCK_REALTIME, res)" . +The +.BR timespec_getres () +function stores the resolution of times retrieved by +.BR timespec_get () +with the specified time base in the +.I struct timespec +pointed to by +.IR tp , +if +.I tp +is non-NULL. +For a particular time base, +the resolution is constant for the lifetime of the calling process. .P .B TIME_UTC -is universally guaranteed to be a valid -.IR base , -and is the only one supported under Linux. -Some other systems support different time bases. +is always a supported time base, +and is the only time base supported on Linux. +The time and resolution in this time base is the same as that 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 -On success, +.BR timespec_get () +returns the nonzero value +.I base +if it represents a supported time base +and the current time was successfully retrieved, or 0 otherwise. +.P +.BR timespec_getres () +returns the nonzero value .I base -is returned. -On error, -\-1 is returned. -.SH ERRORS -Some C libraries -.I may -set -.I errno -to the same value as would be set by -.BR clock_gettime (2) -or -.BR clock_getres (2). -Neither C nor POSIX specify this, -but they don't really indicate it shouldn't happen, either. -Don't rely on this. +if it represents a supported time base, or 0 otherwise. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7). -- 2.48.0
