src/basic/time-util.h

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