Unix time

Unix time^[a] is a date and time representation widely used in computing. It measures time by the number of non-leap seconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch. For example, at midnight on 1 January 2010, Unix time was 1262304000.

Unix time originated as the system time of Unix operating systems. It has come to be widely used in other computer operating systems, file systems, programming languages, and databases. In modern computing, values are sometimes stored with higher granularity, such as microseconds or nanoseconds.

Unix time is currently defined as the number of non-leap seconds which have passed since 00:00:00 UTC on Thursday, 1 January 1970, which is referred to as the Unix epoch.^[3] Unix time is typically encoded as a signed integer.

The Unix time 0 is exactly midnight UTC on 1 January 1970, with Unix time incrementing by 1 for every non-leap second after this. For example, 00:00:00 UTC on 1 January 1971 is represented in Unix time as 31536000. Negative values, on systems that support them, indicate times before the Unix epoch, with the value decreasing by 1 for every non-leap second before the epoch. For example, 00:00:00 UTC on 1 January 1969 is represented in Unix time as −31536000. Every day in Unix time consists of exactly 86400 seconds.

Unix time is sometimes referred to as Epoch time. This can be misleading since Unix time is not the only time system based on an epoch and the Unix epoch is not the only epoch used by other time systems.^[5]

Unix time differs from both Coordinated Universal Time (UTC) and International Atomic Time (TAI) in its handling of leap seconds. UTC includes leap seconds that adjust for the discrepancy between precise time, as measured by atomic clocks, and solar time, relating to the position of the earth in relation to the sun. International Atomic Time (TAI), in which every day is precisely 86400 seconds long, ignores solar time and gradually loses synchronization with the Earth's rotation at a rate of roughly one second per year. In Unix time, every day contains exactly 86400 seconds. Each leap second uses the timestamp of a second that immediately precedes or follows it.^[3]

On a normal UTC day, which has a duration of 86400 seconds, the Unix time number changes in a continuous manner across midnight. For example, at the end of the day used in the examples above, the time representations progress as follows:

When a leap second occurs, the UTC day is not exactly 86400 seconds long and the Unix time number (which always increases by exactly 86400 each day) experiences a discontinuity. Leap seconds may be positive or negative. No negative leap second has ever been declared, but if one were to be, then at the end of a day with a negative leap second, the Unix time number would jump up by 1 to the start of the next day. During a positive leap second at the end of a day, which occurs about every year and a half on average, the Unix time number increases continuously into the next day during the leap second and then at the end of the leap second jumps back by 1 (returning to the start of the next day). For example, this is what happened on strictly conforming POSIX.1 systems at the end of 1998:

Unix time numbers are repeated in the second immediately following a positive leap second. The Unix time number 1483228800 is thus ambiguous: it can refer either to start of the leap second (2016-12-31 23:59:60) or the end of it, one second later (2017-01-01 00:00:00). In the theoretical case when a negative leap second occurs, no ambiguity is caused, but instead there is a range of Unix time numbers that do not refer to any point in UTC time at all.

A Unix clock is often implemented with a different type of positive leap second handling associated with the Network Time Protocol (NTP). This yields a system that does not conform to the POSIX standard. See the section below concerning NTP for details.

When dealing with periods that do not encompass a UTC leap second, the difference between two Unix time numbers is equal to the duration in seconds of the period between the corresponding points in time. This is a common computational technique. However, where leap seconds occur, such calculations give the wrong answer. In applications where this level of accuracy is required, it is necessary to consult a table of leap seconds when dealing with Unix times, and it is often preferable to use a different time encoding that does not suffer from this problem.

A Unix time number is easily converted back into a UTC time by taking the quotient and modulus of the Unix time number, modulo 86400. The quotient is the number of days since the epoch, and the modulus is the number of seconds since midnight UTC on that day. If given a Unix time number that is ambiguous due to a positive leap second, this algorithm interprets it as the time just after midnight. It never generates a time that is during a leap second. If given a Unix time number that is invalid due to a negative leap second, it generates an equally invalid UTC time. If these conditions are significant, it is necessary to consult a table of leap seconds to detect them.

Commonly a Mills-style Unix clock is implemented with leap second handling not synchronous with the change of the Unix time number. The time number initially decreases where a leap should have occurred, and then it leaps to the correct time 1 second after the leap. This makes implementation easier, and is described by Mills' paper.^[6] This is what happens across a positive leap second:

This can be decoded properly by paying attention to the leap second state variable, which unambiguously indicates whether the leap has been performed yet. The state variable change is synchronous with the leap.

A similar situation arises with a negative leap second, where the second that is skipped is slightly too late. Very briefly the system shows a nominally impossible time number, but this can be detected by the TIME_DEL state and corrected.

In this type of system the Unix time number violates POSIX around both types of leap second. Collecting the leap second state variable along with the time number allows for unambiguous decoding, so the correct POSIX time number can be generated if desired, or the full UTC time can be stored in a more suitable format.

The decoding logic required to cope with this style of Unix clock would also correctly decode a hypothetical POSIX-conforming clock using the same interface. This would be achieved by indicating the TIME_INS state during the entirety of an inserted leap second, then indicating TIME_WAIT during the entirety of the following second while repeating the seconds count. This requires synchronous leap second handling. This is probably the best way to express UTC time in Unix clock form, via a Unix interface, when the underlying clock is fundamentally untroubled by leap seconds.

Another, much rarer, non-conforming variant of Unix time keeping involves incrementing the value for all seconds, including leap seconds;^[7] some Linux systems are configured this way.^[8] Time kept in this fashion is sometimes referred to as "TAI" (although timestamps can be converted to UTC if the value corresponds to a time when the difference between TAI and UTC is known), as opposed to "UTC" (although not all UTC time values have a unique reference in systems that do not count leap seconds).^[8]

Because TAI has no leap seconds, and every TAI day is exactly 86400 seconds long, this encoding is actually a pure linear count of seconds elapsed since 1970-01-01T00:00:10 TAI. This makes time interval arithmetic much easier. Time values from these systems do not suffer the ambiguity that strictly conforming POSIX systems or NTP-driven systems have.

In these systems it is necessary to consult a table of leap seconds to correctly convert between UTC and the pseudo-Unix-time representation. This resembles the manner in which time zone tables must be consulted to convert to and from civil time; the IANA time zone database includes leap second information, and the sample code available from the same source uses that information to convert between TAI-based timestamps and local time. Conversion also runs into definitional problems prior to the 1972 commencement of the current form of UTC (see section UTC basis below).

This system, despite its superficial resemblance, is not Unix time. It encodes times with values that differ by several seconds from the POSIX time values. A version of this system, in which the epoch was 1970-01-01T00:00:00 TAI rather than 1970-01-01T00:00:10 TAI, was proposed for inclusion in ISO C's time.h, but only the UTC part was accepted in 2011.^[9] A tai_clock does, however, exist in C++20.

A Unix time number can be represented in any form capable of representing numbers. In some applications the number is simply represented textually as a string of decimal digits, raising only trivial additional problems. However, certain binary representations of Unix times are particularly significant.

The Unix time_t data type that represents a point in time is, on many platforms, a signed integer, traditionally of 32 bits (but see below), directly encoding the Unix time number as described in the preceding section. A signed 32-bit value covers about 68 years before and after the 1970-01-01 epoch. The minimum representable date is Friday 1901-12-13, and the maximum representable date is Tuesday 2038-01-19. One second after 2038-01-19T03:14:07Z this representation will overflow in what is known as the year 2038 problem.

UUIDv7 encodes the Unix epoch timestamp (in milliseconds) in an unsigned 48-bit field. This representation is valid until the year 10889.^[10]

In some newer operating systems, time_t has been widened to 64 bits. This expands the times representable to about 292.3 billion years in both directions, which is over twenty times the present age of the universe.

There was originally some controversy over whether the Unix time_t should be signed or unsigned. If unsigned, its range in the future would be doubled, postponing the 32-bit overflow (by 68 years). However, it would then be incapable of representing times prior to the epoch. The consensus is for time_t to be signed, and this is the usual practice. The software development platform for version 6 of the QNX operating system has an unsigned 32-bit time_t, though older releases used a signed type.

The POSIX and Open Group Unix specifications include the C standard library, which includes the time types and functions defined in the <time.h> header file. The ISO C standard states that time_t must be an arithmetic type, but does not mandate any specific type or encoding for it. POSIX requires time_t to be an integer type, but does not mandate that it be signed or unsigned.

Unix has no tradition of directly representing non-integer Unix time numbers as binary fractions. Instead, times with sub-second precision are represented using composite data types that consist of two integers, the first being a time_t (the integral part of the Unix time), and the second being the fractional part of the time number in millionths (in struct timeval) or billionths (in struct timespec).^[11][12] These structures provide a decimal-based fixed-point data format, which is useful for some applications, and trivial to convert for others.

The present form of UTC, with leap seconds, is defined only starting from 1 January 1972. Prior to that, since 1 January 1961 there was an older form of UTC in which not only were there occasional time steps, which were by non-integer numbers of seconds, but also the UTC second was slightly longer than the SI second, and periodically changed to continuously approximate the Earth's rotation. Prior to 1961 there was no UTC, and prior to 1958 there was no widespread atomic timekeeping; in these eras, some approximation of GMT (based directly on the Earth's rotation) was used instead of an atomic timescale.^{[citation needed]}

The precise definition of Unix time as an encoding of UTC is only uncontroversial when applied to the present form of UTC. The Unix epoch predating the start of this form of UTC does not affect its use in this era: the number of days from 1 January 1970 (the Unix epoch) to 1 January 1972 (the start of UTC) is not in question, and the number of days is all that is significant to Unix time.

The meaning of Unix time values below +63072000 (i.e., prior to 1 January 1972) is not precisely defined. The basis of such Unix times is best understood to be an unspecified approximation of UTC. Computers of that era rarely had clocks set sufficiently accurately to provide meaningful sub-second timestamps in any case. Unix time is not a suitable way to represent times prior to 1972 in applications requiring sub-second precision; such applications must, at least, define which form of UT or GMT they use.

As of 2009^[update], the possibility of ending the use of leap seconds in civil time is being considered.^[13] A likely means to execute this change is to define a new time scale, called International Time^{[citation needed]}, that initially matches UTC but thereafter has no leap seconds, thus remaining at a constant offset from TAI. If this happens, it is likely that Unix time will be prospectively defined in terms of this new time scale, instead of UTC. Uncertainty about whether this will occur makes prospective Unix time no less predictable than it already is: if UTC were simply to have no further leap seconds the result would be the same.

This section needs additional citations for verification. Please help improve this article by adding citations to reliable sources in this section. Unsourced material may be challenged and removed. (September 2019) (Learn how and when to remove this message)

The earliest versions of Unix time had a 32-bit integer incrementing at a rate of 60 Hz, which was the rate of the system clock on the hardware of the early Unix systems. Timestamps stored this way could only represent a range of a little over two and a quarter years. The epoch being counted from was changed with Unix releases to prevent overflow, with midnight on 1 January 1971 and 1 January 1972 both being used as epochs during Unix's early development. Early definitions of Unix time also lacked time zones.^[14][15]

The current epoch of 1 January 1970 00:00:00 UTC was selected arbitrarily by Unix engineers because it was considered a convenient date to work with. The precision was changed to count in seconds in order to avoid short-term overflow.^[1]

When POSIX.1 was written, the question arose of how to precisely define time_t in the face of leap seconds. The POSIX committee considered whether Unix time should remain, as intended, a linear count of seconds since the epoch, at the expense of complexity in conversions with civil time or a representation of civil time, at the expense of inconsistency around leap seconds. Computer clocks of the era were not sufficiently precisely set to form a precedent one way or the other.

The POSIX committee was swayed by arguments against complexity in the library functions,^[16] and firmly defined the Unix time in a simple manner in terms of the elements of UTC time. This definition was so simple that it did not even encompass the entire leap year rule of the Gregorian calendar, and would make 2100 a leap year.

The 2001 edition of POSIX.1 rectified the faulty leap year rule in the definition of Unix time, but retained the essential definition of Unix time as an encoding of UTC rather than a linear time scale. Since the mid-1990s, computer clocks have been routinely set with sufficient precision for this to matter, and they have most commonly been set using the UTC-based definition of Unix time. This has resulted in considerable complexity in Unix implementations, and in the Network Time Protocol, to execute steps in the Unix time number whenever leap seconds occur.^{[citation needed]}

Unix time is widely adopted in computing beyond its original application as the system time for Unix. Unix time is available in almost all system programming APIs, including those provided by both Unix-based and non-Unix operating systems. Almost all modern programming languages provide APIs for working with Unix time or converting them to another data structure. Unix time is also used as a mechanism for storing timestamps in a number of file systems, file formats, and databases.

The C standard library uses Unix time for all date and time functions, and Unix time is sometimes referred to as time_t, the name of the data type used for timestamps in C and C++. C's Unix time functions are defined as the system time API in the POSIX specification.^[17] The C standard library is used extensively in all modern desktop operating systems, including Microsoft Windows and Unix-like systems such as macOS and Linux, where it is a standard programming interface.^[18][19][20]

iOS provides a Swift API which defaults to using an epoch of 1 January 2001 but can also be used with Unix timestamps.^[21] Android uses Unix time alongside a time zone for its system time API.^[22]

Windows does not use Unix time for storing time internally but does use it in system APIs, which are provided in C++ and implement the C standard library specification.^[18] Unix time is used in the PE format for Windows executables.^[23]

Unix time is typically available in major programming languages and is widely used in desktop, mobile, and web application programming. Java provides an Instant object which holds a Unix timestamp in both seconds and nanoseconds.^[24] Python provides a time library which uses Unix time.^[25] JavaScript provides a Date library which provides and stores timestamps in milliseconds since the Unix epoch and is implemented in all modern desktop and mobile web browsers as well as in JavaScript server environments like Node.js.^[26]

Free Pascal implements UNIX time with the GetTickCount (deprecated unsigned 32 bit) and GetTickCount64 (Unsigned 64 bit) functions to a resolution of 1ms on Unix-like platforms.

Filesystems designed for use with Unix-based operating systems tend to use Unix time. APFS, the file system used by default across all Apple devices, and ext4, which is widely used on Linux and Android devices, both use Unix time in nanoseconds for file timestamps.^[27][28] Several archive file formats can store timestamps in Unix time, including RAR and tar.^[29][30] Unix time is also commonly used to store timestamps in databases, including in MySQL and PostgreSQL.^[31][32]

Unix time was designed to encode calendar dates and times in a compact manner intended for use by computers internally. It is not intended to be easily read by humans or to store time-zone-dependent values. It is also limited by default to representing time in seconds, making it unsuited for use when a more precise measurement of time is needed, such as when measuring the execution time of programs.^[33]

Unix time by design does not require a specific size for the storage, but most common implementations of Unix time use a signed integer with the same size as the word size of the underlying hardware. As the majority of modern computers are 32-bit or 64-bit, and a large number of programs are still written in 32-bit compatibility mode, this means that many programs using Unix time are using signed 32-bit integer fields. The maximum value of a signed 32-bit integer is 2³¹ − 1, and the minimum value is −2³¹, making it impossible to represent dates before 13 December 1901 (at 20:45:52 UTC) or after 19 January 2038 (at 03:14:07 UTC). The early cutoff can have an impact on databases that are storing historical information; in some databases where 32-bit Unix time is used for timestamps, it may be necessary to store time in a different form of field, such as a string, to represent dates before 1901. The late cutoff is known as the Year 2038 problem and has the potential to cause issues as the date approaches, as dates beyond the 2038 cutoff would wrap back around to the start of the representable range in 1901.^{[33]: 60 [34]}

Date range cutoffs are not an issue with 64-bit representations of Unix time, as the effective range of dates representable with Unix time stored in a signed 64-bit integer is over 584 billion years, or 292 billion years in either direction of the 1970 epoch.^{[33]: 60-61 [35]}

Unix time is not the only standard for time that counts away from an epoch. The C# programming language's DateTime structure, the FILETIME type in Windows, and Azure Cosmos DB's GetCurrentTicks function store time as a count of 100-nanosecond intervals that have elapsed since 0:00 GMT on 1 January 1 AD,^[36] 1 January 1601,^[37] and 1 January 1970,^[38] which will not overflow until the years 29228,^[39][40] 30828,^[39][41] and 31197,^[42] respectively. Windows epoch time is used to store timestamps for files^[43] and in protocols such as the Active Directory Time Service^[44] and Server Message Block.

The Network Time Protocol used to coordinate time between computers uses an epoch of 1 January 1900, counted in an unsigned 32-bit integer for seconds and another unsigned 32-bit integer for fractional seconds, which rolls over every 2³² seconds (about once every 136 years).^[45]

Many applications and programming languages provide methods for storing time with an explicit time zone.^[46] There are also a number of time format standards which exist to be readable by both humans and computers, such as ISO 8601.

Unix enthusiasts have a history of holding "time_t parties" (pronounced "time tea parties") to celebrate significant values of the Unix time number.^[47][48] These are directly analogous to the new year celebrations that occur at the change of year in many calendars. As the use of Unix time has spread, so has the practice of celebrating its milestones. Usually it is time values that are round numbers in decimal that are celebrated, following the Unix convention of viewing time_t values in decimal. Among some groups round binary numbers are also celebrated,^{[citation needed]} such as +2³⁰, which occurred at 13:37:04 UTC on Saturday, 10 January 2004.

The events that these celebrate are typically described as "N seconds since the Unix epoch", but this is inaccurate; as discussed above, due to the handling of leap seconds in Unix time the number of seconds elapsed since the Unix epoch is slightly greater than the Unix time number for times later than the epoch.

• At 18:36:57 UTC on Wednesday, 17 October 1973, the first appearance of the date in ISO 8601 format^[b] (1973-10-17) within the digits of Unix time (119731017) took place.
• At 01:46:40 UTC on Sunday, 9 September 2001, the Unix billennium (Unix time number 1000000000) was celebrated.^[49] The name billennium is a portmanteau of billion and millennium.^[50][51] Some programs which stored timestamps using a text representation encountered sorting errors, as in a text sort, times after the turnover starting with a 1 digit erroneously sorted before earlier times starting with a 9 digit. Affected programs included the popular Usenet reader KNode and e-mail client KMail, part of the KDE desktop environment. Such bugs were generally cosmetic in nature and quickly fixed once problems became apparent.^{[citation needed]} The problem also affected many Filtrix document-format filters provided with Linux versions of WordPerfect; a patch was created by the user community to solve this problem, since Corel no longer sold or supported that version of the program.^[52]
• At 23:31:30 UTC on Friday, 13 February 2009, the decimal representation of Unix time reached 1234567890 seconds.^[53] Google celebrated this with a Google Doodle.^[54] Parties and other celebrations were held around the world, among various technical subcultures, to celebrate the 1234567890th second.^[47][55]

Vernor Vinge's novel A Deepness in the Sky describes a spacefaring trading civilization thousands of years in the future that still uses the Unix epoch. The "programmer-archaeologist" responsible for finding and maintaining usable code in mature computer systems first believes that the epoch refers to the time when man first walked on the Moon, but then realizes that it is "the 0-second of one of humankind's first computer operating systems".^[56]

• Epoch (computing)
• System time

Wikiversity has learning resources about JavaScript/Epoch time converter

• Unix Programmer's Manual, first edition
• Personal account of the POSIX decisions by Landon Curt Noll
• chrono-Compatible Low-Level Date Algorithms – algorithms to convert between Gregorian and Julian dates and the number of days since the start of Unix time