1 files changed, 253 insertions, 0 deletions
diff --git a/man/man2/clock_nanosleep.2 b/man/man2/clock_nanosleep.2
new file mode 100644
index 0000000..9be2a75
--- /dev/null
+++ b/man/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 2024-05-02 "Linux man-pages (unreleased)"
+.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)