---
title: 5.1 time()
description: "## 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…"
url: "https://edcret.in/docs/linux-os/system-calls/time-system-calls/c-time-function/"
updated: "2026-07-27"
category: Linux OS / System Calls / Time System Calls
---

# 5.1 time()

## 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

| Parameter | Description |
| --- | --- |
| `tloc` | Pointer to a `time_t` object where the current calendar time is stored. Pass `NULL` if you only need the return value. |

## 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 = %ldn", 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 = %ldn", 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 : %ldn", return_value);
    printf("Stored Value : %ldn", 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.

| Date and Time (UTC) | Unix Timestamp |
| --- | --- |
| 1 January 1970 00:00:00 | 0 |
| 1 January 1970 00:00:10 | 10 |
| 1 January 1970 00:01:00 | 60 |
| 1 January 1970 01:00:00 | 3600 |

`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()`