[PATCH v5] manual: Document clock_nanosleep

[Maciej W. Rozycki]

On Fri, 30 May 2025, Arjun Shankar wrote:

> Make minor clarifications in the documentation for 'nanosleep' and add
> an entry for 'clock_nanosleep' as a generalized variant of the former
> function that allows clock selection.
> ---

 OK.

> diff --git a/manual/time.texi b/manual/time.texi
> index 7697b6ba48..7afcaf75cc 100644
> --- a/manual/time.texi
> +++ b/manual/time.texi
> @@ -3194,21 +3194,22 @@ next integer multiple of the actual resolution the system can deliver.
>  @code{*@var{requested_time}} is the elapsed time of the interval you
>  want to sleep.
>  
> -The function returns as @code{*@var{remaining}} the elapsed time left
> -in the interval for which you requested to sleep.  If the interval
> -completed without getting interrupted by a signal, this is zero.
> +If @var{remaining_time} is not the null pointer, the function returns as
> +@code{*@var{remaining_time}} the elapsed time left in the interval for which
> +you requested to sleep.  If the interval completed without getting
> +interrupted by a signal, this is zero.

 OK.

>  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_time})
> +@standards{POSIX.1-2001, time.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +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 call:
> +
> +@smallexample
> +nanosleep (@var{requested_time}, @var{remaining_time})
> +@end smallexample
> +
> +is equivalent to:
> +
> +@smallexample
> +clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time}, @var{remaining_time})
> +@end smallexample

 OK.

> +
> +The @var{clock} argument specifies the clock to use.
> +@xref{Getting the Time}, for the @code{clockid_t} type and possible values
> +of @var{clock}.  Not all clocks listed are supported for use with
> +@code{clock_nanosleep}.  For details, see the manual page
> +@manpageurl{clock_nanosleep,2}.

 OK.  You could've justified the paragraph such that the line break is in 
the middle of @xref just as I did (and the whole paragraph would then line 
up more nicely in the source form), but I'm not going to insist (OK if you 
choose to after all at the commit push time too).

> +
> +The @var{flags} argument is either @code{0} or @code{TIMER_ABSTIME}.  If
> +@var{flags} is @code{0}, then @code{clock_nanosleep} interprets
> +@var{requested_time} as an interval relative to the current time specified
> +by @var{clock}.  If it is @code{TIMER_ABSTIME} instead, @var{requested_time}
> +specifies 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.  When @var{flags} is @code{TIMER_ABSTIME},
> +@var{remaining_time} is not updated.

 OK.

> +
> +The return values and error conditions for @code{clock_nanosleep} are the
> +same as for @code{nanosleep}, with the following conditions additionally
> +defined:

 OK.

 I've left out parts acked previously.

Reviewed-by: Maciej W. Rozycki <macro@redhat.com>

 Thank you for your contribution.

  Maciej