gmtime

Converts a time value to a structure.

structtm*gmtime(consttime_t*timer);

Routine	Required Header	Compatibility
gmtime	<time.h>	ANSI, Win 95, Win NT

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBC.LIB	Single thread static library, retail version
LIBCMT.LIB	Multithread static library, retail version
MSVCRT.LIB	Import library for MSVCRT.DLL, retail version

Return Value

gmtime returns 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

The gmtime, mktime, and localtime functions use the same single, statically allocated structure to hold their results. 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.

Parameter

timer

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

Remarks

The gmtime 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.

Note The target environment should try to determine whether daylight savings time is in effect. The C run-time library assumes the United States’s rules for implementing the calculation of Daylight Saving Time (DST).

Example

/* GMTIME.C: This program uses gmtime 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>

void main( void )
{
   struct tm *newtime;
   long ltime;

   time( &ltime );

   /* Obtain coordinated universal time: */
   newtime = gmtime( &ltime );
   printf( "Coordinated universal time is %s\n",
                               asctime( newtime ) );
}

Output

Coordinated universal time is Tue Mar 23 02:00:56 1993

Time Management Routines

See Also   asctime, ctime, _ftime, localtime, mktime, time