mirror of https://github.com/mkerrisk/man-pages
Remove crufty discussion of HZ, and replace with a pointer to time(7).
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=485636 Replace mentions of "process' by "thread". NOTES: describe case where clock_nanosleep() can be preferable. NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP See also http://thread.gmane.org/gmane.linux.kernel/696854/ "nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?" Some minor rewrites.
This commit is contained in:
parent
46f14bc7b0
commit
b0040075af
119
man2/nanosleep.2
119
man2/nanosleep.2
|
@ -1,6 +1,8 @@
|
||||||
.\" Hey Emacs! This file is -*- nroff -*- source.
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
||||||
.\"
|
.\"
|
||||||
.\" Copyright (C) Markus Kuhn, 1996
|
.\" Copyright (C) Markus Kuhn, 1996
|
||||||
|
.\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk
|
||||||
|
.\" <mtk.manpages@gmail.com>
|
||||||
.\"
|
.\"
|
||||||
.\" This is free documentation; you can redistribute it and/or
|
.\" This is free documentation; you can redistribute it and/or
|
||||||
.\" modify it under the terms of the GNU General Public License as
|
.\" modify it under the terms of the GNU General Public License as
|
||||||
|
@ -25,9 +27,14 @@
|
||||||
.\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
|
.\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
|
||||||
.\" First version written
|
.\" First version written
|
||||||
.\" Modified, 2004-10-24, aeb
|
.\" Modified, 2004-10-24, aeb
|
||||||
.TH NANOSLEEP 2 2007-07-26 "Linux" "Linux Programmer's Manual"
|
.\" 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 cruft discussion of HZ with a pointer tom time(7).
|
||||||
|
.TH NANOSLEEP 2 2008-06-24 "Linux" "Linux Programmer's Manual"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
nanosleep \- pause execution for a specified time
|
nanosleep \- high-resolution sleep
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.B #include <time.h>
|
.B #include <time.h>
|
||||||
.sp
|
.sp
|
||||||
|
@ -42,14 +49,18 @@ Feature Test Macro Requirements for glibc (see
|
||||||
_POSIX_C_SOURCE\ >=\ 199309L
|
_POSIX_C_SOURCE\ >=\ 199309L
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
.BR nanosleep ()
|
.BR nanosleep ()
|
||||||
delays the execution of the program for at least the time specified in
|
suspends the execution of the calling thread
|
||||||
.IR *req .
|
until either at least the time specified in
|
||||||
The function can return earlier if a signal has been delivered to the
|
.IR *req
|
||||||
process.
|
has elapsed, or the delivery of a signal
|
||||||
In this case, it returns \-1, sets \fIerrno\fP to
|
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,
|
||||||
|
.BR nanosleep ()
|
||||||
|
returns \-1, sets \fIerrno\fP to
|
||||||
.BR EINTR ,
|
.BR EINTR ,
|
||||||
and writes the
|
and writes the remaining time into the structure pointed to by
|
||||||
remaining time into the structure pointed to by
|
|
||||||
.I rem
|
.I rem
|
||||||
unless
|
unless
|
||||||
.I rem
|
.I rem
|
||||||
|
@ -58,15 +69,12 @@ The value of
|
||||||
.I *rem
|
.I *rem
|
||||||
can then be used to call
|
can then be used to call
|
||||||
.BR nanosleep ()
|
.BR nanosleep ()
|
||||||
again and complete the specified pause.
|
again and complete the specified pause (but see NOTES).
|
||||||
|
|
||||||
The structure
|
The structure
|
||||||
.I timespec
|
.I timespec
|
||||||
is used to specify intervals of time with nanosecond precision.
|
is used to specify intervals of time with nanosecond precision.
|
||||||
It is
|
It is defined as follows:
|
||||||
specified in
|
|
||||||
.I <time.h>
|
|
||||||
and has the form
|
|
||||||
.sp
|
.sp
|
||||||
.in +4n
|
.in +4n
|
||||||
.nf
|
.nf
|
||||||
|
@ -84,9 +92,12 @@ Compared to
|
||||||
and
|
and
|
||||||
.BR usleep (3),
|
.BR usleep (3),
|
||||||
.BR nanosleep ()
|
.BR nanosleep ()
|
||||||
has the advantage of not affecting any signals, it is standardized by
|
has the the following advantages:
|
||||||
POSIX, it provides higher timing resolution, and it allows to continue
|
it provides a higher resolution for specifying the sleep interval;
|
||||||
a sleep that has been interrupted by a signal more easily.
|
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"
|
.SH "RETURN VALUE"
|
||||||
On successfully sleeping for the requested interval,
|
On successfully sleeping for the requested interval,
|
||||||
.BR nanosleep ()
|
.BR nanosleep ()
|
||||||
|
@ -102,9 +113,9 @@ Problem with copying information from user space.
|
||||||
.TP
|
.TP
|
||||||
.B EINTR
|
.B EINTR
|
||||||
The pause has been interrupted by a non-blocked signal that was
|
The pause has been interrupted by a non-blocked signal that was
|
||||||
delivered to the process.
|
delivered to the thread.
|
||||||
The remaining sleep time has been written
|
The remaining sleep time has been written
|
||||||
into \fI*rem\fP so that the process can easily call
|
into \fI*rem\fP so that the thread can easily call
|
||||||
.BR nanosleep ()
|
.BR nanosleep ()
|
||||||
again and continue with the pause.
|
again and continue with the pause.
|
||||||
.TP
|
.TP
|
||||||
|
@ -117,25 +128,12 @@ was negative.
|
||||||
.SH "CONFORMING TO"
|
.SH "CONFORMING TO"
|
||||||
POSIX.1-2001.
|
POSIX.1-2001.
|
||||||
.SH BUGS
|
.SH BUGS
|
||||||
The current implementation of
|
|
||||||
.BR nanosleep ()
|
|
||||||
is based on the normal kernel timer mechanism, which has a resolution
|
|
||||||
of 1/\fIHZ\fP\ s (see
|
|
||||||
.BR time (7)).
|
|
||||||
Therefore,
|
|
||||||
.BR nanosleep ()
|
|
||||||
pauses always for at least the specified time, however it can take up
|
|
||||||
to 10 ms longer than specified until the process becomes runnable
|
|
||||||
again.
|
|
||||||
For the same reason, the value returned in case of a delivered
|
|
||||||
signal in \fI*rem\fP is usually rounded to the next larger multiple of
|
|
||||||
1/\fIHZ\fP\ s.
|
|
||||||
.SS "Old behavior"
|
.SS "Old behavior"
|
||||||
In order to support applications requiring much more precise pauses
|
In order to support applications requiring much more precise pauses
|
||||||
(e.g., in order to control some time-critical hardware),
|
(e.g., in order to control some time-critical hardware),
|
||||||
.BR nanosleep ()
|
.BR nanosleep ()
|
||||||
would handle pauses of up to 2\ ms by busy waiting with microsecond
|
would handle pauses of up to 2\ ms by busy waiting with microsecond
|
||||||
precision when called from a process scheduled under a real-time policy
|
precision when called from a thread scheduled under a real-time policy
|
||||||
like
|
like
|
||||||
.B SCHED_FIFO
|
.B SCHED_FIFO
|
||||||
or
|
or
|
||||||
|
@ -150,13 +148,64 @@ is stopped by a signal (e.g.,
|
||||||
.BR SIGTSTP ),
|
.BR SIGTSTP ),
|
||||||
then the call fails with the error
|
then the call fails with the error
|
||||||
.B EINTR
|
.B EINTR
|
||||||
after the process is resumed by a
|
after the thread is resumed by a
|
||||||
.B SIGCONT
|
.B SIGCONT
|
||||||
signal.
|
signal.
|
||||||
If the system call is subsequently restarted,
|
If the system call is subsequently restarted,
|
||||||
then the time that the process spent in the stopped state is
|
then the time that the thread spent in the stopped state is
|
||||||
\fInot\fP counted against the sleep interval.
|
\fInot\fP counted against the sleep interval.
|
||||||
|
.SH NOTES
|
||||||
|
If the interval specified in
|
||||||
|
.I req
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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 ()
|
||||||
|
says that discontinuous changes in
|
||||||
|
.B CLOCK_REALTIME
|
||||||
|
should not affect
|
||||||
|
.BR nanosleep ():
|
||||||
|
.RS
|
||||||
|
.PP
|
||||||
|
Setting the value of the
|
||||||
|
.B CLOCK_REALTIME
|
||||||
|
clock via
|
||||||
|
.BR clock_settime ()
|
||||||
|
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 relative
|
||||||
|
interval elapses, independently of the new or old value of the clock.
|
||||||
|
.RE
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
|
.BR clock_nanosleep (2),
|
||||||
.BR sched_setscheduler (2),
|
.BR sched_setscheduler (2),
|
||||||
.BR sleep (3),
|
.BR sleep (3),
|
||||||
.BR timer_create (3),
|
.BR timer_create (3),
|
||||||
|
|
Loading…
Reference in New Issue