=over

=item localtime EXPR
X<localtime> X<ctime>

=item localtime

Converts a time as returned by the time function to a 9-element list
with the time analyzed for the local time zone.  If EXPR is omitted,
L<C<localtime>|/localtime EXPR> uses the current time (as returned by
L<C<time>|/time>).

Typically used as follows:

    #     0    1    2     3     4    5     6     7     8
    my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                                localtime(time);

All list elements are numeric and come straight out of the C C<struct
tm>.  C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours
of the specified time.

C<$mday> is the day of the month in the range C<1..31> (i.e. 1-based).  C<$mon>
is the month in the range C<0..11> (i.e. 0-based), with 0 indicating January
and 11 indicating December.  This makes it easy to get a month name from a
list:

    my @abbr = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
    print "$abbr[$mon] $mday";
    # $mon=9, $mday=18 gives "Oct 18"

C<$year> contains the number of years since 1900 (e.g. C<129> for 2029).

C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating
Wednesday.  C<$yday> is the day of the year, in the range C<0..364>
(or C<0..365> in leap years.)

C<$isdst> is true if the specified time occurs when Daylight Saving
Time is in effect, false otherwise.

To get a human-readable date/time string, use L<POSIX/C<strftime>>:

    use POSIX qw(strftime);
    my @now = localtime;
    my $now_string = strftime "%Y-%m-%d %H:%M:%S", @now;
    # e.g. "2025-11-29 15:19:02"

To get just the year, you can use either L<POSIX/C<strftime>>:

    use POSIX qw(strftime);
    # full year:
    my $year = strftime "%Y", localtime;
    # just the last two digits of the year:
    my $ar = strftime "%y", localtime;

... or manual arithmetic:

    my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                                            localtime;
    # full year:
    $year += 1900;
    # just the last two digits of the year:
    my $ar = sprintf("%02d", $year % 100);

In scalar context, L<C<localtime>|/localtime EXPR> returns the
L<ctime(3)> value:

    my $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"

This scalar value is always in English, and is B<not> locale-dependent.
To get similar but locale-dependent date strings, try for example:

    use POSIX qw(strftime);
    my $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
    # or for GMT formatted appropriately for your locale:
    my $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;

C<$now_string> will be formatted according to the current LC_TIME locale
the program or thread is running in.  See L<perllocale> for how to set
up and change that locale.  Note that C<%a> and C<%b>, the short forms
of the day of the week and the month of the year, may not necessarily be
three characters wide.

The L<Time::gmtime> and L<Time::localtime> modules provide a convenient,
by-name access mechanism to the L<C<gmtime>|/gmtime EXPR> and
L<C<localtime>|/localtime EXPR> functions, respectively.

For a comprehensive date and time representation look at the
L<DateTime> module on CPAN.

For GMT instead of local time use the L<C<gmtime>|/gmtime EXPR> builtin.

See also the L<C<Time::Local>|Time::Local> module (for converting
seconds, minutes, hours, and such back to the integer value returned by
L<C<time>|/time>), and the L<POSIX> module's
L<C<mktime>|POSIX/C<mktime>> function.

Portability issues: L<perlport/localtime>.

=back