vendor/tzcode/tzcode2026avendor/tzcode

1 files changed, 50 insertions, 35 deletions

diff --git a/time2posix.3.txt b/time2posix.3.txt
index 6b0e0449b816..57556b8789dc 100644
--- a/time2posix.3.txt
+++ b/time2posix.3.txt
@@ -13,10 +13,9 @@ SYNOPSIS
        cc ... -ltz
 
 DESCRIPTION
-       IEEE Standard 1003.1 (POSIX) requires the time_t value 536457599 to
-       stand for 1986-12-31 23:59:59 UTC.  This effectively implies that POSIX
-       time_t values cannot include leap seconds and, therefore, that the
-       system time must be adjusted as each leap occurs.
+       IEEE Standard 1003.1 (POSIX) says that time_t 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
@@ -24,53 +23,69 @@ DESCRIPTION
        means that these values will differ from those required by POSIX by the
        net number of leap seconds inserted since the Epoch.
 
-       Typically this is not a problem as the type time_t is intended to be
-       (mostly) opaque – time_t values should only be obtained-from and
-       passed-to functions such as time(2), localtime(3), mktime(3), and
+       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
        difftime(3).  However, POSIX gives an arithmetic expression for
-       directly computing a time_t value from a given date/time, and the same
-       relationship is assumed by some (usually older) applications.  Any
+       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 are provided to address this
-       time_t 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 in lieu of correcting the older applications, or when
-       communicating with POSIX-compliant systems.
+       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 is single-valued.  That is, every local time_t
-       corresponds to a single POSIX time_t.  The posix2time function 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 good
-       indicators of the inferiority of the POSIX representation.
+       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.
-       DATE     TIME     T   X=time2posix(T) posix2time(X)
-       93/06/30 23:59:59 A+0 B+0             A+0
-       93/06/30 23:59:60 A+1 B+1             A+1 or A+2
-       93/07/01 00:00:00 A+2 B+1             A+1 or A+2
-       93/07/01 00:00:01 A+3 B+2             A+3
+       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.
 
-       A leap second deletion would look like...
+         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
 
-       DATE     TIME     T   X=time2posix(T) posix2time(X)
-       ??/06/30 23:59:58 A+0 B+0             A+0
-       ??/07/01 00:00:00 A+1 B+2             A+1
-       ??/07/01 00:00:01 A+2 B+3             A+2
+       A leap second deletion would look like the following, and
+       posix2time(B+1) would return either A or A+1.
 
-                            [Note: posix2time(B+1) => A+0 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 VALUE
+       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), localtime(3), mktime(3), time(2)
+       difftime(3), localtime(3), mktime(3), time(2).
 
 Time Zone Database                                               time2posix(3)