huschi.net

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 (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  call-
       ing 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 execu-
       tion 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  execu-
       tion  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  sig-
       nal 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 sig-
       nal 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 sig-
       nal  and  then  suspend the calling thread waiting for that signal. The
       other  is  to  implement  an  independent  facility.  This  volume   of
       POSIX.1-2008 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
       POSIX.1-2008,  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 ordi-
       narily  complete,  the  sleep()  must  be  shortened to that time and a
       SIGALRM generated (possibly simulated by direct invocation of the  sig-
       nal-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 infi-
       nite hangups, as described in  pause().   Another  such  implementation
       uses the C-language setjmp() and longjmp() functions to avoid that win-
       dow. 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 imple-
       mentations.  These  are  the  cases  mentioned  in   this   volume   of
       POSIX.1-2008 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 developers should note that the type of the  argument  sec-
       onds  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()
       The Base Definitions volume of POSIX.1-2008, <unistd.h>
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri-
       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  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.unix.org/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.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                            SLEEP(3P)