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++ 参考