C 標準庫時間函數詳解：localtime、mktime、difftime 使用與陷阱

C 標準庫時間函數詳解：localtime、mktime、difftime 使用與陷阱

時間處理是系統程式常見需求，標準庫提供 <time.h> 核心函數，但涉及執行緒安全、時區、儲存期等易踩坑細節。

1. localtime：time_t → 本地時間 tm 結構

#include <time.h>
struct tm *localtime(const time_t *timer);

• 輸入：time_t (自 1970-01-01 UTC 秒數)。
• 輸出：指向靜態內部緩衝區的 struct tm * (年/月/日/時/分/秒/星期/儒略日/夏令時)。
• 非執行緒安全：後續呼叫覆蓋緩衝區。
• 安全替代：localtime_r (POSIX) / localtime_s (C11 Annex K)，需自備 struct tm 緩衝區。

2. mktime：tm 結構 → time_t (本地時間轉 UTC 秒數)

time_t mktime(struct tm *tmptr);

• 輸入 tm 視為本地時間，自動修正欄位 (如 tm_sec=60 進位)。
• 輸出：對應的 UTC time_t，-1 表示錯誤。
• 副作用：修正輸入 tm 結構 (填充 tm_wday, tm_yday, 修正越界值)。
• 常用於：日期運算 (加減天)、任意日期轉時間戳。

3. difftime：計算兩時間差 (秒)

double difftime(time_t time1, time_t time0);

• 返回 time1 - time0 的雙精度秒數差。
• 唯一可移植的 time_t 減法方式 (標準未保證 time_t 為算術型別)。

常見陷阱與最佳實踐

完整範例：日期加減運算

#include <time.h>
#include <stdio.h>

int main() {
    time_t now = time(NULL);
    struct tm tm_now;
    localtime_r(&now, &tm_now); // 執行緒安全
    
    // 加 30 天
    tm_now.tm_mday += 30;
    time_t future = mktime(&tm_now); // 自動修正月份/年份
    
    double diff = difftime(future, now);
    printf("30 天后: %.0f 秒 (%.1f 天)\n", diff, diff/86400);
    
    char buf[64];
    strftime(buf, sizeof(buf), "%Y-%m-%d %H:%M:%S", &tm_now);
    printf("未來日期: %s\n", buf);
    return 0;
}