gmtime_s、_gmtime32_s、_gmtime64_s

發行項
06/09/2015

轉換時間值成為一個結構。這些是 0z9czt0w(v=vs.120).md CRT 中的安全性功能中所述。

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
tmSID 結構的指標。傳回結構的欄位表示 timer 引數的評估值 UTC 的而不是本地時間。
time
要儲存時間的指標。時間表示為秒從午夜 (00:00: 00) 1970 年 1 月 1 日 (Coordinated Universal Time (UTC) 經過的時間。

傳回值

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

錯誤狀況

_tm	time	傳回	在 _tm 的值
NULL	any	EINVAL	未修改。
不是 NULL (指向有效的記憶體)	NULL	EINVAL	所有欄位設定為 -1。
非NULL	< 0	EINVAL	所有欄位設定為 -1。

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

備註

_gmtime32_s 函式會破壞 time 的值並將它存入型別的結構 tm，定義在 Time.h。結構的位址傳入 _tm。 time 的值通常取自對 time 函式的呼叫。

注意事項
目標環境應該嘗試判斷日光節約時間是否為作用中。C 執行階段程式庫假設使用美國規則來實作日光節約時間 (DST) 的計算。

如下表所示，每個結構欄位的型別為 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。

_gmtime64_s，使用 __time64_t 結構，讓日期可以表示西元 3000 年 12 月 31 日 UTC之前的日期；而 gmtime32_s 則只能代表西元 2038年 1 月 19 日 03:14:07 UTC 前的日期。 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>

如需更多關於相容性的資訊，請參閱入門介紹中的相容性 (Compatibility) 。

範例

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