C 程式設計/time.h

在 C 程式語言中，time.h (在 C++ 中用作 ctime) 是 C 標準庫中定義的標頭檔案，包含時間和日期函式宣告，以提供對時間/日期操作和格式化的標準化訪問。

函式

char * asctime (const struct tm* tmptr)

將 tm 轉換為格式為 "Www Mmm dd hh:mm:ss yyyy" 的字串，其中 Www 是星期幾，Mmm 是月份字母，dd 是月份中的天數，hh:mm:ss 是時間，yyyy 是年份。該字串後面是一個換行符和一個終止空字元，總共包含 26 個字元。指向的字串是靜態分配的，並由 ctime 和 asctime 函式共享。每次呼叫這些函式之一時，字串的內容都會被覆蓋。

clock_t clock(void)

返回自程序啟動以來的時鐘滴答次數。

char* ctime(const time_t* timer)

將 time_t 時間值轉換為與 asctime 相同格式的字串。指向的字串是靜態分配的，並由 ctime 和 asctime 函式共享。每次呼叫這些函式之一時，字串的內容都會被覆蓋。ctime 還使用 gmtime 和 localtime 作為返回值的內部緩衝區，因此呼叫此函式會覆蓋它。

double difftime(time_t timer2, time_t timer1)

返回 timer2 減去 timer1 以給出兩個時間之間的秒數差。

struct tm* gmtime(const time_t* timer)

將 time_t 值轉換為 UTC 時間的 tm 結構。此結構是靜態分配的，並由 gmtime、localtime 和 ctime 函式共享。每次呼叫這些函式之一時，結構的內容都會被覆蓋。

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

將 time_t 值轉換為 UTC 時間的 tm 結構。該時間儲存在 result 指向的 tm 結構中。此函式是 gmtime 的執行緒安全版本。

struct tm* localtime(const time_t* timer)

將 time_t 時間值轉換為本地時間 (即針對本地時區和夏令時調整的時間) 的 tm 結構。此結構是靜態分配的，並由 gmtime、localtime 和 ctime 函式共享。每次呼叫這些函式之一時，結構的內容都會被覆蓋。

time_t mktime(struct tm* ptm)

將 tm 轉換為 time_t 時間值。檢查作為引數 ptm 傳遞的 tm 結構的成員，如果提供的值不在可能範圍內，或者它們不完整或錯誤，則調整這些值，然後將該結構轉換為返回的 time_t 值。ptm 的 tm_wday 和 tm_yday 成員的原始值被忽略並用相應的計算日期值填充。tm_mday 的範圍不會在確定 tm_mon 和 tm_year 之前進行檢查。發生錯誤時，返回 -1 值。

time_t time(time_t* timer)

從系統時鐘獲取當前時間 (自紀元以來的秒數)。將該值儲存在 timer 中。如果 timer 為空，則不會儲存該值，但仍會由該函式返回。

size t strftime(char* s, size t n, const char* format, const struct tm* tptr)

將 tm 格式化為日期/時間字串。

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

從 buf 字串中掃描值到 tptr 結構中。成功時，它返回指向解析的最後一個字元後面的字元的指標。否則，它返回空值。

time_t timegm(struct tm *brokentime)

timegm 在功能上與 mktime 相同，只是它始終將輸入值視為協調世界時 (UTC)，而不管任何本地時區設定。請注意，timegm 是 gmtime 的逆運算。

可移植性說明：mktime 基本上是普遍可用的。timegm 相當罕見。為了實現最可移植 (但非執行緒安全) 的從 UTC 分解時間到簡單時間的轉換，請將 TZ 環境變數設定為 UTC，呼叫 mktime，然後將 TZ 設定回原值。

Unix 擴充套件

Single UNIX Specification (IEEE 1003.1，以前稱為 POSIX) 為 time.h 添加了兩個函式：asctime_r 和 ctime_r. 這些是 asctime 和 ctime 的可重入版本。這兩個函式都要求呼叫者提供一個緩衝區，用於儲存時間點的文字表示形式。以下示例演示瞭如何使用 localtime 和 asctime 的可重入版本

#define _POSIX_C_SOURCE 200112L
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

int main(void) {
  time_t rawtime;
  struct tm *timeinfo;
  struct tm timeinfoBuffer;
  char *result;

  time(&rawtime);
  /* call localtime */
  timeinfo = localtime_r(&rawtime, &timeinfoBuffer);
  /* allocate memory for the result of asctime call*/
  result = malloc(26 * sizeof(char));
  /* call reentrant asctime function */
  result = asctime_r(timeinfo, result);
  printf("The current date/time is: %s", result);
  /* free allocated memory */
  free(result);

  return 0;
}

由於這些函式不在 C++ 標準中，因此它們不屬於該語言的 std 名稱空間。<vinu.h>

常量

CLK_PER_SEC

定義每秒時鐘滴答次數的常量。由 clock() 函式使用。

CLOCKS_PER_SEC

CLK_PER_SEC 的替代名稱，在某些庫中使用它。

CLK_TCK

CLK_PER_SEC 的過時宏。

資料型別

clock_t

clock() 返回的資料型別。
通常定義為 int 或 long int。

time_t

time() 返回的資料型別。
通常定義為 int 或 long int。

struct tm

時間的“分解”（元件化）日曆表示形式。

日曆時間

C 標準庫中的日曆時間 (也稱為“分解時間”) 表示為 struct 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 年以來的年份

示例

此原始碼片段將當前時間列印到標準輸出流。

#include <stdio.h>
#include <time.h>
 
int main(void)
{
  time_t timer = time(NULL);
  printf("current time is %s", ctime(&timer));
  return 0;
}

參考文獻

• "日曆時間". GNU C 庫參考手冊. 2001-07-06. 檢索於 2007-04-03.
• time.h: 時間型別 – 基本定義參考，The Single UNIX® Specification，Issue 7 來自 The Open Group
• "gmtime". The Open Group Base Specifications. 2008-12-09.

外部連結

• C++ 中繼承自 C 的日期/時間函式參考