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 /************************************************************************** 9 Symbols and macros to supply platform-independent interfaces to time related 10 functions and constants 11 **************************************************************************/ 12 #ifdef __cplusplus 13 extern "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). */ 19 typedef int64_t _PyTime_t; 20 #define _PyTime_MIN PY_LLONG_MIN 21 #define _PyTime_MAX PY_LLONG_MAX 22 23 typedef 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. */ 36 PyAPI_FUNC(PyObject *) _PyLong_FromTime_t( 37 time_t sec); 38 39 /* Convert a PyLong to a time_t. */ 40 PyAPI_FUNC(time_t) _PyLong_AsTime_t( 41 PyObject *obj); 42 43 /* Convert a number of seconds, int or float, to time_t. */ 44 PyAPI_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). */ 52 PyAPI_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). */ 61 PyAPI_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. */ 69 PyAPI_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. */ 77 PyAPI_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. */ 81 PyAPI_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. */ 87 PyAPI_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. */ 92 PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t); 93 94 /* Convert timestamp to a number of milliseconds (10^-3 seconds). */ 95 PyAPI_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). */ 99 PyAPI_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. */ 104 PyAPI_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. */ 110 PyAPI_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. */ 115 PyAPI_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. */ 125 PyAPI_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. */ 135 PyAPI_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. */ 142 PyAPI_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. */ 151 PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void); 152 153 154 /* Structure used by time.get_clock_info() */ 155 typedef 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 */ 166 PyAPI_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. */ 178 PyAPI_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. */ 185 PyAPI_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. */ 189 PyAPI_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. */ 193 PyAPI_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