# perldoc > Time::HiRes

---
type: CommandReference
command: Time::HiRes
mode: perldoc
section: 3
source: perldoc
---

## Quick Reference

- `use Time::HiRes qw(gettimeofday);` — get seconds and microseconds since epoch
- `usleep($microseconds)` — sleep for microseconds
- `nanosleep($nanoseconds)` — sleep for nanoseconds
- `sleep($floating_seconds)` — drop-in replacement for CORE::sleep with subsecond precision
- `alarm($floating_seconds)` — drop-in replacement for CORE::alarm with subsecond precision
- `setitimer($which, $seconds, $interval)` — start interval timer (ITIMER_REAL, ITIMER_VIRTUAL, ITIMER_PROF)
- `clock_gettime(CLOCK_REALTIME)` — get POSIX high-resolution timer value
- `stat("file")` — get file timestamps with subsecond resolution (if supported)

## Name

Time::HiRes — High resolution alarm, sleep, gettimeofday, interval timers

## Synopsis

perl
use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
                    clock_gettime clock_getres clock_nanosleep clock
                    stat lstat utime );

usleep ($microseconds);
nanosleep ($nanoseconds);

ualarm ($microseconds);
ualarm ($microseconds, $interval_microseconds);

$t0 = [gettimeofday];
($seconds, $microseconds) = gettimeofday;

$elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
$elapsed = tv_interval ( $t0, [gettimeofday]);
$elapsed = tv_interval ( $t0 );

use Time::HiRes qw ( time alarm sleep );

$now_fractions = time;
sleep ($floating_seconds);
alarm ($floating_seconds);
alarm ($floating_seconds, $floating_interval);

use Time::HiRes qw( setitimer getitimer );

setitimer ($which, $floating_seconds, $floating_interval );
getitimer ($which);

use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
                    ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF
                    ITIMER_REALPROF );

$realtime   = clock_gettime(CLOCK_REALTIME);
$resolution = clock_getres(CLOCK_REALTIME);

clock_nanosleep(CLOCK_REALTIME, 1.5e9);
clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);

my $ticktock = clock();

use Time::HiRes qw( stat lstat );

my @stat = stat("file");
my @stat = stat(FH);
my @stat = lstat("file");

use Time::HiRes qw( utime );
utime $floating_seconds, $floating_seconds, file...;
## Functions

### Time Functions

- `gettimeofday()` — In list context returns `($seconds, $microseconds)` since epoch. In scalar context returns floating seconds.
- `time()` — Returns floating seconds since epoch. Can be imported as a drop-in replacement for `CORE::time()`. Note: may be rounded up or down relative to core `time()` by up to 0.5 seconds.
- `tv_interval($ref_to_gettimeofday [, $ref_to_later_gettimeofday])` — Returns floating seconds between two times from `gettimeofday()`. If second argument omitted, uses current time.

### Sleeping Functions

- `usleep($useconds)` — Sleep for microseconds (millionths). Returns microseconds actually slept. Can sleep >1 second. Zero sleep acts as a thread yield.
- `nanosleep($nanoseconds)` — Sleep for nanoseconds. Returns nanoseconds actually slept (resolution to microseconds). Can sleep >1 second. Zero sleep acts as a thread yield.
- `sleep($floating_seconds)` — Sleep for specified seconds (floating point). Returns seconds actually slept. Drop-in replacement for `CORE::sleep()`.
- `clock_nanosleep($which, $nanoseconds, $flags)` — Sleep for nanoseconds using POSIX clock. `$flags` can be `TIMER_ABSTIME` for absolute time. Returns nanoseconds actually slept.

### Alarm/Timer Functions

- `ualarm($useconds [, $interval_useconds])` — Schedule a SIGALRM after `$useconds` microseconds, optionally repeating every `$interval_useconds`. Returns remaining time in microseconds or `undef` on error. `ualarm(0)` cancels.
- `alarm($floating_seconds [, $interval_floating_seconds])` — Schedule SIGALRM after `$floating_seconds` seconds. Implemented via `setitimer()` or `ualarm()`. Returns remaining time in seconds or `undef`. Drop-in replacement for `CORE::alarm()`.
- `setitimer($which, $floating_seconds [, $interval_floating_seconds])` — Start interval timer. `$which` is `ITIMER_REAL`, `ITIMER_VIRTUAL`, `ITIMER_PROF`, or `ITIMER_REALPROF`. Returns remaining time (scalar) or remaining and interval (list).
- `getitimer($which)` — Returns remaining time in the timer (scalar) or remaining and interval (list).

### Clock Functions

- `clock_gettime($which)` — Returns seconds of POSIX high-resolution timer (`CLOCK_REALTIME`, `CLOCK_MONOTONIC`, etc.).
- `clock_getres($which)` — Returns resolution (seconds) of the specified clock. Note: resolution may be optimistic.
- `clock()` — Returns process time (user+system) since first call to `clock()`. May wrap at ~2147 seconds (~36 minutes).

### File Timestamp Functions

- `stat` / `lstat` — Override `CORE::stat`/`CORE::lstat` to return subsecond timestamps (access, modify, change) if OS and filesystem support. Check `&Time::HiRes::d_hires_stat` for OS support.
- `utime LIST` — Override `CORE::utime` to set access/modify timestamps with subsecond resolution. Check `&Time::HiRes::d_hires_utime` for OS support. Passing `undef` for both atime and mtime calls syscall with NULL.

## Examples

perl
use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);

# Sleep for 750ms
usleep(750_000);

# Alarm in 2.5s, then every 0.1s
ualarm(2_500_000, 100_000);
# Cancel
ualarm(0);

# Get epoch time
($s, $usec) = gettimeofday();

# Measure elapsed time
$t0 = [gettimeofday];
# ... do stuff ...
$t1 = [gettimeofday];
$t0_t1 = tv_interval $t0, $t1;

# Using imported time, sleep, alarm
use Time::HiRes qw( time alarm sleep );
$now = time;
sleep(2.5);
alarm(10.6666666);

# Interval timer
use Time::HiRes qw( setitimer ITIMER_VIRTUAL time );
$SIG{VTALRM} = sub { print time, "\n" };
setitimer(ITIMER_VIRTUAL, 10, 2.5);

# POSIX high-resolution clock
use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
my $high = clock_gettime(CLOCK_REALTIME);
my $reso = clock_getres(CLOCK_REALTIME);

# Absolute sleep
use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
clock_nanosleep(CLOCK_REALTIME, 1e6);
clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);

# Process time
use Time::HiRes qw( clock );
my $c0 = clock();
# ... do something ...
my $cd = clock() - $c0;

# File timestamps
use Time::HiRes qw( stat );
my ($atime, $mtime, $ctime) = (stat("istics"))[8,9,10];
## C API

The module provides C functions for extension writers via `PL_modglobal`:

- `Time::NVtime` — `NV (*)()` — returns current time as NV (floating seconds).
- `Time::U2time` — `void (*)(pTHX_ UV ret[2])` — returns seconds and microseconds as UV array.

Example:

c
NV (*myNVtime)();
SV **svp = hv_fetchs(PL_modglobal, "Time::NVtime", 0);
if (!svp) croak("Time::HiRes is required");
myNVtime = INT2PTR(NV(*)(), SvIV(*svp));
printf("Time: %" NVff "\n", (*myNVtime)());
## Caveats

- Core `time()` may be rounding rather than truncating, causing a difference of up to 0.5 seconds from `Time::HiRes::time()`.
- System clock adjustments (e.g., NTP) can cause non-monotonic time. On Win32, `Time::HiRes::time()` may drift up to 0.5 seconds but recalibrates. Use `CLOCK_MONOTONIC` if available.
- Not all systems implement all functions; check `&Time::HiRes::d_nanosleep`, `&Time::HiRes::d_hires_stat`, etc.
- Subsecond resolution of file timestamps depends on OS and filesystem (e.g., NTFS supports, FAT does not).
- Interaction between alarms and sleeps is unspecified (may interfere).
- Interval timers on some systems may be non-functional (e.g., QNX, Haiku).
- On macOS pre-10.12, `clock_gettime`, `clock_getres`, `clock_nanosleep` are emulated via Mach timers; `CLOCK_REALTIME` and `CLOCK_MONOTONIC` are identical.

## Diagnostics

- `useconds or interval more than ...` — `ualarm()` with values >1,000,000 when `setitimer()` unavailable.
- `negative time not invented yet` — negative time argument.
- `internal error: useconds < 0` — compiler bug or overflow.
- `useconds or uinterval equal to or more than 1000000` — platform limitation.
- `unimplemented in this platform` — function not available.

## See Also

- [BSD::Resource](https://metacpan.org/pod/BSD::Resource)
- [Time::TAI64](https://metacpan.org/pod/Time::TAI64)
- Your system documentation for `clock(3)`, `clock_gettime(2)`, `clock_getres(3)`, `clock_nanosleep(3)`, `clock_settime(3)`