### 22.7 Sleeping ¶

The function `sleep` 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 `sleep` to wait reliably throughout the specified interval. Otherwise, `sleep` can return sooner if a signal arrives; if you want to wait for a given interval regardless of signals, use `select` (see Waiting for Input or Output) and don’t specify any descriptors to wait for.

Function: `unsigned int` sleep `(unsigned int seconds)` ¶

  Preliminary: | MT-Unsafe sig:SIGCHLD/linux | AS-Unsafe | AC-Unsafe | See POSIX Safety Concepts.

  The `sleep` function waits for seconds seconds or until a signal is delivered, whichever happens first.

  If `sleep` 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.

  The `sleep` function is declared in `unistd.h`.

Resist the temptation to implement a sleep for a fixed amount of time by using the return value of `sleep`, when nonzero, to call `sleep` 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—there is no limit on how much this could shorten or lengthen the wait.

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 `select` and make the waiting period quite accurate. (Of course, heavy system load can cause additional unavoidable delays—unless the machine is dedicated to one application, there is no way you can avoid this.)

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

On GNU systems, it is safe to use `sleep` and `SIGALRM` in the same program, because `sleep` does not work by means of `SIGALRM`.

Function: `int` nanosleep `(const struct timespec *requested_time, struct timespec *remaining_time)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  If resolution to seconds is not enough, the `nanosleep` 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.

  `*requested_time` is the elapsed time of the interval you want to sleep.

  If remaining_time is not the null pointer, the function returns as `*remaining_time` 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.

  `struct timespec` is described in Time Types.

  If the function returns because the interval is over, it returns zero. Otherwise it returns -1 and sets the global variable `errno` to one of the following values:

  `EINTR`

    The call was interrupted because a signal was delivered to the thread. If the remaining_time parameter is not the null pointer, the structure pointed to by remaining_time is updated to contain the remaining elapsed time.

  `EINVAL`

    The nanosecond value in the requested_time parameter contains an invalid value. Either the value is negative or greater than or equal to 1000 million.

  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 `nanosleep` is called. If the thread gets canceled, these resources stay allocated until the program ends. To avoid this, calls to `nanosleep` should be protected using cancellation handlers.

  The `nanosleep` function is declared in `time.h`.

Function: `int` clock_nanosleep `(clockid_t clock, int flags, const struct timespec *requested_time, struct timespec *remaining_time)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function is similar to `nanosleep` while additionally providing the caller with a way to specify the clock to be used to measure elapsed time and express the sleep interval in absolute or relative terms. It returns zero when returning because the interval is over, and a positive error number corresponding to the error encountered otherwise. This is different from `nanosleep`, which returns -1 upon failure and sets the global variable `errno` according to the error encountered instead.

  Except for the return value convention and the way to communicate an error condition the call:

      nanosleep (requested_time, remaining_time)

  is analogous to:

      clock_nanosleep (CLOCK_REALTIME, 0, requested_time, remaining_time)

  The clock argument specifies the clock to use. See Getting the Time, for the `clockid_t` type and possible values of clock. Not all clocks listed are supported for use with `clock_nanosleep`. For details, see the manual page clock_nanosleep(2) See Linux (The Linux Kernel).

  The flags argument is either `0` or `TIMER_ABSTIME`. If flags is `0`, then `clock_nanosleep` interprets requested_time as an interval relative to the current time specified by clock. If it is `TIMER_ABSTIME` instead, requested_time specifies an absolute time measured by clock; if at the time of the call the value requested is less than or equal to the clock specified, then the function returns right away. When flags is `TIMER_ABSTIME`, remaining_time is not updated.

  The `clock_nanosleep` function returns error codes as positive return values. The error conditions for `clock_nanosleep` are the same as for `nanosleep`, with the following conditions additionally defined:

  `EINVAL`

    The clock argument is not a valid clock.

  `EOPNOTSUPP`

    The clock argument is not supported by the kernel for `clock_nanosleep`.

  The `clock_nanosleep` function is declared in `time.h`.