localtime_s、_localtime32_s、_localtime64_s

项目
06/09/2015

转换时间值并更正为本地时间。这些是地方时间，地方时间32，地方时间64有安全增强功能的版本，如CRT 中的安全功能所描述的。

errno_t localtime_s(
   struct tm* _tm,
   const time_t *time 
);
errno_t _localtime32_s(
   struct tm* _tm,
   const time32_t *time 
);
errno_t _localtime64_s(
   struct tm* _tm,
   const _time64_t *time 
);

参数

_tm
要填充的时间结构的指针。
time
指向存储的时间。

返回值

如果成功,是0。如果失败，返回值是错误代码。错误代码在Errno.h中被定义。有关以下这些错误项的列表，请参见系统错误码。

错误情况

_tm	time	返回值	_tm中的值	调用无效参数处理程序
NULL	any	EINVAL	未被修改	是
不是 NULL (指向有效的内存)	NULL	EINVAL	所有字段设置为 -1。	是
不是 NULL (指向有效的内存)	小于0或者大于_MAX__TIME64_T。	EINVAL	所有字段设置为 -1。	否

在前两种错误状态情况下，无效参数处理程序被调用，如参数验证所述。如果允许继续执行，则这些函数将 errno 设置为 EINVAL，并返回EINVAL。

备注

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

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

备注

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

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

localtime_s 是个内联函数，计算结果为 _localtime64_s，并且，time_t 与 __time64_t等效。如果你需要强制编译器将 time_t 编译为旧的32 位 time_t，你可以将 _USE_32BIT_TIME_T定义。这样做将导致 localtime_s 计算结果为 _localtime32_s。不建议这样做，因为该应用程序能在 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_s	<time.h>
_localtime32_s	<time.h>
_localtime64_s	<time.h>

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

示例

// crt_localtime_s.c
/* This program uses _time64 to get the current time 
 * and then uses _localtime64_s() 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;
        char timebuf[26];
        errno_t err;

        // Get time as 64-bit integer.
        _time64( &long_time ); 
        // Convert to local time.
        err = _localtime64_s( &newtime, &long_time ); 
        if (err)
        {
            printf("Invalid argument to _localtime64_s.");
            exit(1);
        }
        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;

        // Convert to an ASCII representation. 
        err = asctime_s(timebuf, 26, &newtime);
        if (err)
        {
           printf("Invalid argument to asctime_s.");
           exit(1);
        }
        printf( "%.19s %s\n", timebuf, am_pm );
}