::dmh::mktime UTC_seconds [delta_vector]* [format]
::dmh::mktime UTC_secs_usecs [delta_vector]* [format]
::dmh::mktime localtime_16 [delta_vector]* [format]
This command is used to convert dates from one format to another, as well as to add or subtract intervals from dates. There are four variations shown above depending on whether the time of interest is expressed as the POSIX count of seconds (localtime format 2), a POSIX count of seconds and microseconds (localtime format 11), a vector of values expressed for the local timezone (localtime default format), or a high resolution UTC timestamp "YYYY-MM-DD hh:mm:ss.uuuuuu" (localtime format 16).
A time_vector is a list of at least 6 integers ordered as Year Month Day Hour Minute Second. The values of the time vector are always understood to be for the localtime zone. If there are more than 6 list elements, the extras are ignored. The values should not have leading zeroes unless octal notation is intended.
The UTC_secs_usecs base time format accepts positive or negative microsecond values that are outside of the usual 0 to 999999 range. This feature is useful if you want to add or subtract some quantity of microseconds from a high resolution time value.
Optional delta_vector arguments are 6 element lists of integers whose values are added to the specified base time to compute a new time value.
The optional format code indicates the desired output format of the result. See the localtime command for format descriptions.
% set four_days_ago [mktime [localtime] "0 0 -4 0 0 0" 9]
2000-03-02 21:09:24
% set ts_gmt [mktime {952398574 889000} 16]
2000-03-07 03:09:34.889000
% mktime {2000-03-07 03:09:34.889000} 11
952398574 889000
% mktime {952398574 -2000} 15
2000-03-06 21:09:33.998000
The addition or subtraction of months or years lacks the precision of adding or subtracting only days, hours, minutes, and seconds since these intervals are not fixed. Also, you may wish to consider the behavior of your calculation if and when it encompasses a Daylight Saving Time change.
To determine the length of an interval between two dates, convert both dates to UTC seconds and subtract.
The range of validity is system dependent but typically only encompasses 1970 through 2036.
If the time cannot be successfully converted, an error is returned.