---

21.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 provides a function clock_gettime that can 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. You can find the resolution of a clock with the function clock_getres. 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 system clocks one wishes to use.

All systems that support this family of functions will define at least this clock constant:

Macro: clockid_t CLOCK_REALTIME ¶

This clock uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated Universal Time. 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 ¶

System-wide clock that 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.

Systems may support more than just these two clocks.

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

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) ¶

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.

These functions, and the constants that identify particular clocks, are declared in time.h.

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 GNU C Library also provides an older, but still widely used, 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 Functions and Variables for Time Zones and in Broken-down Time for working with time zones.

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

Portability Note: As of the 2008 revision of POSIX, this function is considered obsolete. The GNU C Library will continue to provide this function indefinitely, but new programs should use clock_gettime instead.