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.