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 signal 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, 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 .