I've seen a lot of postings on blogs and mailing lists lately showing various functions for calculating/displaying epoch time using ColdFusion.

There are actually two popular variants of epoch - UNIX epoch and Java epoch. UNIX epoch or "UNIX time" is defined by Wikipedia as:

"Unix time, or POSIX time, is a system for describing points in time: it is the number of seconds elapsed since midnight UTC of January 1, 1970, not counting leap seconds. It is widely used not only on Unix-like operating systems but also in many other computing systems. It is neither a linear representation of time nor a true representation of UTC (though it is frequently mistaken for both) as the times it represents are UTC but it has no way of representing UTC leap seconds (e.g. 1998-12-31 23:59:60)."

As you can see, UNIX epoch is expressed as the number of seconds since midnight UTC on January 1, 1970. Java epoch is still based on the same origination date, however, it is expressed in milliseconds.

There are several ways you can get the UNIX/Java epoch time in ColdFusion including using Java, the getTickCount() function, or using dateDiff().

What's important to note here is that the number of seconds/milliseconds returned depends on the method you use and your server's timezone. Both the Java method and getTickCount() return values that are relative to your server's local time, not UTC, which may or may not be how you need it within your application. The dateDiff() function returns the number of seconds relative to UCT time, not your server's local time.

Let's take a look at a few examples to help clarify my point. The following code uses the three methods above. I've written a udf to wrap the dateDiff() function because I want a reusable way to package things and I also want to account for the server's UTC offset using the dateConvert() function:

view plain print about
1<cfscript>
2/**
3 * Returns the number of seconds since UTC January 1, 1970, 00:00:00 (Epoch time).
4 *
5 * @param DateTime      Date/time object you want converted to Epoch time. (Required)
6 * @return Returns a numeric value.
7 * @author Rob Brooks-Bilson (rbils@amkor.com)
8 * @version 1, June 21, 2002
9 */
10function GetEpochTimeFromLocal() {
11 var datetime = 0;
12 if ArrayLenn(Arguments) eq 0) {
13 datetime = Now();
14 }
15 else {
16 datetime = arguments[1];
17 }
18 return DateDiff("s", DateConvert("utc2Local", "January 1 1970 00:00"), datetime);
19}
20</cfscript>
21
22<!--- get epoch using getTickCount(). Note that result is in milliseconds --->
23<cfset x=getTickCount()>
24
25<!--- get epoch using java. Note that result is in milliseconds --->
26<cfset javaEpoch=now()>
27
28<table>
29<cfoutput>
30<tr>
31    <td>Java:</td>
32    <td>#int(javaEpoch.getTime()/1000)#</td>
33</tr>
34<tr>
35    <td>getTickCount():</td>
36    <td>#int(x/1000)#</td>
37</tr>    
38<tr>
39    <td>udf::</td>
40    <td> #GetEpochTimeFromLocal()#</td>
41</tr>
42</cfoutput>
43</table>

If you want to go from epoch to local ColdFusion server date/time, add the following code to the example:

view plain print about
1<cfset epochToLocal = DateAdd("s",getTick,DateConvert("utc2Local", "January 1 1970 00:00"))>
2
3<cfoutput>
4From epoch to date/time: #dateFormat(epochToLocal, 'mm/dd/yyyy')# #timeFormat(epochToLocal)#
5</cfoutput>

You should note that the getTickCount() only started returning Java epoch time as of ColdFusion MX 6.1. Prior to that, it returned a sequential number, but it wasn't epoch.

Here are two links to articles I wrote for the ColdFusion Cookbook that give further clarification:

Convert a date/time to epoch
convert epoch to a CF date/time object

Additionally, there are four UDFs on cflib for converting to/from epoch:

epochTimeToDate()
epochTimeToLocalDate()
getEpochTime()
getEpochTimeFromLocal
millisecondsToDate()
convertActiveDirectoryTime