# nanosleep

## NAME



           nanosleep - high-resolution sleep
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <time.h>**
    
           **int nanosleep(const struct timespec ***_duration_**,**
                         **struct timespec *_Nullable** _rem_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **nanosleep**():
               _POSIX_C_SOURCE >= 199309L
    


## DESCRIPTION



           **nanosleep**() suspends the execution of the calling thread until
           either at least the time specified in _*duration_ has elapsed, or
           the delivery of a signal that triggers the invocation of a handler
           in the calling thread or that terminates the process.
    
           If the call is interrupted by a signal handler, **nanosleep**()
           returns -1, sets _errno_ to **EINTR** , and writes the remaining time
           into the structure pointed to by _rem_ unless _rem_ is NULL.  The
           value of _*rem_ can then be used to call **nanosleep**() again and
           complete the specified pause (but see NOTES).
    
           The **timespec**(3) structure is used to specify intervals of time
           with nanosecond precision.
    
           The value of the nanoseconds field must be in the range [0,
           999999999].
    
           Compared to sleep(3) and usleep(3), **nanosleep**() has the following
           advantages: it provides a higher resolution for specifying the
           sleep interval; POSIX.1 explicitly specifies that it does not
           interact with signals; and it makes the task of resuming a sleep
           that has been interrupted by a signal handler easier.
    


## RETURN VALUE



           On successfully sleeping for the requested duration, **nanosleep**()
           returns 0.  If the call is interrupted by a signal handler or
           encounters an error, then it returns -1, with _errno_ set to
           indicate the error.
    


## ERRORS



           **EFAULT** Problem with copying information from user space.
    
           **EINTR** The pause has been interrupted by a signal that was
                  delivered to the thread (see signal(7)).  The remaining
                  sleep time has been written into _*rem_ so that the thread
                  can easily call **nanosleep**() again and continue with the
                  pause.
    
           **EINVAL** The value in the _tv_nsec_ field was not in the range [0,
                  999999999] or _tv_sec_ was negative.
    


## VERSIONS



           POSIX.1 specifies that **nanosleep**() should measure time against the
           **CLOCK_REALTIME** clock.  However, Linux measures the time using the
           **CLOCK_MONOTONIC** clock.  This probably does not matter, since the
           POSIX.1 specification for clock_settime(2) says that discontinuous
           changes in **CLOCK_REALTIME** should not affect **nanosleep**():
    
                  Setting the value of the **CLOCK_REALTIME** clock via
                  clock_settime(2) shall have no effect on threads that are
                  blocked waiting for a relative time service based upon this
                  clock, including the **nanosleep**() function; ...
                  Consequently, these time services shall expire when the
                  requested duration elapses, independently of the new or old
                  value of the clock.
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           If the _duration_ is not an exact multiple of the granularity
           underlying clock (see time(7)), then the interval will be rounded
           up to the next multiple.  Furthermore, after the sleep completes,
           there may still be a delay before the CPU becomes free to once
           again execute the calling thread.
    
           The fact that **nanosleep**() sleeps for a relative interval can be
           problematic if the call is repeatedly restarted after being
           interrupted by signals, since the time between the interruptions
           and restarts of the call will lead to drift in the time when the
           sleep finally completes.  This problem can be avoided by using
           clock_nanosleep(2) with an absolute time value.
    


## BUGS



           If a program that catches signals and uses **nanosleep**() receives
           signals at a very high rate, then scheduling delays and rounding
           errors in the kernel's calculation of the sleep interval and the
           returned _remain_ value mean that the _remain_ value may steadily
           _increase_ on successive restarts of the **nanosleep**() call.  To avoid
           such problems, use clock_nanosleep(2) with the **TIMER_ABSTIME** flag
           to sleep to an absolute deadline.
    
           In Linux 2.4, if **nanosleep**() is stopped by a signal (e.g.,
           **SIGTSTP**), then the call fails with the error **EINTR** after the
           thread is resumed by a **SIGCONT** signal.  If the system call is
           subsequently restarted, then the time that the thread spent in the
           stopped state is _not_ counted against the sleep interval.  This
           problem is fixed in Linux 2.6.0 and later kernels.
    


* * *