mirror of https://github.com/mkerrisk/man-pages
109 lines
4.1 KiB
Plaintext
109 lines
4.1 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "NANOSLEEP" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" nanosleep
|
|
.SH NAME
|
|
nanosleep \- high resolution sleep (\fBREALTIME\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <time.h>
|
|
.br
|
|
.sp
|
|
int nanosleep(const struct timespec *\fP\fIrqtp\fP\fB, struct timespec
|
|
*\fP\fIrmtp\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fInanosleep\fP() function shall cause the current thread to be
|
|
suspended from execution until either the time interval
|
|
specified by the \fIrqtp\fP argument has elapsed or a signal is delivered
|
|
to the calling thread, and its action is to invoke a
|
|
signal-catching function or to terminate the process. The suspension
|
|
time may be longer than requested because the argument value
|
|
is rounded up to an integer multiple of the sleep resolution or because
|
|
of the scheduling of other activity by the system. But,
|
|
except for the case of being interrupted by a signal, the suspension
|
|
time shall not be less than the time specified by \fIrqtp\fP,
|
|
as measured by the system clock CLOCK_REALTIME.
|
|
.LP
|
|
The use of the \fInanosleep\fP() function has no effect on the action
|
|
or blockage of any signal.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
If the \fInanosleep\fP() function returns because the requested time
|
|
has elapsed, its return value shall be zero.
|
|
.LP
|
|
If the \fInanosleep\fP() function returns because it has been interrupted
|
|
by a signal, it shall return a value of -1 and set
|
|
\fIerrno\fP to indicate the interruption. If the \fIrmtp\fP argument
|
|
is non-NULL, the \fBtimespec\fP structure referenced by it
|
|
is updated to contain the amount of time remaining in the interval
|
|
(the requested time minus the time actually slept). If the
|
|
\fIrmtp\fP argument is NULL, the remaining time is not returned.
|
|
.LP
|
|
If \fInanosleep\fP() fails, it shall return a value of -1 and set
|
|
\fIerrno\fP to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fInanosleep\fP() function shall fail if:
|
|
.TP 7
|
|
.B EINTR
|
|
The \fInanosleep\fP() function was interrupted by a signal.
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fIrqtp\fP argument specified a nanosecond value less than zero
|
|
or greater than or equal to 1000 million.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
It is common to suspend execution of a process for an interval in
|
|
order to poll the status of a non-interrupting function. A
|
|
large number of actual needs can be met with a simple extension to
|
|
\fIsleep\fP() that
|
|
provides finer resolution.
|
|
.LP
|
|
In the POSIX.1-1990 standard and SVR4, it is possible to implement
|
|
such a routine, but the frequency of wakeup is limited by the
|
|
resolution of the \fIalarm\fP() and \fIsleep\fP()
|
|
functions. In 4.3 BSD, it is possible to write such a routine using
|
|
no static storage and reserving no system facilities. Although
|
|
it is possible to write a function with similar functionality to \fIsleep\fP()
|
|
using the
|
|
remainder of the \fItimer_*\fP() functions, such a function requires
|
|
the use of signals
|
|
and the reservation of some signal number. This volume of IEEE\ Std\ 1003.1-2001
|
|
requires that \fInanosleep\fP() be
|
|
non-intrusive of the signals function.
|
|
.LP
|
|
The \fInanosleep\fP() function shall return a value of 0 on success
|
|
and -1 on failure or if interrupted. This latter case is
|
|
different from \fIsleep\fP(). This was done because the remaining
|
|
time is returned via an
|
|
argument structure pointer, \fIrmtp\fP, instead of as the return value.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIsleep\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<time.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|