Skip to content
A binary time encoding in a 64 bit signed integer combining time in µs and time offset
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Note: this timez encoding is outdated. See timez-go for the latest encoding.

A Timez is a binary representation for time stamps encoded in a 64 bit signed integer. It contains

  1. the number of microseconds elapsed since a reference time called the epoch,
  2. the time offset to the UTC time in the location where the stamp was generated.

The epoch is the 1 January 1970 00:00:00 UTC. The Timez time stamp is intended to be transmitted accross internet between locations with a different time offset relative to the UTC time.

Note: the z of Timez has no relation to the military Zulu term used to identify the UTC time.


   64                     11        0   bits
   |__________  __________|________|
   |nbr µs since UTC epoch| offset |
  • The 53 most significant bits is a signed integer in two's complement encoding the number of microseconds elapsed since the reference time called epoch ;
  • The epoch is the 1 January 1970 00:00:00 UTC ;
  • The 11 less significant bits is an unsigned integer encoding the local time offset (including day time saving) in minutes plus 1024 ;
  • The Timez value is invalid when the 11 less significant bits are all 0 ;


  • the covered time range is 1970 +/- 142 years ;
  • the time resolution is in microseconds ;
  • the covered time offset range is +/- 17 hours ;
  • the time offset resolution is in minutes ;
  • the time offset is the sum of the time zone offset and day light saving time ;
  • comparing the 64 bit signed integer is equivalent to UTC time comparison ;
  • the 64 bit integer value 0 can be use as undefined or invalid time stamp value ;
  • the local time of the stamp producer can be deduced using the contained time offset information ;
  • not subject to leap seconds adjustement or day light saving time changes ;
  • not exposed to the year 2038 problem where actual time_t will wrap ;
  • a Timez is stored in a database as a 64 bit signed integer ;
    • thi integer ordering is the same as the UTC time ordering ;
    • selection by UTC time range can be used ;
    • existing data type can be used ;


ISO 8601 defines an international standad ASCII representation of date and time including the time offset information. It is designed to allow sorting by time with a lexical ordering. Unfortunately, the encoded time is the local time. This representation is thus not appropriate when comparing times with different offsets. A prior conversion in UTC time is required.

The glibc and Unix use a signed integer (time_t) with a resolution of seconds. The time zone information with day light saving is stored in different variables.

The integer value is the number of seconds elapsed since the 1 January 1970 00:00:00 UTC. Unfortunately the value will wrap to a negative number the 19 January 1938. This is known as the year 2038 problem.

The function gettimeofday() or the preferred clock_gettime() function returns also a time_t value and a long signed integer providing the nanoseconds elapsed. This value is subject to the same year 2038 problem.

Microsoft has promoted the use of a double float value to store time in second units. A double has 52 bit mantissa and 11 bits exponent. While the value range it may represent is very large, it can't accurately represent fractions of seconds. It also doesn't provide a time zone information.


  • The API and implementation is work in progress. It may still change radically.

  • The code is embryonic and simply a proof of concept. It requires 64bit support. Use the following command to build the simple test program.

    gcc -lrt main.c timez.c

  • The current implementation uses time_t values obtained in the stuct timespec with the clock_gettime() function. It is thus actually exposed to the 2038 problem. This will be fixed in a future implementation. Functions to decode the Timez value into a struct tm equivalent and do the reverse still needs to be implemented. They will introduce a dependency to the IANA timezone database.


You can’t perform that action at this time.