# clock_nanosleep

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


## 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 _T_ 0, executes for a
           while, and then wants to suspend itself until time _T_ 0+_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
           _T_ 0+_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.
    


* * *