1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in 12 * the documentation and/or other materials provided with the 13 * distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 18 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 19 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 22 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 25 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #pragma once 30 31 /** 32 * @file time.h 33 * @brief Clock and timer functionality. 34 */ 35 36 #include <sys/cdefs.h> 37 #include <sys/time.h> 38 #include <xlocale.h> 39 40 __BEGIN_DECLS 41 42 /* If we just use void* in the typedef, the compiler exposes that in error messages. */ 43 struct __timezone_t; 44 45 /** 46 * The `timezone_t` type that represents a timezone. 47 * 48 * To use this with std::unique_ptr you'll want something like 49 * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};` 50 * to remove the pointer. 51 */ 52 typedef struct __timezone_t* timezone_t; 53 54 /** Divisor to compute seconds from the result of a call to clock(). */ 55 #define CLOCKS_PER_SEC 1000000 56 57 /** 58 * The name of the current timezone's non-daylight savings (`tzname[0]`) and 59 * daylight savings (`tzname[1]`) variants. See tzset(). 60 */ 61 extern char* _Nonnull tzname[]; 62 63 /** Whether the current timezone ever uses daylight savings time. See tzset(). */ 64 extern int daylight; 65 66 /** The difference in seconds between UTC and the current timezone. See tzset(). */ 67 extern long int timezone; 68 69 struct sigevent; 70 71 /** 72 * A "broken-down" time, useful for parsing/formatting times for human consumption. 73 */ 74 struct tm { 75 /** Seconds, 0-60. (60 is a leap second.) */ 76 int tm_sec; 77 /** Minutes, 0-59. */ 78 int tm_min; 79 /** Hours, 0-23. */ 80 int tm_hour; 81 /** Day of month, 1-31. */ 82 int tm_mday; 83 /** Month of year, 0-11. (Not 1-12!) */ 84 int tm_mon; 85 /** Years since 1900. (So 2023 is 123, not 2023!) */ 86 int tm_year; 87 /** Day of week, 0-6. (Sunday is 0, Saturday is 6.) */ 88 int tm_wday; 89 /** Day of year, 0-365. */ 90 int tm_yday; 91 /** Daylight savings flag, positive for DST in effect, 0 for DST not in effect, and -1 for unknown. */ 92 int tm_isdst; 93 /** Offset from UTC (GMT) in seconds for this time. */ 94 long int tm_gmtoff; 95 /** Name of the timezone for this time. */ 96 const char* _Nullable tm_zone; 97 }; 98 99 /** Alternative name for `tm_zone` in `struct tm`. */ 100 #define TM_ZONE tm_zone 101 102 /** 103 * [time(2)](http://man7.org/linux/man-pages/man2/time.2.html) returns 104 * the number of seconds since the Unix epoch (1970-01-01 00:00:00 +0000). 105 * 106 * Returns the time in seconds on success, and returns -1 and sets `errno` on failure. 107 */ 108 time_t time(time_t* _Nullable __t); 109 110 /** 111 * [nanosleep(2)](http://man7.org/linux/man-pages/man2/nanosleep.2.html) sleeps 112 * for at least the given time (or until a signal arrives). 113 * 114 * Returns 0 on success, and returns -1 and sets `errno` on failure. If the sleep 115 * was interrupted by a signal, `errno` will be `EINTR` and `remainder` will be 116 * the amount of time remaining. 117 */ 118 int nanosleep(const struct timespec* _Nonnull __duration, struct timespec* _Nullable __remainder); 119 120 /** 121 * [asctime(3)](http://man7.org/linux/man-pages/man3/asctime.3p.html) formats 122 * the time `tm` as a string. 123 * 124 * Returns a pointer to a string on success, and returns NULL on failure. 125 * 126 * That string will be overwritten by later calls to this function. 127 * 128 * New code should prefer strftime(). 129 */ 130 char* _Nullable asctime(const struct tm* _Nonnull __tm); 131 132 /** 133 * [asctime_r(3)](http://man7.org/linux/man-pages/man3/asctime_r.3p.html) formats 134 * the time `tm` as a string in the given buffer `buf`. 135 * 136 * Returns a pointer to a string on success, and returns NULL on failure. 137 * 138 * New code should prefer strftime(). 139 */ 140 char* _Nullable asctime_r(const struct tm* _Nonnull __tm, char* _Nonnull __buf); 141 142 /** 143 * [difftime(3)](http://man7.org/linux/man-pages/man3/difftime.3.html) returns 144 * the difference between two times. 145 * 146 * Returns the difference in seconds. 147 */ 148 double difftime(time_t __lhs, time_t __rhs); 149 150 /** 151 * [mktime(3)](http://man7.org/linux/man-pages/man3/mktime.3p.html) converts 152 * broken-down time `tm` into the number of seconds since the Unix epoch. 153 * 154 * See tzset() for details of how the timezone is set, and mktime_rz() 155 * for an alternative. 156 * 157 * Returns the time in seconds on success, and returns -1 and sets `errno` on failure. 158 */ 159 time_t mktime(struct tm* _Nonnull __tm); 160 161 /** 162 * mktime_z(3) converts broken-down time `tm` into the number of seconds 163 * since the Unix epoch, assuming the given timezone. 164 * 165 * Returns the time in seconds on success, and returns -1 and sets `errno` on failure. 166 * 167 * Available since API level 35. 168 */ 169 time_t mktime_z(timezone_t _Nonnull __tz, struct tm* _Nonnull __tm) __INTRODUCED_IN(35); 170 171 /** 172 * [localtime(3)](http://man7.org/linux/man-pages/man3/localtime.3p.html) converts 173 * the number of seconds since the Unix epoch in `t` to a broken-down time, taking 174 * the device's timezone into account. 175 * 176 * That broken-down time will be overwritten by later calls to this function. 177 * 178 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 179 */ 180 struct tm* _Nullable localtime(const time_t* _Nonnull __t); 181 182 /** 183 * [localtime_r(3)](http://man7.org/linux/man-pages/man3/localtime_r.3p.html) converts 184 * the number of seconds since the Unix epoch in `t` to a broken-down time. 185 * That broken-down time will be written to the given struct `tm`. 186 * 187 * See tzset() for details of how the timezone is set, and localtime_rz() 188 * for an alternative. 189 * 190 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 191 */ 192 struct tm* _Nullable localtime_r(const time_t* _Nonnull __t, struct tm* _Nonnull __tm); 193 194 /** 195 * localtime_rz(3) converts the number of seconds since the Unix epoch in 196 * `t` to a broken-down time, assuming the given timezone. That broken-down 197 * time will be written to the given struct `tm`. 198 * 199 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 200 * 201 * Available since API level 35. 202 */ 203 struct tm* _Nullable localtime_rz(timezone_t _Nonnull __tz, const time_t* _Nonnull __t, struct tm* _Nonnull __tm) __INTRODUCED_IN(35); 204 205 /** 206 * Inverse of localtime(). 207 */ 208 time_t timelocal(struct tm* _Nonnull __tm); 209 210 /** 211 * [gmtime(3)](http://man7.org/linux/man-pages/man3/gmtime.3p.html) converts 212 * the number of seconds since the Unix epoch in `t` to a broken-down time, using 213 * UTC (historically also known as GMT). 214 * 215 * That broken-down time will be overwritten by later calls to this function. 216 * 217 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 218 */ 219 struct tm* _Nullable gmtime(const time_t* _Nonnull __t); 220 221 /** 222 * [gmtime_r(3)](http://man7.org/linux/man-pages/man3/gmtime_r.3p.html) converts 223 * the number of seconds since the Unix epoch in `t` to a broken-down time, using 224 * UTC (historically also known as GMT). 225 * 226 * That broken-down time will be written to the provided struct `tm`. 227 * 228 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 229 */ 230 struct tm* _Nullable gmtime_r(const time_t* _Nonnull __t, struct tm* _Nonnull __tm); 231 232 /** 233 * Inverse of gmtime(). 234 */ 235 time_t timegm(struct tm* _Nonnull __tm); 236 237 /** 238 * [strptime(3)](http://man7.org/linux/man-pages/man3/strptime.3.html) parses 239 * a string `s` assuming format `fmt` into broken-down time `tm`. 240 * 241 * Returns a pointer to the first character _not_ parsed, or null if no characters were parsed. 242 */ 243 char* _Nullable strptime(const char* _Nonnull __s, const char* _Nonnull __fmt, struct tm* _Nonnull __tm) __strftimelike(2); 244 245 /** 246 * Equivalent to strptime() on Android where only C/POSIX locales are available. 247 */ 248 char* _Nullable strptime_l(const char* _Nonnull __s, const char* _Nonnull __fmt, struct tm* _Nonnull __tm, locale_t _Nonnull __l) __strftimelike(2) __INTRODUCED_IN(28); 249 250 /** 251 * [strftime(3)](http://man7.org/linux/man-pages/man3/strftime.3.html) formats 252 * a broken-down time `tm` into the buffer `buf` using format `fmt`. 253 * 254 * Returns a pointer to the first character _not_ parsed, or null if no characters were parsed. 255 */ 256 size_t strftime(char* _Nonnull __buf, size_t __n, const char* _Nonnull __fmt, const struct tm* _Nullable __tm) __strftimelike(3); 257 258 /** 259 * Equivalent to strftime() on Android where only C/POSIX locales are available. 260 */ 261 size_t strftime_l(char* _Nonnull __buf, size_t __n, const char* _Nonnull __fmt, const struct tm* _Nullable __tm, locale_t _Nonnull __l) __strftimelike(3); 262 263 /** 264 * [ctime(3)](http://man7.org/linux/man-pages/man3/ctime.3p.html) formats 265 * the time `tm` as a string. 266 * 267 * Returns a pointer to a string on success, and returns NULL on failure. 268 * 269 * That string will be overwritten by later calls to this function. 270 * 271 * New code should prefer strftime(). 272 */ 273 char* _Nullable ctime(const time_t* _Nonnull __t); 274 275 /** 276 * [ctime_r(3)](http://man7.org/linux/man-pages/man3/ctime.3p.html) formats 277 * the time `tm` as a string in the given buffer `buf`. 278 * 279 * Returns a pointer to a string on success, and returns NULL on failure. 280 * 281 * New code should prefer strftime(). 282 */ 283 char* _Nullable ctime_r(const time_t* _Nonnull __t, char* _Nonnull __buf); 284 285 /** 286 * [tzset(3)](http://man7.org/linux/man-pages/man3/tzset.3.html) tells 287 * libc that the timezone has changed. 288 * 289 * tzset() on Android looks at both the system property 290 * `persist.sys.timezone` and the environment variable `TZ`. The former is 291 * the device's current timezone as shown in Settings, while the latter is 292 * usually unset but can be used to override the global setting. This is a 293 * bad idea outside of unit tests or single-threaded programs because it's 294 * inherently thread-unsafe. See tzalloc(), localtime_rz(), mktime_z(), 295 * and tzfree() for an alternative. 296 */ 297 void tzset(void); 298 299 /** 300 * tzalloc(3) allocates a timezone corresponding to the given Olson ID. 301 * 302 * A null `id` returns the system timezone (as seen in Settings) from 303 * the system property `persist.sys.timezone`, ignoring `$TZ`. Although 304 * tzset() honors `$TZ`, callers of tzalloc() can use `$TZ` themselves if 305 * that's the (thread-unsafe) behavior they want, but by ignoring `$TZ` 306 * tzalloc() is thread safe (though obviously the system timezone can 307 * change, especially if your mobile device is actually mobile!). 308 * 309 * To use this with std::unique_ptr you'll want something like 310 * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};` 311 * to remove the pointer. 312 * 313 * Returns a timezone object on success, and returns NULL and sets `errno` on failure. 314 * 315 * Available since API level 35. 316 */ 317 timezone_t _Nullable tzalloc(const char* _Nullable __id) __INTRODUCED_IN(35); 318 319 /** 320 * tzfree(3) frees a timezone object returned by tzalloc(). 321 * 322 * To use this with std::unique_ptr you'll want something like 323 * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};` 324 * to remove the pointer. 325 * 326 * Available since API level 35. 327 */ 328 void tzfree(timezone_t _Nullable __tz) __INTRODUCED_IN(35); 329 330 /** 331 * [clock(3)](http://man7.org/linux/man-pages/man3/clock.3.html) 332 * returns an approximation of CPU time used, equivalent to 333 * `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)` but with more confusing 334 * units. Use `CLOCKS_PER_SEC` to convert the result to seconds. 335 * 336 * Returns the time in seconds on success, and returns -1 and sets `errno` on failure. 337 * 338 * New code should prefer `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)`. 339 */ 340 clock_t clock(void); 341 342 /** 343 * [clock_getcpuclockid(3)](http://man7.org/linux/man-pages/man3/clock_getcpuclockid.3.html) 344 * gets the clock ID of the cpu-time clock for the given `pid`. 345 * 346 * Returns 0 on success, and returns -1 and returns an error number on failure. 347 */ 348 int clock_getcpuclockid(pid_t __pid, clockid_t* _Nonnull __clock) __INTRODUCED_IN(23); 349 350 /** 351 * [clock_getres(2)](http://man7.org/linux/man-pages/man2/clock_getres.2.html) 352 * gets the resolution of the given clock. 353 * 354 * Returns 0 on success, and returns -1 and returns an error number on failure. 355 */ 356 int clock_getres(clockid_t __clock, struct timespec* _Nullable __resolution); 357 358 /** 359 * [clock_gettime(2)](http://man7.org/linux/man-pages/man2/clock_gettime.2.html) 360 * gets the time according to the given clock. 361 * 362 * Returns 0 on success, and returns -1 and returns an error number on failure. 363 */ 364 int clock_gettime(clockid_t __clock, struct timespec* _Nonnull __ts); 365 366 /** 367 * [clock_nanosleep(2)](http://man7.org/linux/man-pages/man2/clock_nanosleep.2.html) 368 * sleeps for the given time (or until the given time if the TIMER_ABSTIME flag 369 * is used), as measured by the given clock. 370 * 371 * Returns 0 on success, and returns -1 and returns an error number on failure. 372 * If the sleep was interrupted by a signal, the return value will be `EINTR` 373 * and `remainder` will be the amount of time remaining. 374 */ 375 int clock_nanosleep(clockid_t __clock, int __flags, const struct timespec* _Nonnull __time, struct timespec* _Nullable __remainder); 376 377 /** 378 * [clock_settime(2)](http://man7.org/linux/man-pages/man2/clock_settime.2.html) 379 * sets the time for the given clock. 380 * 381 * Returns 0 on success, and returns -1 and returns an error number on failure. 382 */ 383 int clock_settime(clockid_t __clock, const struct timespec* _Nonnull __ts); 384 385 /** 386 * [timer_create(2)](http://man7.org/linux/man-pages/man2/timer_create.2.html) 387 * creates a POSIX timer. 388 * 389 * Returns 0 on success, and returns -1 and sets `errno` on failure. 390 */ 391 int timer_create(clockid_t __clock, struct sigevent* _Nullable __event, timer_t _Nonnull * _Nonnull __timer_ptr); 392 393 /** 394 * [timer_delete(2)](http://man7.org/linux/man-pages/man2/timer_delete.2.html) 395 * destroys a POSIX timer. 396 * 397 * Returns 0 on success, and returns -1 and sets `errno` on failure. 398 */ 399 int timer_delete(timer_t _Nonnull __timer); 400 401 /** 402 * [timer_settime(2)](http://man7.org/linux/man-pages/man2/timer_settime.2.html) 403 * starts or stops a POSIX timer. 404 * 405 * Returns 0 on success, and returns -1 and sets `errno` on failure. 406 */ 407 int timer_settime(timer_t _Nonnull __timer, int __flags, const struct itimerspec* _Nonnull __new_value, struct itimerspec* _Nullable __old_value); 408 409 /** 410 * [timer_gettime(2)](http://man7.org/linux/man-pages/man2/timer_gettime.2.html) 411 * gets the time until the given timer next fires. 412 * 413 * Returns 0 on success, and returns -1 and sets `errno` on failure. 414 */ 415 int timer_gettime(timer_t _Nonnull _timer, struct itimerspec* _Nonnull __ts); 416 417 /** 418 * [timer_getoverrun(2)](http://man7.org/linux/man-pages/man2/timer_getoverrun.2.html) 419 * gets the overrun count (the number of times the timer should have fired, but 420 * didn't) for the last time the timer fired. 421 * 422 * Returns the overrun count on success, and returns -1 and sets `errno` on failure. 423 */ 424 int timer_getoverrun(timer_t _Nonnull __timer); 425 426 /** 427 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_REALTIME. 428 * 429 * Available since API level 29. 430 */ 431 #define TIME_UTC (CLOCK_REALTIME+1) 432 433 /** 434 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_MONOTONIC. 435 * 436 * Available since API level 35. 437 */ 438 #define TIME_MONOTONIC (CLOCK_MONOTONIC+1) 439 440 /** 441 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_PROCESS_CPUTIME_ID. 442 * 443 * Available since API level 35. 444 */ 445 #define TIME_ACTIVE (CLOCK_PROCESS_CPUTIME_ID+1) 446 447 /** 448 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_THREAD_CPUTIME_ID. 449 * 450 * Available since API level 35. 451 */ 452 #define TIME_THREAD_ACTIVE (CLOCK_THREAD_CPUTIME_ID+1) 453 454 /** 455 * timespec_get(3) is equivalent to clock_gettime() for the clock corresponding to the given base. 456 * 457 * Returns the base on success and returns 0 on failure. 458 * 459 * Available since API level 29 for TIME_UTC; other bases arrived later. 460 * Code for Android should prefer clock_gettime(). 461 */ 462 int timespec_get(struct timespec* _Nonnull __ts, int __base) __INTRODUCED_IN(29); 463 464 /** 465 * timespec_getres(3) is equivalent to clock_getres() for the clock corresponding to the given base. 466 * 467 * Returns the base on success and returns 0 on failure. 468 * 469 * Available since API level 35. 470 * Code for Android should prefer clock_gettime(). 471 */ 472 int timespec_getres(struct timespec* _Nonnull __ts, int __base) __INTRODUCED_IN(35); 473 474 __END_DECLS 475