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
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.
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:
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.
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.
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.
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.
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.