Time (Unix)

The idea in one sentence

A Unix timestamp counts seconds (or sometimes milliseconds) that have elapsed since an agreed epoch: 1970-01-01T00:00:00Z—midnight UTC on 1 January 1970—excluding leap seconds in the usual POSIX definition. That single integer is an unambiguous way to store an instant without a time zone label.

Convert a numeric timestamp to a readable date with the Unix timestamp to date tool.

Why engineers like epoch seconds

Civil dates need calendars, time zones, and daylight saving rules. Instantaneous events—“this order was paid,” “this certificate expires,” “this log line was written”—are easier as a monotonic count from a fixed origin. Unix time travels well between languages, databases, and APIs. Sorting timestamps is sorting integers. Differences are subtraction.

The tradeoff is human readability: 1710000000 means little until you convert it. Tools and library formatters bridge that gap.

Seconds versus milliseconds versus nanoseconds

Conventions differ:

Passing a millisecond value to an API that expects seconds produces dates far in the future. Passing seconds to a millisecond API lands near 1970. When integrating, check the docs and test with a known instant.

JavaScript’s Date.now() returns milliseconds. Many backend frameworks default to seconds. Be explicit in JSON field names (createdAtSeconds) when possible.

UTC and local display

The timestamp itself is UTC-based. Displaying it in Berlin or Tokyo applies a time zone conversion for humans; the stored integer does not change. Keep storage in UTC instants and localize at the edges—UI, emails, reports.

Negative timestamps and far futures

Timestamps before 1970 are negative on systems that support them. Far-future dates may overflow 32-bit signed integers: the classic Year 2038 problem for time_t on 32-bit platforms. Modern 64-bit time_t pushes the overflow far beyond practical horizons for second resolution. Prefer 64-bit types in new systems.

Leap seconds (awareness level)

UTC occasionally inserts leap seconds. POSIX Unix time typically ignores leap seconds, treating each day as 86,400 seconds for conversion purposes. For everyday business apps this is fine. For astronomy, telecom, or legal timestamping at second-level precision across leap events, study your industry’s time scale (UTC, TAI, GPS time) and library support.

ISO 8601 alongside Unix time

APIs often accept both:

• 1710000000
• 2024-03-09T16:00:00Z

ISO 8601 strings with a Z or numeric offset communicate the same instant when parsed correctly. Unix time is compact; ISO strings are greppable in logs. Many systems store integers and emit ISO in JSON for readability.

Conversion workflow

1. Identify the unit (s/ms).
2. Interpret the number as UTC epoch.
3. Format with an explicit zone for display.
4. Round-trip: format then parse, or convert back to epoch, to confirm agreement.

Hand conversion without a library is error-prone near month lengths and leap years—use tested libraries for production.

Databases and indexing

Store epoch integers or native timestamp types that normalize to UTC. Avoid storing local civil time without zone if you mean an instant. Indexing integer epochs is straightforward; just document the unit in schema comments.

For “business dates” like invoice calendar days, a date type without time may be better than an epoch at midnight—policy and jurisdiction matter for what “the day” means.

Logging and observability

Log processors love Unix time. Correlate traces across services using the same clock domain as much as possible. Clock skew between hosts still exists—NTP helps—so tolerate small negatives in duration math and prefer server-generated timestamps for authoritative audit trails.

Common bugs

• Unit mismatch (seconds vs milliseconds).
• Treating epoch as local when formatting without Z.
• Stringly typed math on date strings instead of instants.
• Excel converting timestamps to dates with wrong epochs (Excel’s day-zero differs).
• 32-bit overflow on embedded or legacy systems.

Teaching example

Take a timestamp, convert to UTC, then convert to two civil time zones. Confirm that both civil strings refer to the same instant. That exercise builds intuition better than memorizing formulas.

Use from-unix-timestamp-to-date to inspect values you see in APIs or database dumps (with non-sensitive samples).

Related concepts

• Monotonic clocks measure elapsed time and should not go backward; they are not Unix timestamps and should not be persisted as wall time.
• Cron expressions describe civil schedules, not epochs.
• Certificate notAfter fields are instants—compare them in UTC.

Summary

Unix timestamps encode instants as counts from 1970-01-01 UTC. They simplify storage and sorting while pushing human formatting to the edges. Know your units, use 64-bit types, display with explicit zones, and convert with reliable tools when you need to read a raw number as a calendar date.