# sleep

## 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.
    


## 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.
    
           In single-threaded programs, _sleep_() may make use of SIGALRM. In
           multi-threaded programs, _sleep_() shall not make use of SIGALRM and
           the remainder of this DESCRIPTION does not apply.
    
           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 signal mask of the process
           is restored as part of the environment.
    
           Interactions between _sleep_() and _setitimer_() 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 calling thread waiting for
           that signal. The other is to implement an independent facility.
           This volume of POSIX.1‐2017 permits either approach in single-
           threaded programs, but the simple alarm/suspend implementation is
           not appropriate for multi-threaded programs.
    
           In order to comply with the requirement that no primitive shall
           change a process attribute unless explicitly described by this
           volume of POSIX.1‐2017, 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(3p).  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
           POSIX.1‐2017 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(3p).
    
           Since _sleep_() can be implemented using _alarm_(), the discussion
           about alarms occurring early under _alarm_() applies to _sleep_() as
           well.
    
           Application developers 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



           A future version of this standard may require that _sleep_() does
           not make use of SIGALRM in all programs, not just multi-threaded
           programs.
    


* * *