.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "NANOSLEEP" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" nanosleep 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.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 .