gmtime, _gmtime32, _gmtime64

Convert a time value to a structure. More secure versions of these functions are available; see _gmtime_s, _gmtime32_s, _gmtime64_s.

struct tm *gmtime( 
   const time_t *timer 
);
struct tm *_gmtime32( 
   const time32_t *timer 
);
struct tm *_gmtime64( 
   const __time64_t *timer 
);

Parameters

• timer
  Pointer to stored time. The time is represented as seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC).

Return Value

Return a pointer to a structure of type tm. The fields of the returned structure hold the evaluated value of the timer argument in UTC rather than in local time. Each of the structure fields is of type int, as follows:

• tm_sec
  Seconds after minute (0 – 59).

• tm_min
  Minutes after hour (0 – 59).

• tm_hour
  Hours since midnight (0 – 23).

• tm_mday
  Day of month (1 – 31).

• tm_mon
  Month (0 – 11; January = 0).

• tm_year
  Year (current year minus 1900).

• tm_wday
  Day of week (0 – 6; Sunday = 0).

• tm_yday
  Day of year (0 – 365; January 1 = 0).

• tm_isdst
  Always 0 for gmtime.

Both the 32-bit and 64-bit versions of gmtime, mktime, mkgmtime, and localtimeall use a single tm structure per thread for the conversion. Each call to one of these functions destroys the result of any previous call. If timer represents a date before midnight, January 1, 1970, gmtime returns NULL. There is no error return.

_gmtime64, which uses the __time64_t structure, allows dates to be expressed up through 23:59:59, December 31, 3000, UTC, whereas _gmtime32 only represent dates through 03:14:07 January 19, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for both these functions.

In Visual C++ 2005, gmtime is an inline function which evaluates to _gmtime64 and time_t is equivalent to __time64_t. If you need to force the compiler to interpret time_t as the old 32-bit time_t, you can define _USE_32BIT_TIME_T. Doing this will cause gmtime to be in-lined to _gmtime32. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms.

These functions validate their parameter. If timer is a null pointer, or if the timer value is negative, these functions invoke an invalid parameter handler, as described in Parameter Validation. If execution is allowed to continue, the functions return NULL and set errno to EINVAL.

Remarks

The _gmtime32 function breaks down the timer value and stores it in a statically allocated structure of type tm, defined in TIME.H. The value of timer is usually obtained from a call to the time function.

Requirements

For additional compatibility information, see Compatibility in the Introduction.

Example

// 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

.NET Framework Equivalent

• System::DateTime::UtcNow

• System::DateTime::ToUniversalTime

See Also

Concepts

Time Management

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