gmtime-s-gmtime32-s-gmtime64-s.md

description	title	ms.date	api_name	api_location	api_type	topic_type	f1_keywords	helpviewer_keywords
Learn more about: gmtime_s, _gmtime32_s, _gmtime64_s	gmtime_s, _gmtime32_s, _gmtime64_s	02/23/2024	_gmtime32_s gmtime_s _gmtime64_s _o__gmtime32_s _o__gmtime64_s	msvcrt.dll msvcr80.dll msvcr90.dll msvcr100.dll msvcr100_clr0400.dll msvcr110.dll msvcr110_clr0400.dll msvcr120.dll msvcr120_clr0400.dll ucrtbase.dll api-ms-win-crt-time-l1-1-0.dll	DLLExport	apiref	_gmtime_s gmtime64_s gmtime32_s _gmtime64_s gmtime_s _gmtime32_s	gmtime_s function gmtime32_s function time functions gmtime64_s function _gmtime64_s function time structure conversion _gmtime_s function _gmtime32_s function

gmtime_s, _gmtime32_s, _gmtime64_s

Converts a time value to a tm structure. These functions are versions of _gmtime32, _gmtime64 with security enhancements as described in Security features in the CRT.

Syntax

errno_tgmtime_s( structtm*tmDest, const__time_t*sourceTime ); errno_t_gmtime32_s( structtm*tmDest, const__time32_t*sourceTime ); errno_t_gmtime64_s( structtm*tmDest, const__time64_t*sourceTime );

Parameters

tmDest
Pointer to a tm structure. The fields of the returned structure hold the evaluated value of the timer argument in UTC rather than in local time.

sourceTime
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

Zero if successful. The return value is an error code if there's a failure. Error codes are defined in Errno.h; for a listing of these errors, see errno.

Error conditions

tmDest	sourceTime	Return	Value in tmDest
NULL	any	EINVAL	Not modified.
Not NULL (points to valid memory)	NULL	EINVAL	All fields set to -1.
Not NULL	< 0	EINVAL	All fields set to -1.

The first two error conditions invoke the invalid parameter handler, as described in Parameter validation. If execution is allowed to continue, these functions set errno to EINVAL and return EINVAL.

Remarks

The _gmtime32_s function breaks down the sourceTime value and stores it in a structure of type tm, defined in Time.h. The address of the structure is passed in tmDest. The value of sourceTime is often obtained from a call to the time function.

Each of the structure fields is of type int, as shown in the following table.

Field	Description
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_s.

_gmtime64_s, which uses the __time64_t structure, allows dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas gmtime32_s only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for both these functions.

gmtime_s is an inline function that evaluates to _gmtime64_s 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. _USE_32BIT_TIME_T causes gmtime_s to be inlined as _gmtime32_s. We don't recommend _USE_32BIT_TIME_T, because your application may fail after January 18, 2038, and because it isn't allowed on 64-bit platforms.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Requirements

Routine	Required C header	Required C++ header
gmtime_s, _gmtime32_s, _gmtime64_s	<time.h>	<ctime> or <time.h>

For more compatibility information, see Compatibility.

Example

// 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>intmain( void ) { structtmnewtime; __int64ltime; charbuf[26]; errno_terr; _time64( &ltime ); // Obtain coordinated universal time:err=_gmtime64_s( &newtime, &ltime ); if (err) { printf("Invalid Argument to _gmtime64_s."); } // Convert to an ASCII representationerr=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 

See also

Time management
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