C localtime() Function – time.h

localtime() Function

The localtime() function in C time.h converts a time value into a tm structure that represents the corresponding local time. It enables programs to obtain human-readable time components from a numeric time value.

---

Syntax of localtime()

struct tm *localtime(const time_t *timer);

Parameters

Parameter	Description
timer	Pointer to an object of type time_t containing a time value.

The localtime() function interprets the provided time value according to the system’s local timezone settings. Note that the returned pointer refers to an internal static object whose contents may be overwritten by subsequent calls to localtime() or gmtime().

---

Return Value

The function returns a pointer to a tm structure containing the local time representation of the provided time value. If an error occurs, it returns NULL.

---

Examples for localtime()

Example 1: Converting the Current Time to Local Time

This example demonstrates how to obtain the current time and convert it into a local time representation using localtime().

Program

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

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

    /* Get the current time */
    currentTime = time(NULL);

    /* Convert the current time to local time */
    localTime = localtime(&currentTime);

    printf("Current local time:\n");
    printf("Year: %d\n", localTime->tm_year + 1900);
    printf("Month: %d\n", localTime->tm_mon + 1);
    printf("Day: %d\n", localTime->tm_mday);
    printf("Hour: %d\n", localTime->tm_hour);
    printf("Minute: %d\n", localTime->tm_min);
    printf("Second: %d\n", localTime->tm_sec);

    return 0;
}

Explanation:

1. The current time is retrieved using the time() function.
2. localtime() converts the time_t value to a tm structure reflecting local time.
3. The individual components of the local time (year, month, day, hour, minute, and second) are printed.

Program Output:

Current local time:
Year: 2025
Month: 2
Day: 23
Hour: 4
Minute: 40
Second: 49

Example 2: Formatting Local Time Using strftime()

This example shows how to format the local time into a human-readable string using strftime() after converting the current time with localtime().

Program

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

int main() {
    time_t currentTime;
    struct tm *localTime;
    char formattedTime[100];

    /* Get the current time */
    currentTime = time(NULL);

    /* Convert the current time to local time */
    localTime = localtime(&currentTime);

    /* Format the local time into a readable string */
    strftime(formattedTime, sizeof(formattedTime), "%Y-%m-%d %H:%M:%S", localTime);

    printf("Formatted local time: %s\n", formattedTime);

    return 0;
}

Explanation:

1. The current time is obtained and converted to local time using localtime().
2. strftime() formats the tm structure into a string according to the specified format "%Y-%m-%d %H:%M:%S".
3. The formatted string is printed to display the local time in a human-readable format.

Program Output:

Formatted local time: 2025-02-23 04:40:58

Example 3: Converting a Custom Time Value to Local Time

This example demonstrates how to create a custom time value, convert it into a time_t value, and then obtain its local time representation using localtime().

Program

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

int main() {
    struct tm customTime = {0};
    time_t customTimeT;
    struct tm *localTime;

    /* Set custom time: December 25, 2020 10:30:00 */
    customTime.tm_year = 2020 - 1900;  /* Years since 1900 */
    customTime.tm_mon  = 11;           /* Month (0-11, December is 11) */
    customTime.tm_mday = 25;           /* Day of the month */
    customTime.tm_hour = 10;
    customTime.tm_min  = 30;
    customTime.tm_sec  = 0;

    /* Convert struct tm to time_t */
    customTimeT = mktime(&customTime);

    /* Convert the custom time to local time */
    localTime = localtime(&customTimeT);

    printf("Custom local time:\n");
    printf("Year: %d\n", localTime->tm_year + 1900);
    printf("Month: %d\n", localTime->tm_mon + 1);
    printf("Day: %d\n", localTime->tm_mday);
    printf("Hour: %d\n", localTime->tm_hour);
    printf("Minute: %d\n", localTime->tm_min);
    printf("Second: %d\n", localTime->tm_sec);

    return 0;
}

Explanation:

1. A struct tm is initialized with a custom date and time (December 25, 2020 10:30:00).
2. mktime() converts the tm structure to a time_t value.
3. localtime() converts this time_t value to a local time representation.
4. The individual components of the local time are printed to confirm the conversion.

Program Output:

Custom local time:
Year: 2020
Month: 12
Day: 25
Hour: 10
Minute: 30
Second: 0