time.h

time.h是C標準函式庫中取得時間與日期、對時間與日期資料操作及格式化的標頭檔。

表示時間的三種資料類型

• 日曆時間（Calendar Time），是從一個標準時間點（epoch）到現在的時間經過的秒數，不包括插入閏秒對時間的調整。開始計時的標準時間點，各種編譯器一般使用UTC 1970-01-01 00:00:00。日曆時間用資料類型time_t表示。time_t類型實際上一般是32位元整數類型，因此表示的時間不能晚於UTC 2038-01-18 19:14:07。為此，某些編譯器引入了64位元甚至更長的整型來儲存日曆時間，如Visual C++支援__time64_t資料類型，通過_time64()函式取得日曆時間，可支援到UTC 3001-01-01 00:00:00的時間。
• 處理器時間（Processor Time），也被稱為CPU時間（CPU Time），用以度量行程使用的CPU資源。處理器時間以時鐘滴答數（Clock Tick）計算，通常從行程啟動開始計時，因此這是相對時間。時鐘滴答數用系統基本資料類型clock_t來表示，每秒鐘包含CLOCKS_PER_SEC（time.h中定義的常數，一般為1000）個時鐘滴答，也可使用sysconf函式得到每秒的時鐘滴答數。clock_t類型一般是32位元整數類型。
• 分解時間(broken-down time)，用結構資料類型tm表示，tm包含下列結構成員：

成員	描述
int tm_hour	小時 (0 – 23)
int tm_isdst	夏令時啟用 (> 0)、禁用 (= 0)、未知 (< 0)
int tm_mday	一月中的哪一天 (1 – 31)
int tm_min	分 (0 – 59)
int tm_mon	月 (0 – 11, 0 = 一月)
int tm_sec	秒 (0 – 60, 60 = 閏秒)
int tm_wday	一周中的哪一天 (0 – 6, 0 = 周日)
int tm_yday	一年中的哪一天 (0 – 365)
int tm_year	1900 以來的年數

從電腦系統時鐘獲得時間的方法

• time_t time(time_t* timer)

得到從標準計時點（一般是UTC 1970年1月1日午夜）到當前時間的秒數。

• clock_t clock(void)

得到從行程啟動到此次函式呼叫的累計的時鐘滴答數。

Windows API提供了更為精確的GetLocalTime()取得毫秒級的日曆時間；QueryPerformanceCounter和QueryPerformanceFrequency兩個函式取得高於1毫秒的精度。

三種時間日期資料類型的轉換函式

• struct tm* gmtime(const time_t* timer)

從日曆時間time_t到分解時間tm（世界協調時UTC）的轉換。函式返回的是一個靜態分配的tm結構儲存空間，該儲存空間被gmtime, localtime與ctime函式所共享. 這些函式的每一次呼叫會覆蓋這塊tm結構儲存空間的內容。

• struct tm* gmtime_r(const time_t* timer, struct tm* result)

該函式是gmtime函式的執行緒安全版本.

• struct tm* localtime(const time_t* timer)

從日曆時間time_t到分解時間tm的轉換，即結果資料已經調整到本地時區與夏令時。

• time_t mktime(struct tm* ptm)

從基於本地時區(與夏令時)的分解時間tm到日曆時間time_t的轉換。忽略tm_wday與tm_yday的輸入值。如果tm_isdst不確定則輸入設為-1。其它各輸入域的值可以任意設定，輸出時被規格化到正確範圍。例如，想要計算2012年的第200天的日期，設為1月200日，函式會輸出正確的結果

• time_t timegm(struct tm* brokentime)

從分解時間tm（被視作UTC時間，不考慮本地時區設定）到日曆時間time_t的轉換。該函式較少被使用。

時間日期資料的格式化函式

• char *asctime(const struct tm* tmptr)

把分解時間tm輸出到字串，結果的格式為"Www Mmm dd hh:mm:ss yyyy"，即「周幾 月份數 日數 小時數:分鐘數:秒鐘數 年份數」。函式返回的字串為靜態分配，長度不大於26，與ctime函式共享。函式的每次呼叫將覆蓋該字串內容。

• char* ctime(const time_t* timer)

把日曆時間time_t timer輸出到字串，輸出格式與asctime函式一樣.

• size_t strftime(char* s, size_t n, const char* format, const struct tm* tptr)

把分解時間tm轉換為自訂格式的字串，類似於常見的字串格式輸出函式sprintf。例如：strftime(buf, 64, "%Y-%m-%d %H:%M:%S", localtime);

• char * strptime(const char* buf, const char* format, struct tm* tptr)

strftime的逆操作，把字串按照自訂的格式轉換為分解時間tm。

對時間資料的操作

• double difftime(time_t timer2, time_t timer1)

比較兩個日曆時間之差。

原始碼範例

列印當前時間到標準輸出流：

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

int main(void)
{
    time_t  timer = time(NULL);
    printf("ctime is %s\n", ctime(&timer));
    return 0;
}

參考來源

• Calendar Time. The GNU C Library Reference Manual. 2001-07-06 [2007-04-03]. （原始內容存檔於2007-03-28）. 
• gmtime. The Open Group Base Specifications. 2008-12-09 [2011-07-01]. （原始內容存檔於2010-12-08）. 

外部連結

• C++ reference for date/time functions inherited from C（頁面存檔備份，存於網際網路檔案館）