FreeBSD Manual Pages
TIME2POSIX(3) Library Functions Manual TIME2POSIX(3) 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, how- ever, 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), localtime(3), mktime(3), and diff- time(3). 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/dis- secting 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 con- verting 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-com- pliant 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 modi- fying 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 en- vironment variable names a TZif file, overflow can hap- pen for either function for an argument sufficiently close to an extreme time_t value if the TZif file speci- fies unrealistic leap second corrections. SEE ALSO difftime(3), localtime(3), mktime(3), time(3) FreeBSD ports 15.quarterly March 8, 2026 TIME2POSIX(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=time2posix&sektion=3&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>