2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "USLEEP" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" usleep
|
2007-09-20 06:03:25 +00:00
|
|
|
.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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
2007-09-20 17:56:19 +00:00
|
|
|
\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
|
2004-11-03 13:51:07 +00:00
|
|
|
.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 .
|