---
name: "posix2time"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/posix2time"
---

# posix2time(3)

convert seconds since the Epoch

## NAME

**time2posix**, **posix2time** – convert seconds since the Epoch

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<time.h\>**

*time\_t*\

**time2posix**(*time\_t t*);

*time\_t*\

**posix2time**(*time\_t t*);

## DESCRIPTION

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

If the time package is configured with leap-second support enabled, however, no such adjustment is needed and *time\_t* values continue to increase over leap events (as a true “seconds since...” value). This means that these values will differ from those required by POSIX by the net number of leap seconds inserted since the Epoch.

For many C programs this is not a problem as the C standard says that *time\_t* is (mostly) opaque — *time\_t* values should be obtained from and passed to functions such as [time(2)](/time/2.md), [localtime(3)](/localtime/3.md), [mktime(3)](/mktime/3.md), and [difftime(3)](/difftime/3.md). 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.

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.

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 these are indicate problems with the POSIX representation.

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.

| |
| --- |
| DATE TIME T X Y |
| 1993-06-30 23:59:59 A B A |
| 1993-06-30 23:59:60 A+1 B+1 A+1 or A+2 |
| 1993-07-01 00:00:00 A+2 B+1 A+1 or A+2 |
| 1993-07-01 00:00:01 A+3 B+2 A+3 |

A leap second deletion would look like the following, and posix2time(B+1) would return either A or A+1.

| |
| --- |
| DATE TIME T X Y |
| ????-06-30 23:59:58 A B A |
| ????-07-01 00:00:00 A+1 B+2 A+1 |
| ????-07-01 00:00:01 A+2 B+3 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.

## RETURN VALUES

If successful, these functions return the resulting timestamp without modifying *errno*. Otherwise, they set *errno* and return ((time\_t) -1).

## 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.

## SEE ALSO

[difftime(3)](/difftime/3.md), [localtime(3)](/localtime/3.md), [mktime(3)](/mktime/3.md), [time(3)](/time/3.md)