=over

=item localtime EXPR

Converts a time as returned by the time function to a 9-element list
with the time analyzed for the local time zone.  Typically used as
follows:

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

All list elements are numeric, and come straight out of the C `struct
tm'.  $sec, $min, and $hour are the seconds, minutes, and hours of the
specified time.  $mday is the day of the month, and $mon is the month
itself, in the range C<0..11> with 0 indicating January and 11
indicating December.  $year is the number of years since 1900.  That
is, $year is C<123> in year 2023.  $wday is the day of the week, with
0 indicating Sunday and 3 indicating Wednesday.  $yday is the day of
the year, in the range C<0..364> (or C<0..365> in leap years.)  $isdst
is true if the specified time occurs during daylight savings time,
false otherwise.

Note that the $year element is I<not> simply the last two digits of
the year.  If you assume it is, then you create non-Y2K-compliant
programs--and you wouldn't want to do that, would you?

The proper way to get a complete 4-digit year is simply:

	$year += 1900;

And to get the last two digits of the year (e.g., '01' in 2001) do:

	$year = sprintf("%02d", $year % 100);

If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).

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

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

This scalar value is B<not> locale dependent but is a Perl builtin. For GMT
instead of local time use the L</gmtime> builtin. See also the
C<Time::Local> module (to convert the second, minutes, hours, ... back to
the integer value returned by time()), and the L<POSIX> module's strftime(3)
and mktime(3) functions.

To get somewhat similar but locale dependent date strings, set up your
locale environment variables appropriately (please see L<perllocale>) and
try for example:

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

Note that the 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.

=back