関数 Fn localtime は、 Fa clock が指す時刻の値を変換し、現在の時間帯 (および日光節約時間のような他の要素) に調整した後の値について細分化された時間情報が入った ``Fa struct tm '' (後述) を指すポインタを返します。時間帯調整は、 TZ 環境変数 ( tzset(3) を参照) で指定されたように実行されます。 プロセスが tzset(3) をまだ呼び出していない場合、関数 Fn localtime は、 tzset(3) を使用して、時刻変換情報を初期化します。
構造体 tm に代入した後、 Fn localtime は、 Fa tzname の Fa tm_isdst 番めの要素を、 Fn localtime の戻り値とともに使用する時間帯短縮形である ASCII 文字列を指すポインタに設定します。
関数 Fn gmtime は、同様に時刻の値を変換しますが、時間帯の調整はなく、 構造体 tm を指すポインタを返します (後述)。
Fn ctime 関数は、 Fn localtime と同じ方法で現在の時間帯の時刻値を調整し、次の形式の 26 文字の文字列を指すポインタを返します。
Thu Nov 24 18:22:48 1986\n\0
フィールドにはすべて一定の幅があります。
Fn ctime_r は、 Fn ctime と同じ機能ですが、呼び出し元が結果を保存するために出力バッファ Fa buf を準備しなければならないという点は異なります。このバッファは少なくとも 26 文字の長さである必要があります。 Fn localtime_r および Fn gmtime_r は、それぞれ、 Fn localtime および Fn gmtime と同じ機能ですが、呼び出し元が出力バッファ Fa result を準備しなければならないという点は異なります。
Fn asctime 関数は、 Fa *tm が指す構造体 Fa tm 内の細分化された時間を変換し、前述の例に示した形式にします。
Fn asctime_r は、 Fn asctime と同じ機能を備えていますが、呼び出し元が結果を保存するための 出力バッファ Fa buf を準備する点は異なります。このバッファの長さは少なくとも 26 文字である必要があります。
関数 Fn mktime と Fn timegm は、 tm が指す構造体内の細分化した時間を、 time(3) 関数が返す値と同じエンコードの時刻値に変換します (すなわち、基準時点 UTC からの時刻にします)。 Fn mktime は、現在の時間帯設定に従って入力構造体を解釈します ( tzset(3) を参照)。 Fn timegm は、協定世界時 (UTC ) を表す入力構造体を解釈します。
構造体の Fa tm_wday コンポーネントと Fa tm_yday コンポーネントのオリジナル値は無視され、 他のコンポーネントのオリジナルの値はその通常の範囲に制限されませんし、 必要な場合は正規化されます。 例えば、10 月 40 日は 11 月 9 日に変換され、 Fa tm_hour に -1 が指定されると深夜から 1 時間前を意味し、 Fa tm_mday に 0 が指定されると現在の月の直前の日を意味し、 Fa tm_mon に -2 が指定されると Fa tm_year の 1 月から 2 ヶ月前を意味します。( Fa tm_isdst が 正の場合、 Fn mktime は、初期的には、指定時間について夏時間 (たとえば、日光節約時間) が有効であると推測します。 0 の場合は、夏時間が有効でないと想定します。 Fa tm_isdst が 負の値の場合、 Fn mktime 関数は、指定の時間について夏時間が有効であるかどうか 推測しようとします。 Fa tm_isdst メンバと Fa tm_gmtoff メンバは Fn timegm によって強制的に 0 にされます)。
処理が正常に完了すると、構造体の Fa tm_wday コンポーネントおよび Fa tm_yday コンポーネントの値は適宜、設定され、他のコンポーネントは指定の カレンダ時間を表すよう設定されますが、値は通常の範囲にさせられます。 Fa tm_mon と Fa tm_year が決定されるまで、 Fa tm_mday の最終値は設定されません。 Fn mktime は、指定のカレンダ時間を返します。カレンダ時間が表わせない 場合は、-1 が返されます。
Fn difftime 関数は、2 つのカレンダ時間の間の差 ( Fa time1 - Fa time0 ) (秒単位) を返します。
外部宣言と構造体 tm の両方が Aq Pa time.h インクルードファイル内にあります。構造体 tm には少なくとも 次のフィールドがインクルードされています。
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 からのオフセット (秒単位) */
夏時間が有効な場合、フィールド Fa tm_isdst は 0 でなくなります。
フィールド Fa tm_gmtoff は、 UTC から表される時間のオフセット (秒単位) であり、 正の値は本初子午線の東を示します。
Fn asctime_r , Fn ctime_r , Fn gmtime_r , Fn localtime_r の各関数は St -p1003.1-96 に適合しています (ここでも、選択したローカルな時間帯に 閏秒テーブルが含まれていない場合だけです)。
Fn timegm 関数は、いかなる規格によっても指定されていません。 この関数は、上述の標準関数を使用しても、完全にはエミュレート不可能です。
C 言語規格は、プログラムがその現在のローカル時間帯設定を修正する メカニズムを備えていませんし、 POSIX 規格方式は再入可能ではありません (しかし、スレッドセーフシステムが POSIX スレッド環境には備わっています)。
返された構造体 tm の Fa tm_zone フィールドは、キャラクタの静的配列を指します。 これも後の呼び出しで上書きされます ( tzset(3) と tzsetwall(3) の後の呼び出しによって上書きされるのと同じようにです)。
外部変数 Fa tzname の使用はお勧めできません。構造体 tm 内の Fa tm_zone エントリをお勧めします。