SLEEP(3P)                                           POSIX Programmer's Manual                                          SLEEP(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
       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 sig-
       nal 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 sched-
       uled 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  sig-
       nal-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 guaran-
       teed  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, 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                                                     SLEEP(3P)