diff options
Diffstat (limited to 'static/freebsd/man3/time2posix.3')
| -rw-r--r-- | static/freebsd/man3/time2posix.3 | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/static/freebsd/man3/time2posix.3 b/static/freebsd/man3/time2posix.3 new file mode 100644 index 00000000..268f3727 --- /dev/null +++ b/static/freebsd/man3/time2posix.3 @@ -0,0 +1,172 @@ +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. +.Dd March 8, 2026 +.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 +says that +.B time_t +values cannot count 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 +.Vt time_t +values continue to increase over leap events +(as a true +.Dq "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 +For many C programs this is not a problem as the C standard says that +.Vt time_t +is +(mostly) +opaque \(em +.Vt time_t +values should be obtained from and +passed to functions such as +.Xr time 2 , +.Xr localtime 3 , +.Xr mktime 3 , +and +.Xr difftime 3 . +However, +POSIX gives an arithmetic +expression for computing a +.Vt time_t +value directly from a given Universal date and time, +and the same relationship is assumed by some +applications. +Any programs creating/dissecting +.Vt time_t +values +using such a relationship will typically not handle intervals +over leap seconds correctly. +.Pp +The +.Fn time2posix +and +.Fn posix2time +functions address this mismatch by converting +between local +.Vt 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. +.Pp +The +.Fn time2posix +function converts a +.Vt time_t +value to its POSIX counterpart, if one exists. +The +.Fn 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 +.Vt time_t +doesn't exist so an adjacent value is returned. +Both of these are indicate problems with the +POSIX representation. +.Pp +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, +.Li X=time2posix(T) , +.Li Y=posix2time(X) , +.Li A=741484816 , +and +.Li B=A\-17 +because 17 positive leap seconds preceded this leap second. +.Pp +.Bl -column "1993-06-30" "23:59:59" "A+0" "B+0" +.It DATE TIME T X Y +.It 1993-06-30 23:59:59 A B A +.It 1993-06-30 23:59:60 A+1 B+1 A+1 or A+2 +.It 1993-07-01 00:00:00 A+2 B+1 A+1 or A+2 +.It 1993-07-01 00:00:01 A+3 B+2 A+3 +.El +.Pp +A leap second deletion would look like the following, and +.Li posix2time(B+1) +would return either +.Li A +or +.Li A+1 . +.Pp +.Bl -column "????-06-30" "23:59:58" "A+1" "B+2" "A+1" +.It DATE TIME T X Y +.It ????-06-30 23:59:58 A B A +.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 +If leap-second support is not enabled, +local +.Vt time_t +and +POSIX +.Vt time_t +values are equivalent, +and both +.Fn time2posix +and +.Fn posix2time +degenerate to the identity function. +.Sh RETURN VALUES +If successful, these functions return the resulting timestamp without modifying +.Va errno . +Otherwise, they set +.Va errno +and return +.Li "((time_t) -1)" . +.Sh ERRORS +These functions fail if: +.Bl -tag -width Er +.It Bq Er EOVERFLOW +The resulting value cannot be represented. +This can happen for +.Fn posix2time +if its argument is close to the maximum +.Vt time_t +value. +In environments where the +.Ev TZ +environment variable names a TZif file, +overflow can happen for either function for an argument sufficiently +close to an extreme +.Vt time_t +value if the TZif file specifies unrealistic leap second corrections. +.El +.Sh "SEE ALSO" +.Xr difftime 3 , +.Xr localtime 3 , +.Xr mktime 3 , +.Xr time 3 |