PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

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

PROLOG         top

       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         top

       clock_nanosleep — high resolution sleep with specifiable clock

SYNOPSIS         top

       #include <time.h>

       int clock_nanosleep(clockid_t clock_id, int flags,
           const struct timespec *rqtp, struct timespec *rmtp);

DESCRIPTION         top

       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         top

       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         top

       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         top

       None.

APPLICATION USAGE         top

       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         top

       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 POSIX.1‐2008 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         top

       None.

SEE ALSO         top

       clock_getres(3p), nanosleep(3p), pthread_cond_timedwait(3p),
       sleep(3p)

       The Base Definitions volume of POSIX.1‐2008, time.h(0p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the
       source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                 2013                 CLOCK_NANOSLEEP(3P)

Pages that refer to this page: time.h(0p)clock_getres(3p)nanosleep(3p)