gmtime_s, _gmtime32_s, _gmtime64_s

将时间值转换为 tm 结构。 这些函数的版本是 _gmtime32、_gmtime64，具有安全性增强功能，如 CRT 中的安全功能中所述。

语法

errno_t gmtime_s(
   struct tm* tmDest,
   const __time_t* sourceTime
);
errno_t _gmtime32_s(
   struct tm* tmDest,
   const __time32_t* sourceTime
);
errno_t _gmtime64_s(
   struct tm* tmDest,
   const __time64_t* sourceTime
);

参数

tmDest
指向 tm 结构的指针。 返回的结构字段以 UTC 格式保留 timer 参数的计算值，而不是以本地时间格式进行保留。

sourceTime
指向存储时间的指针。 时间表示为自 1970 年 1 月 1 日午夜 (00:00:00)，协调世界时 (UTC) 以来所经过的秒数。

返回值

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

错误条件

tmDest	sourceTime	返回值	tmDest 中的值
NULL	any	EINVAL	未修改。
非 NULL（指向有效内存）	NULL	EINVAL	所有字段都设置为 -1。
非 NULL	< 0	EINVAL	所有字段都设置为 -1。

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

注解

_gmtime32_s 函数将分解 sourceTime 值并将其存储于在 Time.h 中定义的类型 tm 结构中。 结构地址将传入 tmDest 中。 sourceTime 的值通常通过对 time 函数的调用来获取。

每个结构字段的类型均为 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	gmtime_s 始终为 0。

使用 __time64_t 结构的 _gmtime64_s 允许日期最大表示为 3000 年 12 月 31 日 23:59:59，UTC；而 gmtime32_s 只能表示截至 2038 年 1 月 18 日 23:59:59，UTC 之前的日期。 1970 年 1 月 1 日午夜是这两个函数的日期范围下限。

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

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

要求

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

Coordinated universal time is Fri Apr 25 20:12:33 2003

另请参阅

工时管理
asctime_s、_wasctime_s
ctime、_ctime32、_ctime64、_wctime、_wctime32、_wctime64
_ftime、_ftime32、_ftime64
gmtime、_gmtime32、_gmtime64
localtime_s、_localtime32_s、_localtime64_s
_mkgmtime、_mkgmtime32、_mkgmtime64
mktime、_mktime32、_mktime64
time、_time32、_time64