localtime、_localtime32、_localtime64

项目
06/09/2015

转换时间值并更正为本地时间。提供这些函数的更多安全版本；请参见 localtime_s、_localtime32_s、_localtime64_s。

struct tm *localtime(
   const time_t *timer 
);
struct tm *_localtime32(
   const __time32_t *timer
);
struct tm *_localtime64(
   const __time64_t *timer 
);

参数

timer
存储时间的指针。

返回值

如果传递给函数的日期为，返回结构结果的指针或 NULL :

在1970 年 1 月 1 日，午夜之前。
在2038 年 1 月 19 日 03:14:17后，UTC (使用 _time32 和 time32_t)。
在3000 年 12 月 31 日， 23:59:59后,UTC (使用 _time64 和 __time64_t)。

_localtime64，使用 __time64_t 结构，允许日期通过 3000 年 12 月 31 日23:59:59表示，协调通用时间 (UTC)，反之_localtime32通过2038年 1 月 19 日 03:14:07,UTC，表示日期。

localtime 是个内联函数，计算结果为 _localtime64，并且，time_t 与 __time64_t等效。如果你需要强制编译器将 time_t 编译为旧的32 位time_t，你可以定义_USE_32BIT_TIME_T。这样做将导致 localtime 计算结果为 _localtime32。不建议这样做，因为该应用程序能在 2038 年 1 月 19 日之后可能失败，而且64 位平台上是不允许的。

结构类型的字段 tm 存储以下值，其中每个都是 int:

tm_sec
分后的秒 (0 – 59)。
tm_min
时后的分 (0 – 59)。
tm_hour
在午夜 (0 - 23) 之后的小时。
tm_mday
一月中的一天(1 – 31)。
tm_mon
月份 (0 – 11;一月 = 0)。
tm_year
年份 (当前年份减 1900)。
tm_wday
一周中的一天 (0 – 6;周日 = 0)。
tm_yday
一年中的一天(0 – 365; 1 月 1 日 = 0 )。
tm_isdst
如果夏时制有效，是正值；如果夏时制无效，是0；负值，如果夏时制状态未知，是负值。如果设置 TZ 环境变量，C 运行时库将假定适用于美国实现夏时制 (DST) 的计算的规则。

备注

localtime 函数转换一次储存为time_t 值并将结果存储成结构类型tm。 long 值timer 表示午夜 (00:00：00)秒过后，1970 年 1 月 1 日，UTC。此值通常从 time 函数获取。

对于gmtime、mktime、mkgmtime和 localtime 所有的 32 位和 64 位版本都使用同一个 tm 结构来转换线程。每调用这些例程之一将销毁之前调用的结果。

TZ如果用户首次设置全局环境变量localtime将更正本地时区。当TZ 被设置，其他三个环境变量 (_timezone、_daylight和 _tzname) 也会自动设置。如果 TZ 变量未设置，localtime 尝试使用"控制面板"中的日期/时间应用程序指定时区信息。如果无法获取此信息，默认情况下它使用 PST8PDT,（表示太平洋时区）。有关这些变量的描述参见 _tzset。 TZ 是一个微软的扩展名而不是localtime的ANSI 标准定义的部件。

备注

目标环境应该尽量确定夏时制是否有效。

这些函数验证其参数。如果 timer 是无效的指针，或者时间值是负的，则这些函数将调用无效参数处理程序，如参数验证中所述。如果允许执行继续，则函数返回 NULL 并设置 errno 为 EINVAL。

要求

例程	必需的标头
localtime	<time.h>
_localtime32	<time.h>
_localtime64	<time.h>

有关其他兼容性信息，请参见“简介”中的兼容性。

示例

// crt_localtime.cpp
// compile with: /W3
/* This program uses _time64 to get the current time 
 * and then uses localtime64() to convert this time to a structure 
 * representing the local time. The program converts the result 
 * from a 24-hour clock to a 12-hour clock and determines the 
 * proper extension (AM or PM).
 */

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

int main( void )
{
        struct tm *newtime;
        char am_pm[] = "AM";
        __time64_t long_time;

        _time64( &long_time );           // Get time as 64-bit integer.
                                         // Convert to local time.
        newtime = _localtime64( &long_time ); // C4996
        // Note: _localtime64 deprecated; consider _localetime64_s

        if( newtime->tm_hour > 12 )        // Set up extension.
                strcpy_s( am_pm, sizeof(am_pm), "PM" );
        if( newtime->tm_hour > 12 )        // Convert from 24-hour
                newtime->tm_hour -= 12;    //   to 12-hour clock.
        if( newtime->tm_hour == 0 )        // Set hour to 12 if midnight.
                newtime->tm_hour = 12;

        char buff[30];
        asctime_s( buff, sizeof(buff), newtime );
        printf( "%.19s %s\n", buff, am_pm );
}