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



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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 (ADVANCED REALTIME)

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  corre-
       sponding  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 refer-
       enced by it shall be updated to contain the amount of time remaining in the interval (the requested time minus  the  time
       actually  slept).  If the rmtp argument is NULL, the remaining time is not returned. The absolute clock_nanosleep() func-
       tion 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_REAL-
       TIME 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_get-
       time()  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 IEEE Std 1003.1-2001 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 over-
       head. 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 IEEE Std 1003.1-2001,
       <time.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003  Edition,  Standard  for
       Information  Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
       right (C) 2001-2003 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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                           CLOCK_NANOSLEEP(3P)