localtime_s, _localtime32_s, _localtime64_s

将 time_t 时间值转换为 tm 结构，并针对本地时区进行更正。 这些函数的版本是 localtime、_localtime32、_localtime64，具有安全性增强功能，如 CRT 中的安全功能中所述。

语法

errno_t localtime_s(
   struct tm* const tmDest,
   time_t const* const sourceTime
);
errno_t _localtime32_s(
   struct tm* tmDest,
   __time32_t const* sourceTime
);
errno_t _localtime64_s(
   struct tm* tmDest,
   __time64_t const* sourceTime
);

参数

tmDest
指向要填充的时间结构的指针。

sourceTime
指向存储时间的指针。

返回值

如果成功，则返回 0。 如果失败，则返回值为错误代码。 错误代码是在 Errno.h 中定义的。 有关这些错误的列表，请参阅 errno。

错误条件

tmDest	sourceTime	返回值	tmDest 中的值	调用无效参数处理程序
NULL	任意	EINVAL	未修改	是
非 NULL（指向有效内存）	NULL	EINVAL	所有字段都设置为 -1	是
非 NULL（指向有效内存）	小于 0 或大于 _MAX__TIME64_T	EINVAL	所有字段都设置为 -1	否

前两个错误条件会调用无效参数处理程序，如参数验证中所述。 如果允许执行继续，则这些功能将 errno 设置为 EINVAL 并返回 EINVAL。

备注

localtime_s 函数将转换存储为 time_t 值的时间并将结果存储在 tm 类型的结构中。 time_t 值 sourceTime 表示自 1970 年 1 月 1 日午夜 (00: 00:00) (UTC) 起经过的秒数. 此值通常从 time 函数中获取。

如果用户首次设置全局环境变量 TZ，localtime_s 将更正本地时区。 设置 TZ 时，其他三个环境变量（_timezone、_daylight 和 _tzname）也会自动设置。 如果未设置 TZ 变量，localtime_s 将尝试使用控制面板的日期/时间应用程序中指定的时区信息。 如果无法获取此信息，则它默认使用代表太平洋时区的 PST8PDT。 有关这些变量的说明，请参阅 _tzset。 TZ 是 Microsoft 扩展名，但并不是 localtime 的 ANSI 标准定义的一部分。

注意

目标环境应尝试确定夏令时是否生效。

使用 __time64_t 结构的 _localtime64_s 允许日期最大值表示为 3001 年 1 月 18 日 23:59:59，协调世界时 (UTC)；而 _localtime32_s 能表示截至 2038 年 1 月 18 日 23:59:59 之前的日期，UTC。

localtime_s 是计算出 _localtime64_s 的内联函数，且 time_t 等同于 __time64_t。 如果需要强制编译器将 time_t 解释为旧的 32 位 time_t，你可以定义 _USE_32BIT_TIME_T，这会导致 localtime_s 计算为 _localtime32_s。 不建议 _USE_32BIT_TIME_T，因为应用程序可能会在 2038 年 1 月 18 日后失效；且在 64 位平台上不允许使用它。

结构类型 tm 的字段存储以下值，其中每个值为 int。

字段	说明
tm_sec	整分后的秒数 (0 - 59)。
tm_min	整点后的分钟数 (0 - 59)。
tm_hour	午夜以后的小时数 (0 - 23)。
tm_mday	每月的某一日 (1 - 31)。
tm_mon	月（0 - 11；1 月 = 0）。
tm_year	年（当前年份减去 1900）。
tm_wday	每周的某一日（0 - 6；星期天 = 0）。
tm_yday	一年的某一天（0 - 365；1 月 1 日 = 0）。
tm_isdst	如果夏令时生效，则为正值；如果夏令时不生效，则为 0；如果夏令时状态未知，则为负值。

如果设置 TZ 环境变量，C 运行时库假设规则适用于美国，以使用该规则实现夏令时 (DST) 的计算。

默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。

要求

例程	必需的 C 标头	必需的 C++ 标头
localtime_s, _localtime32_s, _localtime64_s	<time.h>	<ctime> 或 <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 );
}

Fri Apr 25 01:19:27 PM

另请参阅

工时管理
asctime_s、_wasctime_s
ctime、_ctime32、_ctime64、_wctime、_wctime32、_wctime64
_ftime、_ftime32、_ftime64
gmtime_s、_gmtime32_s、_gmtime64_s
localtime、_localtime32、_localtime64
time、_time32、_time64
_tzset