C time() Function – time.h

time() Function

The time() function in C retrieves the current calendar time, typically expressed as the number of seconds elapsed since the Unix Epoch (00:00 hours, Jan 1, 1970 UTC). It is extensively used for generating timestamps, measuring time intervals, and in various time-related operations within programs.

---

Syntax of time()

time_t time(time_t *timer);

Parameters

Parameter	Description
timer	A pointer to an object of type time_t where the current time is stored. If this pointer is NULL, the function simply returns the current time.

The value returned by time() represents the number of seconds since the Unix Epoch. It is recommended to use additional functions like localtime(), gmtime(), or difftime() to convert or compare these values in a portable manner.

Return Value

The function returns the current calendar time as a time_t object. If the timer argument is not NULL, the returned value is also stored in the object pointed to by timer. On failure, it returns (time_t)(-1).

---

Examples for time()

Example 1: Retrieving the Current Unix Timestamp

This example demonstrates how to retrieve and display the current time as the number of seconds since the Unix Epoch.

Program

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

int main() {
    time_t currentTime;

    /* Retrieve the current calendar time */
    currentTime = time(NULL);

    if (currentTime == (time_t)(-1)) {
        printf("Failed to obtain the current time.\n");
        return 1;
    }

    printf("Current time (Unix timestamp): %ld\n", currentTime);
    return 0;
}

Explanation:

1. The function time() is called with a NULL argument to simply retrieve the current time.
2. The returned value, which is the Unix timestamp, is stored in currentTime.
3. The program checks for failure and then prints the timestamp.

Program Output:

Current time (Unix timestamp): 1740285517

Example 2: Storing the Current Time via Pointer

This example shows how to pass a non-NULL pointer to time() so that the current time is stored in a variable.

Program

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

int main() {
    time_t timer;
    time_t currentTime;

    /* Retrieve the current time and store it in 'timer' */
    currentTime = time(&timer);

    if (currentTime == (time_t)(-1)) {
        printf("Failed to retrieve the current time.\n");
        return 1;
    }

    printf("Current time (stored via pointer): %ld\n", timer);
    return 0;
}

Explanation:

1. A variable timer of type time_t is declared.
2. The address of timer is passed to time(), which stores the current time in it.
3. The program prints the value stored in timer, verifying the operation.

Program Output:

Current time (stored via pointer): 1740285524

Example 3: Converting Unix Timestamp to a Readable String

This example illustrates how to convert the Unix timestamp obtained from time() to a human-readable format using the ctime() function.

Program

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

int main() {
    time_t currentTime;
    char *readableTime;

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

    if (currentTime == (time_t)(-1)) {
        printf("Failed to get the current time.\n");
        return 1;
    }

    /* Convert the time to a human-readable string */
    readableTime = ctime(&currentTime);
    if (readableTime == NULL) {
        printf("Failed to convert time to string.\n");
        return 1;
    }

    printf("Current local time: %s", readableTime);
    return 0;
}

Explanation:

1. The current time is retrieved using time().
2. The ctime() function converts the Unix timestamp to a human-readable string format.
3. The program prints the formatted time string, which represents the local time.

Program Output:

Current local time: Sun Feb 23 04:38:56 2025