👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for sleep (linux section 3posix)

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

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  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
       process' signal mask is restored as part of the environment.

       Interactions  between  sleep()  and any of setitimer(), ualarm(), or usleep() are unspeci-
       fied.

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 signal-catching function. An implementation based on sigproc-
       mask(), alarm(), and sigsuspend() can avoid these problems.

       Despite all reasonable care, there are several very subtle, but	detectable  and  unavoid-
       able,  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 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 implementa-
       tions, 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					 SLEEP(P)


All times are GMT -4. The time now is 01:56 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password