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 值轉換為 tm 結構作為 UTC 時間。此結構是靜態分配的，由 gmtime、localtime 和 ctime 函式共享。每次呼叫這些函式之一時，結構的內容都會被覆蓋。

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

將 time_t 值轉換為 tm 結構作為 UTC 時間。時間儲存在 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_mon 和 tm_year 之前，不會檢查 tm_mday 的範圍。發生錯誤時，將返回 -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 擴充套件

單一 Unix 規範 (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: 時間型別 – 基礎定義參考，單一 UNIX® 規範，來自開放組的第 7 版
• "gmtime". 開放組基礎規範. 2008-12-09.

外部連結

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