From: Mark Harris Date: Sun, 9 Feb 2025 01:24:14 +0000 (-0800) Subject: man/man3/timespec_get.3: Correct return value and clarify description X-Git-Tag: man-pages-6.11~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=185d0530f8450fb4c9588b451b3674c2dae9862c;p=thirdparty%2Fman-pages.git man/man3/timespec_get.3: Correct return value and clarify description - 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. Clarify that it is the time and resolution that are the same. - 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). Fixes: 7bda5119fe5e (2024-09-08; "timespec_get.3, timespec_getres.3: Add page and link page") Cc: наб Signed-off-by: Mark Harris Message-ID: <5f8dc5d2dc51f080a18de53e98610df43389b98b.1739063937.git.mark.hsj@gmail.com> Signed-off-by: Alejandro Colomar --- diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3 index 8c8d45d33..95a1833e1 100644 --- a/man/man3/timespec_get.3 +++ b/man/man3/timespec_get.3 @@ -18,37 +18,48 @@ Standard C library .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 +.BR timespec (3type) +structure 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 +.BR timespec (3type) +structure 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 +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 -On success, +.BR timespec_get () +returns the nonzero +.I base +if it is a supported time base +and the current time was successfully retrieved, or 0 otherwise. +.P +.BR timespec_getres () +returns the nonzero .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 is a supported time base, or 0 otherwise. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).