.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "USLEEP" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" usleep 
.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
usleep \- suspend execution for an interval
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
int usleep(useconds_t\fP \fIuseconds\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIusleep\fP() function shall cause the calling thread to be suspended
from execution until either the number of realtime
microseconds specified by the argument \fIuseconds\fP 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 due to the
scheduling of other activity by the system.
.LP
The \fIuseconds\fP argument shall be less than one million. If the
value of \fIuseconds\fP is 0, then the call has no
effect.
.LP
If a SIGALRM signal is generated for the calling process during execution
of \fIusleep\fP() and if the SIGALRM signal is being
ignored or blocked from delivery, it is unspecified whether \fIusleep\fP()
returns when the SIGALRM signal is scheduled. If the
signal is being blocked, it is also unspecified whether it remains
pending after \fIusleep\fP() returns or it is discarded.
.LP
If a SIGALRM signal is generated for the calling process during execution
of \fIusleep\fP(), except as a result of a prior call
to \fIalarm\fP(), and if the SIGALRM signal is not being ignored or
blocked from delivery,
it is unspecified whether that signal has any effect other than causing
\fIusleep\fP() to return.
.LP
If a signal-catching function interrupts \fIusleep\fP() and examines
or changes either the time a SIGALRM is scheduled to be
generated, the action associated with the SIGALRM signal, or whether
the SIGALRM signal is blocked from delivery, the results are
unspecified.
.LP
If a signal-catching function interrupts \fIusleep\fP() and calls
\fIsiglongjmp\fP() or \fIlongjmp\fP() to restore an
environment saved prior to the \fIusleep\fP() call, the action associated
with the SIGALRM signal and the time at which a SIGALRM
signal is scheduled to be generated are unspecified. It is also unspecified
whether the SIGALRM signal is blocked, unless the
process' signal mask is restored as part of the environment.
.LP
Implementations may place limitations on the granularity of timer
values. For each interval timer, if the requested timer value
requires a finer granularity than the implementation supports, the
actual timer value shall be rounded up to the next supported
value.
.LP
Interactions between \fIusleep\fP() and any of the following are unspecified:
.sp
.RS
.nf

\fInanosleep\fP()
\fIsetitimer\fP()
\fItimer_create\fP()
\fItimer_delete\fP()
\fItimer_getoverrun\fP()
\fItimer_gettime\fP()
\fItimer_settime\fP()
\fIualarm\fP()
\fIsleep\fP()
.fi
.RE
.SH RETURN VALUE
.LP
Upon successful completion, \fIusleep\fP() shall return 0; otherwise,
it shall return -1 and set \fIerrno\fP to indicate the
error.
.SH ERRORS
.LP
The \fIusleep\fP() function may fail if:
.TP 7
.B EINVAL
The time interval specified one million or more microseconds.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
Applications are recommended to use \fInanosleep\fP() if the Timers
option is
supported, or \fIsetitimer\fP(), \fItimer_create\fP(), \fItimer_delete\fP(),
\fItimer_getoverrun\fP(), \fItimer_gettime\fP(), or \fItimer_settime\fP()
instead of this function.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIalarm\fP(), \fIgetitimer\fP(), \fInanosleep\fP(), \fIsigaction\fP(),
\fIsleep\fP(),
\fItimer_create\fP(), \fItimer_delete\fP(), \fItimer_getoverrun\fP(),
the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<unistd.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 .