clock_nanosleep man page on Fedora

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

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 (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 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(3P)
[top]

List of man pages available for Fedora

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