| Message ID | 20250114193219.378409-1-arjun@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | manual: Document clock_nanosleep | expand |
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
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}) +@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