.\" Copyright (c) 1989, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Arthur Olson.
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93
.\" %Id: ctime.3,v 1.8 1999/01/03 01:07:41 wollman Exp %
.\"
.\" $FreeBSD$
.Dd January 2, 1999
.Dt CTIME 3
.Os BSD 4.3
.Sh 名称
.Nm asctime ,
.Nm asctime_r ,
.Nm ctime ,
.Nm ctime_r ,
.Nm difftime ,
.Nm gmtime ,
.Nm gmtime_r ,
.Nm localtime ,
.Nm localtime_r ,
.Nm mktime ,
.Nm timegm
.Nd バイナリ日付と時刻の値を変換する
.Sh 書式
.Fd #include <time.h>
.Vt extern char *tzname[2];
.Ft char *
.Fn ctime "const time_t *clock"
.Ft double
.Fn difftime "time_t time1" "time_t time0"
.Ft char *
.Fn asctime "const struct tm *tm"
.Ft struct tm *
.Fn localtime "const time_t *clock"
.Ft struct tm *
.Fn gmtime "const time_t *clock"
.Ft time_t
.Fn mktime "struct tm *tm"
.Ft time_t
.Fn timegm "struct tm *tm"
.Ft char *
.Fn ctime_r "const time_t *clock" "char *buf"
.Ft struct tm *
.Fn localtime_r "const time_t *clock" "struct tm *result"
.Ft struct tm *
.Fn gmtime_r "const time_t *clock" "struct tm *result"
.Ft char *
.Fn asctime_r "const struct tm *tm" "char *buf"
.Sh 解説
関数
.Fn ctime ,
.Fn gmtime ,
.Fn localtime
はすべて、基準時点 (00:00:00
.Tn UTC ,
1970 年 1 月 1 日
.Xr time 3
を参照) 以降の時刻 (秒単位) を表す時間の値を引数として取ります。
.Pp
関数
.Fn localtime
は、
.Fa clock
が指す時刻の値を変換し、現在の時間帯 (および日光節約時間のような他の要素)
に調整した後の値について細分化された時間情報が入った
.Dq Fa struct tm
(後述) を指すポインタを返します。時間帯調整は、
.Ev TZ
環境変数 (
.Xr tzset 3
を参照) が指定するように実行されます。
.Xr tzset 3
がプロセスによってまだ呼び出されていない場合、関数
.Fn localtime
は、
.Xr tzset 3
を使用して、時刻変換情報を初期化します。
.Pp
構造体 tm に代入した後、
.Fn localtime
は、
.Fa tzname
の
.Fa tm_isdst
番めのエレメントを、
.Fn localtime
の戻り値とともに使用する時間帯短縮形である
.Tn ASCII
ストリングを指すポインタに設定します。
.Pp
関数
.Fn gmtime
は、同じように時刻の値を変換しますが、時間帯の調整はなく、
構造体 tm を指すポインタを返します (後述)。
.Pp
.Fn ctime
関数は、
.Fn localtime
と同じ方法で現在の時間帯の時刻値を調整し、次の形式の
26 キャラクタのストリングを指すポインタを返します。
.Bd -literal -offset indent
Thu Nov 24 18:22:48 1986\en\e0
.Ed
.Pp
フィールドにはすべて一定の幅があります。
.Pp
.Fn ctime_r
は、
.Fn ctime
と同じ機能ですが、呼び出し元が結果を保存するために出力バッファ
.Fa buf
を準備しなければならないという点は異なります。このバッファは少なくとも
26 キャラクタの長さである必要があります。
.Fn localtime_r
および
.Fn gmtime_r
は、それぞれ、
.Fn localtime
および
.Fn gmtime
と同じ機能ですが、呼び出し元が出力バッファ
.Fa result
を準備しなければならないという点は異なります。
.Pp
.Fn asctime
関数は、
.Fa *tm
が指す構造体
.Fa tm
内の細分化された時間を変換し、前述の例に示した形式にします。
.Pp
.Fn asctime_r
は、
.Fn asctime
と同じ機能を備えていますが、呼び出し元が結果を保存するための
出力バッファ
.Fa buf
を準備する点は異なります。このバッファの長さは少なくとも
26 キャラクタである必要があります。
.Pp
関数
.Fn mktime
と
.Fn timegm
は、
tm
が指す構造体内の細分化した時間を、
.Xr time 3
関数が返す値と同じエンコードの時刻値に変換します (すなわち、Epoch，
.Tn UTC
からの時刻にします)。
.Fn mktime
は、現在の時間帯設定に従って入力構造体を解釈します (
.Xr tzset 3
を参照)。
.Fn timegm
は、協定世界時
.Pq Tn UTC
を表す入力構造体を解釈します。
.Pp
構造体の
.Fa tm_wday
コンポーネントと
.Fa tm_yday
コンポーネントのオリジナル値は無視され、
他のコンポーネントのオリジナルの値はその通常の範囲に制限されません (
.Fa tm_isdst
が正の値の場合、
.Fn mktime
は、初期的には、指定時間についてサマータイム (たとえば、日光節約時間)
が有効であると推測します。ゼロの場合は、サマータイムが有効でないと
想定します。
.Fa tm_isdst
が
負の値の場合、
.Fn mktime
関数は、指定の時間についてサマータイムが有効であるかどうか
推測しようとします。
.Fa tm_isdst
メンバと
.Fa tm_gmtoff
メンバは
.Fn timegm
によって強制的にゼロにされます)。
.Pp
処理が正常に完了すると、構造体の
.Fa tm_wday
コンポーネントおよび
.Fa tm_yday
コンポーネントの値は適宜、設定され、他のコンポーネントは指定の
カレンダー時間を表すよう設定されますが、値は通常の範囲にさせられます。
.Fa tm_mon
と
.Fa tm_year
が決定されるまで、
.Fa tm_mday
の最終値は設定されません。
.Fn mktime
は、指定のカレンダー時間を返します。カレンダー時間が表わせない
場合は、\-1 が返されます。
.Pp
.Fn difftime
関数は、2 つのカレンダー時間の間の差
.Pf ( Fa time1
-
.Fa time0 )
(秒単位) を返します。
.Pp
外部宣言と構造体 tm の両方が
.Aq Pa time.h
インクルードファイル内にあります。構造体 tm には少なくとも
次のフィールドがインクルードされています。
.Bd -literal -offset indent
int tm_sec; /\(** 秒 (0 - 60) \(**/
int tm_min; /\(** 分 (0 - 59) \(**/
int tm_hour; /\(** 時 (0 - 23) \(**/
int tm_mday; /\(** 月内の日 (1 - 31) \(**/
int tm_mon; /\(** 月 (0 - 11) \(**/
int tm_year; /\(** 年 \- 1900 \(**/
int tm_wday; /\(** 曜日 (Sunday = 0) \(**/
int tm_yday; /\(** 年内の日 (0 - 365) \(**/
int tm_isdst; /\(** サマータイムは有効か \(**/
char \(**tm_zone; /\(** 時間帯名の短縮形 \(**/
long tm_gmtoff; /\(** UTC からのオフセット (秒単位) \(**/
.Ed
.Pp
サマータイムが有効な場合、フィールド
.Fa tm_isdst
はゼロでなくなります。
.Pp
フィールド
.Fa tm_gmtoff
は、
.Tn UTC
から表される時間のオフセット (秒単位) であり、
正の値は本初子午線の東を示します。
.Sh 関連項目
.Xr date 1 ,
.Xr gettimeofday 2 ,
.Xr getenv 3 ,
.Xr time 3 ,
.Xr tzset 3 ,
.Xr tzfile 5
.Sh 規格
.Fn asctime ,
.Fn ctime ,
.Fn difftime ,
.Fn gmtime ,
.Fn localtime ,
.Fn mktime
の各関数は、選択したローカルな時間帯に閏秒テーブルが含まれていない
場合だけ、
.St -isoC
と
.St -p1003.1
に準拠します (
.XX zic 8
を参照)。
.Pp
.Fn asctime_r ,
.Fn ctime_r ,
.Fn gmtime_r ,
.Fn localtime_r
の各関数は
.St -iso9945-1
に準拠すると予想されます (ここでも、選択したローカルな時間帯に
閏秒テーブルが含まれていない場合だけです)。
.Sh 歴史
このマニュアルページは、
Arthur Olsen
によって
Berkeley
に寄付された時間パッケージに由来するもので、これは
.Bx 4.3
で現れました。
.Sh バグ
.Fn difftime ,
.Fn mktime
および他の関数の
.Fn \&_r
のついた変種を除いて、これらの関数は、結果を内部静的オブジェクトに残し、
そのオブジェクトを指すポインタを返します。後でこれらの関数を呼び出すと、
同じオブジェクトが修正されます。
.Pp
C 言語規格は、プログラムがその現在のローカル時間帯設定を修正する
メカニズムを備えていませんし、
.Tn POSIX
規格方式は再入可能ではありません (しかし、スレッドセーフシステムが
.Tn POSIX
スレッド環境には備わっています)。
.Pp
返された構造体 tm の
.Fa tm_zone
フィールドは、キャラクタの静的配列を指します。
これも後の呼び出しで上書きされます (
.Xr tzset 3
と
.Xr tzsetwall 3
の後の呼び出しによって上書きされるのと同じようにです)。
.Pp
外部変数
.Fa tzname
の使用はお勧めできません。構造体 tm 内の
.Fa tm_zone
エントリをお勧めします。
