DEV Community


Posted on

Level up: UNIX Timestamp

UNIX Timestamp

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
Enter fullscreen mode Exit fullscreen mode

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))
Enter fullscreen mode Exit fullscreen mode

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

date -r 1534954799
# Linux
date -d @1534954799
Wed Aug 22 12:19:59 EDT 2018 
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

GitHub logo KalenAnson / tsc

UNIX Timestamp Utility


tsc is a simple UNIX Timestamp utility for the shell. It can get the current UNIX timestamp, convert a timestamp into localized time and diff timestamps.


  1. Get current UNIX timestamp: (I realize this is trivial with date(1), but how often have you googled this.)

     $ tsc
  2. Convert timestamp to local time:

     $ tsc 1534950044
     1534950044 -> Wed Aug 22 11:00:44 EDT 2018

    tsc also accepts input from stdin in same format as its arguments (timestamp timestamp ...)

     $ echo 1534947844 | tsc
     1534947844 -> Wed Aug 22 10:24:04 EDT 2018
  3. Diff timestamps (calculates the duration of the smallest and the greatest arguments):

     $ tsc 1534947844 1534947904
     1534947844 -> Wed Aug 22 10:24:04 EDT 2018
     1534947904 -> Wed Aug 22 10:25:04 EDT 2018
     Duration: 00:01:00

    tsc is also a first class utility, so it plays nicely with pipelines. Here we diff a timestamp and 'now'…

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

Top comments (5)

tux0r profile image
date -r 1534954799

That also works on Solaris (illumos). :-) It might be interesting to know that there were several revisions of the "timestamp" before it had its latest form.

And most systems should have 64-bit time_t now ... because the old 32-bit timestamp will overflow soon.

qm3ster profile image
Mihail Malo

I often see people recommend ISO 8601 instead, but I really fail to see why.
I am even being ignored on stackoverflow as we speak.

jrop profile image
Jonathan Apodaca

UNIX timestamps are such a beautiful thing. I just learned about a week ago that, Excel stores dates/times using it's own timestamp, relative to its own epoch, and has several bugs :(

ghost profile image

I've run into a few other timestamp implementations as well.

An embedded device manufacturer in the US produces a line of industrial controllers that I have worked with in the past. The use a custom timestamp that references the epoch 00:00:00 1 January, 1997 EDT. I was pretty blown away that they did not use UTC rather than a -4 GMT time zone.

However I was not shocked that they didn't reference an epoch that begins in 1970. As @tux0r mentioned above, 32bit signed timestamps will overflow before too long. I think their choice of 1997 was a way to still use a signed 32 bit register and buy themselves a couple of decades :).

qm3ster profile image
Mihail Malo

Excel floating window for parsing incomplete dates is hilarious