<html lang="en">
<head>
<title>Sleeping - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Date-and-Time.html#Date-and-Time" title="Date and Time">
<link rel="prev" href="Setting-an-Alarm.html#Setting-an-Alarm" title="Setting an Alarm">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Sleeping"></a>
<p>
Previous:&nbsp;<a rel="previous" accesskey="p" href="Setting-an-Alarm.html#Setting-an-Alarm">Setting an Alarm</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Date-and-Time.html#Date-and-Time">Date and Time</a>
<hr>
</div>

<h3 class="section">21.6 Sleeping</h3>

<p>The function <code>sleep</code> gives a simple way to make the program wait
for a short interval.  If your program doesn't use signals (except to
terminate), then you can expect <code>sleep</code> to wait reliably throughout
the specified interval.  Otherwise, <code>sleep</code> can return sooner if a
signal arrives; if you want to wait for a given interval regardless of
signals, use <code>select</code> (see <a href="Waiting-for-I_002fO.html#Waiting-for-I_002fO">Waiting for I/O</a>) and don't specify
any descriptors to wait for. 
<!-- !!! select can get EINTR; using SA_RESTART makes sleep win too. -->

<!-- unistd.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Function: unsigned int <b>sleep</b> (<var>unsigned int seconds</var>)<var><a name="index-sleep-2697"></a></var><br>
<blockquote><p>The <code>sleep</code> function waits for <var>seconds</var> or until a signal
is delivered, whichever happens first.

        <p>If <code>sleep</code> function returns because the requested interval is over,
it returns a value of zero.  If it returns because of delivery of a
signal, its return value is the remaining time in the sleep interval.

        <p>The <code>sleep</code> function is declared in <samp><span class="file">unistd.h</span></samp>. 
</p></blockquote></div>

   <p>Resist the temptation to implement a sleep for a fixed amount of time by
using the return value of <code>sleep</code>, when nonzero, to call
<code>sleep</code> again.  This will work with a certain amount of accuracy as
long as signals arrive infrequently.  But each signal can cause the
eventual wakeup time to be off by an additional second or so.  Suppose a
few signals happen to arrive in rapid succession by bad luck&mdash;there is
no limit on how much this could shorten or lengthen the wait.

   <p>Instead, compute the calendar time at which the program should stop
waiting, and keep trying to wait until that calendar time.  This won't
be off by more than a second.  With just a little more work, you can use
<code>select</code> and make the waiting period quite accurate.  (Of course,
heavy system load can cause additional unavoidable delays&mdash;unless the
machine is dedicated to one application, there is no way you can avoid
this.)

   <p>On some systems, <code>sleep</code> can do strange things if your program uses
<code>SIGALRM</code> explicitly.  Even if <code>SIGALRM</code> signals are being
ignored or blocked when <code>sleep</code> is called, <code>sleep</code> might
return prematurely on delivery of a <code>SIGALRM</code> signal.  If you have
established a handler for <code>SIGALRM</code> signals and a <code>SIGALRM</code>
signal is delivered while the process is sleeping, the action taken
might be just to cause <code>sleep</code> to return instead of invoking your
handler.  And, if <code>sleep</code> is interrupted by delivery of a signal
whose handler requests an alarm or alters the handling of <code>SIGALRM</code>,
this handler and <code>sleep</code> will interfere.

   <p>On the GNU system, it is safe to use <code>sleep</code> and <code>SIGALRM</code> in
the same program, because <code>sleep</code> does not work by means of
<code>SIGALRM</code>.

<!-- time.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Function: int <b>nanosleep</b> (<var>const struct timespec *requested_time, struct timespec *remaining</var>)<var><a name="index-nanosleep-2698"></a></var><br>
<blockquote><p>If resolution to seconds is not enough the <code>nanosleep</code> function can
be used.  As the name suggests the sleep interval can be specified in
nanoseconds.  The actual elapsed time of the sleep interval might be
longer since the system rounds the elapsed time you request up to the
next integer multiple of the actual resolution the system can deliver.

        <p>*<code>requested_time</code> is the elapsed time of the interval you want to
sleep.

        <p>The function returns as *<code>remaining</code> the elapsed time left in the
interval for which you requested to sleep.  If the interval completed
without getting interrupted by a signal, this is zero.

        <p><code>struct timespec</code> is described in See <a href="Elapsed-Time.html#Elapsed-Time">Elapsed Time</a>.

        <p>If the function returns because the interval is over the return value is
zero.  If the function returns -1 the global variable <var>errno</var>
is set to the following values:

          <dl>
<dt><code>EINTR</code><dd>The call was interrupted because a signal was delivered to the thread. 
If the <var>remaining</var> parameter is not the null pointer the structure
pointed to by <var>remaining</var> is updated to contain the remaining
elapsed time.

          <br><dt><code>EINVAL</code><dd>The nanosecond value in the <var>requested_time</var> parameter contains an
illegal value.  Either the value is negative or greater than or equal to
1000 million. 
</dl>

        <p>This function is a cancellation point in multi-threaded programs.  This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <code>nanosleep</code> is
called.  If the thread gets canceled these resources stay allocated
until the program ends.  To avoid this calls to <code>nanosleep</code> should
be protected using cancellation handlers. 
<!-- ref pthread_cleanup_push / pthread_cleanup_pop -->

        <p>The <code>nanosleep</code> function is declared in <samp><span class="file">time.h</span></samp>. 
</p></blockquote></div>

   </body></html>