USLEEP(3P)                                          POSIX Programmer's Manual                                         USLEEP(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       usleep - suspend execution for an interval

SYNOPSIS
       #include <unistd.h>

       int usleep(useconds_t useconds);


DESCRIPTION
       The  usleep()  function shall cause the calling thread to be suspended from execution until either the number of realtime
       microseconds specified by the argument useconds 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.

       The useconds argument shall be less than one million. If the value of useconds is 0, then the call has no effect.

       If a SIGALRM signal is generated for the calling process during execution of usleep() and if the SIGALRM signal is  being
       ignored or blocked from delivery, it is unspecified whether usleep() returns when the SIGALRM signal is scheduled. If the
       signal is being blocked, it is also unspecified whether it remains pending after usleep() returns or it is discarded.

       If a SIGALRM signal is generated for the calling process during execution of usleep(), except as a result of a prior call
       to  alarm(), and if the SIGALRM signal is not being ignored or blocked from delivery, it is unspecified whether that sig-
       nal has any effect other than causing usleep() to return.

       If a signal-catching function interrupts usleep() 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.

       If a signal-catching function interrupts usleep() and calls siglongjmp() or longjmp() to  restore  an  environment  saved
       prior  to  the  usleep()  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.

       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.

       Interactions between usleep() and any of the following are unspecified:


              nanosleep()
              setitimer()
              timer_create()
              timer_delete()
              timer_getoverrun()
              timer_gettime()
              timer_settime()
              ualarm()
              sleep()

RETURN VALUE
       Upon successful completion, usleep() shall return 0; otherwise, it shall return -1 and set errno to indicate the error.

ERRORS
       The usleep() function may fail if:

       EINVAL The time interval specified one million or more microseconds.


       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       Applications  are  recommended  to  use  nanosleep()  if  the Timers option is supported, or setitimer(), timer_create(),
       timer_delete(), timer_getoverrun(), timer_gettime(), or timer_settime() instead of this function.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       alarm(), getitimer(), nanosleep(), sigaction(), sleep(), timer_create(),  timer_delete(),  timer_getoverrun(),  the  Base
       Definitions volume of IEEE Std 1003.1-2001, <unistd.h>

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,  Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                    USLEEP(3P)