Getting the Time (The GNU C Library)

#### 22.5.1 Getting the Time ¶

The GNU C Library provides several functions for getting the current calendar time, with different levels of resolution.

Function: `time_t` time `(time_t *result)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This is the simplest function for getting the current calendar time. It returns the calendar time as a value of type `time_t`; on POSIX systems, that means it has a resolution of one second. It uses the same clock as ‘`clock_gettime (CLOCK_REALTIME_COARSE)`’, when the clock is available or ‘`clock_gettime (CLOCK_REALTIME)`’ otherwise.

  If the argument result is not a null pointer, the calendar time value is also stored in `*result`.

  This function cannot fail.

Some applications need more precise timekeeping than is possible with a `time_t` alone. Some applications also need more control over what is meant by “the current time.” For these applications, POSIX and ISO C provide functions to retrieve the time with up to nanosecond precision, from a variety of different clocks. Clocks can be system-wide, measuring time the same for all processes; or they can be per-process or per-thread, measuring CPU time consumed by a particular process, or some other similar resource. Each clock has its own resolution and epoch. POSIX and ISO C also provide functions for finding the resolution of a clock. There is no function to get the epoch for a clock; either it is fixed and documented, or the clock is not meant to be used to measure absolute times.

Data Type: clockid_t ¶

  The type `clockid_t` is used for constants that indicate which of several POSIX system clocks one wishes to use.

All systems that support the POSIX functions will define at least this clock constant:

Macro: `clockid_t` CLOCK_REALTIME ¶

  This POSIX clock uses the POSIX Epoch, 1970-01-01 00:00:00 UTC. It is close to, but not necessarily in lock-step with, the clocks of `time` (above) and of `gettimeofday` (below).

A second clock constant which is not universal, but still very common, is for a clock measuring monotonic time. Monotonic time is useful for measuring elapsed times, because it guarantees that those measurements are not affected by changes to the system clock.

Macro: `clockid_t` CLOCK_MONOTONIC ¶

  This system-wide POSIX clock continuously measures the advancement of calendar time, ignoring discontinuous changes to the system’s setting for absolute calendar time.

  The epoch for this clock is an unspecified point in the past. The epoch may change if the system is rebooted or suspended. Therefore, `CLOCK_MONOTONIC` cannot be used to measure absolute time, only elapsed time.

The following clocks are defined by POSIX, but may not be supported by all POSIX systems:

Macro: `clockid_t` CLOCK_PROCESS_CPUTIME_ID ¶

  This POSIX clock measures the amount of CPU time used by the calling process.

Macro: `clockid_t` CLOCK_THREAD_CPUTIME_ID ¶

  This POSIX clock measures the amount of CPU time used by the calling thread.

The following clocks are Linux extensions:

Macro: `clockid_t` CLOCK_MONOTONIC_RAW ¶
Macro: `clockid_t` CLOCK_REALTIME_COARSE ¶
Macro: `clockid_t` CLOCK_MONOTONIC_COARSE ¶
Macro: `clockid_t` CLOCK_BOOTTIME ¶
Macro: `clockid_t` CLOCK_REALTIME_ALARM ¶
Macro: `clockid_t` CLOCK_BOOTTIME_ALARM ¶
Macro: `clockid_t` CLOCK_TAI ¶

  For details of these clocks, see the manual page clock_gettime(2) See Linux (The Linux Kernel).

Systems may support additional clocks beyond those listed here.

Function: `int` clock_gettime `(clockid_t clock, struct timespec *ts)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  Get the current time according to the clock identified by clock, storing it as seconds and nanoseconds in `*ts`. See Time Types, for a description of `struct timespec`.

  The return value is `0` on success and `-1` on failure. The following `errno` error condition is defined for this function:

  `EINVAL`

    The clock identified by clock is not supported.

`clock_gettime` reports the time scaled to seconds and nanoseconds, but the actual resolution of each clock may not be as fine as one nanosecond, and may not be the same for all clocks. POSIX also provides a function for finding out the actual resolution of a clock:

Function: `int` clock_getres `(clockid_t clock, struct timespec *res)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  Get the actual resolution of the clock identified by clock, storing it in `*ts`.

  For instance, if the clock hardware for `CLOCK_REALTIME` uses a quartz crystal that oscillates at 32.768 kHz, then its resolution would be 30.518 microseconds, and ‘`clock_getres (CLOCK_REALTIME, &r)`’ would set `r.tv_sec` to 0 and `r.tv_nsec` to 30518.

  The return value is `0` on success and `-1` on failure. The following `errno` error condition is defined for this function:

  `EINVAL`

    The clock identified by clock is not supported.

Portability Note: On some systems, including systems that use older versions of the GNU C Library, programs that use `clock_gettime` or `clock_setres` must be linked with the `-lrt` library. This has not been necessary with the GNU C Library since version 2.17.

The following ISO C macros and functions for higher-resolution timestamps were standardized more recently than the POSIX functions, so they are less portable to older POSIX systems. However, the ISO C functions are portable to C platforms that do not support POSIX.

Macro: `int` TIME_UTC ¶

  This is a positive integer constant designating a simple calendar time base. In the GNU C Library and other POSIX systems, this is equivalent to the POSIX `CLOCK_REALTIME` clock. On non-POSIX systems, though, the epoch is implementation-defined.

Systems may support more than just this ISO C clock.

Function: `int` timespec_get `(struct timespec *ts, int base)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  Store into `*ts` the current time according to the ISO C time base.

  The base `TIME_UTC` returns the time since the epoch. It corresponds to `CLOCK_REALTIME`.

  The base `TIME_MONOTONIC` returns a monotonically nondecreasing time since an unspecified point in the past that may change if the system is rebooted or suspended. It corresponds to `CLOCK_MONOTONIC`.

  The base `TIME_ACTIVE` returns the CPU time consumed by the process (including all threads). It corresponds to `CLOCK_PROCESS_CPUTIME_ID`.

  The base `TIME_THREAD_ACTIVE` returns the CPU time consumed by the calling thread. It corresponds to `CLOCK_THREAD_CPUTIME_ID`.

  The return value is base on success and `0` on failure.

Function: `int` timespec_getres `(struct timespec *res, int base)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  If ts is non-null, store into `*ts` the resolution of the time provided by `timespec_get` function for the ISO C time base.

  The return value is base on success and `0` on failure.

The previous functions, data types and constants are declared in `time.h`. The GNU C Library also provides an older function for getting the current time with a resolution of microseconds. This function is declared in `sys/time.h`.

Function: `int` gettimeofday `(struct timeval *tp, void *tzp)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  Get the current calendar time, storing it as seconds and microseconds in `*tp`. See Time Types, for a description of `struct timeval`. The clock of `gettimeofday` is close to, but not necessarily in lock-step with, the clocks of `time` and of ‘`clock_gettime (CLOCK_REALTIME)`’ (see above).

  On some historic systems, if tzp was not a null pointer, information about a system-wide time zone would be written to `*tzp`. This feature is obsolete and not supported on GNU systems. You should always supply a null pointer for this argument. Instead, use the facilities described in Broken-down Time for working with time zones.

  This function cannot fail, and its return value is always `0`.

  Portability Note: POSIX.1-2024 removed this function. Although the GNU C Library will continue to provide it indefinitely, portable programs should use `clock_gettime` or `timespec_get` instead.