What is the UNIX timestamp?

Simply put, the UNIX timestamp (or just a 'timestamp') is how your computer tells time. Somewhat simplified, your computer basically keeps a count of each passing second, and stores that in as an integer.

More fully, the UNIX timestamp is the number of seconds (including leap seconds) from some arbitrary point in the past, namely 00:00:00 1 January, 1970 UTC. 'UTC', which stands for 'Universal Coordinated Time', happens to be the same as 'GMT' or solar time at the Royal Observatory in Greenwich, London.

You might recognize 1970 as near the dawn of the modern computing age, so it's kind of fitting that it is also referred to as the UNIX epoch.

So the UNIX timestamp 0 corresponds to the beginning of the UNIX epoch or midnight on 1 Jan, 1970. As I write this post the current timestamp is about 1534954799, time flies.

Go ahead and grab the current timestamp on your machine; open a terminal and use the date* command like so:

date +%s

date(1) when invoked with the format specifier %s should show your PC's current timestamp (this assumes a POSIX compliant shell of course).

* Here is the same thing on windows power shell, just for entertainment value:

[int][double]::Parse((Get-Date (get-date).touniversaltime() -UFormat %s))

To go the other direction, from a timestamp to a date/time string use one of the following:

# BSD/OSX
date -r 1534954799
# Linux
date -d @1534954799
Wed Aug 22 12:19:59 EDT 2018 

You will also find that most programming languages and date libraries have great support for working with the UNIX timestamp.

Why Use a Timestamp?

The first and probably most basic reason that computers use timestamps is, well computers. Keeping track of system time in a 16, 32 or 64bit value (or set of values for fractional seconds) is easy for most operating systems.

The choice of the UNIX timestamp as the way to track time on a POSIX compliant system also simplifies the task of coordinating time on different computers. All systems that keep track of the passage of time in a UNIX timestamp share the same timestamp, (theoretically anyway), regardless of where they are located on the planet.

Also note that a timestamp is both date and time in the sense that 'Date' corresponds to a calendar date and 'Time' corresponds to some point in a given 24 hour day with localization as well, 'UTC'. All this, contained in a simple number on PCs everywhere, all counting up to infinity at the same time, doomed to fail, but I digress :).

The Timestamp's Joys

You might begin to realize that as a software developer, storing date and time as a timestamp is rather convenient. This is especially true when working on larger systems that span time zones.

If we only need one second resolution, then the date and time that something occurred on our system can be represented and stored cleanly as a single integer value (signed of course, because there was time prior to 1970) in our database, log files or wherever.

The alternative requires us to capture some human readable date/time string (with time zone localization of course) and store that as a value. But fear not, there has been lots of standardization of date time strings over the years. This totally works, but has its own challenges.

Trials of Working with Timestamps

Timestamps are great for computers and any coordinated system, but they aren't that approachable for humans. So anyone working with timestamps needs to be aware of a couple of pitfalls. Once you grasp these you will come to love the timestamp.

Pitfall 1: Conversion to date/time

When working with time across different time zones using the UNIX timestamp can be very convenient. If it is 1534955931 in New York, it is 1534955931 in Berlin as well. However, when converting the timestamp to date/time (remember some format of calendar time and clock time) we must reference a time zone.

Since Berlin is 6 hours ahead of New York ('CEST' vs 'EDT' in New York presently) this must be accounted for when converting from a timestamp to either of the two locations above. So the same timestamp 1534955931 has the following two date/time representations for the two cities in our illustration:

Wed Aug 22 12:38:51 EDT 2018 # New York
Wed Aug 22 18:38:51 CEST 2018 # Berlin

The challenge of converting a timestamp to a local date/time is usually handled by your operating system. Your operating system has your current time zone stored somewhere and most commands like date(1) will access this value from the system environment or some other means. But when converting a timestamp to another locale, you need to either specify the target time zone or take the possible difference in time into account manually.

So remember, when you record a timestamp, the value is saved as UTC, but when you convert a timestamp to date/time the value needs to reference a time zone (sometimes defaults to local time, sometimes the default of 'UTC' is assumed).

Pitfall 2: Resolution

UNIX timestamps are usually represented as seconds. However most operating systems have much higher resolution than this. If you need higher resolution than one second, you will probably need to use an extended timestamp which contains a decimal portion that corresponds to fractional seconds.

Getting a timestamp with sub-second resolution is not really a problem, but you may find that some date libraries are limited here a touch or have different levels of resolution.

For example Javascript stores Numbers in 64bit format, so a floating point timestamp will have less resolution than you can get from a modern monotonic clock which returns time in as high as 128bit resolution. There are ways around this, but realize that when using date libraries and hi-res timestamps ymmv.

Pitfall 3: Synchronization

It is said that the man with a watch always knows what time it is, but the man with two watches is never sure.

The standardization of the UNIX timestamp is a great step toward offering a framework for coordinated time, but it leaves open the question of synchronization. Programmers usually have to rely on additional means to provide high accuracy time synchronization like the network time protocol (ntp).

If you are designing a distributed system that needs highly accurate time accounting, make sure you have some means in place to facilitate the synchronization of system time. NTP is usually a good choice but you will need to configure you system to use it in some cases.

Show and Tell

There are lots of times when something has been logged as a timestamp and I need a quick conversion to a human readable date/time string.

To simplify my life I created a simple utility to help me convert timestamps to the local time in my terminal and to do a few other cool things. There is not much magic to this, but I have found it to be really helpful.

Check it out and feel free to use it or share it if it was helpful.

I hope that you <3 the UNIX timestamp just a bit more from reading this.