mirror of https://github.com/mkerrisk/man-pages
Documents clock_nanosleep(2).
This commit is contained in:
parent
1b4cf8f4c7
commit
02afffe0fb
|
@ -0,0 +1,246 @@
|
|||
.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
|
||||
.\" <mtk.manpages@gmail.com>
|
||||
.\"
|
||||
.\" 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.
|
||||
.\"
|
||||
.TH CLOCK_NANOSLEEP 2 2008-06-26 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
clock_nanosleep \- high-resolution sleep with specifiable clock
|
||||
.SH SYNOPSIS
|
||||
.B #include <time.h>
|
||||
.nf
|
||||
.sp
|
||||
.BI "int clock_nanosleep(clockid_t " clock_id ", int " flags ,
|
||||
.BI " const struct timespec *" request ,
|
||||
.BI " struct timespec *" remain );
|
||||
.fi
|
||||
.sp
|
||||
.in -4n
|
||||
Feature Test Macro Requirements for glibc (see
|
||||
.BR feature_test_macros (7)):
|
||||
.in
|
||||
.sp
|
||||
.BR clock_nanosleep ():
|
||||
_XOPEN_SOURCE\ >=\ 600
|
||||
.SH DESCRIPTION
|
||||
Like
|
||||
.BR nanosleep (2),
|
||||
.BR clock_nanosleep ()
|
||||
allows allows the caller 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.
|
||||
|
||||
The time values passed to and returned by this call are specified using
|
||||
.I timespec
|
||||
structures, defined as follows:
|
||||
.sp
|
||||
.in +4n
|
||||
.nf
|
||||
struct timespec {
|
||||
time_t tv_sec; /* seconds */
|
||||
long tv_nsec; /* nanoseconds [0 .. 999999999] */
|
||||
};
|
||||
.fi
|
||||
.in
|
||||
|
||||
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 non-settable, 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 (3)
|
||||
for further details on these clocks.
|
||||
|
||||
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 .
|
||||
|
||||
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.
|
||||
|
||||
.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.
|
||||
|
||||
If the call is interrupted by a signal handler,
|
||||
.BR clock_nanosleep ()
|
||||
returns \-1, and sets
|
||||
.I errno
|
||||
to
|
||||
.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 a positive error number.
|
||||
.SH ERRORS
|
||||
.B EFAULT
|
||||
.I request
|
||||
or
|
||||
.I remain
|
||||
specified an invalid address.
|
||||
.TP
|
||||
.B EINTR
|
||||
The sleep was interrupted by a signal handler.
|
||||
.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 (2)
|
||||
system call first appeared in Linux 2.6.
|
||||
Support is available in glibc since version 2.1.
|
||||
.SH "CONFORMING TO"
|
||||
POSIX.1-2001.
|
||||
.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.
|
||||
|
||||
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 (3)
|
||||
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.
|
||||
|
||||
.BR clock_nanosleep ()
|
||||
is never restarted after being interrupted by a signal handler,
|
||||
regardless of the use of the
|
||||
.BR sigaction (2)
|
||||
.B SA_SIGACTION
|
||||
flag.
|
||||
|
||||
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.)
|
||||
|
||||
POSIX.1 specifies that
|
||||
.BR clock_nanosleep ()
|
||||
has no effect on signals dispositions or the signal mask.
|
||||
|
||||
POSIX.1 specifies that after changing the value of the
|
||||
.B CLOCK_REALTIME
|
||||
clock via
|
||||
.BR clock_settime (),
|
||||
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.
|
||||
|
||||
POSIX.1 specifies that
|
||||
changing the value of the
|
||||
.B CLOCK_REALTIME
|
||||
clock via
|
||||
.BR clock_settime ()
|
||||
shall have no effect on a thread that is blocked on a relative
|
||||
.BR clock_nanosleep ().
|
||||
.SH "SEE ALSO"
|
||||
.BR nanosleep (2),
|
||||
.BR clock_getres (3),
|
||||
.BR sleep (3),
|
||||
.BR timer_create (3),
|
||||
.BR usleep (3),
|
||||
.BR time (7)
|
Loading…
Reference in New Issue