.- .

将时间值转换为 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++ 标头
.- . <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

另请参阅

工时管理
%>

.- .
.- .
.- .
.- .
.- .
.- .