---
name: time
signature: 'time'
since: 5.0
status: documented
categories: ["Time"]
---

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

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

# time

Return the current wall-clock time as an integer number of seconds
since the system epoch.

`time` is the starting point for every other date and time operation
in Perl. It reads the system clock and returns a single integer —
the number of non-leap seconds since the epoch, which on every
supported platform is `00:00:00 UTC, 1 January 1970` (Unix time).
The result is suitable for feeding directly to [`gmtime`](gmtime) or
[`localtime`](localtime) to break it down into a calendar date, or
for subtracting two readings to measure elapsed time.

## Synopsis

```perl
time
```

## What you get back

A plain integer: seconds since `1970-01-01 00:00:00 UTC`, truncated
(not rounded) toward zero. No sub-second precision — two calls within
the same second return the same value. For millisecond or microsecond
granularity, use `Time::HiRes::time`.

`time` takes no arguments; the bare word is the entire call. Writing
`time()` is also fine and sometimes clearer next to other function
calls.

## Examples

Raw reading of the clock:

```perl
my $now = time;
print "$now\n";                       # e.g. 1745424000
```

Human-readable local date and time — `time` pairs with
[`localtime`](localtime) in scalar context for a formatted string:

```perl
print scalar localtime, "\n";         # Wed Apr 23 12:00:00 2026
```

The same reading broken into fields for calendar arithmetic:

```perl
my ($sec, $min, $hour, $mday, $mon, $year) = localtime time;
$year += 1900;
$mon  += 1;
printf "%04d-%02d-%02d %02d:%02d:%02d\n",
       $year, $mon, $mday, $hour, $min, $sec;
```

Elapsed-time measurement around a block of work — the idiomatic
whole-second stopwatch:

```perl
my $t0 = time;
do_work();
my $elapsed = time - $t0;
print "took ${elapsed}s\n";
```

UTC rather than local time — feed the same integer to
[`gmtime`](gmtime):

```perl
my @utc = gmtime time;                # same fields, UTC-based
print scalar gmtime, "\n";            # Wed Apr 23 10:00:00 2026
```

## Edge cases

- **No sub-second resolution.** Back-to-back calls in the same
  second return the same integer, so `time - $t0` for fast work
  prints `0`. Use `Time::HiRes::time`
  for a floating-point reading with microsecond precision:

  ```perl
  use Time::HiRes qw(time);
  my $t0 = time;                      # now a float
  do_work();
  printf "%.6f s\n", time - $t0;
  ```

- **Leap seconds.** The returned count excludes leap seconds; it is
  POSIX "seconds since the epoch" as reported by the kernel. Code
  that subtracts two `time` readings measures wall-clock elapsed
  seconds, not SI seconds, across a leap-second boundary.
- **Integer width.** The value is a signed integer wide enough for
  current and far-future timestamps on all supported platforms
  (64-bit). The 2038 problem does not apply here.
- **Timezone.** `time` itself is timezone-agnostic — the integer
  names a single instant in UTC. Timezones only enter the picture
  when you convert via [`localtime`](localtime); `gmtime` stays in
  UTC.
- **Monotonicity.** `time` follows the system clock. If the clock
  is stepped backward (NTP adjustment, manual change), a later
  call may return a smaller value than an earlier one. For elapsed
  measurements that must not go backward, use a monotonic clock via
  `Time::HiRes::clock_gettime(CLOCK_MONOTONIC)`.
- **In arithmetic.** `time + 3600` is one hour from now; `time - 86400`
  is 24 hours ago. Feed the result to [`localtime`](localtime) or
  [`gmtime`](gmtime) to render it.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`gmtime`](gmtime) — break a `time` value into UTC calendar fields
  (or a formatted string in scalar context)
- [`localtime`](localtime) — same, but in the local timezone; the
  most common partner for `time`
- [`sleep`](sleep) — pause for a whole number of seconds; pairs
  naturally with `time` for coarse scheduling
- [`alarm`](alarm) — schedule a `SIGALRM` a given number of
  seconds in the future
- `Time::HiRes::time` — floating-point seconds with microsecond
  resolution when whole-second granularity is not enough