Debian Codegraph @

src/basic/time-util.h

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2 #pragma once
3
4 #include <limits.h>
5 #include <time.h>
6
7 #include "basic-forward.h"
8
9 #define PRI_NSEC PRIu64
10 #define PRI_USEC PRIu64
11 #define NSEC_FMT "%" PRI_NSEC
12 #define USEC_FMT "%" PRI_USEC
13
14 typedef struct dual_timestamp {
15 usec_t realtime;
16 usec_t monotonic;
17 } dual_timestamp;
18
19 typedef struct triple_timestamp {
20 usec_t realtime;
21 usec_t monotonic;
22 usec_t boottime;
23 } triple_timestamp;
24
25 typedef enum TimestampStyle {
26 TIMESTAMP_PRETTY,
27 TIMESTAMP_US,
28 TIMESTAMP_UTC,
29 TIMESTAMP_US_UTC,
30 TIMESTAMP_UNIX,
31 TIMESTAMP_DATE,
32 _TIMESTAMP_STYLE_MAX,
33 _TIMESTAMP_STYLE_INVALID = -EINVAL,
34 } TimestampStyle;
35
36 #define USEC_INFINITY ((usec_t) UINT64_MAX)
37 #define NSEC_INFINITY ((nsec_t) UINT64_MAX)
38
39 #define MSEC_PER_SEC 1000ULL
40 #define USEC_PER_SEC ((usec_t) 1000000ULL)
41 #define USEC_PER_MSEC ((usec_t) 1000ULL)
42 #define NSEC_PER_SEC ((nsec_t) 1000000000ULL)
43 #define NSEC_PER_MSEC ((nsec_t) 1000000ULL)
44 #define NSEC_PER_USEC ((nsec_t) 1000ULL)
45
46 #define USEC_PER_MINUTE ((usec_t) (60ULL*USEC_PER_SEC))
47 #define NSEC_PER_MINUTE ((nsec_t) (60ULL*NSEC_PER_SEC))
48 #define USEC_PER_HOUR ((usec_t) (60ULL*USEC_PER_MINUTE))
49 #define NSEC_PER_HOUR ((nsec_t) (60ULL*NSEC_PER_MINUTE))
50 #define USEC_PER_DAY ((usec_t) (24ULL*USEC_PER_HOUR))
51 #define NSEC_PER_DAY ((nsec_t) (24ULL*NSEC_PER_HOUR))
52 #define USEC_PER_WEEK ((usec_t) (7ULL*USEC_PER_DAY))
53 #define NSEC_PER_WEEK ((nsec_t) (7ULL*NSEC_PER_DAY))
54 #define USEC_PER_MONTH ((usec_t) (2629800ULL*USEC_PER_SEC))
55 #define NSEC_PER_MONTH ((nsec_t) (2629800ULL*NSEC_PER_SEC))
56 #define USEC_PER_YEAR ((usec_t) (31557600ULL*USEC_PER_SEC))
57 #define NSEC_PER_YEAR ((nsec_t) (31557600ULL*NSEC_PER_SEC))
58
59 /* We assume a maximum timezone length of 6. TZNAME_MAX is not defined on Linux, but glibc internally initializes this
60 * to 6. Let's rely on that. */
61 #define FORMAT_TIMESTAMP_MAX (3U+1U+10U+1U+8U+1U+6U+1U+6U+1U)
62 #define FORMAT_TIMESTAMP_RELATIVE_MAX 256U
63 #define FORMAT_TIMESPAN_MAX 64U
64
65 #define TIME_T_MAX (time_t)((UINTMAX_C(1) << ((sizeof(time_t) << 3) - 1)) - 1)
66
67 #define DUAL_TIMESTAMP_NULL ((dual_timestamp) {})
68 #define DUAL_TIMESTAMP_INFINITY ((dual_timestamp) { USEC_INFINITY, USEC_INFINITY })
69 #define TRIPLE_TIMESTAMP_NULL ((triple_timestamp) {})
70
71 #define TIMESPEC_OMIT ((const struct timespec) { .tv_nsec = UTIME_OMIT })
72
73 usec_t now(clockid_t clock);
74 nsec_t now_nsec(clockid_t clock);
75
76 usec_t map_clock_usec_raw(usec_t from, usec_t from_base, usec_t to_base);
77 usec_t map_clock_usec(usec_t from, clockid_t from_clock, clockid_t to_clock);
78
79 dual_timestamp* dual_timestamp_now(dual_timestamp *ts);
80 dual_timestamp* dual_timestamp_from_realtime(dual_timestamp *ts, usec_t u);
81 dual_timestamp* dual_timestamp_from_monotonic(dual_timestamp *ts, usec_t u);
82 dual_timestamp* dual_timestamp_from_boottime(dual_timestamp *ts, usec_t u);
83
84 triple_timestamp* triple_timestamp_now(triple_timestamp *ts);
85 triple_timestamp* triple_timestamp_from_realtime(triple_timestamp *ts, usec_t u);
86 triple_timestamp* triple_timestamp_from_boottime(triple_timestamp *ts, usec_t u);
87
88 #define DUAL_TIMESTAMP_HAS_CLOCK(clock) \
89 IN_SET(clock, CLOCK_REALTIME, CLOCK_REALTIME_ALARM, CLOCK_MONOTONIC)
90
91 #define TRIPLE_TIMESTAMP_HAS_CLOCK(clock) \
92 IN_SET(clock, CLOCK_REALTIME, CLOCK_REALTIME_ALARM, CLOCK_MONOTONIC, CLOCK_BOOTTIME, CLOCK_BOOTTIME_ALARM)
93
94 static inline bool timestamp_is_set(usec_t timestamp) {
95 return timestamp > 0 && timestamp != USEC_INFINITY;
96 }
97
98 static inline bool dual_timestamp_is_set(const dual_timestamp *ts) {
99 return timestamp_is_set(ts->realtime) ||
100 timestamp_is_set(ts->monotonic);
101 }
102
103 static inline bool triple_timestamp_is_set(const triple_timestamp *ts) {
104 return timestamp_is_set(ts->realtime) ||
105 timestamp_is_set(ts->monotonic) ||
106 timestamp_is_set(ts->boottime);
107 }
108
109 usec_t triple_timestamp_by_clock(triple_timestamp *ts, clockid_t clock);
110
111 usec_t timespec_load(const struct timespec *ts) _pure_;
112 nsec_t timespec_load_nsec(const struct timespec *ts) _pure_;
113 struct timespec* timespec_store(struct timespec *ts, usec_t u);
114 struct timespec* timespec_store_nsec(struct timespec *ts, nsec_t n);
115
116 #define TIMESPEC_STORE(u) timespec_store(&(struct timespec) {}, (u))
117 #define TIMESPEC_STORE_NSEC(n) timespec_store_nsec(&(struct timespec) {}, (n))
118
119 usec_t timeval_load(const struct timeval *tv) _pure_;
120 struct timeval* timeval_store(struct timeval *tv, usec_t u);
121
122 #define TIMEVAL_STORE(u) timeval_store(&(struct timeval) {}, (u))
123
124 char* format_timestamp_style(char *buf, size_t l, usec_t t, TimestampStyle style) _warn_unused_result_;
125 char* format_timestamp_relative_full(char *buf, size_t l, usec_t t, clockid_t clock, bool implicit_left) _warn_unused_result_;
126 char* format_timespan(char *buf, size_t l, usec_t t, usec_t accuracy) _warn_unused_result_;
127
128 _warn_unused_result_
129 static inline char* format_timestamp_relative(char *buf, size_t l, usec_t t) {
130 return format_timestamp_relative_full(buf, l, t, CLOCK_REALTIME, /* implicit_left= */ false);
131 }
132 _warn_unused_result_
133 static inline char* format_timestamp_relative_monotonic(char *buf, size_t l, usec_t t) {
134 return format_timestamp_relative_full(buf, l, t, CLOCK_MONOTONIC, /* implicit_left= */ false);
135 }
136
137 _warn_unused_result_
138 static inline char* format_timestamp(char *buf, size_t l, usec_t t) {
139 return format_timestamp_style(buf, l, t, TIMESTAMP_PRETTY);
140 }
141
142 /* Note: the lifetime of the compound literal is the immediately surrounding block,
143 * see C11 §6.5.2.5, and
144 * https://stackoverflow.com/questions/34880638/compound-literal-lifetime-and-if-blocks */
145 #define FORMAT_TIMESTAMP(t) format_timestamp((char[FORMAT_TIMESTAMP_MAX]){}, FORMAT_TIMESTAMP_MAX, t)
146 #define FORMAT_TIMESTAMP_RELATIVE(t) \
147 format_timestamp_relative((char[FORMAT_TIMESTAMP_RELATIVE_MAX]){}, FORMAT_TIMESTAMP_RELATIVE_MAX, t)
148 #define FORMAT_TIMESTAMP_RELATIVE_MONOTONIC(t) \
149 format_timestamp_relative_monotonic((char[FORMAT_TIMESTAMP_RELATIVE_MAX]){}, FORMAT_TIMESTAMP_RELATIVE_MAX, t)
150 #define FORMAT_TIMESPAN(t, accuracy) format_timespan((char[FORMAT_TIMESPAN_MAX]){}, FORMAT_TIMESPAN_MAX, t, accuracy)
151 #define FORMAT_TIMESTAMP_STYLE(t, style) \
152 format_timestamp_style((char[FORMAT_TIMESTAMP_MAX]){}, FORMAT_TIMESTAMP_MAX, t, style)
153
154 const char* get_tzname(bool dst);
155 int parse_gmtoff(const char *t, long *ret);
156 int parse_timestamp(const char *t, usec_t *ret);
157
158 int parse_sec(const char *t, usec_t *ret);
159 int parse_sec_fix_0(const char *t, usec_t *ret);
160 int parse_sec_def_infinity(const char *t, usec_t *ret);
161 int parse_time(const char *t, usec_t *ret, usec_t default_unit);
162 int parse_nsec(const char *t, nsec_t *ret);
163
164 int get_timezones(char ***ret);
165 int verify_timezone(const char *name, int log_level);
166 static inline bool timezone_is_valid(const char *name, int log_level) {
167 return verify_timezone(name, log_level) >= 0;
168 }
169
170 void reset_timezonep(char **p);
171 char* save_timezone(void);
172 #define SAVE_TIMEZONE \
173 _unused_ _cleanup_(reset_timezonep) \
174 char *_saved_timezone_ = save_timezone()
175
176 bool clock_supported(clockid_t clock);
177
178 usec_t usec_shift_clock(usec_t x, clockid_t from, clockid_t to);
179
180 int get_timezone(char **ret);
181 int get_timezone_prefer_env(char **ret);
182 const char* etc_localtime(void);
183
184 int mktime_or_timegm_usec(struct tm *tm, bool utc, usec_t *ret);
185 int localtime_or_gmtime_usec(usec_t t, bool utc, struct tm *ret);
186
187 int parse_calendar_date_full(const char *s, bool allow_pre_epoch, usec_t *ret_usec, struct tm *ret_tm);
188
189 static inline int parse_calendar_date(const char *s, usec_t *ret) {
190 return parse_calendar_date_full(s, /* allow_pre_epoch= */ false, ret, NULL);
191 }
192
193 #define BIRTH_DATE_UNSET \
194 (const struct tm) { \
195 .tm_year = INT_MIN, \
196 }
197
198 #define BIRTH_DATE_IS_SET(tm) ((tm).tm_year != INT_MIN)
199
200 static inline int parse_birth_date(const char *s, struct tm *ret) {
201 return parse_calendar_date_full(s, /* allow_pre_epoch= */ true, NULL, ret);
202 }
203
204 uint32_t usec_to_jiffies(usec_t usec);
205 usec_t jiffies_to_usec(uint32_t jiffies);
206
207 bool in_utc_timezone(void);
208
209 static inline usec_t usec_add(usec_t a, usec_t b) {
210 /* Adds two time values, and makes sure USEC_INFINITY as input results as USEC_INFINITY in output,
211 * and doesn't overflow. */
212 return saturate_add(a, b, USEC_INFINITY);
213 }
214
215 static inline usec_t usec_sub_unsigned(usec_t timestamp, usec_t delta) {
216 if (timestamp == USEC_INFINITY) /* Make sure infinity doesn't degrade */
217 return USEC_INFINITY;
218 if (timestamp < delta)
219 return 0;
220
221 return timestamp - delta;
222 }
223
224 static inline usec_t usec_sub_signed(usec_t timestamp, int64_t delta) {
225 if (delta == INT64_MIN) { /* prevent overflow */
226 assert_cc(-(INT64_MIN + 1) == INT64_MAX);
227 assert_cc(USEC_INFINITY > INT64_MAX);
228 return usec_add(timestamp, (usec_t) INT64_MAX + 1);
229 }
230 if (delta < 0)
231 return usec_add(timestamp, (usec_t) (-delta));
232
233 return usec_sub_unsigned(timestamp, (usec_t) delta);
234 }
235
236 int usleep_safe(usec_t usec);
237
238 /* The last second we can format is 31. Dec 9999, 1s before midnight, because otherwise we'd enter 5 digit
239 * year territory. However, since we want to stay away from this in all timezones we take one day off. */
240 #define USEC_TIMESTAMP_FORMATTABLE_MAX_64BIT ((usec_t) 253402214399000000) /* Thu 9999-12-30 23:59:59 UTC */
241 /* With a 32-bit time_t we can't go beyond 2038...
242 * We parse timestamp with RFC-822/ISO 8601 (e.g. +06, or -03:00) as UTC, hence the upper bound must be off
243 * by USEC_PER_DAY. See parse_timestamp() for more details. */
244 #define USEC_TIMESTAMP_FORMATTABLE_MAX_32BIT (((usec_t) INT32_MAX) * USEC_PER_SEC - USEC_PER_DAY)
245 #if SIZEOF_TIME_T == 8
246 # define USEC_TIMESTAMP_FORMATTABLE_MAX USEC_TIMESTAMP_FORMATTABLE_MAX_64BIT
247 #elif SIZEOF_TIME_T == 4
248 # define USEC_TIMESTAMP_FORMATTABLE_MAX USEC_TIMESTAMP_FORMATTABLE_MAX_32BIT
249 #else
250 # error "Yuck, time_t is neither 4 nor 8 bytes wide?"
251 #endif
252
253 int time_change_fd(void);
254
255 DECLARE_STRING_TABLE_LOOKUP(timestamp_style, TimestampStyle);