Hi Mark, On Sat, Feb 08, 2025 at 12:41:42PM -0800, Mark Harris wrote: > - 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). LGTM. C23 7.19.2.6p4 says If the timespec_get function is successful it returns the nonzero value base; otherwise, it returns zero. > - 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). LGTM. The paragraph quoted above confirms this. > - Clarify that timespec_getres(NULL, base) is a valid call to check > whether the specified time base is supported (C23 7.29.2.7). LGTM. > - 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). LGTM. C23 7.19.2.7p2 says For each supported base, multiple calls to the timespec_getres function during the same program execution shall have identical results. > - Calls to these functions are not technically equivalent to any > clock_* function call; at least the return value will be different. It would be interesting to clarify if they are equivalent except for the return value. > - 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). LGTM. > Signed-off-by: Mark Harris <mark.hsj@xxxxxxxxx> Please add appropriate tags: Fixes: 7bda5119fe5e (2024-09-08; "timespec_get.3, timespec_getres.3: Add page and link page") Cc: наб <nabijaczleweli@xxxxxxxxxxxxxxxxxx> > --- > 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 I would say .BR timespec (3type) structure We usually say XXX structure in the manual pages, instead of struct XXX. Just for consistency, I'd follow that. > +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. LGTM. > .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 Maybe s/is/are/ and s/that/those/? > +.I clock_gettime(CLOCK_REALTIME, res) > +and > +.IR "clock_getres(CLOCK_REALTIME, tp)" , I'd use a non-breaking space: .I clock_gettime(CLOCK_REALTIME,\~res) and .IR clock_getres(CLOCK_REALTIME,\~tp) , > +respectively. > +Other systems may support additional time bases. LGTM. > .SH RETURN VALUE > -On success, > +.BR timespec_get () > +returns the nonzero value I think I'd remove "value". What do you think? > +.I base > +if it represents a supported time base > +and the current time was successfully retrieved, or 0 otherwise. D'oh. Someone designed another non-standard return value. <facepalm/> Have a lovely night! Alex > +.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 > -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
