Time::TAI64(3)

NAME
Time::TAI64 - Perl extension for converting TAI64 strings into standard unix timestamps.

SYNOPSIS
Generate TAI64 timestamps

  use Time::TAI64 qw/tai64n/;
  use Time::HiRes qw/time/;

  $now = time; # High precision
  printf "%s\n", unixtai64n($now);

Print out human readable logs

  use Time::TAI64 qw/:tai64n/;

  open FILE, "/var/log/multilog/stats";
  while(my $line = <FILE>) {
    my($tai,$log) = split(' ',$line,2);
    printf "%s %s",tai64nlocal($tai),$log;
  }
  close FILE;

DESCRIPTION
This is a package provides routines to convert TAI64 strings, like timestamps produced by multilog, into values that can be processed by other perl functions to display the timestamp in human-readable form and/or use in mathematical computations.

EXPORTS
In order to use any of these functions, they must be properly imported by using any of the following tags to use related functions:

:tai
    Generic Functions

tai2unix ( $tai_string )
    This method converts a tai64, tai64n, or tai64na string into a unix timestamp. If successfull, this function returns an integer value containing the number of seconds since Jan 1, 1970 as would perl's "time" function. If an error occurs, the function returns a 0.

tai2strftime ( $tai64_string, $format_string )
    This method converts the tai64, tai64n, or tai64na string given as its first parameter and, returns a formatted string of the converted timestamp as formatted by its second parameter using strftime conventions.

    If this second parameter is ommited, it defaults to "%a %b %d %H:%M:%S %Y" which should print the timestamp as: Mon Nov 1 12:00:00 2004

:tai64
    TAI64 Functions as well as Generic Functions

tai64unix ( $tai64_string )
    This method converts the tai64 string given as its only parameter and if successfull, returns a value for timestamp that is compatible with the value returned from "time".

unixtai64 ( timestamp )
    This method converts a unix timestamp into a TAI64 string.

:ta64n
    TAI64N Functions as well as Generic Functions

tai64nunix ( $tai64n_string )
    This method converts the tai64n string given as its only parameter and if successfull, returns a value for timestamp that is compatible with the value returned from "Time::HiRes::time".

unixtai64n ( timestamp )
unixtai64n ( seconds , nanoseconds )
    This methods returns a tai64n string using the parameters supplied by the user making the following assumptions:

    •   If seconds and nanoseconds are given, these values are used to compute the tai64n string. If nanoseconds evaluates to more than 1 second, the value of both seconds and nanoseconds are reevaluated. Both seconds and nanoseconds are assumed to be integers, any fractional part is truncated.

    •   If timestamp is an integer, nanoseconds is assumed to be 0.

    •   If timestamp is a "real" number, the integer part is used for the seconds and the fractional part is converted to nanoseconds.

tai64nlocal ( $tai64n_string )
    This utility returns a string representing the tai64n timestamp converted to local time in ISO format: YYYY-MM-DD HH:MM:SS.SSSSSSSSS.

    The reason to include this funtion is to provide compatibility with the command-line version included in daemontools.

:tai64na
    TAI64NA Functions as well as Generic Functions

tai64naunix ( $tai64na_string )
    This method converts the tai64na string given as its only parameter and if successfull, returns a value for timestamp that is compatible with the value returned from "Time::HiRes::time".

unixtai64na ( timestamp )
unixtai64na ( seconds , nanoseconds , attoseconds )
    This method returns a tai64na string unsing the parameters supplied by the user making the following assumptions:

    •   If seconds, nanoseconds and attoseconds are given, these values are used to compute the tai64na string. If either nanoseconds evaluates to more than 1 second, or attoseconds evaluates to more than 1 nanosecond, then seconds, nanoseconds, and attoseconds are reevaluated. These values are assumed to be integers, any fractional part is truncated.

    •   If timestamp is an integer, both nanoseconds and attoseconds are assumed to be 0.

    •   If timestamp is a "real" number, the integer part is used for the seconds and the fractional part is converted to nanoseconds amd attoseconds.

SEE ALSO
http://pobox.com/~djb/libtai/tai64.html

http://cr.yp.to/daemontools.html

AUTHOR
Jorge Valdes, <jorge@joval.info>

HISTORY
This module was started by AMS, but would not have been completed if Iain Truskett hadn't taken over. After his death, Jorge Valdes assumed ownership and rewrote it in Perl.

COPYRIGHT AND LICENSE
Copyright (C) 2004-2006 by Jorge Valdes

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.

AVAILABILITY
The lastest version of this library is likely to be available from CPAN.

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 439:
    You forgot a '=back' before '=head1'