[PATCH v2] manual: Correct return value description of 'clock_nanosleep'

[Mark Harris]

Arjun Shankar <arjun@redhat.com> wrote:
>
> Commit 1a3d8f2201d4d613401ce5be9a283f4f28c43093 incorrectly described
> 'clock_nanosleep' as having the same return values as 'nanosleep'.  Fix
> this, clarifying that 'clock_nanosleep' returns a positive error number
> upon failure instead of setting 'errno'.  Also clarify that 'nanosleep'
> returns '-1' upon error.
>
> Fixes: 1a3d8f2201d4d613401ce5be9a283f4f28c43093
> Reported-by: Mark Harris <mark.hsj@gmail.com>
> ---
> v1: https://sourceware.org/pipermail/libc-alpha/2025-June/167149.html
> Changes in v2: incorporate Florian's suggestion:
>   https://sourceware.org/pipermail/libc-alpha/2025-June/167151.html
> ---
>  manual/time.texi | 33 ++++++++++++++-------------------
>  1 file changed, 14 insertions(+), 19 deletions(-)
>
> diff --git a/manual/time.texi b/manual/time.texi
> index cbe9f00e17..697a6287f2 100644
> --- a/manual/time.texi
> +++ b/manual/time.texi
> @@ -3201,9 +3201,9 @@ interrupted by a signal, this is zero.
>
>  @code{struct timespec} is described in @ref{Time Types}.
>
> -If the function returns because the interval is over, the return value is
> -zero.  If the function returns @math{-1}, the global variable @code{errno}
> -is set to the following values:
> +If the function returns because the interval is over, it returns zero.
> +Otherwise it returns @math{-1} and sets the global variable @code{errno} to
> +one of the following values:

Ok.

>
>  @table @code
>  @item EINTR
> @@ -3232,19 +3232,14 @@ The @code{nanosleep} function is declared in @file{time.h}.
>  @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
> +This function is similar to @code{nanosleep} while additionally 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.  It
> +returns zero when returning because the interval is over, and a positive
> +error number corresponding to the error encountered otherwise.  This is
> +different from @code{nanosleep}, which returns @math{-1} upon failure and
> +sets the global variable @code{errno} according to the error encountered
> +instead.

Ok.

>
>  The @var{clock} argument specifies the clock to use.
>  @xref{Getting the Time}, for the @code{clockid_t} type and possible values
> @@ -3261,9 +3256,9 @@ 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.
>
> -The return values and error conditions for @code{clock_nanosleep} are the
> -same as for @code{nanosleep}, with the following conditions additionally
> -defined:
> +The @code{clock_nanosleep} function returns error codes as positive return
> +values.  The error conditions for @code{clock_nanosleep} are the same as for
> +@code{nanosleep}, with the following conditions additionally defined:

Ok.

>
>  @table @code
>  @item EINVAL
> --
> 2.49.0
>

Reviewed-by: Mark Harris <mark.hsj@gmail.com>


 - Mark