gmtime() Function

The gmtime() function in C time.h converts a given time value into a structured representation of Coordinated Universal Time (UTC), which is essentially the same as GMT. This conversion is useful when you need to work with time data independent of local time zones.

Syntax of gmtime()

</>
Copy
struct tm *gmtime(const time_t *timer);

Parameters

ParameterDescription
timerA pointer to an object of type time_t containing the time value to be converted. This value is usually obtained from the time() function.

The gmtime() function uses the time value provided to populate a struct tm with the corresponding UTC values. Note that the returned pointer refers to an internal static object, which may be overwritten by subsequent calls to gmtime() or localtime().

Return Value

The function returns a pointer to a struct tm containing the UTC time representation corresponding to the time value pointed to by timer. Because this pointer refers to an internal static object, its value may be altered by later calls to time conversion functions.

Examples for gmtime()

Example 1: Converting the Current Time to UTC

This example demonstrates how to convert the current time obtained from time() into a UTC time structure using gmtime().

Program

</>
Copy
#include <stdio.h>
#include <time.h>

int main() {
    time_t currentTime;
    struct tm *utcTime;

    // Obtain the current time
    currentTime = time(NULL);

    // Convert current time to UTC
    utcTime = gmtime(&currentTime);

    // Display UTC time components
    printf("UTC Year   : %d\n", utcTime->tm_year + 1900);
    printf("UTC Month  : %d\n", utcTime->tm_mon + 1);
    printf("UTC Day    : %d\n", utcTime->tm_mday);
    printf("UTC Hour   : %d\n", utcTime->tm_hour);
    printf("UTC Minute : %d\n", utcTime->tm_min);
    printf("UTC Second : %d\n", utcTime->tm_sec);

    return 0;
}

Explanation:

  1. The program retrieves the current time using time().
  2. gmtime() converts this time value into a struct tm representing UTC.
  3. The various components of the UTC time (year, month, day, hour, minute, and second) are printed.

Program Output:

UTC Year   : 2025
UTC Month  : 2
UTC Day    : 23
UTC Hour   : 4
UTC Minute : 42
UTC Second : 5

Example 2: Converting a Specific Time Value (Unix Epoch)

This example shows how to convert a predetermined time value, such as the Unix epoch (0 seconds), into its UTC representation.

Program

</>
Copy
#include <stdio.h>
#include <time.h>

int main() {
    time_t epochTime = 0;
    struct tm *utcTime;

    // Convert Unix epoch (0 seconds) to UTC
    utcTime = gmtime(&epochTime);

    // Display UTC time components for the epoch
    printf("UTC Year   : %d\n", utcTime->tm_year + 1900);
    printf("UTC Month  : %d\n", utcTime->tm_mon + 1);
    printf("UTC Day    : %d\n", utcTime->tm_mday);
    printf("UTC Hour   : %d\n", utcTime->tm_hour);
    printf("UTC Minute : %d\n", utcTime->tm_min);
    printf("UTC Second : %d\n", utcTime->tm_sec);

    return 0;
}

Explanation:

  1. A specific time value of 0 is set, which represents the Unix epoch (January 1, 1970, 00:00:00 UTC).
  2. gmtime() converts this value into a struct tm containing the corresponding UTC date and time.
  3. The program prints each component of the UTC time structure.

Program Output:

UTC Year   : 1970
UTC Month  : 1
UTC Day    : 1
UTC Hour   : 0
UTC Minute : 0
UTC Second : 0

Example 3: Converting a Custom Time Value to UTC

This example illustrates converting a custom time value (expressed in seconds since the Unix epoch) to its UTC representation using gmtime().

Program

</>
Copy
#include <stdio.h>
#include <time.h>

int main() {
    // Custom time value for January 1, 2021 00:00:00 UTC
    time_t customTime = 1609459200;
    struct tm *utcTime;

    // Convert the custom time value to UTC
    utcTime = gmtime(&customTime);

    // Display the converted UTC time components
    printf("UTC Year   : %d\n", utcTime->tm_year + 1900);
    printf("UTC Month  : %d\n", utcTime->tm_mon + 1);
    printf("UTC Day    : %d\n", utcTime->tm_mday);
    printf("UTC Hour   : %d\n", utcTime->tm_hour);
    printf("UTC Minute : %d\n", utcTime->tm_min);
    printf("UTC Second : %d\n", utcTime->tm_sec);

    return 0;
}

Explanation:

  1. A custom time value representing January 1, 2021 00:00:00 UTC is defined.
  2. gmtime() converts this time value into a struct tm containing the UTC date and time components.
  3. The program prints the year, month, day, hour, minute, and second from the UTC structure.

Program Output:

UTC Year   : 2021
UTC Month  : 1
UTC Day    : 1
UTC Hour   : 0
UTC Minute : 0
UTC Second : 0