1clock_nanosleep(2)            System Calls Manual           clock_nanosleep(2)
2
3
4

NAME

6       clock_nanosleep - high-resolution sleep with specifiable clock
7

LIBRARY

9       Standard C library (libc, -lc), since glibc 2.17
10
11       Before glibc 2.17, Real-time library (librt, -lrt)
12

SYNOPSIS

14       #include <time.h>
15
16       int clock_nanosleep(clockid_t clockid, int flags,
17                           const struct timespec *request,
18                           struct timespec *_Nullable remain);
19
20   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21
22       clock_nanosleep():
23           _POSIX_C_SOURCE >= 200112L
24

DESCRIPTION

26       Like nanosleep(2), clock_nanosleep() allows the calling thread to sleep
27       for an interval specified with nanosecond precision.  It differs in al‐
28       lowing  the caller to select the clock against which the sleep interval
29       is to be measured, and in allowing the sleep interval to  be  specified
30       as either an absolute or a relative value.
31
32       The time values passed to and returned by this call are specified using
33       timespec(3) structures.
34
35       The clockid argument specifies the clock against which the sleep inter‐
36       val  is  to  be  measured.  This argument can have one of the following
37       values:
38
39       CLOCK_REALTIME
40              A settable system-wide real-time clock.
41
42       CLOCK_TAI (since Linux 3.10)
43              A system-wide clock derived from wall-clock  time  but  ignoring
44              leap seconds.
45
46       CLOCK_MONOTONIC
47              A nonsettable, monotonically increasing clock that measures time
48              since some unspecified point in the past that  does  not  change
49              after system startup.
50
51       CLOCK_BOOTTIME (since Linux 2.6.39)
52              Identical  to  CLOCK_MONOTONIC, except that it also includes any
53              time that the system is suspended.
54
55       CLOCK_PROCESS_CPUTIME_ID
56              A settable per-process clock that measures CPU time consumed  by
57              all threads in the process.
58
59       See  clock_getres(2) for further details on these clocks.  In addition,
60       the   CPU   clock   IDs   returned   by   clock_getcpuclockid(3)    and
61       pthread_getcpuclockid(3) can also be passed in clockid.
62
63       If flags is 0, then the value specified in request is interpreted as an
64       interval relative to the  current  value  of  the  clock  specified  by
65       clockid.
66
67       If  flags  is TIMER_ABSTIME, then request is interpreted as an absolute
68       time as measured by the clock, clockid.  If request  is  less  than  or
69       equal to the current value of the clock, then clock_nanosleep() returns
70       immediately without suspending the calling thread.
71
72       clock_nanosleep() suspends the execution of the  calling  thread  until
73       either  at least the time specified by request has elapsed, or a signal
74       is delivered that causes a signal handler to be called or  that  termi‐
75       nates the process.
76
77       If the call is interrupted by a signal handler, clock_nanosleep() fails
78       with the error EINTR.  In addition, if remain is not  NULL,  and  flags
79       was not TIMER_ABSTIME, it returns the remaining unslept time in remain.
80       This value can then be used to call clock_nanosleep()  again  and  com‐
81       plete a (relative) sleep.
82

RETURN VALUE

84       On  successfully sleeping for the requested interval, clock_nanosleep()
85       returns 0.  If the call is interrupted by a signal handler  or  encoun‐
86       ters  an error, then it returns one of the positive error number listed
87       in ERRORS.
88

ERRORS

90       EFAULT request or remain specified an invalid address.
91
92       EINTR  The sleep was interrupted by a signal handler; see signal(7).
93
94       EINVAL The value in  the  tv_nsec  field  was  not  in  the  range  [0,
95              999999999] or tv_sec was negative.
96
97       EINVAL clockid  was invalid.  (CLOCK_THREAD_CPUTIME_ID is not a permit‐
98              ted value for clockid.)
99
100       ENOTSUP
101              The kernel does not support sleeping against this clockid.
102

STANDARDS

104       POSIX.1-2008.
105

HISTORY

107       POSIX.1-2001.  Linux 2.6, glibc 2.1.
108

NOTES

110       If the interval specified in request is not an exact  multiple  of  the
111       granularity  underlying  clock (see time(7)), then the interval will be
112       rounded up to the next multiple.  Furthermore,  after  the  sleep  com‐
113       pletes,  there may still be a delay before the CPU becomes free to once
114       again execute the calling thread.
115
116       Using an absolute timer is useful for preventing timer  drift  problems
117       of  the type described in nanosleep(2).  (Such problems are exacerbated
118       in programs that try to restart a relative sleep that is repeatedly in‐
119       terrupted  by  signals.)  To perform a relative sleep that avoids these
120       problems, call clock_gettime(2) for the desired clock, add the  desired
121       interval  to  the  returned time value, and then call clock_nanosleep()
122       with the TIMER_ABSTIME flag.
123
124       clock_nanosleep() is never restarted after being interrupted by a  sig‐
125       nal handler, regardless of the use of the sigaction(2) SA_RESTART flag.
126
127       The remain argument is unused, and unnecessary, when flags is TIMER_AB‐
128       STIME.  (An absolute sleep can be restarted using the same request  ar‐
129       gument.)
130
131       POSIX.1  specifies that clock_nanosleep() has no effect on signals dis‐
132       positions or the signal mask.
133
134       POSIX.1 specifies that after changing the value of  the  CLOCK_REALTIME
135       clock via clock_settime(2), the new clock value shall be used to deter‐
136       mine  the  time  at   which   a   thread   blocked   on   an   absolute
137       clock_nanosleep()  will  wake up; if the new clock value falls past the
138       end of the sleep interval, then the clock_nanosleep() call will  return
139       immediately.
140
141       POSIX.1  specifies  that changing the value of the CLOCK_REALTIME clock
142       via clock_settime(2) shall have no effect on a thread that  is  blocked
143       on a relative clock_nanosleep().
144

SEE ALSO

146       clock_getres(2),   nanosleep(2),  restart_syscall(2),  timer_create(2),
147       sleep(3), timespec(3), usleep(3), time(7)
148
149
150
151Linux man-pages 6.04              2023-03-30                clock_nanosleep(2)
Impressum