C 标准库＜time.h＞函数详解

概述

1 核心数据类型

1.1 time_t

1.2 clock_t

1.3 struct tm

1.4 size_t

2 核心函数

2.1 时间获取函数

2.2 时间转换函数

2.3 时间差计算

2.4 时间格式化函数

3 线程安全版本（POSIX 扩展）

3.1 函数列表

3.2 时间处理完整示例

4 重要注意事项

5 实际应用场景

5.1 日志记录

5.2 定时任务

5.3 性能分析

5.4 时间戳转换

6 Nordic MCU上验证

概述

本文主要介绍C 标准库 <time.h> 函数，<time.h> 是 C 语言中处理时间和日期的标准库，提供了一系列函数和数据类型用于时间获取、转换和格式化操作提供了一套完整的时间处理工具链，尽管在精度和时区处理上有一定限制，但对于大多数应用场景已经足够。在开发跨平台应用时，应注意不同系统对线程安全和时区支持的差异。

1 核心数据类型

1.1 `time_t`

描述：表示日历时间的算术类型（通常为整数）
特性：

存储从 "纪元"（通常为 1970-01-01 00:00:00 UTC）起经过的秒数

在 32 位系统上最大值为 2038-01-19 03:14:07（Y2038 问题）

64 位系统可表示约 2920 亿年的时间范围

1.2 `clock_t`

描述：表示处理器时间的算术类型
用途：测量程序执行时间（CPU 时间）

1.3 `struct tm`

描述：分解时间结构

struct tm {int tm_sec;   // 秒 [0-60]（允许闰秒）int tm_min;   // 分 [0-59]int tm_hour;  // 时 [0-23]int tm_mday;  // 月中的日 [1-31]int tm_mon;   // 月份 [0-11]（0=一月）int tm_year;  // 年份（从1900开始的年数）int tm_wday;  // 星期几 [0-6]（0=周日）int tm_yday;  // 年中的日 [0-365]int tm_isdst; // 夏令时标志：>0（生效）、0（不生效）、<0（未知）
};

1.4 `size_t`

用于 strftime 函数表示缓冲区大小

2 核心函数

2.1 时间获取函数

1) time_t time(time_t *timer)

功能：获取当前日历时间

参数：

timer：存储结果的指针（可为 NULL）

返回：

成功：当前时间（从纪元开始的秒数）

失败：(time_t)(-1)

time_t now;
now = time(NULL);  // 获取当前时间

2) clock_t clock(void)

功能：获取程序使用的处理器时间

返回：

成功：从程序启动开始的 CPU 时间（时钟滴答数）

失败：(clock_t)(-1)

注意：需除以 CLOCKS_PER_SEC 转换为秒

clock_t start = clock();
// 执行代码...
clock_t end = clock();
double cpu_time = (double)(end - start) / CLOCKS_PER_SEC;

2.2 时间转换函数

1) struct tm *gmtime(const time_t *timer);

功能：将日历时间转换为 UTC 时间

参数：timer - 指向日历时间的指针

返回：指向静态 tm 结构的指针（非线程安全）

time_t now = time(NULL);
struct tm *utc_time = gmtime(&now);

2) struct tm *localtime(const time_t *timer);

功能：将日历时间转换为本地时间（考虑时区和夏令时）

参数：timer - 指向日历时间的指针

返回：指向静态 tm 结构的指针（非线程安全）

time_t now = time(NULL);
struct tm *local_time = localtime(&now);

3) time_t mktime(struct tm *timeptr);

功能：将本地时间转换为日历时间

特性：

自动规范化超出范围的字段

计算并填充 tm_wday 和 tm_yday

正确处理夏令时

struct tm new_year = {0};
new_year.tm_year = 124; // 2024年（2024-1900）
new_year.tm_mon = 0;    // 一月
new_year.tm_mday = 1;   // 1号
time_t timestamp = mktime(&new_year);

2.3 时间差计算

double difftime(time_t time1, time_t time0);

功能：计算两个日历时间的差值（秒）

返回：time1 - time0（以秒为单位的双精度值）

time_t start = time(NULL);
// 执行操作...
time_t end = time(NULL);
double elapsed = difftime(end, start);

2.4 时间格式化函数

1) char *asctime(const struct tm *timeptr);

功能：将 tm 结构转换为固定格式字符串

格式："Day Mon dd hh:mm:ss yyyy\n"

返回：指向静态缓冲区的指针（非线程安全）

struct tm *t = localtime(&now);
printf("Current: %s", asctime(t));
// 输出示例：Tue Jun 18 14:30:45 2024

2) char *ctime(const time_t *timer);

功能：将日历时间转换为本地时间字符串

等效：asctime(localtime(timer))

返回：指向静态缓冲区的指针（非线程安全）

time_t now = time(NULL);
printf("Current: %s", ctime(&now));

3) size_t strftime(char *str, size_t maxsize, const char *format, const struct tm *timeptr);

功能：自定义格式化时间输出

参数：

str：输出缓冲区

maxsize：缓冲区最大容量

format：格式字符串

timeptr：指向 tm 结构的指针

返回：写入字符数（不包括终止空字符），失败返回0

常用格式说明符：

说明符	含义	示例
`%Y`	四位年份	2024
`%y`	两位年份	24
`%m`	月份（01-12）	06
`%d`	月中的日（01-31）	18
`%H`	24小时制小时（00-23）	14
`%I`	12小时制小时（01-12）	02
`%M`	分钟（00-59）	30
`%S`	秒（00-60）	45
`%A`	完整星期名	Tuesday
`%a`	缩写星期名	Tue
`%B`	完整月份名	June
`%b`	缩写月份名	Jun
`%p`	AM/PM	PM
`%Z`	时区名	CST
`%z`	UTC偏移（+HHMM）	+0800
`%F`	ISO 8601日期格式	2024-06-18
`%T`	ISO 8601时间格式	14:30:45

char buffer[80];
strftime(buffer, sizeof(buffer), "%Y-%m-%d %H:%M:%S %Z", localtime(&now));
printf("Formatted: %s\n", buffer); // 2024-06-18 14:30:45 CST