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()函数共享同一个静态时间结构，每次调用这两个函数时，都会覆盖这个静态时间结构中的内容；
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("gmtime()   函数返回值 = %p\n", timeinfo);
   // 将时间转换为本地时间
   timeinfo = localtime(&rawtime);
   // 输出结果
   printf("localtime()函数返回值 = %p\n", timeinfo);
   //
   return 0;
}

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

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

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

4.2 示例2

示例代码如下所示：

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；
2. 静态时间结构内容被覆盖。

4.3 示例3

示例代码如下所示：

int main() {
   //
   time_t rawtime = 0;
   struct tm* timeinfo = NULL;
   struct tm saved_timeinfo = {0};
   // 获取当前时间
   time(&rawtime);
   // 将时间转换为本地时间
   timeinfo = localtime(&rawtime);
   // 拷贝本地时间
   saved_timeinfo = *timeinfo;
   // 输出结果
   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);

   printf("存储在动态时间结构中的本地时间 : %d-%02d-%02d %02d:%02d:%02d\n",
      saved_timeinfo.tm_year + 1900,
      saved_timeinfo.tm_mon + 1,
      saved_timeinfo.tm_mday,
      saved_timeinfo.tm_hour,
      saved_timeinfo.tm_min,
      saved_timeinfo.tm_sec);
   //
   return 0;
}

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