Hi Ahelenia,
On Thu, Sep 05, 2024 at 01:41:58PM GMT, Ahelenia Ziemiańska wrote:
> If you're wondering how errno is affected, so am I; no-one really says;
> quoth POSIX:
> If base is TIME_UTC, the members of ts shall be set to the same values as would be set by a call
> to clock_gettime(CLOCK_REALTIME, ts).
>
> RETURN VALUE
> If the timespec_get( ) function is successful it shall return the non-zero value base; otherwise, it
> shall return zero.
>
> ERRORS
> See DESCRIPTION.
>
> But this is a moot point since clock_gettime() can't fail anyway
> (glibc doesn't even check the error).
I see at least the following errors in clock_gettime(2):
EFAULT
tp points outside the accessible address space.
EINVAL
The clockid specified is invalid for one of two reasons.
Either the System‐V style hard coded positive value is out
of range, or the dynamic clock ID does not refer to a valid
instance of a clock object.
EINVAL
The clockid specified in a call to clock_settime() is not a
settable clock.
ENODEV
The hot‐pluggable device (like USB for example) represented
by a dynamic clk_id has disappeared after its character de‐
vice was opened.
ENOTSUP
The operation is not supported by the dynamic POSIX clock
device specified.
EOVERFLOW
The timestamp would not fit in time_t range. This can hap‐
pen if an executable with 32‐bit time_t is run on a 64‐bit
kernel when the time is 2038‐01‐19 03:14:08 UTC or later.
However, when the system time is out of time_t range in
other situations, the behavior is undefined.
>
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@xxxxxxxxxxxxxxxxxx>
> ---
> man/man3/timespec_get.3 | 82 +++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 82 insertions(+)
> create mode 100644 man/man3/timespec_get.3
>
> diff --git a/man/man3/timespec_get.3 b/man/man3/timespec_get.3
> new file mode 100644
> index 000000000..5e053d551
> --- /dev/null
> +++ b/man/man3/timespec_get.3
> @@ -0,0 +1,82 @@
> +'\" t
> +.\" SPDX-License-Identifier: 0BSD
> +.\"
> +.TH timespec_get 3 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +timespec_get, timespec_getres \- standard C clock and time functions
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc ),
> +.SH SYNOPSIS
> +.nf
> +.B #include <time.h>
> +.P
> +.BI "int timespec_get(struct timespec *" res ", int " base );
> +.BI "int timespec_getres(struct timespec *" tp ", int " base );
> +.fi
> +.P
> +.RS -4
> +Feature Test Macro Requirements for glibc (see
> +.BR feature_test_macros (7)):
> +.RE
> +.P
> +.BR timespec_get ():
> +.nf
> + _ISOC11_SOURCE || _ISOC2X_SOURCE
> + || __STDC_VERSION__ >= 201112L
> + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
> +.P
> +.BR timespec_getres ():
> +.nf
> + _ISOC2X_SOURCE || __STDC_VERSION__ > 201710L
> +.fi
> +.SH DESCRIPTION
> +.BI timespec_get\fR(\fP tp ", TIME_UTC)"
This should be fully italics (inline code).
> +is defined as
> +.BI "clock_gettime\fR(\fPCLOCK_REALTIME, " tp )\fR.\fP
Same here: fully italics, since it's inline code.
> +.P
> +.BI timespec_getres\fR(\fP res ", TIME_UTC)"
> +is equivalent to
> +.BI "timespec_getres\fR(\fPCLOCK_REALTIME, " res )\fR.\fP
> +.P
> +.BR TIME_UTC
> +is universally guaranteed to be a valid
> +.IR base ,
> +and is the only one supported under Linux.
> +.SH RETURN VALUE
> +.B 0
> +if base is unsupported or the call failed, otherwise
> +.IR base .
> +.SH ATTRIBUTES
> +For an explanation of the terms used in this section, see
> +.BR attributes (7).
> +.TS
> +allbox;
> +lbx lb lb
> +l l l.
> +Interface Attribute Value
> +T{
> +.na
> +.nh
> +.BR timespec_get (),
> +.BR timespec_getres ()
> +T} Thread safety MT-Safe
> +.TE
> +.SH STANDARDS
> +.BR timespec_get (),
> +.BR TIME_UTC :
> +C23, POSIX.1-2024.
> +.br
> +.BR timespec_getres ():
> +C23.
> +.br
I prefer:
.TP
.BR timespec_get ()
.TQ
.B TIME_UTC
C23,
POSIX.1-2024.
.TP
.BR timespec_getres ()
C23.
Have a lovely night!
Alex
> +.SH HISTORY
> +.BR timespec_get (),
> +.BR TIME_UTC :
> +C11, POSIX.1-2024, glibc 2.16, musl 1.1.10.
> +.br
> +.BR timespec_getres ():
> +C23, glibc 2.34.
> +.SH SEE ALSO
> +.BR clock_gettime (2),
> +.BR clock_getres (2)
> --
> 2.39.2
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
