gmtime, gmtime_r, gmtime_s

 

C

編譯器支援

語言

標頭檔案

型別支援

程式工具

變參函式支援

錯誤處理

動態記憶體管理

字串庫

演算法

數值

日期和時間工具

輸入/輸出支援

本地化支援

併發支援 (C11)

技術規範

符號索引

 

日期和時間工具

函式

時間操作

difftime

time

clock

timespec_get (C11)

timespec_getres (C23)

格式轉換

asctimeasctime_s (C23 中已廢棄)(C11)

ctimectime_s (C23 中已廢棄)(C11)

strftime

wcsftime (C95)

gmtimegmtime_rgmtime_s (C23)(C11)

localtimelocaltime_rlocaltime_s (C23)(C11)

mktime

常量

CLOCKS_PER_SEC

型別

tm

time_t

clock_t

timespec (C11)

 

定義於標頭檔案 <time.h>
struct tm* gmtime  ( const time_t* timer );	(1)
struct tm* gmtime_r( const time_t* timer, struct tm* buf );	(2)	(自 C23 起)
struct tm* gmtime_s( const time_t* restrict timer, struct tm* restrict buf );	(3)	(C11 起)

1) 將給定時間（自紀元以來的時間，由 timer 指向的 time_t 值）轉換為日曆時間，以協調世界時 (UTC) 表示，格式為 struct tm。結果儲存在靜態儲存中，並返回指向該靜態儲存的指標。

2) 同 (1)，但函式使用使用者提供的儲存 buf 來儲存結果。

3) 同 (1)，但函式使用使用者提供的儲存 buf 來儲存結果，並且在執行時檢測到以下錯誤並呼叫當前安裝的約束處理程式函式

• timer 或 buf 是空指標

與所有邊界檢查函式一樣，只有當實現定義了 __STDC_LIB_EXT1__ 並且使用者在包含 <time.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整數常量 1 時，才能保證 gmtime_s 可用。

引數

timer	-	指向要轉換的 time_t 物件的指標
buf	-	指向儲存結果的 struct tm 物件的指標

返回值

1) 成功時返回指向靜態內部 tm 物件的指標，否則返回空指標。該結構可能在 gmtime、localtime 和 ctime 之間共享，並且每次呼叫都可能被覆蓋。

2,3) buf 指標的副本，或錯誤時（可能是執行時約束違規或無法將指定時間轉換為 UTC）返回空指標。

注意

gmtime 可能不是執行緒安全的。

POSIX 要求如果 gmtime 和 gmtime_r 因引數過大而失敗，則將 errno 設定為 EOVERFLOW。

Microsoft CRT 中 gmtime_s 的實現與 C 標準不相容，因為它引數順序顛倒了。

示例

執行此程式碼

#define __STDC_WANT_LIB_EXT1__ 1
#define _XOPEN_SOURCE // for putenv
#include <stdio.h>
#include <stdlib.h>   // for putenv
#include <time.h>
 
int main(void)
{
    time_t t = time(NULL);
    printf("UTC:       %s", asctime(gmtime(&t)));
    printf("local:     %s", asctime(localtime(&t)));
    // POSIX-specific
    putenv("TZ=Asia/Singapore");
    printf("Singapore: %s", asctime(localtime(&t)));
 
#ifdef __STDC_LIB_EXT1__
    struct tm buf;
    char str[26];
    asctime_s(str, sizeof str, gmtime_s(&t, &buf));
    printf("UTC:       %s", str);
    asctime_s(str, sizeof str, localtime_s(&t, &buf));
    printf("local:     %s", str);
#endif
}

可能的輸出

UTC:       Fri Sep 15 14:22:05 2017
local:     Fri Sep 15 14:22:05 2017
Singapore: Fri Sep 15 22:22:05 2017
UTC:       Fri Sep 15 14:22:05 2017
local:     Fri Sep 15 14:22:05 2017

參考

• C23 標準 (ISO/IEC 9899:2024)

• 7.27.3.3 gmtime 函式 (p: TBD)

• K.3.8.2.3 gmtime_s 函式 (p: TBD)

• C17 標準 (ISO/IEC 9899:2018)

• 7.27.3.3 gmtime 函式 (p: 288)

• K.3.8.2.3 gmtime_s 函式 (p: 454-455)

• C11 標準 (ISO/IEC 9899:2011)

• 7.27.3.3 gmtime 函式 (p: 393-394)

• K.3.8.2.3 gmtime_s 函式 (p: 626-627)

• C99 標準 (ISO/IEC 9899:1999)

• 7.23.3.3 gmtime 函式 (p: 343)

• C89/C90 標準 (ISO/IEC 9899:1990)

• 4.12.3.3 gmtime 函式

另請參閱

localtimelocaltime_rlocaltime_s (C23)(C11)	將自紀元以來的時間轉換為以本地時間表示的日曆時間 (函式)
C++ 文件 關於 gmtime