Man Pages

clock_nanosleep(3p) - phpMan clock_nanosleep(3p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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 (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 cur-
       rent 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  sys-
       tem.  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 cor-
       responding  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  rela-
       tive  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 dif-
       ference 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 includ-
       ing  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  abso-
       lute 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, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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 .



IEEE/The Open Group                  2003                  CLOCK_NANOSLEEP(3P)