# time

> C++ Atlas: `cppatlas.com/w/c/chrono/time` | Source: https://en.cppreference.com/w/c/chrono/time | Domain: Date and time utilities | Standards: C11, C23

Returns the current calendar time encoded as a time_t object, and also stores it in the time_t object pointed to by arg (unless arg is a null pointer)

## Official Specification Summary (cppreference)

```cpp
// Defined in header <time.h>
time_t time( time_t* arg );
```

Returns the current calendar time encoded as a `time_t` object, and also stores it in the `time_t` object pointed to by `arg` (unless `arg` is a null pointer)

### Parameters

- `arg` - pointer to a `time_t` object where the time will be stored, or a null pointer

### Return value

Current calendar time encoded as `time_t` object on success, `(time_t)(-1)` on error. If `arg` is not a null pointer, the return value is also stored in the object pointed to by `arg`.

### Notes

The encoding of calendar time in `time_t` is unspecified, but most systems conform to POSIX specification and return a value of integral type holding the number of seconds since the Epoch. Implementations in which `time_t` is a 32-bit signed integer (many historical implementations) fail in the year 2038.

### Example

```c
#include <stdint.h>
#include <stdio.h>
#include <time.h>

int main(void)
{
    time_t result = time(NULL);
    if (result != (time_t)(-1))
        printf("The current time is %s(%jd seconds since the Epoch)\n",
               asctime(gmtime(&result)), (intmax_t)result);
}
```

Possible output:

```text
The current time is Fri Apr 24 15:05:25 2015
(1429887925 seconds since the Epoch)
```

### References

- C23 standard (ISO/IEC 9899:2024):

  - 7.27.2.4 The time function (p: TBD)

- C17 standard (ISO/IEC 9899:2018):

  - 7.27.2.4 The time function (p: 286)

- C11 standard (ISO/IEC 9899:2011):

  - 7.27.2.4 The time function (p: 391)

- C99 standard (ISO/IEC 9899:1999):

  - 7.23.2.4 The time function (p: 341)

- C89/C90 standard (ISO/IEC 9899:1990):

  - 4.12.2.4 The time function

### See also

- [`localtime`](https://en.cppreference.com/w/c/chrono/localtime), [`localtime_r`](https://en.cppreference.com/w/c/chrono/localtime) (C23), [`localtime_s`](https://en.cppreference.com/w/c/chrono/localtime) (C11): converts time since epoch to calendar time expressed as local time (function)
- [`gmtime`](https://en.cppreference.com/w/c/chrono/gmtime), [`gmtime_r`](https://en.cppreference.com/w/c/chrono/gmtime) (C23), [`gmtime_s`](https://en.cppreference.com/w/c/chrono/gmtime) (C11): converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC) (function)
- [`timespec_get`](https://en.cppreference.com/w/c/chrono/timespec_get) (C11): returns the calendar time in seconds and nanoseconds based on a given time base (function)
- [C++ documentation for `time`](https://en.cppreference.com/w/cpp/chrono/c/time)

---
Attribution: content from https://en.cppreference.com/w/c/chrono/time (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.