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 的日期/时间函数参考