| .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk |
| .\" <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH CLOCK_NANOSLEEP 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| clock_nanosleep \- high-resolution sleep with specifiable clock |
| .SH SYNOPSIS |
| .B #include <time.h> |
| .nf |
| .PP |
| .BI "int clock_nanosleep(clockid_t " clock_id ", int " flags , |
| .BI " const struct timespec *" request , |
| .BI " struct timespec *" remain ); |
| .fi |
| .PP |
| Link with \fI\-lrt\fP (only for glibc versions before 2.17). |
| .PP |
| .ad l |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR clock_nanosleep (): |
| .RS 4 |
| _POSIX_C_SOURCE\ >=\ 200112L |
| .RE |
| .ad |
| .SH DESCRIPTION |
| Like |
| .BR nanosleep (2), |
| .BR clock_nanosleep () |
| allows the calling thread to sleep for an interval specified |
| with nanosecond precision. |
| It differs in allowing the caller to select the clock against |
| which the sleep interval is to be measured, |
| and in allowing the sleep interval to be specified as |
| either an absolute or a relative value. |
| .PP |
| The time values passed to and returned by this call are specified using |
| .I timespec |
| structures, defined as follows: |
| .PP |
| .in +4n |
| .EX |
| struct timespec { |
| time_t tv_sec; /* seconds */ |
| long tv_nsec; /* nanoseconds [0 .. 999999999] */ |
| }; |
| .EE |
| .in |
| .PP |
| The |
| .I clock_id |
| argument specifies the clock against which the sleep interval |
| is to be measured. |
| This argument can have one of the following values: |
| .TP 17 |
| .BR CLOCK_REALTIME |
| A settable system-wide real-time clock. |
| .TP |
| .BR CLOCK_MONOTONIC |
| A nonsettable, monotonically increasing clock that measures time |
| since some unspecified point in the past that does not change after |
| system startup. |
| .\" On Linux this clock measures time since boot. |
| .TP |
| .BR CLOCK_PROCESS_CPUTIME_ID |
| A settable per-process clock that measures CPU time consumed |
| by all threads in the process. |
| .\" There is some trickery between glibc and the kernel |
| .\" to deal with the CLOCK_PROCESS_CPUTIME_ID case. |
| .PP |
| See |
| .BR clock_getres (2) |
| for further details on these clocks. |
| In addition, the CPU clock IDs returned by |
| .BR clock_getcpuclockid (3) |
| and |
| .BR pthread_getcpuclockid (3) |
| can also be passed in |
| .IR clock_id . |
| .PP |
| If |
| .I flags |
| is 0, then the value specified in |
| .I request |
| is interpreted as an interval relative to the current |
| value of the clock specified by |
| .IR clock_id . |
| .PP |
| If |
| .I flags |
| is |
| .BR TIMER_ABSTIME , |
| then |
| .I request |
| is interpreted as an absolute time as measured by the clock, |
| .IR clock_id . |
| If |
| .I request |
| is less than or equal to the current value of the clock, |
| then |
| .BR clock_nanosleep () |
| returns immediately without suspending the calling thread. |
| .PP |
| .BR clock_nanosleep () |
| suspends the execution of the calling thread |
| until either at least the time specified by |
| .IR request |
| has elapsed, |
| or a signal is delivered that causes a signal handler to be called or |
| that terminates the process. |
| .PP |
| If the call is interrupted by a signal handler, |
| .BR clock_nanosleep () |
| fails with the error |
| .BR EINTR . |
| In addition, if |
| .I remain |
| is not NULL, and |
| .I flags |
| was not |
| .BR TIMER_ABSTIME , |
| it returns the remaining unslept time in |
| .IR remain . |
| This value can then be used to call |
| .BR clock_nanosleep () |
| again and complete a (relative) sleep. |
| .SH RETURN VALUE |
| On successfully sleeping for the requested interval, |
| .BR clock_nanosleep () |
| returns 0. |
| If the call is interrupted by a signal handler or encounters an error, |
| then it returns one of the positive error number listed in ERRORS. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .I request |
| or |
| .I remain |
| specified an invalid address. |
| .TP |
| .B EINTR |
| The sleep was interrupted by a signal handler; see |
| .BR signal (7). |
| .TP |
| .B EINVAL |
| The value in the |
| .I tv_nsec |
| field was not in the range 0 to 999999999 or |
| .I tv_sec |
| was negative. |
| .TP |
| .B EINVAL |
| .I clock_id |
| was invalid. |
| .RB ( CLOCK_THREAD_CPUTIME_ID |
| is not a permitted value for |
| .IR clock_id .) |
| .SH VERSIONS |
| The |
| .BR clock_nanosleep () |
| system call first appeared in Linux 2.6. |
| Support is available in glibc since version 2.1. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008. |
| .SH NOTES |
| If the interval specified in |
| .I request |
| is not an exact multiple of the granularity underlying clock (see |
| .BR 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. |
| .PP |
| Using an absolute timer is useful for preventing |
| timer drift problems of the type described in |
| .BR nanosleep (2). |
| (Such problems are exacerbated in programs that try to restart |
| a relative sleep that is repeatedly interrupted by signals.) |
| To perform a relative sleep that avoids these problems, call |
| .BR clock_gettime (2) |
| for the desired clock, |
| add the desired interval to the returned time value, |
| and then call |
| .BR clock_nanosleep () |
| with the |
| .B TIMER_ABSTIME |
| flag. |
| .PP |
| .BR clock_nanosleep () |
| is never restarted after being interrupted by a signal handler, |
| regardless of the use of the |
| .BR sigaction (2) |
| .B SA_RESTART |
| flag. |
| .PP |
| The |
| .I remain |
| argument is unused, and unnecessary, when |
| .I flags |
| is |
| .BR TIMER_ABSTIME . |
| (An absolute sleep can be restarted using the same |
| .I request |
| argument.) |
| .PP |
| POSIX.1 specifies that |
| .BR clock_nanosleep () |
| has no effect on signals dispositions or the signal mask. |
| .PP |
| POSIX.1 specifies that after changing the value of the |
| .B CLOCK_REALTIME |
| clock via |
| .BR clock_settime (2), |
| the new clock value shall be used to determine the time |
| at which a thread blocked on an absolute |
| .BR clock_nanosleep () |
| will wake up; |
| if the new clock value falls past the end of the sleep interval, then the |
| .BR clock_nanosleep () |
| call will return immediately. |
| .PP |
| POSIX.1 specifies that |
| changing the value of the |
| .B CLOCK_REALTIME |
| clock via |
| .BR clock_settime (2) |
| shall have no effect on a thread that is blocked on a relative |
| .BR clock_nanosleep (). |
| .SH SEE ALSO |
| .BR clock_getres (2), |
| .BR nanosleep (2), |
| .BR restart_syscall (2), |
| .BR timer_create (2), |
| .BR sleep (3), |
| .BR usleep (3), |
| .BR time (7) |
