[PATCH v3] manual: Document clock_nanosleep

[Arjun Shankar]

This commit makes minor clarifications in the documentation for
`nanosleep' and adds an entry for `clock_nanosleep' as a generalized
variant of it that allows clock selection.
---
v2: https://sourceware.org/pipermail/libc-alpha/2025-May/166879.html
Florian's review: https://sourceware.org/pipermail/libc-alpha/2025-May/166880.html
Changes in v3:
 * Address Florian's review comments, dropping a misleading comment and
   referring to the canonical list of clockid_t values instead of having an
   incomplete/duplicate list.
---
 manual/time.texi | 59 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 49 insertions(+), 10 deletions(-)

diff --git a/manual/time.texi b/manual/time.texi
index 7697b6ba48..09cba58530 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -3180,12 +3180,12 @@ On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in
 the same program, because @code{sleep} does not work by means of
 @code{SIGALRM}.
 
-@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
+@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time})
 @standards{POSIX.1, time.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c On Linux, it's a syscall.  On Mach, it calls gettimeofday and uses
 @c ports.
-If resolution to seconds is not enough the @code{nanosleep} function can
+If resolution to seconds is not enough, the @code{nanosleep} function can
 be used.  As the name suggests the sleep interval can be specified in
 nanoseconds.  The actual elapsed time of the sleep interval might be
 longer since the system rounds the elapsed time you request up to the
@@ -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
+If @var{remaining_time} is not the null pointer,
+@code{*@var{remaining_time}} is used by the function to return 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.
 
 @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}
+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:
 
 @table @code
 @item EINTR
 The call was interrupted because a signal was delivered to the thread.
-If the @var{remaining} parameter is not the null pointer the structure
-pointed to by @var{remaining} is updated to contain the remaining
+If the @var{remaining_time} parameter is not the null pointer, the structure
+pointed to by @var{remaining_time} is updated to contain the remaining
 elapsed time.
 
 @item EINVAL
@@ -3220,10 +3221,48 @@ illegal value.  Either the value is negative or greater than or equal to
 This function is a cancellation point in multi-threaded programs.  This
 is a problem if the thread allocates some resources (like memory, file
 descriptors, semaphores or whatever) at the time @code{nanosleep} is
-called.  If the thread gets canceled these resources stay allocated
-until the program ends.  To avoid this calls to @code{nanosleep} should
+called.  If the thread gets canceled, these resources stay allocated
+until the program ends.  To avoid this, calls to @code{nanosleep} should
 be protected using cancellation handlers.
 @c ref pthread_cleanup_push / pthread_cleanup_pop
 
 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.  Calling
+@samp{nanosleep (@var{requested_time}, @var{remaining_time})} is equivalent
+to: @samp{clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time},
+@var{remaining_time})}.
+
+The argument @var{clock} is used to specify the clock to be used.  The
+@code{clockid_t} type and possible values of @var{clock} defined by POSIX
+are described in @ref{Getting the Time}.
+
+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}
+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.  When @var{flags} is
+@code{TIMER_ABSTIME}, @var{remaining_time} is not updated.
+
+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 EOPNOTSUPP
+The @var{clock} argument is not supported by the kernel for
+@code{clock_nanosleep}.
+@end table
+
+The @code{clock_nanosleep} function is declared in @file{time.h}.
+@end deftypefun
-- 
2.49.0