mirror of https://github.com/mkerrisk/man-pages
250 lines
6.5 KiB
Groff
250 lines
6.5 KiB
Groff
.\" 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-07-09 "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
|
|
Link with \fI\-lrt\fP.
|
|
.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 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 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.
|
|
|
|
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
|
|
.TP
|
|
.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 ()
|
|
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 (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.
|
|
|
|
.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 (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.
|
|
|
|
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 nanosleep (2),
|
|
.BR timer_create (2),
|
|
.BR clock_getres (2),
|
|
.BR sleep (3),
|
|
.BR usleep (3),
|
|
.BR time (7)
|