1 files changed, 102 insertions, 15 deletions
diff --git a/manual/time.texi b/manual/time.texi
index 04c97f5..d003ddb 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -148,7 +148,8 @@ and pass them to the functions that convert them to broken-down time
 On POSIX-conformant systems, @code{time_t} is an integer type and its
 values represent the number of seconds elapsed since the @dfn{POSIX Epoch},
 which is January 1, 1970, at 00:00:00 Coordinated Universal Time (UTC)@.
-The count of seconds ignores leap seconds.
+The count of seconds ignores leap seconds.  Additionally, POSIX.1-2024
+added the requirement that @code{time_t} be at least 64 bits wide.
 
 @Theglibc{} additionally guarantees that @code{time_t} is a signed
 type, and that all of its functions operate correctly on negative
@@ -528,7 +529,36 @@ Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure
 absolute time, only elapsed time.
 @end deftypevr
 
-Systems may support more than just these two POSIX clocks.
+The following clocks are defined by POSIX, but may not be supported by
+all POSIX systems:
+
+@deftypevr Macro clockid_t CLOCK_PROCESS_CPUTIME_ID
+@standards{POSIX.1, time.h}
+This POSIX clock measures the amount of CPU time used by the calling
+process.
+@end deftypevr
+
+@deftypevr Macro clockid_t CLOCK_THREAD_CPUTIME_ID
+@standards{POSIX.1, time.h}
+This POSIX clock measures the amount of CPU time used by the calling
+thread.
+@end deftypevr
+
+The following clocks are Linux extensions:
+
+@deftypevr Macro clockid_t CLOCK_MONOTONIC_RAW
+@deftypevrx Macro clockid_t CLOCK_REALTIME_COARSE
+@deftypevrx Macro clockid_t CLOCK_MONOTONIC_COARSE
+@deftypevrx Macro clockid_t CLOCK_BOOTTIME
+@deftypevrx Macro clockid_t CLOCK_REALTIME_ALARM
+@deftypevrx Macro clockid_t CLOCK_BOOTTIME_ALARM
+@deftypevrx Macro clockid_t CLOCK_TAI
+@standards{Linux, time.h}
+For details of these clocks, see the manual page
+@manpageurl{clock_gettime,2}.
+@end deftypevr
+
+Systems may support additional clocks beyond those listed here.
 
 @deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts})
 @standards{POSIX.1, time.h}
@@ -3150,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
@@ -3164,36 +3194,93 @@ 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.
 
 @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:
 
 @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
 The nanosecond value in the @var{requested_time} parameter contains an
-illegal value.  Either the value is negative or greater than or equal to
+invalid value.  Either the value is negative or greater than or equal to
 1000 million.
 @end table
 
 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 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.
+
+Except for the return value convention and the way to communicate an error
+condition the call:
+
+@smallexample
+nanosleep (@var{requested_time}, @var{remaining_time})
+@end smallexample
+
+is analogous to:
+
+@smallexample
+clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time}, @var{remaining_time})
+@end smallexample
+
+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}.
+
+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.
+
+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:
+
+@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