clockgettime

Clock_gettime is a POSIX API function used to obtain the current value of a specified clock. It takes a clock identifier and a pointer to a timespec structure, which is filled with the time data. The timespec contains tv_sec (the seconds portion) and tv_nsec (the nanoseconds portion). The nanoseconds field represents fractional seconds with high precision. For CLOCK_REALTIME the seconds are counted from the Unix epoch; for other clocks the origin is implementation-defined or unspecified.

Common clocks include CLOCK_REALTIME (wall-clock time), CLOCK_MONOTONIC (steady clock not affected by system time changes), CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID (CPU time used by the process or thread). Many platforms also support clocks such as CLOCK_BOOTTIME or CLOCK_TAI; availability varies by system.

The function returns 0 on success and -1 on error, with errno set to indicate the failure. Typical errors are EINVAL for an invalid clock id and EFAULT if the provided timespec pointer is outside the process address space. It may also fail for other hardware or implementation-specific reasons.

Usage considerations include choosing the appropriate clock for the task: use CLOCK_REALTIME for timestamps tied to real-world time, and CLOCK_MONOTONIC for measuring elapsed time or timeouts, since it is not affected by changes to the system clock. The timespec’s nanosecond precision enables finer granularity than seconds-only timers.

Implementation notes: include <time.h> and link as required by the target platform (some older systems required -lrt; on modern Linux/glibc this is usually unnecessary). clock_gettime is widely used in performance timing, synchronization, and timeout handling due to its high resolution and predictable behavior.

---