clock_nanosleep()

Synopsis:

#include <time.h>

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

Arguments:

clock_id

The ID of the clock to use to measure the time. The possible clock types are:

CLOCK_REALTIME — the standard POSIX-defined clock. Timers based on this clock wake up the processor if it's in a power-saving mode.
CLOCK_SOFTTIME — (a QNX Neutrino extension) this clock is active only when the processor isn't in a power-saving mode. For example, an application using a CLOCK_SOFTTIME timer to sleep wouldn't wake up the processor when the application was due to wake up. This will allow the processor to enter a power-saving mode.
While the processor isn't in a power-saving mode, CLOCK_SOFTTIME behaves the same as CLOCK_REALTIME.
CLOCK_MONOTONIC — this clock always increases at a constant rate and can't be adjusted.

The clock_nanosleep() function fails if the clock_id argument refers to the CPU-time clock of the calling thread.

For more information about the different clocks, see “Other clock sources” in the Clocks, Timers, and Getting a Kick Every So Often of Getting Started with QNX Neutrino.

flags

Flags that specify when to suspend the execution of the current thread. The only flag that is currently defined is:

TIMER_ABSTIME — specify that the time specified by the rqtp argument is an absolute time. The current thread is suspended from execution until the time value of the clock specified by clock_id reaches the time specified by the rqtp argument.
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() returns immediately, and the calling process isn't suspended.

When TIMER_ABSTIME is not set, the time specified by the rqtp argument is an interval. The current thread is suspended from execution until this interval has elapsed.

Calling clock_nanosleep() with TIMER_ABSTIME not set and clock_id set to CLOCK_REALTIME is equivalent to calling nanosleep() with the same rqtp and rmtp arguments.

rqtp

A pointer to a timespec structure with the requested timeout. If TIMER_ABSTIME is set, it is the requested time to sleep until; otherwise, it is the time interval to sleep.

Although timespec has a resolution of nanoseconds, the resolution on the sleep period depends on the clock used (usually ClockPeriod()).

rmtp

NULL, or a pointer to a timespec structure in which the function can store the amount of time remaining in an interval.

For the relative clock_nanosleep() function, if rmtp isn't NULL, the timespec structure referenced by it is updated to contain the amount of time remaining in the interval (the requested time minus the time actually slept). If it's NULL, the remaining time isn't returned.

The absolute clock_nanosleep() function has no effect on the structure referenced by rmtp.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The clock_nanosleep() function suspends the current thread from execution until:

If TIMER_ABSTIME is set, the time value of the clock specified by clock_id reaches the absolute time specified by the rqtp argument.
Or:
If TIMER_ABSTIME is not set, the time interval specified by the rqtp argument has elapsed.
Or:
A signal is delivered to the calling thread, and the signal's action is to invoke a signal-catching function or terminate the process.

At the end of the suspension, the thread becomes READY and is scheduled to run as normal, based on priority and the scheduling algorithm.

The nanosleep() function always uses CLOCK_REALTIME.

The suspension time may be longer than requested because the argument value is rounded up to a multiple of the sleep resolution (see the “Understanding the Microkernel's Concept of Time” chapter of the QNX Neutrino Programmer's Guide) or because of scheduling and other system activity. Except for the case of being interrupted by a signal, the suspension time for:

the relative clock_nanosleep() function (TIMER_ABSTIME not set) — isn't less than the time interval specified by rqtp, as measured by the corresponding clock
the absolute clock_nanosleep() function (TIMER_ABSTIME set) — is 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.

Using the clock_nanosleep() function has no effect on the action or blockage of any signal.

Returns:

Zero if the requested time has elapsed, or a corresponding error value if clock_nanosleep() has been interrupted by a signal, or fails.

Errors:

EINTR: The call 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 TIMER_ABSTIME is specified in flags and the rqtp argument is outside the range for the clock specified by clock_id; or the clock_id argument doesn't 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() isn't supported, such as a CPU-time clock.

Classification:

POSIX 1003.1

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes