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: наб <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Mark Harris <mark.hsj@gmail.com>
Message-ID: <5f8dc5d2dc51f080a18de53e98610df43389b98b.1739063937.git.mark.hsj@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
index 8c8d45d336d41ae0587718fbcc42c9ac5c63907a..95a1833e1a6a67ed77bb9b0a01c1744e407ad80b 100644 (file)
--- 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).