Overview #

The clock_gettime() function retrieves the current time of a specified system clock with nanosecond precision.

Unlike time() and gettimeofday(), which always return the current calendar time, clock_gettime() can retrieve time from different system clocks, such as the real-time clock, monotonic clock, and CPU-time clocks.

It is the recommended API for high-resolution time measurements on modern Linux systems.

Header File #

#include <time.h>

Man Pages #

man 2 clock_gettime
man 3 clock_gettime

• Section 2 documents the Linux system call.
• Section 3 documents the C library wrapper.

Function Prototype #

int clock_gettime(clockid_t clockid,
                  struct timespec *tp);

Parameters #

Return Value #

On success, the function returns:

0

On failure, it returns:

-1

If an error occurs, errno is set appropriately.

Data Types #

clockid_t #

clockid_t identifies the system clock used by clock_gettime().

Some commonly used clock IDs are:

struct timespec #

The retrieved time is stored in a timespec structure.

struct timespec
{
    time_t tv_sec;
    long   tv_nsec;
};

Examples #

Example 1 – Get the Current Real Time #

main.c #

#include <stdio.h>
#include <time.h>

int main(void)
{
    struct timespec ts;

    if (clock_gettime(CLOCK_REALTIME, &ts) == -1)
    {
        perror("clock_gettime");
        return 1;
    }

    printf("Seconds     : %ld\n", ts.tv_sec);
    printf("Nanoseconds : %ld\n", ts.tv_nsec);

    return 0;
}

Output #

Seconds     : 1753642158
Nanoseconds : 348297641

The output will be different on your system.

Explanation #

struct timespec ts;

Declares a timespec structure to store the current time.

clock_gettime(CLOCK_REALTIME, &ts);

Retrieves the current calendar time with nanosecond precision.

ts.tv_sec

Contains the number of seconds.

ts.tv_nsec

Contains the nanosecond portion of the current second.

Example 2 – Measure Elapsed Time #

main.c #

#include <stdio.h>
#include <time.h>

int main(void)
{
    struct timespec start, end;

    clock_gettime(CLOCK_MONOTONIC, &start);

    for (volatile long i = 0; i < 100000000; i++);

    clock_gettime(CLOCK_MONOTONIC, &end);

    double elapsed =
        (end.tv_sec - start.tv_sec) +
        (end.tv_nsec - start.tv_nsec) / 1000000000.0;

    printf("Elapsed Time = %.9f seconds\n", elapsed);

    return 0;
}

Output #

Elapsed Time = 0.184572631 seconds

The output will vary depending on your system.

Explanation #

clock_gettime(CLOCK_MONOTONIC, &start);

Records the starting time using the monotonic clock.

clock_gettime(CLOCK_MONOTONIC, &end);

Records the ending time.

(end.tv_sec - start.tv_sec)

Calculates the elapsed time in whole seconds.

(end.tv_nsec - start.tv_nsec) / 1000000000.0

Converts the elapsed nanoseconds into fractional seconds.

elapsed = ...

Calculates the total elapsed time in seconds.

Common Clock IDs #

Notes #

• clock_gettime() provides nanosecond precision.
• It supports multiple system clocks.
• CLOCK_MONOTONIC is recommended for measuring elapsed time because it is not affected by system clock adjustments.
• CLOCK_REALTIME represents the current calendar time and can change if the system clock is adjusted.
• On failure, the function returns -1 and sets errno.
• clock_gettime() is the preferred timing API for modern Linux applications.

Related Functions #

• time()
• gettimeofday()
• clock()
• difftime()
• clock_getres()
• clock_settime()