localtime、_localtime32、_localtime64
转换时间值并更正为本地时间。 提供这些函数的更多安全版本;请参见 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 );
}
.NET Framework 等效项
请参见
参考
ctime、_ctime32、_ctime64、_wctime、_wctime32、_wctime64