1 files changed, 267 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/clock_nanosleep.3p b/upstream/archlinux/man3p/clock_nanosleep.3p
new file mode 100644
index 00000000..341ed3a4
--- /dev/null
+++ b/upstream/archlinux/man3p/clock_nanosleep.3p
@@ -0,0 +1,267 @@
+'\" et
+.TH CLOCK_NANOSLEEP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+clock_nanosleep
+\(em high resolution sleep with specifiable clock
+.SH SYNOPSIS
+.LP
+.nf
+#include <time.h>
+.P
+int clock_nanosleep(clockid_t \fIclock_id\fP, int \fIflags\fP,
+    const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP);
+.fi
+.SH DESCRIPTION
+If the flag TIMER_ABSTIME
+is not set in the
+.IR flags
+argument, the
+\fIclock_nanosleep\fR()
+function shall cause the current thread to be suspended from execution
+until either the time interval specified by the
+.IR rqtp
+argument has elapsed, or a signal is delivered to the calling thread
+and its action is to invoke a signal-catching function, or the process
+is terminated. The clock used to measure the time shall be the clock
+specified by
+.IR clock_id .
+.P
+If the flag TIMER_ABSTIME is set in the
+.IR flags
+argument, the
+\fIclock_nanosleep\fR()
+function shall cause the current thread to be suspended from execution
+until either the time value of the clock specified by
+.IR clock_id
+reaches the absolute time specified by the
+.IR rqtp
+argument, or a signal is delivered to the calling thread and its action
+is to invoke a signal-catching function, or the process is terminated.
+If, at the time of the call, the time value specified by
+.IR rqtp
+is less than or equal to the time value of the specified clock, then
+\fIclock_nanosleep\fR()
+shall return immediately and the calling process shall not be
+suspended.
+.P
+The suspension time caused by this function may be longer than
+requested because the argument value is rounded up to an integer
+multiple of the sleep resolution, or because of the scheduling of other
+activity by the system. But, except for the case of being interrupted
+by a signal, the suspension time for the relative
+\fIclock_nanosleep\fR()
+function (that is, with the TIMER_ABSTIME flag not set) shall not be
+less than the time interval specified by
+.IR rqtp ,
+as measured by the corresponding clock. The suspension for the absolute
+\fIclock_nanosleep\fR()
+function (that is, with the TIMER_ABSTIME flag set) shall be in effect
+at least until the value of the corresponding clock reaches the
+absolute time specified by
+.IR rqtp ,
+except for the case of being interrupted by a signal.
+.P
+The use of the
+\fIclock_nanosleep\fR()
+function shall have no effect on the action or blockage of any signal.
+.P
+The
+\fIclock_nanosleep\fR()
+function shall fail if the
+.IR clock_id
+argument refers to the CPU-time clock of the calling thread. It is
+unspecified whether
+.IR clock_id
+values of other CPU-time clocks are allowed.
+.SH "RETURN VALUE"
+If the
+\fIclock_nanosleep\fR()
+function returns because the requested time has elapsed, its return
+value shall be zero.
+.P
+If the
+\fIclock_nanosleep\fR()
+function returns because it has been interrupted by a signal, it shall
+return the corresponding error value. For the relative
+\fIclock_nanosleep\fR()
+function, if the
+.IR rmtp
+argument is non-NULL, the
+.BR timespec
+structure referenced by it shall be updated to contain the amount of
+time remaining in the interval (the requested time minus the time
+actually slept). The
+.IR rqtp
+and
+.IR rmtp
+arguments can point to the same object. If the
+.IR rmtp
+argument is NULL, the remaining time is not returned. The absolute
+\fIclock_nanosleep\fR()
+function has no effect on the structure referenced by
+.IR rmtp .
+.P
+If
+\fIclock_nanosleep\fR()
+fails, it shall return the corresponding error value.
+.SH ERRORS
+The
+\fIclock_nanosleep\fR()
+function shall fail if:
+.TP
+.BR EINTR
+The
+\fIclock_nanosleep\fR()
+function was interrupted by a signal.
+.TP
+.BR EINVAL
+The
+.IR rqtp
+argument specified a nanosecond value less than zero or greater than or
+equal to 1\|000 million; or the TIMER_ABSTIME flag was specified in
+flags and the
+.IR rqtp
+argument is outside the range for the clock specified by
+.IR clock_id ;
+or the
+.IR clock_id
+argument does not specify a known clock, or specifies the CPU-time
+clock of the calling thread.
+.TP
+.BR ENOTSUP
+The
+.IR clock_id
+argument specifies a clock for which
+\fIclock_nanosleep\fR()
+is not supported, such as a CPU-time clock.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+Calling
+\fIclock_nanosleep\fR()
+with the value TIMER_ABSTIME not set in the
+.IR flags
+argument and with a
+.IR clock_id
+of CLOCK_REALTIME is equivalent to calling
+\fInanosleep\fR()
+with the same
+.IR rqtp
+and
+.IR rmtp
+arguments.
+.SH RATIONALE
+The
+\fInanosleep\fR()
+function specifies that the system-wide clock CLOCK_REALTIME is used to
+measure the elapsed time for this time service. However, with the
+introduction of the monotonic clock CLOCK_MONOTONIC a new relative
+sleep function is needed to allow an application to take advantage of
+the special characteristics of this clock.
+.P
+There are many applications in which a process needs to be suspended
+and then activated multiple times in a periodic way; for example, to
+poll the status of a non-interrupting device or to refresh a display
+device. For these cases, it is known that precise periodic activation
+cannot be achieved with a relative
+\fIsleep\fR()
+or
+\fInanosleep\fR()
+function call. Suppose, for example, a periodic process that is
+activated at time
+.IR T 0,
+executes for a while, and then wants to suspend itself until time
+.IR T 0+\c
+.IR T ,
+the period being
+.IR T .
+If this process wants to use the
+\fInanosleep\fR()
+function, it must first call
+\fIclock_gettime\fR()
+to get the current time, then calculate the difference between the
+current time and
+.IR T 0+\c
+.IR T
+and, finally, call
+\fInanosleep\fR()
+using the computed interval. However, the process could be preempted by
+a different process between the two function calls, and in this case
+the interval computed would be wrong; the process would wake up later
+than desired. This problem would not occur with the absolute
+\fIclock_nanosleep\fR()
+function, since only one function call would be necessary to suspend
+the process until the desired time. In other cases, however, a relative
+sleep is needed, and that is why both functionalities are required.
+.P
+Although it is possible to implement periodic processes using the
+timers interface, this implementation would require the use of signals,
+and the reservation of some signal numbers. In this regard, the reasons
+for including an absolute version of the
+\fIclock_nanosleep\fR()
+function in POSIX.1\(hy2008 are the same as for the inclusion of the relative
+\fInanosleep\fR().
+.P
+It is also possible to implement precise periodic processes using
+\fIpthread_cond_timedwait\fR(),
+in which an absolute timeout is specified that takes effect if the
+condition variable involved is never signaled. However, the use of this
+interface is unnatural, and involves performing other operations on
+mutexes and condition variables that imply an unnecessary overhead.
+Furthermore,
+\fIpthread_cond_timedwait\fR()
+is not available in implementations that do not support threads.
+.P
+Although the interface of the relative and absolute versions of the new
+high resolution sleep service is the same
+\fIclock_nanosleep\fR()
+function, the
+.IR rmtp
+argument is only used in the relative sleep. This argument is needed in
+the relative
+\fIclock_nanosleep\fR()
+function to reissue the function call if it is interrupted by a signal,
+but it is not needed in the absolute
+\fIclock_nanosleep\fR()
+function call; if the call is interrupted by a signal, the absolute
+\fIclock_nanosleep\fR()
+function can be invoked again with the same
+.IR rqtp
+argument used in the interrupted call.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIclock_getres\fR\^(\|)",
+.IR "\fInanosleep\fR\^(\|)",
+.IR "\fIpthread_cond_timedwait\fR\^(\|)",
+.IR "\fIsleep\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<time.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .