=encoding utf8
=head1 NAME
POSIX::1003::Time - POSIX handling time
=head1 SYNOPSIS
use POSIX::1003::Time;
tzset(); # set-up local timezone from $ENV{TZ}
($std, $dst) = tzname; # timezone abbreviations
$str = ctime($timestamp); # is equivalent to:
$str = asctime(localtime($timestamp))
$str = strftime("%A, %B %d, %Y", 0, 0, 0, 12, 11, 95, 2);
$str = strftime("%A, %B %d, %Y", {day => 12, month => 12
, year => 1995, wday => 2});
# $str contains "Tuesday, December 12, 1995"
$timestamp = mktime(0, 30, 10, 12, 11, 95);
$timestamp = mktime {min => 30, hour => 10, day => 12
, month => 12, year => 1995};
print "Date = ", ctime($timestamp);
print scalar localtime;
my $year = (localtime)[5] + 1900;
$timespan = difftime($end, $begin);
=head1 DESCRIPTION
=head1 FUNCTIONS
=head2 Standard POSIX
B<Warning:> the functions L<asctime()|POSIX::1003::Time/"Standard POSIX">, L<mktime()|POSIX::1003::Time/"Standard POSIX">, and L<strftime()|POSIX::1003::Time/"Standard POSIX">
share a weird complex encoding with L<localtime()|POSIX::1003::Time/"Standard POSIX"> and L<gmtime()|POSIX::1003::Time/"Standard POSIX">:
the month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at
zero. I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0,
not 1. The year (C<year>) is given in years since 1900. I.e., the year
1995 is 95; the year 2001 is 101.
=over 4
=item B<asctime>($sec, $min, $hour, $mday, $mon, $year, ...)
The C<asctime> function uses C<strftime> with a fixed format, to produce
timestamps with a trailing new-line. Example:
"Sun Sep 16 01:03:52 1973\n"
The parameter order is the same as for L<strftime()|POSIX::1003::Time/"Standard POSIX"> without its C<$format>
parameter:
my $str = asctime($sec, $min, $hour, $mday, $mon, $year,
$wday, $yday, $isdst);
=item B<clock>()
The amount of spent processor time in microseconds.
=item B<ctime>($timestamp)
# equivalent
my $str = ctime $timestamp;
my $str = asctime localtime $timestamp;
=item B<difftime>($timestamp, $timestamp)
Difference between two TIMESTAMPs, which are floats.
$timespan = difftime($end, $begin);
=item B<gmtime>( [$time] )
Simply L<perlfunc/gmtime>
=item B<localtime>( [$time] )
Simply L<perlfunc/localtime>
=item B<mktime>(@tm|\%date)
Convert date/time info to a calendar time. Returns "undef" on failure.
# Calendar time for December 12, 1995, at 10:30 am
my $ts = mktime 0, 30, 10, 12, 11, 95;
print "Date = ", ctime($ts);
my %tm = (min => 30, hour => 10, day => 12, month => 12, year => 1995);
my $ts = mktime \%tm; # %tm will get updated, mday and yday added
=item B<strftime>($format, @tm|\%date)
The formatting of C<strftime> is extremely flexible but the parameters
are quite tricky. Read carefully!
my $str = strftime($fmt, $sec, $min, $hour,
$mday, $mon, $year, $wday, $yday, $isdst);
my $str = strftime($fmt, {month => 12, year => 2015};
If you want your code to be portable, your $format argument
should use only the conversion specifiers defined by the ANSI C
standard (C89, to play safe). These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
But even then, the results of some of the conversion specifiers are
non-portable.
[0.95_5] This implementation of C<strftime()> is character-set aware,
even when the LC_TIME table does not match the type of the format string.
=item B<strptime>($timestring, $format)
Translate the TIMESTRING into a time-stamp (seconds since epoch).
The $format describes how the $timestring should be interpreted.
Returned is a HASH with the usefull data from the 'tm' structure (as
described in the standard strptime manual page) The keys are stripped
from the C<tm_> prefix.
example:
# traditional interface
my ($sec, $min, ...) = strptime "12:24", "%H:%S";
# date as hash
my $tm = strptime "12:24", "%H:%S";
print "$tm->{hour}/$tm->{min}\n";
my $time = mktime $tm;
=item B<tzname>()
Returns the strings to be used to represent Standard time (STD)
respectively Daylight Savings Time (DST).
tzset();
my ($std, $dst) = tzname;
=item B<tzset>()
Set-up local timezone from C<$ENV{TZ}> and the OS.
=back
=head1 CONSTANTS
=for comment
#TABLE_TIME_START
The constant names for this module are inserted here during
installation.
=for comment
#TABLE_TIME_END
=head1 SEE ALSO
This module is part of POSIX-1003 distribution version 1.02,
built on November 10, 2020. Website: F<http://perl.overmeer.net/CPAN>. The code is based on L<POSIX>, which
is released with Perl itself. See also L<POSIX::Util> for
additional functionality.
=head1 COPYRIGHTS
Copyrights 2011-2020 on the perl code and the related documentation
by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>