38 - localtime()函数

1 函数原型

localtime()：时间类型转换，函数原型如下：

struct tm * localtime (const time_t * timer);

ctime库描述如下：

Convert time_t to tm as local time
1. Uses the value pointed by timer to fill a tm structure with the values that represent the corresponding time, expressed for the local timezone.

1. localtime()函数和gmtime()函数都用于将秒数表示的时间转换为更具可读性的时间结构，区别在于：
   （1）localtime()函数将时间从time_t类型转换为本地时间；
   （2）gmtime()函数将时间从time_t类型转换为协调世界时（UTC）；
   （3）本地时间可以通过将协调世界时（UTC）加上或减去时区偏移量来获得，如北京位于东八区，这意味着北京时间比协调世界时（UTC）快8个小时，即UTC+8。

2 参数

localtime()函数只有一个参数timer：

1. 参数timer是一个指向time_t类型对象的指针，类型为time_t*；timer指向的对象包含要转换的时间值。

ctime库描述如下：

timer
1. Pointer to an object of type time_t that contains a time value.
2. time_t is an alias of a fundamental arithmetic type capable of representing times as returned by function time.

3 参数

localtime()函数的返回值类型为struct tm*类型：

1. 转换成功，返回一个指向静态时间结构的指针，该结构包含了转换后的本地时间的各个组成部分；
2. 转换失败，返回NULL。

特别说明

1. 静态时间结构是指结构的存储空间在程序开始时分配，并在程序结束时释放，在程序运行期间其生命周期是静态的；
2. 同一程序中所有的gmtime()函数和localtime()函数共享同一个静态时间结构；每次调用gmtime()函数或localtime()函数时，都会擦写、更新或覆盖静态时间结构的原有内容；
3. 如果要保存静态时间结构的原有内容，必须在程序中单独声明一个struct tm类型的时间结构，在每次调用gmtime()函数或localtime()函数后，将静态时间结构的原有内容拷贝至新的时间结构中。

ctime库描述如下：

1. A pointer to a tm structure with its members filled with the values that correspond to the local time representation of timer.
2. The returned value points to an internal object whose validity or value may be altered by any subsequent call to gmtime or localtime.

4 示例

4.1 示例1

示例代码如下所示：

int main() {
   //
   time_t rawtime = 0;
   struct tm* timeinfo = NULL;
   // 获取当前时间
   time(&rawtime);
   // 将时间转换为UTC时间
   timeinfo = gmtime(&rawtime);
   // 输出结果
   printf("UTC时间  : %d-%02d-%02d %02d:%02d:%02d\n",
      timeinfo->tm_year + 1900,
      timeinfo->tm_mon + 1,
      timeinfo->tm_mday,
      timeinfo->tm_hour,
      timeinfo->tm_min,
      timeinfo->tm_sec);
   // 将时间转换为本地时间
   timeinfo = localtime(&rawtime);
   // 输出结果
   printf("本地时间 : %d-%02d-%02d %02d:%02d:%02d\n",
      timeinfo->tm_year + 1900,
      timeinfo->tm_mon + 1,
      timeinfo->tm_mday,
      timeinfo->tm_hour,
      timeinfo->tm_min,
      timeinfo->tm_sec);
   //
   return 0;
}

代码运行结果如下图所示：

代码及运行结果分析如下：

1. 本地时间 = UTC时间 + 8。

4.2 示例2

示例代码如下所示：

int main() {
   //
   time_t rawtime = 0;
   struct tm* timeinfo = NULL;
   // 获取当前时间
   time(&rawtime);
   // 将时间转换为UTC时间
   timeinfo = gmtime(&rawtime);
   printf("gmtime()函数返回值 = %p\n", timeinfo);
   // 将时间转换为本地时间
   timeinfo = localtime(&rawtime);
   // 输出结果
   printf("localtime()函数返回值 = %p\n", timeinfo);
   //
   return 0;
}

代码运行结果如下图所示：

代码及运行结果分析如下：

1. gmtime()函数和localtime()函数的返回值是指针，两指针值相同说明指向的是同一片内存空间，即两函数维护的是同一个静态时间结构。