diff options
Diffstat (limited to 'man2/clock_nanosleep.2')
| -rw-r--r-- | man2/clock_nanosleep.2 | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2 new file mode 100644 index 0000000..d1e53a6 --- /dev/null +++ b/man2/clock_nanosleep.2 @@ -0,0 +1,253 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH clock_nanosleep 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +clock_nanosleep \- high-resolution sleep with specifiable clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ), +since glibc 2.17 +.PP +Before glibc 2.17, +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.B #include <time.h> +.nf +.PP +.BI "int clock_nanosleep(clockid_t " clockid ", int " flags , +.BI " const struct timespec *" request , +.BI " struct timespec *_Nullable " remain ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR clock_nanosleep (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +Like +.BR nanosleep (2), +.BR clock_nanosleep () +allows the calling thread to sleep for an interval specified +with nanosecond precision. +It differs in allowing the caller to select the clock against +which the sleep interval is to be measured, +and in allowing the sleep interval to be specified as +either an absolute or a relative value. +.PP +The time values passed to and returned by this call are specified using +.BR timespec (3) +structures. +.PP +The +.I clockid +argument specifies the clock against which the sleep interval +is to be measured. +This argument can have one of the following values: +.\" Look in time/posix-timers.c (kernel 5.6 sources) for the +.\" 'struct k_clock' structures that have an 'nsleep' method +.TP +.B CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.BR CLOCK_TAI " (since Linux 3.10)" +A system-wide clock derived from wall-clock time but ignoring leap seconds. +.TP +.B CLOCK_MONOTONIC +A nonsettable, monotonically increasing clock that measures time +since some unspecified point in the past that does not change after +system startup. +.\" On Linux this clock measures time since boot. +.TP +.BR CLOCK_BOOTTIME " (since Linux 2.6.39)" +Identical to +.BR CLOCK_MONOTONIC , +except that it also includes any time that the system is suspended. +.TP +.B CLOCK_PROCESS_CPUTIME_ID +A settable per-process clock that measures CPU time consumed +by all threads in the process. +.\" There is some trickery between glibc and the kernel +.\" to deal with the CLOCK_PROCESS_CPUTIME_ID case. +.PP +See +.BR clock_getres (2) +for further details on these clocks. +In addition, the CPU clock IDs returned by +.BR clock_getcpuclockid (3) +and +.BR pthread_getcpuclockid (3) +can also be passed in +.IR clockid . +.\" Sleeping against CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM +.\" is also possible (tested), with CAP_WAKE_ALARM, but I'm not +.\" sure if this is useful or needs to be documented. +.PP +If +.I flags +is 0, then the value specified in +.I request +is interpreted as an interval relative to the current +value of the clock specified by +.IR clockid . +.PP +If +.I flags +is +.BR TIMER_ABSTIME , +then +.I request +is interpreted as an absolute time as measured by the clock, +.IR clockid . +If +.I request +is less than or equal to the current value of the clock, +then +.BR clock_nanosleep () +returns immediately without suspending the calling thread. +.PP +.BR clock_nanosleep () +suspends the execution of the calling thread +until either at least the time specified by +.I request +has elapsed, +or a signal is delivered that causes a signal handler to be called or +that terminates the process. +.PP +If the call is interrupted by a signal handler, +.BR clock_nanosleep () +fails with the error +.BR EINTR . +In addition, if +.I remain +is not NULL, and +.I flags +was not +.BR TIMER_ABSTIME , +it returns the remaining unslept time in +.IR remain . +This value can then be used to call +.BR clock_nanosleep () +again and complete a (relative) sleep. +.SH RETURN VALUE +On successfully sleeping for the requested interval, +.BR clock_nanosleep () +returns 0. +If the call is interrupted by a signal handler or encounters an error, +then it returns one of the positive error number listed in ERRORS. +.SH ERRORS +.TP +.B EFAULT +.I request +or +.I remain +specified an invalid address. +.TP +.B EINTR +The sleep was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The value in the +.I tv_nsec +field was not in the range [0, 999999999] or +.I tv_sec +was negative. +.TP +.B EINVAL +.I clockid +was invalid. +.RB ( CLOCK_THREAD_CPUTIME_ID +is not a permitted value for +.IR clockid .) +.TP +.B ENOTSUP +The kernel does not support sleeping against this +.IR clockid . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +Linux 2.6, +glibc 2.1. +.SH NOTES +If the interval specified in +.I request +is not an exact multiple of the granularity underlying clock (see +.BR time (7)), +then the interval will be rounded up to the next multiple. +Furthermore, after the sleep completes, there may still be a delay before +the CPU becomes free to once again execute the calling thread. +.PP +Using an absolute timer is useful for preventing +timer drift problems of the type described in +.BR nanosleep (2). +(Such problems are exacerbated in programs that try to restart +a relative sleep that is repeatedly interrupted by signals.) +To perform a relative sleep that avoids these problems, call +.BR clock_gettime (2) +for the desired clock, +add the desired interval to the returned time value, +and then call +.BR clock_nanosleep () +with the +.B TIMER_ABSTIME +flag. +.PP +.BR clock_nanosleep () +is never restarted after being interrupted by a signal handler, +regardless of the use of the +.BR sigaction (2) +.B SA_RESTART +flag. +.PP +The +.I remain +argument is unused, and unnecessary, when +.I flags +is +.BR TIMER_ABSTIME . +(An absolute sleep can be restarted using the same +.I request +argument.) +.PP +POSIX.1 specifies that +.BR clock_nanosleep () +has no effect on signals dispositions or the signal mask. +.PP +POSIX.1 specifies that after changing the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2), +the new clock value shall be used to determine the time +at which a thread blocked on an absolute +.BR clock_nanosleep () +will wake up; +if the new clock value falls past the end of the sleep interval, then the +.BR clock_nanosleep () +call will return immediately. +.PP +POSIX.1 specifies that +changing the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2) +shall have no effect on a thread that is blocked on a relative +.BR clock_nanosleep (). +.SH SEE ALSO +.BR clock_getres (2), +.BR nanosleep (2), +.BR restart_syscall (2), +.BR timer_create (2), +.BR sleep (3), +.BR timespec (3), +.BR usleep (3), +.BR time (7) |