1.. highlight:: c 2 3.. _c-api-time: 4 5PyTime C API 6============ 7 8.. versionadded:: 3.13 9 10The clock C API provides access to system clocks. 11It is similar to the Python :mod:`time` module. 12 13For C API related to the :mod:`datetime` module, see :ref:`datetimeobjects`. 14 15 16Types 17----- 18 19.. c:type:: PyTime_t 20 21 A timestamp or duration in nanoseconds, represented as a signed 64-bit 22 integer. 23 24 The reference point for timestamps depends on the clock used. For example, 25 :c:func:`PyTime_Time` returns timestamps relative to the UNIX epoch. 26 27 The supported range is around [-292.3 years; +292.3 years]. 28 Using the Unix epoch (January 1st, 1970) as reference, the supported date 29 range is around [1677-09-21; 2262-04-11]. 30 The exact limits are exposed as constants: 31 32.. c:var:: PyTime_t PyTime_MIN 33 34 Minimum value of :c:type:`PyTime_t`. 35 36.. c:var:: PyTime_t PyTime_MAX 37 38 Maximum value of :c:type:`PyTime_t`. 39 40 41Clock Functions 42--------------- 43 44The following functions take a pointer to a :c:expr:`PyTime_t` that they 45set to the value of a particular clock. 46Details of each clock are given in the documentation of the corresponding 47Python function. 48 49The functions return ``0`` on success, or ``-1`` (with an exception set) 50on failure. 51 52On integer overflow, they set the :c:data:`PyExc_OverflowError` exception and 53set ``*result`` to the value clamped to the ``[PyTime_MIN; PyTime_MAX]`` 54range. 55(On current systems, integer overflows are likely caused by misconfigured 56system time.) 57 58As any other C API (unless otherwise specified), the functions must be called 59with the :term:`GIL` held. 60 61.. c:function:: int PyTime_Monotonic(PyTime_t *result) 62 63 Read the monotonic clock. 64 See :func:`time.monotonic` for important details on this clock. 65 66.. c:function:: int PyTime_PerfCounter(PyTime_t *result) 67 68 Read the performance counter. 69 See :func:`time.perf_counter` for important details on this clock. 70 71.. c:function:: int PyTime_Time(PyTime_t *result) 72 73 Read the “wall clock” time. 74 See :func:`time.time` for details important on this clock. 75 76 77Raw Clock Functions 78------------------- 79 80Similar to clock functions, but don't set an exception on error and don't 81require the caller to hold the GIL. 82 83On success, the functions return ``0``. 84 85On failure, they set ``*result`` to ``0`` and return ``-1``, *without* setting 86an exception. To get the cause of the error, acquire the GIL and call the 87regular (non-``Raw``) function. Note that the regular function may succeed after 88the ``Raw`` one failed. 89 90.. c:function:: int PyTime_MonotonicRaw(PyTime_t *result) 91 92 Similar to :c:func:`PyTime_Monotonic`, 93 but don't set an exception on error and don't require holding the GIL. 94 95.. c:function:: int PyTime_PerfCounterRaw(PyTime_t *result) 96 97 Similar to :c:func:`PyTime_PerfCounter`, 98 but don't set an exception on error and don't require holding the GIL. 99 100.. c:function:: int PyTime_TimeRaw(PyTime_t *result) 101 102 Similar to :c:func:`PyTime_Time`, 103 but don't set an exception on error and don't require holding the GIL. 104 105 106Conversion functions 107-------------------- 108 109.. c:function:: double PyTime_AsSecondsDouble(PyTime_t t) 110 111 Convert a timestamp to a number of seconds as a C :c:expr:`double`. 112 113 The function cannot fail, but note that :c:expr:`double` has limited 114 accuracy for large values. 115