summaryrefslogtreecommitdiffstats
path: root/man2/clock_nanosleep.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/clock_nanosleep.2')
-rw-r--r--man2/clock_nanosleep.2253
1 files changed, 0 insertions, 253 deletions
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
deleted file mode 100644
index 12948c7..0000000
--- a/man2/clock_nanosleep.2
+++ /dev/null
@@ -1,253 +0,0 @@
-.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
-.\" <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.TH clock_nanosleep 2 2024-03-05 "Linux man-pages 6.7"
-.SH NAME
-clock_nanosleep \- high-resolution sleep with specifiable clock
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc ),
-since glibc 2.17
-.P
-Before glibc 2.17,
-Real-time library
-.RI ( librt ", " \-lrt )
-.SH SYNOPSIS
-.B #include <time.h>
-.nf
-.P
-.BI "int clock_nanosleep(clockid_t " clockid ", int " flags ,
-.BI " const struct timespec *" t ,
-.BI " struct timespec *_Nullable " remain );
-.fi
-.P
-.RS -4
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.RE
-.P
-.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.
-.P
-The time values passed to and returned by this call are specified using
-.BR timespec (3)
-structures.
-.P
-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 counting 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.
-.P
-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.
-.P
-If
-.I flags
-is 0, then the value specified in
-.I t
-is interpreted as an interval relative to the current
-value of the clock specified by
-.IR clockid .
-.P
-If
-.I flags
-is
-.BR TIMER_ABSTIME ,
-then
-.I t
-is interpreted as an absolute time as measured by the clock,
-.IR clockid .
-If
-.I t
-is less than or equal to the current value of the clock,
-then
-.BR clock_nanosleep ()
-returns immediately without suspending the calling thread.
-.P
-.BR clock_nanosleep ()
-suspends the execution of the calling thread
-until either at least the time specified by
-.I t
-has elapsed,
-or a signal is delivered that causes a signal handler to be called or
-that terminates the process.
-.P
-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 t
-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 t
-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.
-.P
-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.
-.P
-.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.
-.P
-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 t
-argument.)
-.P
-POSIX.1 specifies that
-.BR clock_nanosleep ()
-has no effect on signals dispositions or the signal mask.
-.P
-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.
-.P
-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)