C++ ctime gmtime() - Convert Time to UTC

Updated on September 27, 2024
gmtime() header image

Introduction

The gmtime() function in C++ is a part of the C standard library, which manipulates and formats date and time based on Coordinated Universal Time (UTC). This function converts the local time, provided as a timestamp in the form of a time_t value, into UTC format, represented as a tm structure. Understanding how to use this function is essential for applications requiring time coordination across different geographical regions.

In this article, you will learn how to use the gmtime() function in various C++ programming contexts. Discover the steps for converting local time to UTC and handling the returned structure to extract and format time elements such as year, month, day, and time.

Using gmtime() in C++

Convert Time to UTC

  1. Include the necessary headers, ctime for time manipulations and iostream for output operations.

  2. Obtain the current local time using time(nullptr).

  3. Convert the local time to a tm structure representing UTC time using gmtime().

    cpp
    #include <ctime>
    #include <iostream>
    
    int main() {
        // Obtain current local time
        time_t current_time = time(nullptr);
        // Convert local time to UTC
        tm* utc_time = gmtime(&current_time);
    
        // Output the UTC time details
        std::cout << "UTC time: " << 1900 + utc_time->tm_year << "-" 
                  << 1 + utc_time->tm_mon << "-" 
                  << utc_time->tm_mday << " " 
                  << utc_time->tm_hour << ":" 
                  << utc_time->tm_min << ":" 
                  << utc_time->tm_sec << std::endl;
    
        return 0;
    }
    

    Here, the program first captures the current local time. gmtime() then converts this to UTC, storing the result in a tm structure. The elements of this structure are adjusted to human-readable format and displayed.

Handling Potential Issues

  1. Note that gmtime() returns a pointer to a statically allocated tm structure, which may be overwritten by subsequent calls.

  2. Ensure to use this pointer or copy its contents before any subsequent time manipulation function calls that might alter it.

    Improving Safeness with gmtime_r()

    For thread-safe implementation, consider using gmtime_r() available in POSIX systems, which uses a user-provided buffer for the tm structure.

    cpp
    #include <ctime>
    #include <iostream>
    
    int main() {
        time_t current_time = time(nullptr);
        tm utc_time_struct;
        tm* utc_time = gmtime_r(&current_time, &utc_time_struct);
    
        if (utc_time) {
            std::cout << "UTC time: " << 1900 + utc_time->tm_year << "-"
                      << 1 + utc_time->tm_mon << "-"
                      << utc_time->tm_mday << " "
                      << utc_time->tm_hour << ":"
                      << utc_time->tm_min << ":"
                      << utc_time->tm_sec << std::endl;
        }
        return 0;
    }
    

    This code uses gmtime_r() where utc_time_struct is used to store the time data, ensuring that the time data is preserved and not overwritten by other time functions running on different threads.

Conclusion

The gmtime() function provides a straightforward approach for converting local time into UTC in C++. Given its ease of use and critical role in time manipulation in software, understanding how to properly utilize and handle the tm structure is fundamental. Whether for logging, synchronization, or any other purpose requiring time stamps in universal time, gmtime() serves as an essential tool in the C++ programmer's toolkit. Remember to consider thread safety and the static nature of the output when integrating this function into multi-threaded applications.