The GNU C Library provides several functions for getting the current calendar time, with different levels of resolution.
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.
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:
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.
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.
Systems may support more than just these two POSIX clocks.
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:
EINVALThe 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:
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:
EINVALThe 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.
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.
int timespec_get (struct timespec *ts, int base) ¶Store into *ts the current time according to the ISO C time base.
The return value is base on success and 0 on failure.
int timespec_getres (struct timespec *res, int base) ¶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.
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.