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