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#

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.

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 — see below.
Negative integer — sleep does not sleep. It emits a warning, sets $! (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 combined with a signal handler:

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

Because sleep is itself commonly implemented on top of alarm on Unix systems, you generally cannot mix 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 with the first three arguments undef:
```
select undef, undef, undef, 0.25;   # sleep 250 ms
```
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:

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

Poll loop with a back-off:

until (ready()) {
    sleep 1;
}

Detecting an early wake:

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:

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

Cancelling a long wait with alarm:

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 $!. If you compute the argument, validate it first.
Mixing with 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.