gmtime, gmtime_s

Defined in header `<time.h>`
struct tm gmtime( const time_t time );	(1)
struct tm gmtime_s(const time_t restrict time, struct tm *restrict result);	(2)	(since C11)

1) Converts given time since epoch (a time_t value pointed to by time) into calendar time, expressed in Coordinated Universal Time (UTC) in the struct tm format. The result is stored in static storage and a pointer to that static storage is returned.

2) Same as (1), except that the function uses user-provided storage result for the result and that the following errors are detected at runtime and call the currently installed constraint handler function:

time or result is a null pointer

As with all bounds-checked functions, gmtime_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including time.h.

Parameters

time	-	pointer to a time_t object to convert
result	-	pointer to a struct tm object to store the result

Return value

1) pointer to a static internal tm object on success, or null pointer otherwise. The structure may be shared between gmtime, localtime, and ctime and may be overwritten on each invocation.

2) copy of the result pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to UTC)

Notes

This function gmtime may not be thread-safe.

POSIX requires that this function sets errno to EOVERFLOW if it fails because the argument is too large.

POSIX defines a thread-safe alternative gmtime_r, which is similar to the C11 function gmtime_s, except that it does not check the validity of its input parameters.

Example

Run this code

#define __STDC_WANT_LIB_EXT1__ 1
#define _XOPEN_SOURCE // for putenv
#include <time.h>
#include <stdio.h>
#include <stdlib.h>   // for putenv

int main(void)
{
    time_t t = time(NULL);
    printf("UTC:      %s", asctime(gmtime(&t)));
    printf("local:    %s", asctime(localtime(&t)));
    // POSIX-specific
    putenv("TZ=Asia/Singapore");
    printf("Singapore:%s", asctime(localtime(&t)));

#ifdef __STDC_LIB_EXT1__
    struct tm buf;
    char str[26];
    asctime_s(str,sizeof str,gmtime_s(&t, &buf));
    printf("UTC:  %s", str);
    asctime_s(str,sizeof str,localtime_s(&t, &buf));
    printf("local:%s", str);
#endif
}

Possible output:

UTC:       Fri Sep 15 14:22:05 2017
local:     Fri Sep 15 14:22:05 2017
Singapore: Fri Sep 15 22:22:05 2017
UTC:   Fri Sep 15 14:22:05 2017
local: Fri Sep 15 14:22:05 2017

References

C11 standard (ISO/IEC 9899:2011):

7.27.3.3 The gmtime function (p: 393-394)

K.3.8.2.3 The gmtime_s function (p: 626-627)

C99 standard (ISO/IEC 9899:1999):

7.23.3.3 The gmtime function (p: 343)

C89/C90 standard (ISO/IEC 9899:1990):

4.12.3.3 The gmtime function

Language
Headers
Type support
Program utilities
Variadic function support
Error handling
Dynamic memory management
Date and time utilities
Strings library
Algorithms
Numerics
Input/output support
Localization support
Atomic operations (C11)
Thread support (C11)
Technical Specifications