- 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@xxxxxxxxxxxxxxxxxx>
Signed-off-by: Mark Harris <mark.hsj@xxxxxxxxx>
---
man/man3/timespec_get.3 | 63 ++++++++++++++++++++++++-----------------
1 file changed, 37 insertions(+), 26 deletions(-)
diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
index 8c8d45d33..ecac06d99 100644
--- a/man/man3/timespec_get.3
+++ b/man/man3/timespec_get.3
@@ -18,37 +18,48 @@ .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
+.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).
Range-diff against v1:
1: c6990f9c9 ! 1: 5f8dc5d2d man/man3/timespec_get.3: Correct return value and clarify description
@@ Commit message
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@xxxxxxxxxxxxxxxxxx>
Signed-off-by: Mark Harris <mark.hsj@xxxxxxxxx>
## man/man3/timespec_get.3 ##
@@ man/man3/timespec_get.3: .SH SYNOPSIS
+The
+.BR timespec_get ()
+function stores the current time, based on the specified time base, in the
-+.I struct timespec
-+pointed to by
++.BR timespec (3type)
++structure pointed to by
+.IR res .
.P
-.I timespec_getres(res, TIME_UTC)
@@ man/man3/timespec_get.3: .SH SYNOPSIS
+function stores the resolution of times retrieved by
+.BR timespec_get ()
+with the specified time base in the
-+.I struct timespec
-+pointed to by
++.BR timespec (3type)
++structure pointed to by
+.IR tp ,
+if
+.I tp
@@ man/man3/timespec_get.3: .SH SYNOPSIS
-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)
++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)" ,
++.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
++returns the nonzero
+.I base
-+if it represents a supported time 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 value
++returns the nonzero
.I base
-is returned.
-On error,
@@ man/man3/timespec_get.3: .SH SYNOPSIS
-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.
++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).
--
2.48.0
