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 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). 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 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 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 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, Copyright (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.opengroup.org/unix/online.html .