程序员的噩梦：用C/C++把UTC时间转成UNIX时间戳竟然这么难？

时间处理在编程中看似平常，却隐藏着无数坑点。本文作者以 C 或 C++ 中将 UTC 时间字符串转换为 UNIX 时间戳为例，分享其中的难点以及最优解决方案

原文链接：https://berthub.eu/articles/posts/how-to-get-a-unix-epoch-from-a-utc-date-time-string/

作者 | bert hubert 翻译 | 苏宓

出品 | CSDN（ID：CSDNnews）

要将「Fri, 17 Jan 2025 06:07:07」UTC 这样的时间字符串转换为 1737094027（一个从 1970-01-01 00:00:00 UTC 开始的秒数表示，虽然只是理论上的秒数，并不完全准确），看起来似乎不难。

但实际上，真正尝试完成这个操作时会发现，POSIX 时间处理函数在各种 C 库及其衍生语言中隐藏着许多让人意想不到的“特性”和不符合直觉的行为。尽管 C 和 UNIX 世界有许多优秀的设计，但时间处理显然不是其中之一。

然而，仍有一些可行性方法存在。在探讨具体方法之前，先提供一些背景知识。

快速解读（TL;DR）：

1. 避免调用 setlocale()：如果你从不调用 setlocale()，那么可以直接使用 strptime() 来解析 UTC 时间字符串。

2. 避免 %z 或 %Z 格式符：解析时请勿使用这两个格式符。

3. 转换为 UNIX 时间戳：将 strptime() 解析后生成的 struct tm 结构体传递给 timegm()（在 Windows 上使用 mkgmtime()），即可得到对应的 UNIX 时间戳。

4. 如果使用了 setlocale()，需要更复杂的处理：具体解决方案在下文中会有解释。

5. C++ 提供了更好的时间处理支持，这也可以从 C 中借用。

时间点的复杂性

即便忽略闰秒和广义相对论的影响，时间本身就足够复杂了。当我们将人类的行为和政治因素引入时间处理时，事情会变得异常棘手。

例如，在阿姆斯特丹，“2025 年 3 月 30 日 02:20”这个时间点在当地根本就不存在：

$ TZ=Europe/Amsterdam date -d '20250330 01:59:59'
Sun Mar 30 01:59:59 AM CET 2025
$ TZ=Europe/Amsterdam date -d '20250330 02:30:00'
date: invalid date ‘20250330 02:30:00’

这点至少是明确的。由于夏令时的切换，时间会直接从 01:59:59 跳到 03:00:00。因此，工具无法解析“02:30:00”，因为在那一天的阿姆斯特丹，这个时间点根本不存在。

但对于“2024年10月27日 02:30”这个时间点，情况变得更加难以解释。因为夏令时的结束，在 02:59:59 的下一秒，时间会重新变为 02:00:00。这意味着当地会出现两个都被称为“02:00”的时间点。而我们的工具在处理这种情况时开始做出一些看似任意的选择：

$ TZ=Europe/Amsterdam date -d '20241027 01:59:59' +"%Y-%m-%d %H:%M:%S %s %z"
2024-10-27 01:59:59 1729987199 +0200
$ TZ=Europe/Amsterdam date -d '20241027 02:00:00' +"%Y-%m-%d %H:%M:%S %s %z"
2024-10-27 02:00:00 1729990800 +0100

你看，当解析 02:00:00 时，我使用的 GNU date 工具选择了第二个出现的时间点。据我观察，这可能是因为我在一月份运行了这个命令。如果在四月份运行，它可能会选择第一个 02:00:00 实例。是不是让人有些搞不懂？

POSIX 的时间概念

最有用的时间表示方式，毫无疑问是用某个已知“纪元”（epoch）之后或之前的秒数来指定时间点。例如：

• POSIX/Unix 的纪元是 1970-01-01 00:00:00 UTC

• GPS 的纪元是 1980-01-06 00:00:00 UTC

• Galileo（“欧盟版 GPS”）的纪元是 1999-08-21 23:59:47 UTC

• 北斗系统的起始历元是 2006-01-01 00:00:00 UTC

GPS、Galileo 和北斗系统明智地忽略了闰秒，将这些问题留给人类去处理。

但是，我们偏爱 POSIX/Unix 的 time_t 是有充分理由的。它几乎不会有任何歧义，除了在闰秒期间——而闰秒可能再也不会出现了。

然而，人类难以理解诸如 1737214750 这样的数字。因此，我们需要将时间戳与包含月份等复杂概念的“人类友好”时间表示相互转换。为此，UNIX 提供了 struct tm，用于存储“细分时间”：

struct tm {
int tm_sec; /* Seconds [0, 60] */
int tm_min; /* Minutes [0, 59] */
int tm_hour; /* Hour [0, 23] */
int tm_mday; /* Day of the month [1, 31] */
int tm_mon; /* Month [0, 11] (January = 0) */
int tm_year; /* Year minus 1900 */
int tm_wday; /* Day of the week [0, 6] (Sunday = 0) */
int tm_yday; /* Day of the year [0, 365] (Jan/01 = 0) */
int tm_isdst; /* Daylight savings flag */
long tm_gmtoff; /* Seconds East of UTC */
const char *tm_zone; /* Timezone abbreviation */
};

标准规定 struct tm 至少要包含这些字段，但实现中可能还会有其他字段。

然而，现在这个结构体显然是“过度定义”的。例如，星期几（tm_wday）和每年的第几天（tm_yday）完全可以从其他字段推导出来。而 tm_gmtoff、tm_zone 和 tm_isdst 的意义定义不明确，使用时往往会造成困惑。

有趣的是，苏联的 GLONASS 卫星导航系统并没有采用纪元时间戳的方法，而是基于“莫斯科标准时间”的 struct tm，包括闰秒。这种设计据说引发了许多问题，也算是“自作自受”。

struct tm 的一个重要用途是作为 mktime() 的输入。mktime() 的部分功能是将“根据你当地时区的细分时间”转换为 UNIX 时间戳（epoch 时间戳）。然而，mktime() 的作用远不止于此！

根据 Linux 的 glibc 手册页，mktime() 的描述相当模糊。 而 IEEE Std 1003.1-2024 规范则用了更多（令人泄气的）文字来解释它。

mktime() 不会处理 tm_gmtoff 或 tm_zone。其输入仅限于：tm_year、tm_mon、tm_mday、tm_hour、tm_min、tm_sec 和 tm_isdst。tm_isdst 也有特殊处理的情况，譬如 tm_isdst 可以设置为负值，表示让 mktime() 自动判断指定时间是否处于夏令时。

如上所述，时间问题其实在现实中很复杂。例如，如果想将日期调整一周，你可以简单地向 time_t 时间戳添加 604800秒。但如果这种调整跨越了夏令时边界，你的下午两点约会可能会变成下一周的下午一点或三点。这显然不是人类期望的结果。

mktime() 不仅返回一个 time_t 值，还会规范化传入的 struct tm。截至 2024 年，关于如何规范化的规则已经明确。例如，要计算“下一周的同一时间”，可以将当前时间加上 7 天（tm.tm_mday += 7），然后再次调用 mktime()。即使你构造出了一个像“3月35日”这样的日期，mktime() 也会将其修正为有效日期。

然而，当我们实际这样做时，却发现它不起作用：

struct tm tm = {.tm_hour=14, .tm_mday = 28,
.tm_mon = 2, .tm_year = 2025 - 1900,
.tm_isdst = -1}; // <- NOTE the -1

time_t t = mktime(&tm);
cout << "original: "<< ctime(&t);

tm.tm_mday += 7;
t = mktime(&tm);

cout << "mktime adjusted:  "<< ctime(&t);

在欧洲/阿姆斯特丹时区，这段代码输出：

original: Fri Mar 28 14:00:00 2025
mktime adjusted: Fri Apr  4 15:00:00 2025

为什么预约时间发生了 1 小时的偏移？问题实则出在 tm.tm_isdst 身上。

mktime() 的设计要求开发者明确指定时间是否处于夏令时状态，或者将这一决定交由 mktime() 自动判断（通过设置 tm_isdst = -1）。

在第一次调用 mktime() 时，系统检测到时间不处于夏令时，因此将 tm_isdst 设置为 0。但第二次调用时，这一状态未被清除，尽管新的目标时间实际上处于夏令时中。这导致了错误的调整结果。

所以在第二次调用 mktime() 之前，重置 tm_isdst 为 -1：

tm.tm_isdst = -1;

这样可以避免偏移问题，并正确调整预约时间。

解析 UTC 时间

现在，mktime() 会将你传递的时间解释为“本地时间”。这意味着在处理 UTC 时间之前，你应该将时区设置为 UTC。但如果你的应用程序中有其他线程运行，修改整个应用程序的时区可能会带来副作用。不过，如果没有其他线程，你可以这么做。

更新：有人指出，多线程程序无法修改环境变量。因此，这个方法就无效了。

有一个非标准/预标准的函数广泛可用，它可以显著改善处理 UTC 的情况。根据《IEEE Std 1003.1-2024》：

“未来版本的标准预计会新增一个 timegm() 函数，它与 mktime() 类似，但由 timeptr 指向的 tm 结构包含以协调世界时 (UTC) 表示的分解时间。”

为了解析 UTC 中的分解时间，推荐使用 timegm()，而不是修改 TZ 环境变量。在 Windows 上，timegm() 被称为 mkgmtime()。如果你使用的是 AIX（唯一不支持 timegm() 的平台），可以找到一个独立的实现版本。

总结：

1. 当对本地时间使用 mktime() 时，将 tm_isdst 设置为 -1，这通常是“人类”期望的。否则可能会在夏令时切换时返回随机的两个时间点之一（如“02:30”）。

2. 填写 struct tm 时，确保先将其他字段清零。

3. 注意，mktime() 会修改传入的 struct tm，可能产生副作用。在重用之前至少重置 tm_isdst。

4. 无论对 tm_gmtoff 或 tm_zone 做了什么，mktime() 都会使用当前时区。如果希望将 struct tm 解释为 UTC，需要设置 TZ 环境变量为 UTC，但这会影响其他线程的时间操作。

5. 更简单的做法：直接使用 timegm() 或 mkgmtime()。

但是，我们该如何将时间字符串转换为 struct tm？

解析时间字符串

理想情况下，我们希望能将 Fri, 17 Jan 2025 06:07:07 GMT 输入到 strptime() 中，并得到一个有效的 struct tm。

但根据 Linux glibc 的 strptime() 手册页描述，关于 %z 和 %Z 时区格式说明符的行为是含糊的：

出于对称性的考虑，glibc 尝试让 strptime() 支持与 strftime() 相同的格式字符。（在大多数情况下，相应的字段会被解析，但 tm 中的字段可能不会被更改。）

现在，我们的目标是将 UTC 时间字符串转换为 UNIX 时间戳。许多人可能希望通过 %Z 解析 GMT 后，再用 mktime() 达到目的。

但我们之前了解到，mktime() 根本不处理 tm_gmtoffset 或 tm_zone，因此即使 strptime() 能正确解析时区信息，也没有任何作用。而事实是，它也解析不对。

截至 2024 年，Open Group 的规范对 strptime() 提供了明确的说明，提到了当前实现中的各种问题与不足。例如：

• %z 的行为没有明确规定，解析类似 +0200 的偏移量通常不会奏效。

• %Z 的作用非常有限，仅在某些情况下有效。如果你的地区时区有 DST 标识符（例如 CEST）与常规时区（例如 CET）不同，并且 %Z 解析到了其中一个，它可能会为您正确设置 tm_isdst，但也可能不行（特别是如果你住在爱尔兰）。

一般来说，解析像 EST 这样的字符串毫无意义，因为它并无明确含义，仅在本地可能有用。

幸运的是，由于我们可以通过 gmtime() 获取 UTC 时间，完全可以忽略 %z 和 %Z，它们并不是必须的。

strptime 的语言环境问题

通常情况下，我们希望解析包含英文日期和月份名称的时间字符串，并希望 strptime() 能处理这些情况。然而，IEEE/Open Group 标准明确指出：

“这些转换是根据当前语言环境的 LC_TIME 类别决定的。”

糟糕。我以前并不知道，除非特别设置，C 和 C++ 程序会默认使用 “C” 语言环境，这实际上等同于美式英语。这意味着默认情况下，所有 LC_TIME 等环境变量都会被忽略。这对解析大多数以英文表示的时间字符串来说非常有用，因为数据中的时间几乎总是英文格式。

但是，如果你的 C 或 C++ 程序调用了 setlocale()，请求了非 “C” 的语言环境，那么你的程序可能会仅适用于例如荷兰语格式的时间字符串，而这种情况非常罕见。

现在你可能会考虑在调用 strptime() 之前将语言环境切换为 “C”，然后再切换回来。然而，不幸的是，setlocale() 在多线程程序中并不安全（除非在线程启动之前调用）。即使可以安全使用，也可能会干扰其他线程的输出。

因此，通常情况下，如果需要解析特定的时间字符串并使用 strptime()，请确保程序的语言环境设置为预期的值。虽然有 strftime_l() 允许指定格式化时间时的语言环境，但等价的 strptime_l() 并未正式提供。

值得一提的是，OpenBSD 的 strptime() 实现完全忽略了语言环境，只支持 “C”。

解析类似 17 Jan 2025 06:07:07 的字符串并填写一个 struct tm 其实并不困难，然后交由 mktime() 处理实际的 UNIX 时间戳计算工作。

使用纯 C++ 解决语言环境问题

虽然 C++ iostreams 不太受欢迎，但在处理语言环境方面比 C/POSIX 做得更好。在 C++ 中，你可以为每个 iostream 设置独立的语言环境。以下是一个可以从 C 调用的 C++ 辅助函数，用于解析任意 UTC 时间字符串：

extern "C"
int utcstr2epoch(const char* timestr, const char* fmtstr, struct tm* output)
{
std::tm t = {}; // tm_isdst = 0, don't think about it please, this is UTC
std::istringstream ss(timestr);
ss.imbue(std::locale()); // "LANG=C", but local

ss >> std::get_time(&t, fmtstr);
if (ss.fail())
return -1;
// now fix up the day of week, day of year etc
t.tm_isdst = 0; // no thinking!
t.tm_wday = -1;
if(mktime(&t) == -1 && t.tm_wday == -1) // "real error"
return -1;

*output = t;
return 0;
}

这个函数展示了如何为 mktime() 处理错误。当你请求解析 31st December 1969 23:59 时，mktime() 会返回 -1 表示错误。此时可以使用 tm_wday 作为标志位来判断是否进行了任何处理。

还有一个基于 C 的小型演示程序，它可以解析英文 UTC 时间戳，并根据调用环境的语言环境输出结果：

$ LC_TIME="nl_NL.utf-8" ./utcparse "1 Jan 1970 00:00:00" "%d %b %Y %H:%M:%S"
UTC Time: donderdag, 1 januari 1970 00:00:00, day of year 001
time_t: 0

C++20 的极致体验

C++20 及更高版本提供了豪华的时区数据库（timezone database）。虽然并非所有编译器都支持，但幸运的是，可以使用预标准化的独立版本。有时候，我们得感谢那些愿意花费数年时间为我们提供精美代码的人，比如 Howard Hinnant。

以下是一个优雅的例子：

auto meet_nyc = make_zoned("America/New_York",
date::local_days{Monday[1]/May/2016} + 9h);
auto meet_lon = make_zoned("Europe/London", meet_nyc);
auto meet_syd = make_zoned("Australia/Sydney", meet_nyc);
cout << "The New York meeting is " << meet_nyc << '\n';
cout << "The London meeting is " << meet_lon << '\n';
cout << "The Sydney meeting is " << meet_syd << '\n';

该代码解析了“2016 年 5 月第一个星期一上午 9 点（纽约当地时间）”，并无缝转换到其他两个时区：

The New York meeting is 2016-05-02 09:00:00 EDT
The London meeting is 2016-05-02 14:00:00 BST
The Sydney   meeting is 2016-05-02 23:00:00 AEST 

更棒的是，这个库不仅支持操作系统的时区数据库，还可以直接使用 IANA tzdb，这使得你能够精确计算 1978 年的一次飞行持续时间，包括经过夏令时的变化以及闰秒。令人惊叹。