NAME

       sleep - suspend execution for an interval of time

SYNOPSIS

       #include <unistd.h>

       unsigned sleep(unsigned seconds);

DESCRIPTION

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

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

       If a SIGALRM signal is generated for the calling  process  during  execution  of  sleep(),
       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 sleep() to return.

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

       Interactions   between   sleep()  and  any  of  setitimer(),  ualarm(),  or  usleep()  are
       unspecified.

RETURN VALUE

       If sleep() returns because the requested time has elapsed, the value returned shall be  0.
       If  sleep()  returns  due to delivery of a signal, the return value shall be the "unslept"
       amount (the requested time minus the time actually slept) in seconds.

ERRORS

       No errors are defined.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       There are two general approaches to the implementation of the sleep() function. One is  to
       use the alarm() function to schedule a SIGALRM signal and then suspend the process waiting
       for that signal. The other is  to  implement  an  independent  facility.  This  volume  of
       IEEE Std 1003.1-2001 permits either approach.

       In order to comply with the requirement that no primitive shall change a process attribute
       unless explicitly described by this  volume  of  IEEE Std 1003.1-2001,  an  implementation
       using  SIGALRM  must  carefully take into account any SIGALRM signal scheduled by previous
       alarm() calls, the action previously established for  SIGALRM,  and  whether  SIGALRM  was
       blocked. If a SIGALRM has been scheduled before the sleep() would ordinarily complete, the
       sleep() must be shortened to that time and a  SIGALRM  generated  (possibly  simulated  by
       direct  invocation  of  the signal-catching function) before sleep() returns. If a SIGALRM
       has been scheduled after the sleep() would ordinarily complete, it must be rescheduled for
       the  same  time  before sleep() returns. The action and blocking for SIGALRM must be saved
       and restored.

       Historical implementations often implement the SIGALRM-based  version  using  alarm()  and
       pause().  One  such implementation is prone to infinite hangups, as described in pause() .
       Another such implementation uses the C-language setjmp() and longjmp() functions to  avoid
       that  window.  That implementation introduces a different problem: when the SIGALRM signal
       interrupts a signal-catching function installed by the user to catch a  different  signal,
       the   longjmp()   aborts   that  signal-catching  function.  An  implementation  based  on
       sigprocmask(), alarm(), and sigsuspend() can avoid these problems.

       Despite  all  reasonable  care,  there  are  several  very  subtle,  but  detectable   and
       unavoidable,  differences  between  the  two types of implementations. These are the cases
       mentioned in this volume of IEEE Std 1003.1-2001 where some  other  activity  relating  to
       SIGALRM takes place, and the results are stated to be unspecified.  All of these cases are
       sufficiently unusual as not to be of concern to most applications.

       See also the discussion of the term realtime in alarm() .

       Since sleep() can be implemented using alarm(),  the  discussion  about  alarms  occurring
       early under alarm() applies to sleep() as well.

       Application writers should note that the type of the argument seconds and the return value
       of sleep() is unsigned. That means that a  Strictly  Conforming  POSIX  System  Interfaces
       Application  cannot pass a value greater than the minimum guaranteed value for {UINT_MAX},
       which the ISO C standard sets as 65535, and any application  passing  a  larger  value  is
       restricting   its   portability.   A   different   type  was  considered,  but  historical
       implementations, including those with a 16-bit int type, consistently use either  unsigned
       or int.

       Scheduling  delays may cause the process to return from the sleep() function significantly
       after the requested time. In such cases, the return value should be set to zero, since the
       formula  (requested  time  minus  the  time  actually  spent) yields a negative number and
       sleep() returns an unsigned.

FUTURE DIRECTIONS

       None.

SEE ALSO

       alarm() , getitimer() , nanosleep() , pause() , sigaction() ,  sigsetjmp()  ,  ualarm()  ,
       usleep() , 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 .