diff options
Diffstat (limited to 'man/man2/nanosleep.2')
| -rw-r--r-- | man/man2/nanosleep.2 | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/man/man2/nanosleep.2 b/man/man2/nanosleep.2 new file mode 100644 index 000000000..e7132ee32 --- /dev/null +++ b/man/man2/nanosleep.2 @@ -0,0 +1,221 @@ +.\" Copyright (C) Markus Kuhn, 1996 +.\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> +.\" First version written +.\" Modified, 2004-10-24, aeb +.\" 2008-06-24, mtk +.\" Minor rewrites of some parts. +.\" NOTES: describe case where clock_nanosleep() can be preferable. +.\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP +.\" Replace crufty discussion of HZ with a pointer to time(7). +.TH nanosleep 2 (date) "Linux man-pages (unreleased)" +.SH NAME +nanosleep \- high-resolution sleep +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.P +.BI "int nanosleep(const struct timespec *" duration , +.BI " struct timespec *_Nullable " rem ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nanosleep (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR nanosleep () +suspends the execution of the calling thread +until either at least the time specified in +.I *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. +.P +If the call is interrupted by a signal handler, +.BR nanosleep () +returns \-1, sets +.I errno +to +.BR EINTR , +and writes the remaining time into the structure pointed to by +.I rem +unless +.I rem +is NULL. +The value of +.I *rem +can then be used to call +.BR nanosleep () +again and complete the specified pause (but see NOTES). +.P +The +.BR timespec (3) +structure +is used to specify intervals of time with nanosecond precision. +.P +The value of the nanoseconds field must be in the range [0, 999999999]. +.P +Compared to +.BR sleep (3) +and +.BR usleep (3), +.BR 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. +.SH RETURN VALUE +On successfully sleeping for the requested duration, +.BR nanosleep () +returns 0. +If the call is interrupted by a signal handler or encounters an error, +then it returns \-1, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Problem with copying information from user space. +.TP +.B EINTR +The pause has been interrupted by a signal that was +delivered to the thread (see +.BR signal (7)). +The remaining sleep time has been written +into +.I *rem +so that the thread can easily call +.BR nanosleep () +again and continue with the pause. +.TP +.B EINVAL +The value in the +.I tv_nsec +field was not in the range [0, 999999999] or +.I tv_sec +was negative. +.SH VERSIONS +POSIX.1 specifies that +.BR nanosleep () +should measure time against the +.B CLOCK_REALTIME +clock. +However, Linux measures the time using the +.B CLOCK_MONOTONIC +clock. +.\" See also http://thread.gmane.org/gmane.linux.kernel/696854/ +.\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME? +.\" Date: 2008-06-22 07:35:41 GMT +This probably does not matter, since the POSIX.1 specification for +.BR clock_settime (2) +says that discontinuous changes in +.B CLOCK_REALTIME +should not affect +.BR nanosleep (): +.RS +.P +Setting the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2) +shall +have no effect on threads that are blocked waiting for a relative time +service based upon this clock, including the +.BR nanosleep () +function; ... +Consequently, +these time services shall expire when the requested duration elapses, +independently of the new or old value of the clock. +.RE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +In order to support applications requiring much more precise pauses +(e.g., in order to control some time-critical hardware), +.BR nanosleep () +would handle pauses of up to 2 milliseconds by busy waiting with microsecond +precision when called from a thread scheduled under a real-time policy +like +.B SCHED_FIFO +or +.BR SCHED_RR . +This special extension was removed in Linux 2.5.39, +and is thus not available in Linux 2.6.0 and later kernels. +.SH NOTES +If the +.I duration +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. +.P +The fact that +.BR 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 +.BR clock_nanosleep (2) +with an absolute time value. +.SH BUGS +If a program that catches signals and uses +.BR 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 +.I remain +value mean that the +.I remain +value may steadily +.I increase +on successive restarts of the +.BR nanosleep () +call. +To avoid such problems, use +.BR clock_nanosleep (2) +with the +.B TIMER_ABSTIME +flag to sleep to an absolute deadline. +.P +In Linux 2.4, if +.BR nanosleep () +is stopped by a signal (e.g., +.BR SIGTSTP ), +then the call fails with the error +.B EINTR +after the thread is resumed by a +.B SIGCONT +signal. +If the system call is subsequently restarted, +then the time that the thread spent in the stopped state is +.I not +counted against the sleep interval. +This problem is fixed in Linux 2.6.0 and later kernels. +.SH SEE ALSO +.BR clock_nanosleep (2), +.BR restart_syscall (2), +.BR sched_setscheduler (2), +.BR timer_create (2), +.BR sleep (3), +.BR timespec (3), +.BR usleep (3), +.BR time (7) |