gmtime_s、_gmtime32_s、_gmtime64_s

项目
06/09/2015

时间值转换为结构。 _gmtime32, _gmtime64 的一些安全增强功能版本（如 CRT 中的安全功能所述）。

errno_t gmtime_s(
   struct tm* _tm,
   const __time_t* time
);
errno_t _gmtime32_s(
   struct tm* _tm,
   const __time32_t* time
);
errno_t _gmtime64_s(
   struct tm* _tm,
   const __time64_t* time 
);

参数

_tm
指向tm 结构的指针。返回的结构的字段表示按照 UTC timer 参数的计算的值而不是按本地时间。
time
存储时间的指针。该时间表示为自1970年1月1号午夜（00:00:00）开始的秒数，世界标准时间（UTC）。

返回值

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

错误情况

_tm	time	返回	_tm中的值
NULL	any	EINVAL	未被修改
不是 NULL (指向有效的内存)	NULL	EINVAL	所有字段设置为 -1。
非 NULL	< 0	EINVAL	所有字段设置为 -1。

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

备注

_gmtime32_s函数分解 time 并存储在 tm,类型的一个静态分配结构，定义在 TIME.H。结构的地址在传递 _tm。通常是从一个调用到time 函数获得 time的值。

备注

目标环境应该尽量确定夏时制是否有效。C 运行库假设使用美国规则实现夏令时的计算。

如下表所示，每个结构字段，是 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
对于 gmtime，总是为0。

_gmtime64_s，使用 __time64_t 结构，启用到达3000年12月31号 23:59:59 的日期，UTC； gmtime32_s 启用到达2038年1月19号 03:14:07 的日期，UTC。 1970 年 1 月 1 日 00:00:00是所有这些函数的下限的日期范围。

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

要求

例程	必需的标头
gmtime_s	<time.h>
_gmtime32_s	<time.h>
_gmtime64_s	<time.h>

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

示例

// crt_gmtime64_s.c
// This program uses _gmtime64_s to convert a 64-bit
// integer representation of coordinated universal time
// to a structure named newtime, then uses asctime_s to
// convert this structure to an output string.
 

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

int main( void )
{
   struct tm newtime;
   __int64 ltime;
   char buf[26];
   errno_t err;

   _time64( &ltime );

   // Obtain coordinated universal time: 
   err = _gmtime64_s( &newtime, &ltime );
   if (err)
   {
      printf("Invalid Argument to _gmtime64_s.");
   }
   
   // Convert to an ASCII representation 
   err = asctime_s(buf, 26, &newtime);
   if (err)
   {
      printf("Invalid Argument to asctime_s.");
   }

   printf( "Coordinated universal time is %s\n", 
           buf );
}