Overview #

The time() function returns the current calendar time as the number of seconds elapsed since the Unix Epoch (January 1, 1970, 00:00:00 UTC).

It is commonly used to obtain timestamps for logging, measuring elapsed time, and performing date and time calculations.

Header File #

#include <time.h>

Man Pages #

man 2 time
man 3 time

• Section 2 describes the Linux system call.
• Section 3 describes the C library function.

Function Prototype #

time_t time(time_t *tloc);

Parameters #

Return Value #

On success, time() returns the current calendar time as a value of type time_t.

On failure, it returns:

(time_t)-1

Data Types #

time_t #

time_t is a standard C data type used to represent calendar time.

The actual underlying type is implementation-defined and may vary between systems.

Examples #

Example 1 – Get the Current Time #

main.c #

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

int main(void)
{
    time_t current_time;

    current_time = time(NULL);

    printf("Current Time = %ld\n", current_time);

    return 0;
}

Output #

Current Time = 1753642158

The output will be different on your system.

Explanation #

time_t current_time;

Declares a variable of type time_t to store the current calendar time.

current_time = time(NULL);

Calls time() to obtain the current calendar time.

Passing NULL indicates that the function should only return the value and does not need to store it through the pointer parameter.

printf("Current Time = %ld\n", current_time);

Displays the Unix timestamp returned by time().

Example 2 – Store the Time Using tloc #

main.c #

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

int main(void)
{
    time_t current_time;
    time_t return_value;

    return_value = time(&current_time);

    printf("Return Value : %ld\n", return_value);
    printf("Stored Value : %ld\n", current_time);

    return 0;
}

Output #

Return Value : 1753642158
Stored Value : 1753642158

The values will be different on your system.

Explanation #

return_value = time(&current_time);

The address of current_time is passed to time().

The function stores the current calendar time in current_time and also returns the same value.

As a result, both variables contain identical values.

Unix Epoch #

The value returned by time() represents the number of seconds elapsed since the Unix Epoch.

The Unix Epoch is defined as:

1 January 1970
00:00:00 UTC

At that instant, the Unix timestamp was:

0

Every second that passes increases the timestamp by one.

time() returns the Unix timestamp, not a formatted date or time.

Notes #

• Returns the current calendar time.
• The returned value is measured in seconds.
• Pass NULL if you only need the return value.
• Pass the address of a time_t object if you also want the function to store the value.
• The returned value is commonly called a Unix timestamp.
• Use functions such as ctime(), localtime(), or gmtime() to convert the timestamp into a human-readable date and time.

Related Functions #

• ctime()
• localtime()
• gmtime()
• difftime()
• clock()