CLOCK_NANOSLEEP(3)         POSIX Programmer's Manual        CLOCK_NANOSLEEP(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       clock_nanosleep -- high resolution sleep with specifiable clock

SSYYNNOOPPSSIISS
       #include <time.h>

       int clock_nanosleep(clockid_t _c_l_o_c_k___i_d, int _f_l_a_g_s,
           const struct timespec *_r_q_t_p, struct timespec *_r_m_t_p);

DDEESSCCRRIIPPTTIIOONN
       If the flag TIMER_ABSTIME is not set in the _f_l_a_g_s argument, the
       _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function shall cause the current thread to be
       suspended from execution until either the time interval specified by
       the _r_q_t_p 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 _c_l_o_c_k___i_d.

       If the flag TIMER_ABSTIME is set in the _f_l_a_g_s argument, the
       _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function shall cause the current thread to be
       suspended from execution until either the time value of the clock
       specified by _c_l_o_c_k___i_d reaches the absolute time specified by the _r_q_t_p
       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 _r_q_t_p is less
       than or equal to the time value of the specified clock, then
       _c_l_o_c_k___n_a_n_o_s_l_e_e_p() shall return immediately and the calling process
       shall not be suspended.

       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 _c_l_o_c_k___n_a_n_o_s_l_e_e_p()
       function (that is, with the TIMER_ABSTIME flag not set) shall not be
       less than the time interval specified by _r_q_t_p, as measured by the
       corresponding clock. The suspension for the absolute _c_l_o_c_k___n_a_n_o_s_l_e_e_p()
       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 _r_q_t_p, except for the case of being
       interrupted by a signal.

       The use of the _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function shall have no effect on the
       action or blockage of any signal.

       The _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function shall fail if the _c_l_o_c_k___i_d argument
       refers to the CPU-time clock of the calling thread. It is unspecified
       whether _c_l_o_c_k___i_d values of other CPU-time clocks are allowed.

RREETTUURRNN VVAALLUUEE
       If the _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function returns because the requested time
       has elapsed, its return value shall be zero.

       If the _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function returns because it has been
       interrupted by a signal, it shall return the corresponding error value.
       For the relative _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function, if the _r_m_t_p argument is
       non-NULL, the ttiimmeessppeecc 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 _r_q_t_p and _r_m_t_p arguments can
       point to the same object. If the _r_m_t_p argument is NULL, the remaining
       time is not returned. The absolute _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function has no
       effect on the structure referenced by _r_m_t_p.

       If _c_l_o_c_k___n_a_n_o_s_l_e_e_p() fails, it shall return the corresponding error
       value.

EERRRROORRSS
       The _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function shall fail if:

       EEIINNTTRR  The _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function was interrupted by a signal.

       EEIINNVVAALL The _r_q_t_p argument specified a nanosecond value less than zero or
              greater than or equal to 1000 million; or the TIMER_ABSTIME flag
              was specified in flags and the _r_q_t_p argument is outside the
              range for the clock specified by _c_l_o_c_k___i_d; or the _c_l_o_c_k___i_d
              argument does not specify a known clock, or specifies the CPU-
              time clock of the calling thread.

       EENNOOTTSSUUPP
              The _c_l_o_c_k___i_d argument specifies a clock for which
              _c_l_o_c_k___n_a_n_o_s_l_e_e_p() is not supported, such as a CPU-time clock.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Calling _c_l_o_c_k___n_a_n_o_s_l_e_e_p() with the value TIMER_ABSTIME not set in the
       _f_l_a_g_s argument and with a _c_l_o_c_k___i_d of CLOCK_REALTIME is equivalent to
       calling _n_a_n_o_s_l_e_e_p() with the same _r_q_t_p and _r_m_t_p arguments.

RRAATTIIOONNAALLEE
       The _n_a_n_o_s_l_e_e_p() 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.

       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 _s_l_e_e_p() or _n_a_n_o_s_l_e_e_p() function
       call. Suppose, for example, a periodic process that is activated at
       time _T0, executes for a while, and then wants to suspend itself until
       time _T0+_T, the period being _T.  If this process wants to use the
       _n_a_n_o_s_l_e_e_p() function, it must first call _c_l_o_c_k___g_e_t_t_i_m_e() to get the
       current time, then calculate the difference between the current time
       and _T0+_T and, finally, call _n_a_n_o_s_l_e_e_p() 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 _c_l_o_c_k___n_a_n_o_s_l_e_e_p() 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.

       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 _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function in
       POSIX.1-2008 are the same as for the inclusion of the relative
       _n_a_n_o_s_l_e_e_p().

       It is also possible to implement precise periodic processes using
       _p_t_h_r_e_a_d___c_o_n_d___t_i_m_e_d_w_a_i_t(), 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, _p_t_h_r_e_a_d___c_o_n_d___t_i_m_e_d_w_a_i_t()
       is not available in implementations that do not support threads.

       Although the interface of the relative and absolute versions of the new
       high resolution sleep service is the same _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function,
       the _r_m_t_p argument is only used in the relative sleep. This argument is
       needed in the relative _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function to reissue the
       function call if it is interrupted by a signal, but it is not needed in
       the absolute _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function call; if the call is
       interrupted by a signal, the absolute _c_l_o_c_k___n_a_n_o_s_l_e_e_p() function can be
       invoked again with the same _r_q_t_p argument used in the interrupted call.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_l_o_c_k___g_e_t_r_e_s(), _n_a_n_o_s_l_e_e_p(), _p_t_h_r_e_a_d___c_o_n_d___t_i_m_e_d_w_a_i_t(), _s_l_e_e_p()

       The Base Definitions volume of POSIX.1-2017, <<ttiimmee..hh>>

CCOOPPYYRRIIGGHHTT
       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 .

       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 .



IEEE/The Open Group                  2017                   CLOCK_NANOSLEEP(3)
