1*0a6a1f1dSLionel Sambuc.\" $NetBSD: time2posix.3,v 1.19 2014/10/07 21:51:03 christos Exp $ 2*0a6a1f1dSLionel Sambuc.Dd October 6, 2014 32fe8fb19SBen Gras.Dt TIME2POSIX 3 42fe8fb19SBen Gras.Os 52fe8fb19SBen Gras.Sh NAME 62fe8fb19SBen Gras.Nm time2posix , 72fe8fb19SBen Gras.Nm time2posix_z , 82fe8fb19SBen Gras.Nm posix2time , 92fe8fb19SBen Gras.Nm posix2time_z , 102fe8fb19SBen Gras.Nd convert seconds since the Epoch 112fe8fb19SBen Gras.Sh LIBRARY 122fe8fb19SBen Gras.Lb libc 132fe8fb19SBen Gras.Sh SYNOPSIS 142fe8fb19SBen Gras.In time.h 152fe8fb19SBen Gras.Ft time_t 162fe8fb19SBen Gras.Fn time2posix "time_t t" 172fe8fb19SBen Gras.Ft time_t 182fe8fb19SBen Gras.Fn time2posix_z "const timezone_t tz" "time_t t" 192fe8fb19SBen Gras.Ft time_t 202fe8fb19SBen Gras.Fn posix2time "time_t t" 212fe8fb19SBen Gras.Ft time_t 222fe8fb19SBen Gras.Fn posix2time_z "const timezone_t tz" "time_t t" 232fe8fb19SBen Gras.Sh DESCRIPTION 242fe8fb19SBen Gras.St -p1003.1 25*0a6a1f1dSLionel Sambucrequires the 26*0a6a1f1dSLionel Sambuc.Ft time_t 27*0a6a1f1dSLionel Sambucvalue of 28*0a6a1f1dSLionel Sambuc.Dv 536457599 29*0a6a1f1dSLionel Sambucto stand for 302fe8fb19SBen Gras.Dl Wed Dec 31 23:59:59 UTC 1986 . 312fe8fb19SBen GrasThis effectively implies that POSIX 32*0a6a1f1dSLionel Sambuc.Ft time_t 33*0a6a1f1dSLionel Sambucvalues cannot include leap seconds and, therefore, 342fe8fb19SBen Grasthat the system time must be adjusted as each leap occurs. 352fe8fb19SBen Gras.Pp 362fe8fb19SBen GrasIf the time package is configured with leap-second support 372fe8fb19SBen Grasenabled, however, no such adjustment is needed and 382fe8fb19SBen Gras.Va time_t 392fe8fb19SBen Grasvalues continue to increase over leap events 40*0a6a1f1dSLionel Sambuc(as a true 41*0a6a1f1dSLionel Sambuc.Dq "seconds since..." 42*0a6a1f1dSLionel Sambucvalue). 432fe8fb19SBen GrasThis means that these values will differ from those required by POSIX 442fe8fb19SBen Grasby the net number of leap seconds inserted since the Epoch. 452fe8fb19SBen Gras.Pp 462fe8fb19SBen GrasTypically this is not a problem as the type 472fe8fb19SBen Gras.Va time_t 482fe8fb19SBen Grasis intended to be (mostly) 49*0a6a1f1dSLionel Sambucopaque \*(en 502fe8fb19SBen Gras.Va time_t 512fe8fb19SBen Grasvalues should only be obtained-from and 522fe8fb19SBen Graspassed-to functions such as 532fe8fb19SBen Gras.Xr time 3 , 542fe8fb19SBen Gras.Xr localtime 3 , 552fe8fb19SBen Gras.Xr localtime_r 3 , 562fe8fb19SBen Gras.Xr localtime_rz 3 , 572fe8fb19SBen Gras.Xr mktime 3 , 582fe8fb19SBen Gras.Xr mktime_z 3 , 592fe8fb19SBen Grasand 602fe8fb19SBen Gras.Xr difftime 3 . 612fe8fb19SBen GrasHowever, POSIX gives an arithmetic expression for directly computing a 622fe8fb19SBen Gras.Va time_t 632fe8fb19SBen Grasvalue from a given date/time, and the same relationship is assumed by 642fe8fb19SBen Grassome (usually older) applications. 652fe8fb19SBen GrasAny programs creating/dissecting 662fe8fb19SBen Gras.Va time_t Ns 's 672fe8fb19SBen Grasusing such a relationship will typically not handle intervals over 682fe8fb19SBen Grasleap seconds correctly. 692fe8fb19SBen Gras.Pp 702fe8fb19SBen GrasThe 712fe8fb19SBen Gras.Fn time2posix , 722fe8fb19SBen Gras.Fn time2posix_z , 732fe8fb19SBen Gras.Fn posix2time , 742fe8fb19SBen Grasand 752fe8fb19SBen Gras.Fn posix2time_z 762fe8fb19SBen Grasfunctions are provided to address this 772fe8fb19SBen Gras.Va time_t 782fe8fb19SBen Grasmismatch by converting between local 792fe8fb19SBen Gras.Va time_t 802fe8fb19SBen Grasvalues and their POSIX equivalents. 812fe8fb19SBen GrasThis is done by accounting for the number of time-base changes that would 822fe8fb19SBen Grashave taken place on a POSIX system as leap seconds were inserted or deleted. 832fe8fb19SBen GrasThese converted values can then be used in lieu of correcting the 842fe8fb19SBen Grasolder applications, or when communicating with POSIX-compliant systems. 852fe8fb19SBen Gras.Pp 862fe8fb19SBen Gras.Fn time2posix 872fe8fb19SBen Grasand 882fe8fb19SBen Gras.Fn time2posix_z 892fe8fb19SBen Grasare single-valued. 902fe8fb19SBen GrasThat is, every local 912fe8fb19SBen Gras.Va time_t 922fe8fb19SBen Grascorresponds to a single POSIX 932fe8fb19SBen Gras.Va time_t . 942fe8fb19SBen Gras.Fn posix2time 952fe8fb19SBen Grasand 962fe8fb19SBen Gras.Fn posix2time 972fe8fb19SBen Grasare less well-behaved: for a positive leap second hit the result is not 982fe8fb19SBen Grasunique, and for a negative leap second hit the corresponding POSIX 992fe8fb19SBen Gras.Va time_t 1002fe8fb19SBen Grasdoesn't exist so an adjacent value is returned. 1012fe8fb19SBen GrasBoth of these are good indicators of the inferiority of the POSIX 1022fe8fb19SBen Grasrepresentation. 1032fe8fb19SBen Gras.Pp 1042fe8fb19SBen GrasThe 1052fe8fb19SBen Gras.Dq z 1062fe8fb19SBen Grasvariants of the two functions behave exactly like their counterparts, 1072fe8fb19SBen Grasbut they operate in the given 1082fe8fb19SBen Gras.Fa tz 1092fe8fb19SBen Grasargument which was previously allocated using 1102fe8fb19SBen Gras.Xr tzalloc 3 1112fe8fb19SBen Grasand are re-entrant. 1122fe8fb19SBen Gras.Pp 1132fe8fb19SBen GrasThe following table summarizes the relationship between a 1142fe8fb19SBen Gras.Va time_t 1152fe8fb19SBen Grasand its conversion to, and back from, the POSIX representation over 1162fe8fb19SBen Grasthe leap second inserted at the end of June, 1993. 1172fe8fb19SBen Gras.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent 1182fe8fb19SBen Gras.It Sy DATE TIME T X=time2posix(T) posix2time(X) 1192fe8fb19SBen Gras.It 93/06/30 23:59:59 A+0 B+0 A+0 1202fe8fb19SBen Gras.It 93/06/30 23:59:60 A+1 B+1 A+1 or A+2 1212fe8fb19SBen Gras.It 93/07/01 00:00:00 A+2 B+1 A+1 or A+2 1222fe8fb19SBen Gras.It 93/07/01 00:00:01 A+3 B+2 A+3 1232fe8fb19SBen Gras.El 1242fe8fb19SBen Gras.Pp 1252fe8fb19SBen GrasA leap second deletion would look like... 1262fe8fb19SBen Gras.Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent 1272fe8fb19SBen Gras.It Sy DATE TIME T X=time2posix(T) posix2time(X) 1282fe8fb19SBen Gras.It ??/06/30 23:59:58 A+0 B+0 A+0 1292fe8fb19SBen Gras.It ??/07/01 00:00:00 A+1 B+2 A+1 1302fe8fb19SBen Gras.It ??/07/01 00:00:01 A+2 B+3 A+2 1312fe8fb19SBen Gras.El 1322fe8fb19SBen Gras[Note: posix2time(B+1) =\*[Gt] A+0 or A+1] 1332fe8fb19SBen Gras.Pp 1342fe8fb19SBen GrasIf leap-second support is not enabled, local 1352fe8fb19SBen Gras.Va time_t Ns 's 1362fe8fb19SBen Grasand POSIX 1372fe8fb19SBen Gras.Va time_t Ns 's 1382fe8fb19SBen Grasare equivalent, and both 1392fe8fb19SBen Gras.Fn time2posix 1402fe8fb19SBen Grasand 1412fe8fb19SBen Gras.Fn posix2time 1422fe8fb19SBen Grasdegenerate to the identity function. 1432fe8fb19SBen Gras.Sh SEE ALSO 1442fe8fb19SBen Gras.Xr difftime 3 , 1452fe8fb19SBen Gras.Xr localtime 3 , 1462fe8fb19SBen Gras.Xr localtime_r 3 , 1472fe8fb19SBen Gras.Xr localtime_rz 3 , 1482fe8fb19SBen Gras.Xr mktime 3 , 1492fe8fb19SBen Gras.Xr mktime_z 3 , 1502fe8fb19SBen Gras.Xr time 3 , 1512fe8fb19SBen Gras.Xr tzalloc 3 1522fe8fb19SBen Gras.\" @(#)time2posix.3 7.7 1532fe8fb19SBen Gras.\" This file is in the public domain, so clarified as of 1542fe8fb19SBen Gras.\" 1996-06-05 by Arthur David Olson. 155