1#ifndef Py_LIMITED_API 2#ifndef Py_PYTIME_H 3#define Py_PYTIME_H 4 5#include "pyconfig.h" /* include for defines */ 6#include "object.h" 7 8/************************************************************************** 9Symbols and macros to supply platform-independent interfaces to time related 10functions and constants 11**************************************************************************/ 12#ifdef __cplusplus 13extern "C" { 14#endif 15 16/* _PyTime_t: Python timestamp with subsecond precision. It can be used to 17 store a duration, and so indirectly a date (related to another date, like 18 UNIX epoch). */ 19typedef int64_t _PyTime_t; 20#define _PyTime_MIN PY_LLONG_MIN 21#define _PyTime_MAX PY_LLONG_MAX 22 23typedef enum { 24 /* Round towards minus infinity (-inf). 25 For example, used to read a clock. */ 26 _PyTime_ROUND_FLOOR=0, 27 /* Round towards infinity (+inf). 28 For example, used for timeout to wait "at least" N seconds. */ 29 _PyTime_ROUND_CEILING=1, 30 /* Round to nearest with ties going to nearest even integer. 31 For example, used to round from a Python float. */ 32 _PyTime_ROUND_HALF_EVEN 33} _PyTime_round_t; 34 35/* Convert a time_t to a PyLong. */ 36PyAPI_FUNC(PyObject *) _PyLong_FromTime_t( 37 time_t sec); 38 39/* Convert a PyLong to a time_t. */ 40PyAPI_FUNC(time_t) _PyLong_AsTime_t( 41 PyObject *obj); 42 43/* Convert a number of seconds, int or float, to time_t. */ 44PyAPI_FUNC(int) _PyTime_ObjectToTime_t( 45 PyObject *obj, 46 time_t *sec, 47 _PyTime_round_t); 48 49/* Convert a number of seconds, int or float, to a timeval structure. 50 usec is in the range [0; 999999] and rounded towards zero. 51 For example, -1.2 is converted to (-2, 800000). */ 52PyAPI_FUNC(int) _PyTime_ObjectToTimeval( 53 PyObject *obj, 54 time_t *sec, 55 long *usec, 56 _PyTime_round_t); 57 58/* Convert a number of seconds, int or float, to a timespec structure. 59 nsec is in the range [0; 999999999] and rounded towards zero. 60 For example, -1.2 is converted to (-2, 800000000). */ 61PyAPI_FUNC(int) _PyTime_ObjectToTimespec( 62 PyObject *obj, 63 time_t *sec, 64 long *nsec, 65 _PyTime_round_t); 66 67 68/* Create a timestamp from a number of seconds. */ 69PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds); 70 71/* Macro to create a timestamp from a number of seconds, no integer overflow. 72 Only use the macro for small values, prefer _PyTime_FromSeconds(). */ 73#define _PYTIME_FROMSECONDS(seconds) \ 74 ((_PyTime_t)(seconds) * (1000 * 1000 * 1000)) 75 76/* Create a timestamp from a number of nanoseconds. */ 77PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(long long ns); 78 79/* Convert a number of seconds (Python float or int) to a timetamp. 80 Raise an exception and return -1 on error, return 0 on success. */ 81PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t, 82 PyObject *obj, 83 _PyTime_round_t round); 84 85/* Convert a number of milliseconds (Python float or int, 10^-3) to a timetamp. 86 Raise an exception and return -1 on error, return 0 on success. */ 87PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t, 88 PyObject *obj, 89 _PyTime_round_t round); 90 91/* Convert a timestamp to a number of seconds as a C double. */ 92PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t); 93 94/* Convert timestamp to a number of milliseconds (10^-3 seconds). */ 95PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t, 96 _PyTime_round_t round); 97 98/* Convert timestamp to a number of microseconds (10^-6 seconds). */ 99PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t, 100 _PyTime_round_t round); 101 102/* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int 103 object. */ 104PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t); 105 106/* Convert a timestamp to a timeval structure (microsecond resolution). 107 tv_usec is always positive. 108 Raise an exception and return -1 if the conversion overflowed, 109 return 0 on success. */ 110PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t, 111 struct timeval *tv, 112 _PyTime_round_t round); 113 114/* Similar to _PyTime_AsTimeval(), but don't raise an exception on error. */ 115PyAPI_FUNC(int) _PyTime_AsTimeval_noraise(_PyTime_t t, 116 struct timeval *tv, 117 _PyTime_round_t round); 118 119/* Convert a timestamp to a number of seconds (secs) and microseconds (us). 120 us is always positive. This function is similar to _PyTime_AsTimeval() 121 except that secs is always a time_t type, whereas the timeval structure 122 uses a C long for tv_sec on Windows. 123 Raise an exception and return -1 if the conversion overflowed, 124 return 0 on success. */ 125PyAPI_FUNC(int) _PyTime_AsTimevalTime_t( 126 _PyTime_t t, 127 time_t *secs, 128 int *us, 129 _PyTime_round_t round); 130 131#if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE) 132/* Convert a timestamp to a timespec structure (nanosecond resolution). 133 tv_nsec is always positive. 134 Raise an exception and return -1 on error, return 0 on success. */ 135PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts); 136#endif 137 138/* Get the current time from the system clock. 139 140 The function cannot fail. _PyTime_Init() ensures that the system clock 141 works. */ 142PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void); 143 144/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. 145 The clock is not affected by system clock updates. The reference point of 146 the returned value is undefined, so that only the difference between the 147 results of consecutive calls is valid. 148 149 The function cannot fail. _PyTime_Init() ensures that a monotonic clock 150 is available and works. */ 151PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void); 152 153 154/* Structure used by time.get_clock_info() */ 155typedef struct { 156 const char *implementation; 157 int monotonic; 158 int adjustable; 159 double resolution; 160} _Py_clock_info_t; 161 162/* Get the current time from the system clock. 163 * Fill clock information if info is not NULL. 164 * Raise an exception and return -1 on error, return 0 on success. 165 */ 166PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo( 167 _PyTime_t *t, 168 _Py_clock_info_t *info); 169 170/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. 171 The clock is not affected by system clock updates. The reference point of 172 the returned value is undefined, so that only the difference between the 173 results of consecutive calls is valid. 174 175 Fill info (if set) with information of the function used to get the time. 176 177 Return 0 on success, raise an exception and return -1 on error. */ 178PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo( 179 _PyTime_t *t, 180 _Py_clock_info_t *info); 181 182 183/* Initialize time. 184 Return 0 on success, raise an exception and return -1 on error. */ 185PyAPI_FUNC(int) _PyTime_Init(void); 186 187/* Converts a timestamp to the Gregorian time, using the local time zone. 188 Return 0 on success, raise an exception and return -1 on error. */ 189PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm); 190 191/* Converts a timestamp to the Gregorian time, assuming UTC. 192 Return 0 on success, raise an exception and return -1 on error. */ 193PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm); 194 195#ifdef __cplusplus 196} 197#endif 198 199#endif /* Py_PYTIME_H */ 200#endif /* Py_LIMITED_API */ 201