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 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 sig-
       nal 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 imple-
       mentations.   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 .

IEEE/The Open Group                  2003                            SLEEP(3P)