# PyTime C API

Added in version 3.13.

The clock C API provides access to system clocks. It is similar to the Python `time` module.

For C API related to the `datetime` module, see DateTime Objects.

## Types

type PyTime_t

  A timestamp or duration in nanoseconds, represented as a signed 64-bit integer.

  The reference point for timestamps depends on the clock used. For example, `PyTime_Time()` returns timestamps relative to the UNIX epoch.

  The supported range is around [-292.3 years; +292.3 years]. Using the Unix epoch (January 1st, 1970) as reference, the supported date range is around [1677-09-21; 2262-04-11]. The exact limits are exposed as constants:

PyTime_t PyTime_MIN

  Minimum value of `PyTime_t`.

PyTime_t PyTime_MAX

  Maximum value of `PyTime_t`.

## Clock Functions

The following functions take a pointer to a PyTime_t that they set to the value of a particular clock. Details of each clock are given in the documentation of the corresponding Python function.

The functions return `0` on success, or `-1` (with an exception set) on failure.

On integer overflow, they set the `PyExc_OverflowError` exception and set `*result` to the value clamped to the `[PyTime_MIN; PyTime_MAX]` range. (On current systems, integer overflows are likely caused by misconfigured system time.)

As any other C API (unless otherwise specified), the functions must be called with the GIL held.

int PyTime_Monotonic(PyTime_t *result)

  Read the monotonic clock. See `time.monotonic()` for important details on this clock.

int PyTime_PerfCounter(PyTime_t *result)

  Read the performance counter. See `time.perf_counter()` for important details on this clock.

int PyTime_Time(PyTime_t *result)

  Read the “wall clock” time. See `time.time()` for details important on this clock.

## Raw Clock Functions

Similar to clock functions, but don’t set an exception on error and don’t require the caller to hold the GIL.

On success, the functions return `0`.

On failure, they set `*result` to `0` and return `-1`, without setting an exception. To get the cause of the error, acquire the GIL and call the regular (non-`Raw`) function. Note that the regular function may succeed after the `Raw` one failed.

int PyTime_MonotonicRaw(PyTime_t *result)

  Similar to `PyTime_Monotonic()`, but don’t set an exception on error and don’t require holding the GIL.

int PyTime_PerfCounterRaw(PyTime_t *result)

  Similar to `PyTime_PerfCounter()`, but don’t set an exception on error and don’t require holding the GIL.

int PyTime_TimeRaw(PyTime_t *result)

  Similar to `PyTime_Time()`, but don’t set an exception on error and don’t require holding the GIL.

## Conversion functions

double PyTime_AsSecondsDouble(PyTime_t t)

  Convert a timestamp to a number of seconds as a C double.

  The function cannot fail, but note that double has limited accuracy for large values.