Getting the Time (The GNU C Library) (2024)

21.5.1 Getting the Time

The GNU C Library provides several functions for getting the currentcalendar 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; onPOSIX systems, that means it has a resolution of one second. Ituses 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 timevalue is also stored in *result.

This function cannot fail.

Some applications need more precise timekeeping than is possible witha time_t alone. Some applications also need more control overwhat is meant by “the current time.” For these applications, POSIXprovides a function clock_gettime that can retrieve the timewith 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 consumedby a particular process, or some other similar resource. Each clockhas its own resolution and epoch. You can find the resolution of aclock with the function clock_getres. There is no function toget the epoch for a clock; either it is fixed and documented, or theclock 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 ofseveral system clocks one wishes to use.

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

Macro: clockid_t CLOCK_REALTIME ¶

This clock uses the POSIX epoch, 00:00:00 on January 1, 1970, CoordinatedUniversal Time. It is close to, but not necessarily in lock-step with, theclocks 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 isuseful for measuring elapsed times, because it guarantees that thosemeasurements are not affected by changes to the system clock.

Macro: clockid_t CLOCK_MONOTONIC ¶

System-wide clock that continuously measures the advancement ofcalendar time, ignoring discontinuous changes to the system’ssetting 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 measureabsolute 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. Thefollowing 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 andnanoseconds, but the actual resolution of each clock may not be asfine as one nanosecond, and may not be the same for all clocks. POSIXalso provides a function for finding out the actual resolution of aclock:

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_REALTIMEuses a quartz crystal that oscillates at 32.768 kHz,then its resolution would be 30.518 microseconds,and ‘clock_getres(CLOCK_REALTIME,&r)’ would setr.tv_sec to 0 and r.tv_nsec to 30518.

The return value is 0 on success and -1 on failure. Thefollowing 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 useolder versions of the GNU C Library, programs that use clock_gettimeor 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, functionfor getting the current time with a resolution of microseconds. Thisfunction 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 microsecondsin *tp. See Time Types, for a description ofstruct 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 onGNU systems. You should always supply a null pointer for thisargument. 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, thisfunction is considered obsolete. The GNU C Library will continue to providethis function indefinitely, but new programs should useclock_gettime instead.