diff options
Diffstat (limited to 'lib/libc/stdtime/time2posix.3')
-rw-r--r-- | lib/libc/stdtime/time2posix.3 | 123 |
1 files changed, 0 insertions, 123 deletions
diff --git a/lib/libc/stdtime/time2posix.3 b/lib/libc/stdtime/time2posix.3 deleted file mode 100644 index 1a1ec95..0000000 --- a/lib/libc/stdtime/time2posix.3 +++ /dev/null @@ -1,123 +0,0 @@ -.\" $FreeBSD$ -.\" -.Dd September 11, 2005 -.Dt TIME2POSIX 3 -.Os -.Sh NAME -.Nm time2posix , -.Nm posix2time -.Nd convert seconds since the Epoch -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In time.h -.Ft time_t -.Fn time2posix "time_t t" -.Ft time_t -.Fn posix2time "time_t t" -.Sh DESCRIPTION -.St -p1003.1-88 -legislates that a time_t value of -536457599 shall correspond to "Wed Dec 31 23:59:59 GMT 1986." -This effectively implies that POSIX time_t's cannot include leap -seconds and, -therefore, -that the system time must be adjusted as each leap occurs. -.Pp -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. -.Pp -Typically this is not a problem as the type time_t is intended -to be -(mostly) -opaque\(emtime_t values should only be obtained-from and -passed-to functions such as -.Xr time 3 , -.Xr localtime 3 , -.Xr mktime 3 -and -.Xr difftime 3 . -However, -.St -p1003.1-88 -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 programs creating/dissecting time_t's -using such a relationship will typically not handle intervals -over leap seconds correctly. -.Pp -The -.Fn time2posix -and -.Fn 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. -.Pp -The -.Fn time2posix -function is single-valued. -That is, -every local time_t -corresponds to a single POSIX time_t. -The -.Fn 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 does not exist so an adjacent value is returned. -Both of these are good indicators of the inferiority of the -POSIX representation. -.Pp -The following table summarizes the relationship between time_t -and its conversion to, -and back from, -the POSIX representation over the leap second inserted at the end of June, -1993. -.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" -.It Sy "DATE TIME T X=time2posix(T) posix2time(X)" -.It "93/06/30 23:59:59 A+0 B+0 A+0" -.It "93/06/30 23:59:60 A+1 B+1 A+1 or A+2" -.It "93/07/01 00:00:00 A+2 B+1 A+1 or A+2" -.It "93/07/01 00:00:01 A+3 B+2 A+3" -.El -.Pp -A leap second deletion would look like... -.Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" -.It Sy "DATE TIME T X=time2posix(T) posix2time(X)" -.It "??/06/30 23:59:58 A+0 B+0 A+0" -.It "??/07/01 00:00:00 A+1 B+2 A+1" -.It "??/07/01 00:00:01 A+2 B+3 A+2" -.El -.Pp -.D1 No "[Note: posix2time(B+1) => A+0 or A+1]" -.Pp -If leap-second support is not enabled, -local time_t's and -POSIX time_t's are equivalent, -and both -.Fn time2posix -and -.Fn posix2time -degenerate to the identity function. -.Sh "SEE ALSO" -.Xr difftime 3 , -.Xr localtime 3 , -.Xr mktime 3 , -.Xr time 3 -.\" @(#)time2posix.3 8.2 -.\" This file is in the public domain, so clarified as of -.\" 1996-06-05 by Arthur David Olson. |