gmtime(), gmtime64() — Convert time to broken-down UTC time

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3 Language Environment®	both

Format

#include <time.h>

struct tm *gmtime(const time_t *timer);

#define _LARGE_TIME_API
#include <time.h>

struct tm *gmtime64(const time64_t *timer);

General description

Converts the calendar time pointed to by timer into a broken-down time, expressed as Coordinated Universal Time (UTC).

¹

The value pointed to by timer is usually obtained by a call to the time() function.

The relationship between a time in seconds since the Epoch used as an argument to gmtime() and the tm structure (defined in the <time.h> header) is that the result is as specified in the expression given in the definition of seconds since the Epoch, where the names in the structure and in the expression correspond.

The function gmtime64() will behave exactly like gmtime() except it will break down a time64_t value pointing to a calendar time beyond 03:14:07 UTC on January 19, 2038 with a limit of 23:59:59 UTC on December 31, 9999.

Returned value

Returns a pointer to a tm structure containing the broken-down time, expressed in Coordinated Universal Time (UTC) corresponding to calendar time pointed to by timer. The fields in tm are shown in Table 1. If the calendar time pointed to by timer cannot be converted to broken-down time (in UTC), gmtime() returns a NULL pointer.

Error code: Description
EOVERFLOW: The result cannot be represented.

Notes:

The range (0-60) for tm_sec allows for as many as one leap second.
The gmtime() and localtime() functions may use a common, statically allocated buffer for the conversion. Each call to one of these functions may alter the result of the previous call.
The calendar time returned by the time() function begins at the epoch, which was at 00:00:00 Coordinated Universal Time (UTC), January 1, 1970.

Example

CELEBG23

⁄* CELEBG23                                      

   This example uses the &gmtime. function to convert a                         
   time_t representation to a Coordinated Universal Time                        
   character string and then converts it to a printable string                  
   using &asct..                                                                
                                                                                
 *⁄                                                                             
#include <stdio.h>                                                              
#include <time.h>                                                               
                                                                                
int main(void)                                                                  
{                                                                               
   time_t ltime;                                                                
   time(&ltime);                                                                
   printf ("Coordinated Universal Time is %s\n",                                
            asctime(gmtime(&ltime)));                                           
}

Output

Coordinated Universal Time (UTC) is Fri Jun 16 21:01:44 2001