TIME2POSIX(3)

💖 NAME 💖

okay so this is TIME2POSIX(3), from the Library Functions Manual — the page for time2posix and posix2time, aka the little duo that converts seconds since the Epoch. no cap, that’s the whole vibe.

🫶 LIBRARY 🫶

bestie, these live in the Standard C Library (libc, -lc). iconic behavior.

✨ SYNOPSIS ✨

#include <time.h>

time_t
time2posix(time_t t);

time_t
posix2time(time_t t);

🌸 DESCRIPTION 🌸

So IEEE Std 1003.1-1988 (“POSIX.1”) says values cannot count leap seconds, and therefore the system time must be adjusted as each leap occurs. that’s the rules, fr fr.

But if the time package is configured with leap-second support enabled, no such adjustment is needed, and time_t values continue to increase over leap events — like a true “seconds since...” value. the way that works means these values will differ from the ones POSIX requires by the net number of leap seconds inserted since the Epoch. lowkey a whole situation.

For many C programs this is not a problem, because the C standard says time_t is (mostly) opaque — time_t values should be obtained from and passed to functions such as time(2), localtime(3), mktime(3), and difftime(3). obsessed with that for them. However, POSIX gives an arithmetic expression for computing a time_t value directly from a given Universal date and time, and the same relationship is assumed by some applications. any programs creating/dissecting time_t values using such a relationship will typically not handle intervals over leap seconds correctly. not me finding out the hard way 😭.

The time2posix() and posix2time() functions address this mismatch by converting between local time_t values and their POSIX equivalents. This is done by accounting for the number of time-base changes that would have taken place on a POSIX system as leap seconds were inserted or deleted. these converted values can then be used when communicating with POSIX-compliant systems. slay.

The time2posix() function converts a time_t value to its POSIX counterpart, if one exists. The posix2time() function does the reverse but is less well-behaved: for a positive leap second hit the result is not unique, and for a negative leap second hit the corresponding POSIX time_t doesn’t exist so an adjacent value is returned. both of those are red flags that the POSIX representation has problems. periodt.

The following table summarizes the relationship between a time T and its conversion to, and back from, the POSIX representation over the leap second inserted at the end of June, 1993. In this table, X=time2posix(T), Y=posix2time(X), A=741484816, and B=A-17 because 17 positive leap seconds preceded this leap second. the columns are DATE, TIME, T, X, Y:

• Date 1993-06-30, time 23:59:59 → T = A, X = B, Y = A
• Date 1993-06-30, time 23:59:60 → T = A+1, X = B+1, Y = A+1 or A+2
• Date 1993-07-01, time 00:00:00 → T = A+2, X = B+1, Y = A+1 or A+2
• Date 1993-07-01, time 00:00:01 → T = A+3, X = B+2, Y = A+3

A leap second deletion would look like the following, and posix2time(B+1) would return either A or A+1. again, columns are DATE, TIME, T, X, Y:

• Date ????-06-30, time 23:59:58 → T = A, X = B, Y = A
• Date ????-07-01, time 00:00:00 → T = A+1, X = B+2, Y = A+1
• Date ????-07-01, time 00:00:01 → T = A+2, X = B+3, Y = A+2

If leap-second support is not enabled, local time_t and POSIX time_t values are equivalent, and both time2posix() and posix2time() degenerate to the identity function. it’s giving “same picture, different font.” 💅

🎀 RETURN VALUES 🎀

If successful, these functions return the resulting timestamp without modifying errno. Otherwise, they set errno and return ((time_t) -1). brutal but fair.

💅 ERRORS 💅

These functions fail if:

• [EOVERFLOW] — the resulting value cannot be represented. This can happen for posix2time() if its argument is close to the maximum time_t value. In environments where the TZ environment variable names a TZif file, overflow can happen for either function for an argument sufficiently close to an extreme time_t value if the TZif file specifies unrealistic leap second corrections.

bestie, that’s the edge-case corner: EOVERFLOW is not a vibe, it’s a real error condition. 🫶

👑 SEE ALSO 👑

difftime(3), localtime(3), mktime(3), time(3) — go read the whole friend group, iykyk. 🦋

---

💖 cute sign-off: source/version is Debian, date is March 8, 2026 — bye bestie, go convert those timestamps! 🎀