C语言getlocaltime如何获取本地时间？

在标准的 C 语言库（如 C89/C90, C99, C11）中，并没有一个叫做 getlocaltime 的函数。

这个函数名通常出现在 Windows 的 API（应用程序编程接口）中，当你看到或需要使用 getlocaltime 时，几乎可以肯定你正在编写 Windows 平台下的代码。

下面,我将围绕 Windows API 的 getlocaltime 函数进行详细说明，并介绍在标准 C 中实现同样功能的正确方法。

Windows API 的 getlocaltime

getlocaltime 是 Windows 系统提供的一个函数，用于获取当前的本地时间（即你电脑系统设置时区的时间）。

函数原型

#include <windows.h>
void WINAPI getlocaltime(
  [out] LPSYSTEMTIME lpSystemTime
);

参数说明

• lpSystemTime: 这是一个指向 SYSTEMTIME 结构体的输出参数（指针），函数会将获取到的本地时间信息填充到这个结构体中，调用时，你需要先定义一个 SYSTEMTIME 结构体变量，然后将它的地址传递给该函数。

SYSTEMTIME 结构体

这个结构体包含了时间的各个组成部分,定义如下：

typedef struct _SYSTEMTIME {
  WORD wYear;      // 年份，2025
  WORD wMonth;     // 月份，1 (一月) 到 12 (十二月)
  WORD wDayOfWeek; // 星期，0 (星期日) 到 6 (星期六)
  WORD wDay;       // 日期，1 到 31
  WORD wHour;      // 小时，0 到 23
  WORD wMinute;    // 分钟，0 到 59
  WORD wSecond;    // 秒，0 到 59
  WORD wMilliseconds; // 毫秒，0 到 999
} SYSTEMTIME, *PSYSTEMTIME, *LPSYSTEMTIME;

• WORD 是一个 16 位无符号整数（typedef unsigned short WORD;）。

返回值

getlocaltime 没有返回值（void），所有时间信息都通过 lpSystemTime 指针指向的结构体返回。

使用示例

下面的代码演示了如何在 Windows 程序中使用 getlocaltime。

#include <stdio.h>
#include <windows.h> // 必须包含此头文件
int main() {
    // 1. 定义一个 SYSTEMTIME 结构体变量
    SYSTEMTIME st;
    // 2. 调用 getlocaltime，将 st 的地址传递给它
    getlocaltime(&st);
    // 3. 打印结构体中的各个成员
    printf("当前的本地时间是:\n");
    printf("年份: %d\n", st.wYear);
    printf("月份: %d\n", st.wMonth);
    printf("日期: %d\n", st.wDay);
    printf("星期: %d (0=周日, 1=周一, ...)\n", st.wDayOfWeek);
    printf("小时: %d\n", st.wHour);
    printf("分钟: %d\n", st.wMinute);
    printf("秒钟: %d\n", st.wSecond);
    printf("毫秒: %d\n", st.wMilliseconds);
    return 0;
}

编译和运行： 你需要使用支持 Windows API 的编译器，Visual Studio 的 cl.exe 或者 MinGW 的 gcc。

# 使用 MinGW (gcc) 编译
gcc -o getlocaltime_example.exe getlocaltime_example.c

可能的输出：

当前的本地时间是:
年份: 2025
月份: 10
日期: 27
星期: 5 (0=周日, 1=周一, ...)
小时: 14
分钟: 30
秒钟: 55
毫秒: 123

标准 C 语言中的替代方案

为了编写跨平台的代码（即在 Linux, macOS, Windows 等不同操作系统上都能编译运行），你应该使用标准 C 库中的时间函数，最常用的是 localtime 函数。

推荐的跨平台方法：localtime + time

这是获取本地时间的标准做法。

步骤：

1. 包含头文件：<time.h>
2. 获取当前时间戳：使用 time() 函数，它返回一个 time_t 类型的值，表示从 1970年1月1日 00:00:00 UTC 到现在的秒数。
3. 转换为本地时间结构体：将 time_t 值传递给 localtime() 函数，它会返回一个指向 struct tm 的指针，该指针包含了分解后的本地时间。

struct tm 结构体

struct tm {
  int tm_sec;   // 秒，0 到 59
  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 年开始的年数，2025年就是 123 (2025 - 1900)
  int tm_wday;  // 星期，0 (星期日) 到 6 (星期六)
  int tm_yday;  // 一年中的第几天，0 到 365
  int tm_isdst; // 夏令时标志，>0 表示夏令时，0 表示非夏令时，<0 表示信息不可用
};

• 特别注意：tm_mon 和 tm_year 的表示方式与 Windows 的 SYSTEMTIME 不同，这是最常见的错误来源。

使用示例

#include <stdio.h>
#include <time.h>   // 必须包含此头文件
int main() {
    // 1. 定义一个 time_t 变量来存储时间戳
    time_t rawtime;
    // 2. 获取当前时间戳
    time(&rawtime);
    // 3. 使用 localtime 将时间戳转换为本地时间结构体
    //    localtime 返回一个指向静态 struct tm 的指针，所以不需要我们自己定义变量
    struct tm *timeinfo = localtime(&rawtime);
    // 4. 打印结构体中的各个成员
    printf("当前的本地时间是:\n");
    printf("年份: %d\n", timeinfo->tm_year + 1900); // tm_year 需要加上 1900
    printf("月份: %d\n", timeinfo->tm_mon + 1);    // tm_mon 需要加上 1
    printf("日期: %d\n", timeinfo->tm_mday);
    printf("星期: %d (0=周日, 1=周一, ...)\n", timeinfo->tm_wday);
    printf("小时: %d\n", timeinfo->tm_hour);
    printf("分钟: %d\n", timeinfo->tm_min);
    printf("秒钟: %d\n", timeinfo->tm_sec);
    return 0;
}

编译和运行： 这个代码在任何支持 C 标准库的系统上都可以编译。

# 在 Linux, macOS, Windows (with MinGW) 上都可以
gcc -o localtime_example.c -o localtime_example

getlocaltime vs localtime 对比

关于线程安全

标准的 localtime 函数返回一个指向内部静态数据的指针，如果在多线程程序中，一个线程正在读取 localtime 返回的数据，而另一个线程又调用了 localtime，那么第一个线程的数据就会被覆盖，导致数据错乱。

解决方案：

1. Windows 平台: 使用 localtime_s，这是微软提供的安全版本。

   #include <time.h>
   // ...
   struct tm timeinfo;
   time_t rawtime;
   time(&rawtime);
   // 安全版本，目标缓冲区 timeinfo 作为第一个参数
   localtime_s(&timeinfo, &rawtime); 

2. Linux/macOS (POSIX 标准): 使用 localtime_r (reentrant)。

   #include <time.h>
   // ...
   struct tm timeinfo;
   time_t rawtime;
   time(&rawtime);
   // reentrant 版本，目标缓冲区 timeinfo 作为第二个参数
   localtime_r(&rawtime, &timeinfo);

对于初学者或仅限于 Windows 环境的开发，getlocaltime 非常直观，但如果你希望你的代码更具通用性和专业性，强烈建议学习和使用标准 C 的 time 和 localtime 函数。