C gmtime() Function

The gmtime() function in C is a standard library function that converts a time_t value to a tm structure representing Coordinated Universal Time (UTC). It is part of the C standard library (time.h). This function is useful for converting calendar time to a broken-down time representation in UTC.

Table of Contents

  1. Introduction
  2. gmtime() Function Syntax
  3. Examples
    • Converting time_t to tm as UTC
    • Using gmtime() with Current Time
  4. Real-World Use Case
  5. Conclusion

Introduction

The gmtime() function converts a time_t value, representing calendar time, to a tm structure that represents the corresponding UTC time. This is useful for applications that need to work with time in a standardized, time zone-independent format.

gmtime() Function Syntax

The syntax for the gmtime() function is as follows:

#include <time.h>
struct tm *gmtime(const time_t *timer);

Parameters:

  • timer: A pointer to a time_t value that represents the time to be converted.

Returns:

  • The function returns a pointer to a statically allocated tm structure representing the UTC time. If an error occurs, it returns NULL.

Examples

Converting time_t to tm as UTC

To demonstrate how to use gmtime() to convert a time_t value to a tm structure in UTC, we will write a simple program that retrieves the current time and converts it to UTC.

Example

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

int main() {
    time_t current_time;
    struct tm *utc_time;

    // Get the current time
    current_time = time(NULL);

    // Convert the time to UTC
    utc_time = gmtime(&current_time);

    // Check if the conversion was successful
    if (utc_time != NULL) {
        // Print the result
        printf("UTC time: %d-%02d-%02d %02d:%02d:%02d\n",
               utc_time->tm_year + 1900, utc_time->tm_mon + 1, utc_time->tm_mday,
               utc_time->tm_hour, utc_time->tm_min, utc_time->tm_sec);
    } else {
        printf("Failed to convert time to UTC.\n");
    }

    return 0;
}

Output:

UTC time: 2023-07-04 12:34:56

Using gmtime() with User Input

This example shows how to use gmtime() to convert a user-provided time_t value to a tm structure in UTC.

Example

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

int main() {
    struct tm time_struct = {0};
    time_t time_value;
    struct tm *utc_time;

    // Get user input for the date and time
    printf("Enter year: ");
    scanf("%d", &time_struct.tm_year);
    time_struct.tm_year -= 1900; // Adjust year

    printf("Enter month (1-12): ");
    scanf("%d", &time_struct.tm_mon);
    time_struct.tm_mon -= 1; // Adjust month

    printf("Enter day of the month (1-31): ");
    scanf("%d", &time_struct.tm_mday);

    printf("Enter hour (0-23): ");
    scanf("%d", &time_struct.tm_hour);

    printf("Enter minute (0-59): ");
    scanf("%d", &time_struct.tm_min);

    printf("Enter second (0-59): ");
    scanf("%d", &time_struct.tm_sec);

    // Convert tm structure to time_t
    time_value = mktime(&time_struct);

    // Convert the time to UTC
    utc_time = gmtime(&time_value);

    // Print the result
    if (utc_time != NULL) {
        printf("UTC time: %d-%02d-%02d %02d:%02d:%02d\n",
               utc_time->tm_year + 1900, utc_time->tm_mon + 1, utc_time->tm_mday,
               utc_time->tm_hour, utc_time->tm_min, utc_time->tm_sec);
    } else {
        printf("Failed to convert time to UTC.\n");
    }

    return 0;
}

Output (example user input year "2023", month "7", day "4", hour "12", minute "30", second "0"):

Enter year: 2023
Enter month (1-12): 7
Enter day of the month (1-31): 4
Enter hour (0-23): 12
Enter minute (0-59): 30
Enter second (0-59): 0
UTC time: 2023-07-04 12:30:00

Real-World Use Case

Converting Local Time to UTC for Standardized Storage

In real-world applications, the gmtime() function can be used to convert local times to UTC for standardized storage in databases or logs, ensuring consistency across different time zones.

Example: Storing Timestamps in UTC

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

// Function to get user input for date and time
void get_user_input(struct tm *time_struct) {
    printf("Enter year: ");
    scanf("%d", &time_struct->tm_year);
    time_struct->tm_year -= 1900; // Adjust year

    printf("Enter month (1-12): ");
    scanf("%d", &time_struct->tm_mon);
    time_struct->tm_mon -= 1; // Adjust month

    printf("Enter day of the month (1-31): ");
    scanf("%d", &time_struct->tm_mday);

    printf("Enter hour (0-23): ");
    scanf("%d", &time_struct->tm_hour);

    printf("Enter minute (0-59): ");
    scanf("%d", &time_struct->tm_min);

    printf("Enter second (0-59): ");
    scanf("%d", &time_struct->tm_sec);
}

int main() {
    struct tm local_time = {0};
    time_t time_value;
    struct tm *utc_time;

    // Get user input for the local date and time
    get_user_input(&local_time);

    // Convert tm structure to time_t
    time_value = mktime(&local_time);

    // Convert the time to UTC
    utc_time = gmtime(&time_value);

    // Print the result
    if (utc_time != NULL) {
        printf("UTC time: %d-%02d-%02d %02d:%02d:%02d\n",
               utc_time->tm_year + 1900, utc_time->tm_mon + 1, utc_time->tm_mday,
               utc_time->tm_hour, utc_time->tm_min, utc_time->tm_sec);
    } else {
        printf("Failed to convert time to UTC.\n");
    }

    return 0;
}

Output (example user input year "2023", month "7", day "4", hour "12", minute "30", second "0"):

Enter year: 2023
Enter month (1-12): 7
Enter day of the month (1-31): 4
Enter hour (0-23): 12
Enter minute (0-59): 30
Enter second (0-59): 0
UTC time: 2023-07-04 12:30:00

Conclusion

The gmtime() function is essential for converting a time_t value to a tm structure representing UTC time in C. It is useful in various applications, particularly in date and time manipulation, where it is necessary to convert calendar time to a broken-down time representation in UTC for calculations, storage, and display.

Comments

Spring Boot 3 Paid Course Published for Free
on my Java Guides YouTube Channel

Subscribe to my YouTube Channel (165K+ subscribers):
Java Guides Channel

Top 10 My Udemy Courses with Huge Discount:
Udemy Courses - Ramesh Fadatare