SLEEP(3)                   POSIX Programmer's Manual                  SLEEP(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       sleep -- suspend execution for an interval of time

SSYYNNOOPPSSIISS
       #include <unistd.h>

       unsigned sleep(unsigned _s_e_c_o_n_d_s);

DDEESSCCRRIIPPTTIIOONN
       The _s_l_e_e_p() function shall cause the calling thread to be suspended
       from execution until either the number of realtime seconds specified by
       the argument _s_e_c_o_n_d_s 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, _s_l_e_e_p() may make use of SIGALRM. In multi-
       threaded programs, _s_l_e_e_p() 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 _s_l_e_e_p() and if the SIGALRM signal is being ignored or
       blocked from delivery, it is unspecified whether _s_l_e_e_p() returns when
       the SIGALRM signal is scheduled. If the signal is being blocked, it is
       also unspecified whether it remains pending after _s_l_e_e_p() returns or it
       is discarded.

       If a SIGALRM signal is generated for the calling process during
       execution of _s_l_e_e_p(), except as a result of a prior call to _a_l_a_r_m(),
       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 _s_l_e_e_p() to return.

       If a signal-catching function interrupts _s_l_e_e_p() 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 _s_l_e_e_p() and calls _s_i_g_l_o_n_g_j_m_p()
       or _l_o_n_g_j_m_p() to restore an environment saved prior to the _s_l_e_e_p() 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 _s_l_e_e_p() and _s_e_t_i_t_i_m_e_r() are unspecified.

RREETTUURRNN VVAALLUUEE
       If _s_l_e_e_p() returns because the requested time has elapsed, the value
       returned shall be 0. If _s_l_e_e_p() 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.

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       There are two general approaches to the implementation of the _s_l_e_e_p()
       function. One is to use the _a_l_a_r_m() 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 _a_l_a_r_m() calls, the
       action previously established for SIGALRM, and whether SIGALRM was
       blocked. If a SIGALRM has been scheduled before the _s_l_e_e_p() would
       ordinarily complete, the _s_l_e_e_p() must be shortened to that time and a
       SIGALRM generated (possibly simulated by direct invocation of the
       signal-catching function) before _s_l_e_e_p() returns. If a SIGALRM has been
       scheduled after the _s_l_e_e_p() would ordinarily complete, it must be
       rescheduled for the same time before _s_l_e_e_p() returns. The action and
       blocking for SIGALRM must be saved and restored.

       Historical implementations often implement the SIGALRM-based version
       using _a_l_a_r_m() and _p_a_u_s_e().  One such implementation is prone to
       infinite hangups, as described in _p_a_u_s_e().  Another such implementation
       uses the C-language _s_e_t_j_m_p() and _l_o_n_g_j_m_p() 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 _l_o_n_g_j_m_p() aborts that signal-
       catching function. An implementation based on _s_i_g_p_r_o_c_m_a_s_k(), _a_l_a_r_m(),
       and _s_i_g_s_u_s_p_e_n_d() 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 _r_e_a_l_t_i_m_e in _a_l_a_r_m().

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

       Application developers should note that the type of the argument
       _s_e_c_o_n_d_s and the return value of _s_l_e_e_p() is uunnssiiggnneedd.  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 iinntt type,
       consistently use either uunnssiiggnneedd or iinntt.

       Scheduling delays may cause the process to return from the _s_l_e_e_p()
       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 _s_l_e_e_p()
       returns an uunnssiiggnneedd.

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

SSEEEE AALLSSOO
       _a_l_a_r_m(), _g_e_t_i_t_i_m_e_r(), _n_a_n_o_s_l_e_e_p(), _p_a_u_s_e(), _s_i_g_a_c_t_i_o_n(), _s_i_g_s_e_t_j_m_p()

       The Base Definitions volume of POSIX.1-2017, <<uunniissttdd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                             SLEEP(3)
