.\" %FreeBSD: src/lib/libc/stdtime/time2posix.3,v 1.9.2.4 2001/12/14 18:33:59 ru Exp %
.\" $FreeBSD$
.\"
.Dd May 1, 1996
.Dt TIME2POSIX 3
.Os
.Sh 名称
.Nm time2posix ,
.Nm posix2time
.Nd 基準時点からの秒数を変換
.Sh ライブラリ
.Lb libc
.Sh 書式
.In time.h
.Ft time_t
.Fn time2posix "const time_t *t"
.Ft time_t
.Fn posix2time "const time_t *t"
.Sh 解説
.St -p1003.1-88
は、536457599 という time_t 値を "1986 年 12 月 31 日 23:59:59"
に対応させるように規定しています。これは、実際上 POSIX の time_t が
うるう秒を含むことはできず、従ってシステム時間はうるう秒が起きるたびに
調整する必要があることを意味しています。
.Pp
しかしながら、時間パッケージのうるう秒サポートが有効に設定されている
場合は、このような調整は必要がなく、time_t 値はうるう秒が
起きても正しく (真の「…からの秒数」で) 進みます。
これは、これらの値が基準時点以後に挿入された
正味のうるう秒だけ POSIX によって要求される値と異なることを意味します。
.Pp
通常は、タイプ time_t は (ほとんどの場合) 不透明なので
\(em すなわち time_t 値は
.Xr time 3 ,
.Xr localtime 3 ,
.Xr mktime 3 ,
.Xr difftime 3
などの関数からのみ取得し、またそれらの関数のみに渡すように
考えられているので \(em 
このことは問題になりません。
しかしながら、
.St -p1003.1-88
は、日付/時間から time_t 値を直接計算する数式を与えており、
プログラムによってはこの関係を前提条件にしているものがあります。
通常、この関係を使って time_t の作成/分析を行っているプログラムでは、
うるう秒をまたがる間隔を正しく処理できません。
.Pp
.Fn time2posix
および
.Fn posix2time
関数は、ローカルの time_t 値とそれに相当する POSIX 等価の値との間で
変換を行って、この time_t のミスマッチに対応するために
用意されたものです。これは、うるう秒の挿入や
削除に応じて POSIX システムに起きたタイムベース変更の回数を数える
ことにより行います。これらの変換値は、
古いアプリケーションを訂正する代りに、あるいは POSIX 準拠システムと
通信するときに用いることができます。
.Pp
.Fn time2posix
関数は単一の値を持ちます。すなわち、すべてのローカルの time_t は、
単一の POSIX time_t に対応します。
.Fn posix2time
関数の動作は、それほど行儀よくありません。
正のうるう秒に出会うとその結果は 1 つにはならず、
また負のうるう秒に対しては対応する time_t が存在しないために
それに近い値が返されます。これらの 2 つの例は、POSIX による
表現の欠陥度を示すよい指標であるといえます。
.Pp
次の表は、1993 年 6 月末に挿入されたうるう秒に対して、time_t と
その POSIX 表現への変換値、およびそれを再変換して戻した値との関係を示します。
.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
うるう秒削除は次のようになります。
.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 "[注: posix2time(B+1) => A+0 or A+1]"
.Pp
うるう秒サポートが有効になっていない場合は、
ローカルの time_t と POSIX の time_t は等価となり、
.Fn time2posix
および
.Fn posix2time
関数はともに恒等関数となります。
.Sh 関連項目
.Xr difftime 3 ,
.Xr localtime 3 ,
.Xr mktime 3 ,
.Xr time 3