clock_nanosleep man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

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

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 sus‐
       pended 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 sus‐
       pended from execution until either the time value of the	 clock	speci‐
       fied  by clock_id reaches the absolute time specified by the rqtp argu‐
       ment, 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 multi‐
       ple  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 cor‐
       responding 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	 abso‐
       lute  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	inter‐
       rupted  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 con‐
       tain 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 argu‐
	      ment 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 ser‐
       vice. However, with the introduction of the monotonic clock CLOCK_MONO‐
       TONIC  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 perform‐
       ing 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 func‐
       tion 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 .

IEEE/The Open Group		     2003		    CLOCK_NANOSLEEP(P)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net