gmtime_s、_gmtime32_s、_gmtime64_s

將時間值轉換成 tm 結構。 這些函式是 _gmtime32, _gmtime64 的版本，具有 CRT 中的安全性功能中所述的安全性增強功能。

語法

errno_t gmtime_s(
   struct tm* tmDest,
   const __time_t* sourceTime
);
errno_t _gmtime32_s(
   struct tm* tmDest,
   const __time32_t* sourceTime
);
errno_t _gmtime64_s(
   struct tm* tmDest,
   const __time64_t* sourceTime
);

參數

tmDest
tm 結構的指標。 傳回結構的欄位以 UTC 來保存 timer 引數的評估值，而非當地時間。

sourceTime
預存時間的指標。 時間以國際標準時間 1970 年 1 月 1 日 (UTC) 午夜 (00: 00:00) 以來經過的秒代表。

傳回值

如果成功，則為零。 如果失敗，傳回的值會是錯誤碼。 錯誤碼於 Errno.h 中定義；如需這些錯誤的清單，請參閱 errno。

錯誤條件

tmDest	sourceTime	傳回	tmDest 中的值
NULL	任意	EINVAL	未修改。
非 NULL (指向有效的記憶體)	NULL	EINVAL	所有的欄位設定為 -1。
不是 NULL	< 0	EINVAL	所有的欄位設定為 -1。

前兩個錯誤狀況都會叫用無效的參數處理常式，如參數驗證中所述。 如果允許繼續執行，這些函式會將 errno 設為 EINVAL，並傳回 EINVAL。

備註

_gmtime32_s 函式會細分 sourceTime 值，並將它儲存在 tm 類型的結構中，如 Time.h 中所定義。 結構的位址會傳入 tmDest。 sourceTime 的值通常取自對 time 函式的呼叫。

每個結構欄位是 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_s 一律為 0。

使用 __time64_t 結構的 _gmtime64_s，允許表示至 3000 年 12 月 31 日 23:59:59 UTC 為止的日期，而 gmtime32_s 只能表示至 2038 年 1 月 18 日23:59:59 UTC 的日期。 1970 年 1 月 1 日午夜是所有這兩個函式的日期範圍下限。

gmtime_s 是評估為 _gmtime64_s 的內嵌函式，而 time_t 相當於 __time64_t。 如果您要強制編譯器將 time_t 解譯為舊的 32 位元 time_t，您可以定義 _USE_32BIT_TIME_T。 _USE_32BIT_TIME_T 導致 gmtime_s 內嵌為 _gmtime32_s。 我們不建議使用 _USE_32BIT_TIME_T，原因是您的應用程式可能會在 2038 年 1 月 18 日後失敗，也因為 64 位元平台上不允許這種定義。

根據預設，此函式的全域狀態會限定於應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。

需求

常式	必要的 C 標頭	必要的 C++ 標頭
gmtime_s、_gmtime32_s、_gmtime64_s	<time.h>	<ctime> 或 <time.h>

如需相容性詳細資訊，請參閱相容性。

範例

// 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 );
}

Coordinated universal time is Fri Apr 25 20:12:33 2003

另請參閱

時間管理
asctime_s、_wasctime_s
ctime、_ctime32、_ctime64、_wctime、_wctime32、_wctime64
_ftime、_ftime32、_ftime64
gmtime、_gmtime32、_gmtime64
localtime_s、_localtime32_s、_localtime64_s
_mkgmtime、_mkgmtime32、_mkgmtime64
mktime、_mktime32、_mktime64
time、_time32、_time64