nanosleep(2)

1NANOSLEEP(2)               Linux Programmer's Manual              NANOSLEEP(2)
2
3
4

NAME

6       nanosleep - pause execution for a specified time
7

SYNOPSIS

9       #define _POSIX_C_SOURCE 199309 #include <time.h>
10
11       int nanosleep(const struct timespec *req, struct timespec *rem);
12

DESCRIPTION

14       nanosleep()  delays  the execution of the program for at least the time
15       specified in *req.  The function can return earlier  if  a  signal  has
16       been  delivered to the process. In this case, it returns -1, sets errno
17       to EINTR, and writes the remaining time into the structure  pointed  to
18       by  rem unless rem is NULL.  The value of *rem can then be used to call
19       nanosleep() again and complete the specified pause.
20
21       The structure timespec is  used  to  specify  intervals  of  time  with
22       nanosecond precision. It is specified in <time.h> and has the form
23
24              struct timespec {
25                  time_t tv_sec;        /* seconds */
26                  long   tv_nsec;       /* nanoseconds */
27              };
28
29       The value of the nanoseconds field must be in the range 0 to 999999999.
30
31       Compared  to  sleep(3)  and usleep(3), nanosleep() has the advantage of
32       not affecting any signals, it is standardized  by  POSIX,  it  provides
33       higher  timing  resolution,  and it allows to continue a sleep that has
34       been interrupted by a signal more easily.
35

RETURN VALUE

37       On  successfully  sleeping  for  the  requested  interval,  nanosleep()
38       returns  0.   If the call is interrupted by a signal handler or encoun‐
39       ters an error, then it returns -1,  with  errno  set  to  indicate  the
40       error.
41

ERRORS

43       EFAULT Problem with copying information from user space.
44
45       EINTR  The  pause has been interrupted by a non-blocked signal that was
46              delivered to the process. The  remaining  sleep  time  has  been
47              written   into   *rem  so  that  the  process  can  easily  call
48              nanosleep() again and continue with the pause.
49
50       EINVAL The value in the tv_nsec  field  was  not  in  the  range  0  to
51              999999999 or tv_sec was negative.
52

BUGS

54       The current implementation of nanosleep() is based on the normal kernel
55       timer mechanism, which  has  a  resolution  of  1/HZ s  (see  time(7)).
56       Therefore,  nanosleep()  pauses always for at least the specified time,
57       however it can take up to 10 ms longer than specified until the process
58       becomes runnable again. For the same reason, the value returned in case
59       of a delivered signal in *rem is usually rounded  to  the  next  larger
60       multiple of 1/HZ s.
61
62   Old behaviour
63       In  order  to  support  applications requiring much more precise pauses
64       (e.g., in order to control some  time-critical  hardware),  nanosleep()
65       would handle pauses of up to 2 ms by busy waiting with microsecond pre‐
66       cision when called from a process scheduled under  a  real-time  policy
67       like  SCHED_FIFO  or  SCHED_RR.   This special extension was removed in
68       kernel 2.5.39, hence is still present in current 2.4 kernels,  but  not
69       in 2.6 kernels.
70
71       In  Linux  2.4,  if nanosleep() is stopped by a signal (e.g., SIGTSTP),
72       then the call fails with the error EINTR after the process  is  resumed
73       by  a  SIGCONT  signal.   If the system call is subsequently restarted,
74       then the time that the process  spent  in  the  stopped  state  is  not
75       counted against the sleep interval.
76

CONFORMING TO

78       POSIX.1-2001.
79