---
name: sleep
signature: 'sleep EXPR'
since: 5.0
status: documented
categories: ["Processes"]
---

```{index} single: sleep; Perl built-in
```

*[Processes](../perlfunc-by-category)*

# sleep

Pause the process for a number of whole seconds.

`sleep` suspends execution of the current process for `EXPR` seconds,
or — with no argument — until a signal wakes it. The argument is
truncated to an integer; sub-second delays require a different tool
(see below). The return value is the number of seconds actually slept,
which can be less than requested if a signal interrupted the call.

## Synopsis

```perl
sleep EXPR
sleep
```

## What you get back

An integer: the number of seconds the process was actually suspended.
On an uninterrupted call this equals the (truncated) argument. If a
signal delivered during the sleep unblocks the call early, the return
value is the shorter, real elapsed time. For bare `sleep`, the value
is whatever the implementation slept before a signal arrived.

```perl
my $slept = sleep 10;
warn "woken early after $slept s" if $slept < 10;
```

## Argument handling

- **Positive integer** — the normal case. Sleep that many seconds.
- **Non-integer** (e.g. `2.9`) — the fractional part is **discarded**.
  `sleep 2.9` sleeps two seconds, not nearly three. For fractional
  delays use `Time::HiRes::sleep`, `Time::HiRes::usleep`, or the
  four-argument form of [`select`](select) — see below.
- **Negative integer** — `sleep` does **not** sleep. It emits a warning,
  sets [`$!`](../perlvar) (`errno`), and returns zero.
- **Zero** — `sleep 0` is permitted, but still performs a call into the
  underlying platform sleep primitive with whatever side effects that
  entails. It is therefore **not** exactly identical to skipping the
  call. In particular, `sleep 0` is not the same as a bare `sleep` with
  no argument.
- **No argument** — `sleep` with no argument sleeps indefinitely, until
  a signal is delivered. This is distinct from `sleep 0`.

## Interruption by signals

`sleep` returns early if the process receives a signal whose handler
runs (or whose default action does not terminate the process). The
canonical pattern for a bounded wait that can be cancelled from
elsewhere is an [`alarm`](alarm) combined with a signal handler:

```perl
eval {
    local $SIG{ALRM} = sub { die "Alarm!\n" };
    sleep;
};
die $@ unless $@ eq "Alarm!\n";
```

Because `sleep` is itself commonly implemented on top of [`alarm`](alarm)
on Unix systems, you generally **cannot** mix [`alarm`](alarm) and
`sleep` calls in the same program without surprises. Pick one.

## Sub-second delays

`sleep` is integer-only by design. For finer-grained waits use one of:

- `Time::HiRes::sleep($seconds)` — accepts a floating-point
  number of seconds. Since Perl 5.8 `Time::HiRes` ships with the core
  distribution.
- `Time::HiRes::usleep($microseconds)` — integer microseconds.
- The four-argument form of [`select`](select) with the first three
  arguments [`undef`](undef):

  ```perl
  select undef, undef, undef, 0.25;   # sleep 250 ms
  ```

- [`syscall`](syscall) into `setitimer(2)` if your platform supports
  it and you need tight control over timers.

See also `POSIX::pause`, which blocks the process until any signal
arrives — effectively a bare `sleep` without an implementation-defined
maximum.

## Examples

Fixed delay:

```perl
print "working...\n";
sleep 3;
print "done\n";
```

Poll loop with a back-off:

```perl
until (ready()) {
    sleep 1;
}
```

Detecting an early wake:

```perl
my $want = 30;
my $got  = sleep $want;
if ($got < $want) {
    warn "interrupted after $got of $want seconds\n";
}
```

Wait for a signal without burning CPU — bare `sleep` suspends until
`SIGALRM` (or any other caught signal) arrives:

```perl
$SIG{USR1} = sub { warn "got USR1\n" };
sleep;                                  # wakes on USR1 delivery
```

Cancelling a long wait with [`alarm`](alarm):

```perl
eval {
    local $SIG{ALRM} = sub { die "timeout\n" };
    alarm 5;
    sleep 3600;                         # at most 5 seconds really
    alarm 0;
};
alarm 0;
die $@ if $@ && $@ ne "timeout\n";
```

## Edge cases

- **Bare `sleep` does not truly sleep "forever"**. The implementation
  has a maximum — in practice, whatever the underlying C `sleep(3)` or
  equivalent accepts — but for all realistic purposes it blocks until
  a signal arrives. Treat it as an indefinite wait.
- **`sleep 0` ≠ no call**. The platform `sleep(0)` syscall still runs.
  On most systems this yields the CPU briefly; do not rely on the
  specific behaviour across platforms.
- **`sleep` versus wall-clock time**. On older systems `sleep` could
  return up to a full second *early* due to coarse second counting.
  Modern systems sleep the full amount, but may overshoot: the
  scheduler may not wake your process immediately on a busy system.
  `sleep N` guarantees *at least* `N` seconds of suspension on modern
  kernels, not *exactly* `N`.
- **Negative arguments are not clamped**. They are a hard no-op that
  sets [`$!`](../perlvar). If you compute the argument, validate it first.
- **Mixing with [`alarm`](alarm) is fragile**. The alarm timer and the
  sleep timer may be the same resource. Establish one discipline
  (either `alarm` + bare `sleep`, or plain `sleep N` without alarms)
  and stick to it within a program.
- **Signals that merely set a flag still wake `sleep`**. Any signal
  whose delivery causes a handler to run returns control to Perl;
  `sleep` then returns early even if the handler itself does nothing
  visible.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`alarm`](alarm) — schedule a `SIGALRM` after a given number of
  seconds; the classic way to bound a `sleep` or any other blocking
  call
- [`select`](select) — in its four-argument form with an undefined
  readfds/writefds/exceptfds triple, provides sub-second sleeps
- [`wait`](wait), [`waitpid`](waitpid) — block on child processes
  rather than on time
- `Time::HiRes::sleep` — floating-point seconds
- `Time::HiRes::usleep` — integer microseconds
- `POSIX::pause` — block until any signal arrives