gmtime_s、_gmtime32_s、_gmtime64_s

[アーティクル]
08/09/2011

時刻の値を構造体に変換します。これらの関数は、「CRT のセキュリティ機能」に説明されているように、_gmtime32、_gmtime64 のセキュリティが強化されたバージョンです。

errno_t gmtime_s(
   struct tm* _tm,
   const __time_t* time
);
errno_t _gmtime32_s(
   struct tm* _tm,
   const __time32_t* time
);
errno_t _gmtime64_s(
   struct tm* _tm,
   const __time64_t* time 
);

パラメーター

_tm
tm 構造体へのポインター。返された構造体の各フィールドには、timer 引数を現地時刻ではなく UTC で評価した値が格納されています。
time
格納されている時刻へのポインター。時刻は、世界協定時刻 (UTC: Coordinated Universal Time) の 1970 年 1 月 1 日の深夜 00:00:00 から経過した時間 (秒単位) を表します。

戻り値

正常に終了した場合は 0 を返します。エラーが発生した場合の戻り値はエラーコードです。エラーコードは、Errno.h で定義されています。これらのエラーの一覧については、「errno 定数」を参照してください。

エラー条件

_tm	time	Return	_tm の値
NULL	any	EINVAL	変更されない。
NULL 以外 (有効なメモリを指し示している)	NULL	EINVAL	すべてのフィールドが -1 に設定される。
NULL 以外	< 0	EINVAL	すべてのフィールドが -1 に設定される。

最初の 2 つのエラー条件の場合、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、これらの関数は errno を EINVAL に設定し、EINVAL を返します。

解説

_gmtime32_s 関数は、time 値を展開して、Time.h に定義されている tm 型の構造体に格納します。構造体のアドレスは、_tm に渡されます。 time 値は通常、time 関数の呼び出しにより取得されます。

注意

対象の環境で夏時間が有効かどうかを確認してください。 C ランタイムライブラリでは、アメリカ合衆国の規則を前提に夏時間を計算します。

構造体には、次に示す int 型のフィールドがあります。

tm_sec
秒 (0 ～ 59)。
tm_min
分 (0 ～ 59)。
tm_hour
時 (0 ～ 23)。
tm_mday
日 (1 ～ 31)。
tm_mon
月 (0 ～ 11、1 月 = 0)。
tm_year
年 (実際の西暦から 1900 を引いた数)
tm_wday
曜日 (0 ～ 6、日曜日 = 0)。
tm_yday
年内の通算日 (0 ～ 365、1 月 1 日 = 0)。
tm_isdst
gmtime では常に 0。

__time64_t 構造体を使用する _gmtime64_s は、UTC の 3000 年 12 月 31 日の 23 時 59 分 59 秒までの日付を表すことができます。それに対して、gmtime32_s は、UTC の 2038 年 1 月 19 日の 03 時 14 分 07 秒までしか表すことができません。これらの関数の日付範囲の下限は、どちらも 1970 年 1 月 1 日の午前零時です。

gmtime_s評価される、インライン関数は_gmtime64_sとtime_tに相当する__time64_t。コンパイラが time_t を従来の 32 ビット time_t として解釈するようにするには、_USE_32BIT_TIME_T を定義します。この定義を行うことにより、gmtime_s は _gmtime32_s にインライン展開されます。この方法はお勧めしません。2038 年 1 月 18 日以降にアプリケーションでエラーが発生する可能性があり、64 ビットプラットフォームでは使用できないためです。

必要条件

ルーチン	必須ヘッダー
gmtime_s	<time.h>
_gmtime32_s	<time.h>
_gmtime64_s	<time.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// crt_gmtime64_s.c
// This program uses _gmtime64_s to convert a 64-bit
// integer representation of coordinated universal time
// to a structure named newtime, then uses asctime_s to
// convert this structure to an output string.
 

#include <time.h>
#include <stdio.h>

int main( void )
{
   struct tm newtime;
   __int64 ltime;
   char buf[26];
   errno_t err;

   _time64( &ltime );

   // Obtain coordinated universal time: 
   err = _gmtime64_s( &newtime, &ltime );
   if (err)
   {
      printf("Invalid Argument to _gmtime64_s.");
   }
   
   // Convert to an ASCII representation 
   err = asctime_s(buf, 26, &newtime);
   if (err)
   {
      printf("Invalid Argument to asctime_s.");
   }

   printf( "Coordinated universal time is %s\n", 
           buf );
}