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



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

NAME
       clock_nanosleep -- high resolution sleep with specifiable clock

SYNOPSIS
       #include <time.h>

       int clock_nanosleep(clockid_t clock__id, int flags,
           const struct timespec *rqtp, struct timespec *rmtp);

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

       If the flag TIMER_ABSTIME is set in the flags argument, the
       clock__nanosleep() function shall cause the current thread to be
       suspended from execution until either the time value of the clock
       specified by clock__id reaches the absolute time specified by the 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 rqtp is less
       than or equal to the time value of the specified clock, then
       clock__nanosleep() 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 clock__nanosleep()
       function (that is, with the TIMER_ABSTIME flag not set) shall not be
       less than the time interval specified by rqtp, as measured by the
       corresponding clock. The suspension for the absolute clock__nanosleep()
       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 rqtp, except for the case of being
       interrupted by a signal.

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

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

RETURN VALUE
       If the clock__nanosleep() function returns because the requested time
       has elapsed, its return value shall be zero.

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

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

ERRORS
       The clock__nanosleep() function shall fail if:

       EINTR  The clock__nanosleep() function was interrupted by a signal.

       EINVAL The rqtp 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 rqtp argument is outside the
              range for the clock specified by clock__id; or the clock__id
              argument does not specify a known clock, or specifies the CPU-
              time clock of the calling thread.

       ENOTSUP
              The clock__id argument specifies a clock for which
              clock__nanosleep() is not supported, such as a CPU-time clock.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       Calling clock__nanosleep() with the value TIMER_ABSTIME not set in the
       flags argument and with a clock__id of CLOCK_REALTIME is equivalent to
       calling nanosleep() with the same rqtp and rmtp arguments.

RATIONALE
       The nanosleep() 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 sleep() or nanosleep() 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
       nanosleep() function, it must first call clock__gettime() to get the
       current time, then calculate the difference between the current time
       and _T0+_T and, finally, call nanosleep() 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 clock__nanosleep() 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 clock__nanosleep() function in
       POSIX.1-2008 are the same as for the inclusion of the relative
       nanosleep().

       It is also possible to implement precise periodic processes using
       pthread__cond__timedwait(), 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, pthread__cond__timedwait()
       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 clock__nanosleep() function,
       the rmtp argument is only used in the relative sleep. This argument is
       needed in the relative clock__nanosleep() function to reissue the
       function call if it is interrupted by a signal, but it is not needed in
       the absolute clock__nanosleep() function call; if the call is
       interrupted by a signal, the absolute clock__nanosleep() function can be
       invoked again with the same rqtp argument used in the interrupted call.

FUTURE DIRECTIONS
       None.

SEE ALSO
       clock__getres(), nanosleep(), pthread__cond__timedwait(), sleep()

       The Base Definitions volume of POSIX.1-2017, <time.h>

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 .

       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)
