manual: Document clock_nanosleep
Checks
| Context |
Check |
Description |
| redhat-pt-bot/TryBot-apply_patch |
success
|
Patch applied to master at the time it was sent
|
| linaro-tcwg-bot/tcwg_glibc_build--master-arm |
success
|
Build passed
|
| redhat-pt-bot/TryBot-32bit |
success
|
Build for i686
|
| linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_glibc_check--master-arm |
success
|
Test passed
|
| linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 |
success
|
Test passed
|
Commit Message
---
manual/time.texi | 56 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 56 insertions(+)
Comments
Hi Arjun,
Thank you for your submission. Please find a couple of issues noted
below.
On Tue, 14 Jan 2025, Arjun Shankar wrote:
> ---
> manual/time.texi | 56 ++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 56 insertions(+)
Please add a commit description with a summary of the changes made.
> diff --git a/manual/time.texi b/manual/time.texi
> index 90bc9a2566..830a09ad9d 100644
> --- a/manual/time.texi
> +++ b/manual/time.texi
> @@ -3195,3 +3195,59 @@ be protected using cancellation handlers.
>
> The @code{nanosleep} function is declared in @file{time.h}.
> @end deftypefun
> +
> +@deftypefun int clock_nanosleep (clockid_t @var{clock}, int @var{flags}, const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
It's a preexisting problem with `nanosleep', but I think with both
functions `remaining' ought to be called `remaining_time' for consistency
with `requested_time' (internally we call the parameters `req' and `rem'
anyway).
> +@standards{POSIX.1-2001, time.h}
> +@c This function is a syscall on Linux
Missing full stop.
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +This function is like @code{nanosleep}, except that it allows the caller to
> +specify the clock to be used to measure elapsed time and supports specifying
> +the sleep interval in absolute or relative terms.
I find "function is like" sounding vague and colloquial. How about:
"
This function is a generalized variant of @code{nanosleep}, providing the
caller with a way to specify the clock to be used to measure elapsed time
and express the sleep interval in absolute or relative terms.
"
?
> The argument @code{clock}
> +is used to specify the clock to be used and supports the following values on
> +Linux:
It has to be @var{clock} rather than @code{clock} as used with function
argument names.
> +
> +@table @code
> +@item CLOCK_REALTIME
> +A system-wide clock that measures wall-clock time.
> +
> +@item CLOCK_TAI
> +A system-wide clock derived from wall-clock time that accounts for leap
> +seconds.
> +
> +@item CLOCK_MONOTONIC
> +
> +A system-wide clock that represents monotonically non-decreasing time. This
> +clock is not affected by discontinuous jumps in system time and is
> +guaranteed to not go backwards on consecutive calls. However, it does not
> +count time for which the system is suspended.
> +
> +@item CLOCK_BOOTTIME
> +A system-wide clock that is identical to CLOCK_MONOTONIC except that it also
Missing @code{} around CLOCK_MONOTONIC.
> +counts time for which the system is suspended.
> +
> +@item CLOCK_PROCESS_CPUTIME_ID
> +A clock that measures CPU time consumed by all threads in the calling
> +process.
> +@end table
> +
> +The @code{flags} argument is either @code{0} or @code{TIMER_ABSTIME}. If
> +@code{flags} is @code{0}, then @code{clock_nanosleep} interprets
> +@code{requested_time} as an interval relative to the current time specified
> +by @code{clock}.
Similarly @var{flags}, @var{requested_time} rather than @code{flags},
@code{requested_time}.
I think this:
> If it is @code{TIMER_ABSTIME} instead,
> +@code{requested_time} is interpreted as an absolute time measured by
> +@code{clock}.
is worth clarification, so how about (also using @var{} where needed):
"
If it is @code{TIMER_ABSTIME} instead, @var{requested_time} is
interpreted as an absolute time measured by @var{clock}; if at the time
of the call the value requested is less than or equal to the clock
specified, then the function returns right away.
"
? Or is it not the case (in which case we'd not be POSIX-compliant here;
please note that there is no such requirement for !TIMER_ABSTIME calls
and zero interval requested)?
Also there's a note missing on `remaining' *not* ever being updated in
the TIMER_ABSTIME case, so please add one, and neither your description
nor the original one for `nanosleep' says NULL is valid for `remaining'.
> +
> +Compared to @code{nanosleep}, the following additional error conditions can
> +occur:
> +
> +@table @code
> +@item EINVAL
> +The @var{clock} argument is not a valid clock.
> +
> +@item ENOTSUP
> +The @var{clock} argument is not supported by the kernel.
We prefer spelling this error as EOPNOTSUPP (there's no ENOTSUP on Linux
and we alias it by hand; this is allowed by POSIX).
Also I find the description misleading, it seems synonymous to one
immediately above. How about:
"
@item EOPNOTSUPP
The @var{clock} argument is not supported by the kernel for
@code{clock_nanosleep}.
"
?
> +
> +@item EPERM
> +This process does not have permission to use this @code{clock}.
Where is this error coming from, I seem unable to find it anywhere?
> +@end table
> +@end deftypefun
There's a reference missing for EOVERFLOW with either function (EFAULT
may also be returned, but our convention is not to mention it).
And then here to wrap up and summarise the reference to `nanosleep' at
the beginning:
"
Calling @samp{nanosleep (@var{requested_time}, @var{remaining})} is
equivalent to: @samp{clock_nanosleep (CLOCK_REALTIME, 0,
@var{requested_time}, @var{remaining})}.
"
or suchlike (please double-check rendering, but I'm fairly sure I got it
right)?
Please also add a reference to the relevant header such as with the other
functions, i.e.:
"The @code{clock_nanosleep} function is declared in @file{time.h}."
FWIW I find it easier to catch wrong use of Texinfo commands with the PDF
rendering of the manual.
Please send an updated version with the changes requested applied, or
come back to me if you have any questions or concerns.
Maciej
@@ -3195,3 +3195,59 @@ be protected using cancellation handlers.
The @code{nanosleep} function is declared in @file{time.h}.
@end deftypefun
+
+@deftypefun int clock_nanosleep (clockid_t @var{clock}, int @var{flags}, const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
+@standards{POSIX.1-2001, time.h}
+@c This function is a syscall on Linux
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is like @code{nanosleep}, except that it allows the caller to
+specify the clock to be used to measure elapsed time and supports specifying
+the sleep interval in absolute or relative terms. The argument @code{clock}
+is used to specify the clock to be used and supports the following values on
+Linux:
+
+@table @code
+@item CLOCK_REALTIME
+A system-wide clock that measures wall-clock time.
+
+@item CLOCK_TAI
+A system-wide clock derived from wall-clock time that accounts for leap
+seconds.
+
+@item CLOCK_MONOTONIC
+
+A system-wide clock that represents monotonically non-decreasing time. This
+clock is not affected by discontinuous jumps in system time and is
+guaranteed to not go backwards on consecutive calls. However, it does not
+count time for which the system is suspended.
+
+@item CLOCK_BOOTTIME
+A system-wide clock that is identical to CLOCK_MONOTONIC except that it also
+counts time for which the system is suspended.
+
+@item CLOCK_PROCESS_CPUTIME_ID
+A clock that measures CPU time consumed by all threads in the calling
+process.
+@end table
+
+The @code{flags} argument is either @code{0} or @code{TIMER_ABSTIME}. If
+@code{flags} is @code{0}, then @code{clock_nanosleep} interprets
+@code{requested_time} as an interval relative to the current time specified
+by @code{clock}. If it is @code{TIMER_ABSTIME} instead,
+@code{requested_time} is interpreted as an absolute time measured by
+@code{clock}.
+
+Compared to @code{nanosleep}, the following additional error conditions can
+occur:
+
+@table @code
+@item EINVAL
+The @var{clock} argument is not a valid clock.
+
+@item ENOTSUP
+The @var{clock} argument is not supported by the kernel.
+
+@item EPERM
+This process does not have permission to use this @code{clock}.
+@end table
+@end deftypefun