122 lines
5.6 KiB
Diff
122 lines
5.6 KiB
Diff
commit 1a3d8f2201d4d613401ce5be9a283f4f28c43093
|
|
Author: Arjun Shankar <arjun@redhat.com>
|
|
Date: Fri May 30 02:09:50 2025 +0200
|
|
|
|
manual: Document clock_nanosleep
|
|
|
|
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.
|
|
Reviewed-by: Maciej W. Rozycki <macro@redhat.com>
|
|
|
|
diff --git a/manual/time.texi b/manual/time.texi
|
|
index 6b2d133f8e3080f3..2df54a1b28c72ffe 100644
|
|
--- a/manual/time.texi
|
|
+++ b/manual/time.texi
|
|
@@ -3179,12 +3179,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
|
|
@@ -3193,21 +3193,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.
|
|
|
|
@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
|
|
@@ -3219,10 +3220,58 @@ invalid 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. 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
|
|
+
|
|
+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 return values and 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
|