nanosleep()

Updated: May 06, 2022

Suspend a thread until a timeout or signal occurs

Synopsis:

#include <time.h>

int nanosleep( const struct timespec* rqtp,
               struct timespec* rmtp );

Arguments:

rqtp
A pointer to a timespec structure that specifies the time interval for which you want to suspend the thread.
rmtp
NULL, or a pointer to a timespec structure where the function can store the amount of time remaining in the interval (the requested time minus the time actually slept).

Library:

libc

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

Description:

The nanosleep() function causes the calling thread to be suspended from execution until either:

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 uses CLOCK_REALTIME; clock_nanosleep() is similar, but you can choose which clock to use, and you can specify a relative or absolute time.

Note: While nanosleep() looks like you can specify a sleep duration down to the nanosecond level, the actual delay will still be driven by the system clock tick. Assuming the usual default clock tick is 1 ms, the shortest delay you can get from nanosleep() will be 1.5 ms on average.

This function can interfere with the kernel's efforts to manage power usage. The suspension time may be longer than requested because the argument value is rounded up to be a multiple of the system timer 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.

Returns:

0
The requested time has elapsed.
-1
The nanosleep() function was interrupted by a signal (errno is set).

Errors:

EAGAIN
All timers are in use. You'll have to wait for a process to release one.
EFAULT
A fault occurred trying to access the buffers provided.
EINTR
The nanosleep() function was interrupted by a signal.
EINVAL
The number of nanoseconds specified by the tv_nsec member of the timespec structure pointed to by rqtp is less than zero or greater than or equal to 1000 million.

Classification:

POSIX 1003.1

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