gmtime, _gmtime32, _gmtime64

将 time_t 时间值转换为 tm 结构。 提供这些函数的更安全版本；请参阅 gmtime_s、_gmtime32_s、_gmtime64_s。

语法

struct tm *gmtime( const time_t *sourceTime );
struct tm *_gmtime32( const __time32_t *sourceTime );
struct tm *_gmtime64( const __time64_t *sourceTime );

参数

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

返回值

指向类型 tm 的结构的指针。 返回的结构字段以 UTC 格式保留 sourceTime 参数的计算值，而不是以本地时间格式进行保留。 每个结构字段的类型均为 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 始终为 0。

gmtime、mktime、mkgmtime 和 localtime 的 32 位和 64 位版本均为每个线程使用一个常用的 tm 结构以进行转换。 对这些函数的每次调用都会破坏以前调用的结果。 如果 sourceTime 表示 1970 年 1 月 1 日午夜前的日期，则 gmtime 返回 NULL。 无错误返回。

使用 __time64_t 结构的 _gmtime64 允许日期最大表示为 3000 年 12 月 31 日 23:59:59，UTC。 _gmtime32 仅表示日期为 2038 年 1 月 18 日 23:59:59，UTC。 1970 年 1 月 1 日午夜是这两个函数的日期范围下限。

gmtime 是计算出 _gmtime64 的内联函数，且 time_t 等同于 __time64_t，除非定义了 _USE_32BIT_TIME_T。 如果必须强制编译器将 time_t 解释为旧的 32 位 time_t，则可以定义 _USE_32BIT_TIME_T，但执行此操作会导致将 gmtime 内联到 _gmtime32 并将 time_t 定义为 __time32_t。 我们不建议使用 _USE_32BIT_TIME_T，因为它不允许在 64 位平台上使用。 任何情况下，应用程序都可能会在 2038 年 1 月 18 日之后无法正常工作。

这些函数验证其参数。 如果 sourceTime 为 NULL 指针，或 sourceTime 值为负值，这些函数将调用无效参数处理程序，如参数验证中所述。 如果允许执行继续，则这些函数返回 NULL，并且将 errno 设置为 EINVAL。

注解

_gmtime32 函数将分解 sourceTime 值并将其存储于在 TIME.H 中定义的类型 tm 的静态分配结构中。 sourceTime 的值往往通过对 time 函数的调用来获取。

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

要求

例程	必需的 C 标头	必需的 C++ 标头
gmtime, _gmtime32, _gmtime64	<time.h>	<ctime> 或 <time.h>

有关兼容性的详细信息，请参阅 兼容性。

示例

// crt_gmtime.c
// compile with: /W3
// This program uses _gmtime64 to convert a long-
// integer representation of coordinated universal time
// to a structure named newtime, then uses asctime to
// convert this structure to an output string.

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

int main(void)
{
   struct tm *newtime;
   __int64 ltime;
   char buff[80];

   _time64( &ltime );

   // Obtain coordinated universal time:
   newtime = _gmtime64( &ltime ); // C4996
   // Note: _gmtime64 is deprecated; consider using _gmtime64_s
   asctime_s( buff, sizeof(buff), newtime );
   printf( "Coordinated universal time is %s\n", buff );
}

Coordinated universal time is Tue Feb 12 23:11:31 2002

另请参阅

工时管理
asctime、_wasctime
ctime、_ctime32、_ctime64、_wctime、_wctime32、_wctime64
_ftime、_ftime32、_ftime64
gmtime_s、_gmtime32_s、_gmtime64_s
localtime、_localtime32、_localtime64
_mkgmtime、_mkgmtime32、_mkgmtime64
mktime、_mktime32、_mktime64
time、_time32、_time64