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)](https://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)](https://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)](https://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)](https://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)](https://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)](https://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 170 #if __BIONIC_AVAILABILITY_GUARD(35) 171 time_t mktime_z(timezone_t _Nonnull __tz, struct tm* _Nonnull __tm) __INTRODUCED_IN(35); 172 #endif /* __BIONIC_AVAILABILITY_GUARD(35) */ 173 174 175 /** 176 * [localtime(3)](https://man7.org/linux/man-pages/man3/localtime.3p.html) converts 177 * the number of seconds since the Unix epoch in `t` to a broken-down time, taking 178 * the device's timezone into account. 179 * 180 * That broken-down time will be overwritten by later calls to this function. 181 * 182 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 183 */ 184 struct tm* _Nullable localtime(const time_t* _Nonnull __t); 185 186 /** 187 * [localtime_r(3)](https://man7.org/linux/man-pages/man3/localtime_r.3p.html) converts 188 * the number of seconds since the Unix epoch in `t` to a broken-down time. 189 * That broken-down time will be written to the given struct `tm`. 190 * 191 * See tzset() for details of how the timezone is set, and localtime_rz() 192 * for an alternative. 193 * 194 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 195 */ 196 struct tm* _Nullable localtime_r(const time_t* _Nonnull __t, struct tm* _Nonnull __tm); 197 198 /** 199 * localtime_rz(3) converts the number of seconds since the Unix epoch in 200 * `t` to a broken-down time, assuming the given timezone. That broken-down 201 * time will be written to the given struct `tm`. 202 * 203 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 204 * 205 * Available since API level 35. 206 */ 207 208 #if __BIONIC_AVAILABILITY_GUARD(35) 209 struct tm* _Nullable localtime_rz(timezone_t _Nonnull __tz, const time_t* _Nonnull __t, struct tm* _Nonnull __tm) __INTRODUCED_IN(35); 210 #endif /* __BIONIC_AVAILABILITY_GUARD(35) */ 211 212 213 /** 214 * Inverse of localtime(). 215 */ 216 time_t timelocal(struct tm* _Nonnull __tm); 217 218 /** 219 * [gmtime(3)](https://man7.org/linux/man-pages/man3/gmtime.3p.html) converts 220 * the number of seconds since the Unix epoch in `t` to a broken-down time, using 221 * UTC (historically also known as GMT). 222 * 223 * That broken-down time will be overwritten by later calls to this function. 224 * 225 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 226 */ 227 struct tm* _Nullable gmtime(const time_t* _Nonnull __t); 228 229 /** 230 * [gmtime_r(3)](https://man7.org/linux/man-pages/man3/gmtime_r.3p.html) converts 231 * the number of seconds since the Unix epoch in `t` to a broken-down time, using 232 * UTC (historically also known as GMT). 233 * 234 * That broken-down time will be written to the provided struct `tm`. 235 * 236 * Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure. 237 */ 238 struct tm* _Nullable gmtime_r(const time_t* _Nonnull __t, struct tm* _Nonnull __tm); 239 240 /** 241 * Inverse of gmtime(). 242 */ 243 time_t timegm(struct tm* _Nonnull __tm); 244 245 /** 246 * [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html) parses 247 * a string `s` assuming format `fmt` into broken-down time `tm`. 248 * 249 * Returns a pointer to the first character _not_ parsed, or null if no characters were parsed. 250 */ 251 char* _Nullable strptime(const char* _Nonnull __s, const char* _Nonnull __fmt, struct tm* _Nonnull __tm) __strftimelike(2); 252 253 /** 254 * Equivalent to strptime() on Android where only C/POSIX locales are available. 255 */ 256 char* _Nullable strptime_l(const char* _Nonnull __s, const char* _Nonnull __fmt, struct tm* _Nonnull __tm, locale_t _Nonnull __l) __strftimelike(2) __RENAME(strptime); 257 258 /** 259 * [strftime(3)](https://man7.org/linux/man-pages/man3/strftime.3.html) formats 260 * a broken-down time `tm` into the buffer `buf` using format `fmt`. 261 * 262 * Returns a pointer to the first character _not_ parsed, or null if no characters were parsed. 263 */ 264 size_t strftime(char* _Nonnull __buf, size_t __n, const char* _Nonnull __fmt, const struct tm* _Nullable __tm) __strftimelike(3); 265 266 /** 267 * Equivalent to strftime() on Android where only C/POSIX locales are available. 268 */ 269 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); 270 271 /** 272 * [ctime(3)](https://man7.org/linux/man-pages/man3/ctime.3p.html) formats 273 * the time `tm` as a string. 274 * 275 * Returns a pointer to a string on success, and returns NULL on failure. 276 * 277 * That string will be overwritten by later calls to this function. 278 * 279 * New code should prefer strftime(). 280 */ 281 char* _Nullable ctime(const time_t* _Nonnull __t); 282 283 /** 284 * [ctime_r(3)](https://man7.org/linux/man-pages/man3/ctime.3p.html) formats 285 * the time `tm` as a string in the given buffer `buf`. 286 * 287 * Returns a pointer to a string on success, and returns NULL on failure. 288 * 289 * New code should prefer strftime(). 290 */ 291 char* _Nullable ctime_r(const time_t* _Nonnull __t, char* _Nonnull __buf); 292 293 /** 294 * [tzset(3)](https://man7.org/linux/man-pages/man3/tzset.3.html) tells 295 * libc that the timezone has changed. 296 * 297 * tzset() on Android looks at both the system property 298 * `persist.sys.timezone` and the environment variable `TZ`. The former is 299 * the device's current timezone as shown in Settings, while the latter is 300 * usually unset but can be used to override the global setting. This is a 301 * bad idea outside of unit tests or single-threaded programs because it's 302 * inherently thread-unsafe. See tzalloc(), localtime_rz(), mktime_z(), 303 * and tzfree() for an alternative. 304 */ 305 void tzset(void); 306 307 /** 308 * tzalloc(3) allocates a timezone corresponding to the given Olson ID. 309 * 310 * A null `id` returns the system timezone (as seen in Settings) from 311 * the system property `persist.sys.timezone`, ignoring `$TZ`. Although 312 * tzset() honors `$TZ`, callers of tzalloc() can use `$TZ` themselves if 313 * that's the (thread-unsafe) behavior they want, but by ignoring `$TZ` 314 * tzalloc() is thread safe (though obviously the system timezone can 315 * change, especially if your mobile device is actually mobile!). 316 * 317 * To use this with std::unique_ptr you'll want something like 318 * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};` 319 * to remove the pointer. 320 * 321 * Returns a timezone object on success, and returns NULL and sets `errno` on failure. 322 * 323 * Available since API level 35. 324 */ 325 326 #if __BIONIC_AVAILABILITY_GUARD(35) 327 timezone_t _Nullable tzalloc(const char* _Nullable __id) __INTRODUCED_IN(35); 328 329 /** 330 * tzfree(3) frees a timezone object returned by tzalloc(). 331 * 332 * To use this with std::unique_ptr you'll want something like 333 * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};` 334 * to remove the pointer. 335 * 336 * Available since API level 35. 337 */ 338 void tzfree(timezone_t _Nullable __tz) __INTRODUCED_IN(35); 339 #endif /* __BIONIC_AVAILABILITY_GUARD(35) */ 340 341 342 /** 343 * [clock(3)](https://man7.org/linux/man-pages/man3/clock.3.html) 344 * returns an approximation of CPU time used, equivalent to 345 * `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)` but with more confusing 346 * units. Use `CLOCKS_PER_SEC` to convert the result to seconds. 347 * 348 * Returns the time in seconds on success, and returns -1 and sets `errno` on failure. 349 * 350 * New code should prefer `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)`. 351 */ 352 clock_t clock(void); 353 354 /** 355 * [clock_getcpuclockid(3)](https://man7.org/linux/man-pages/man3/clock_getcpuclockid.3.html) 356 * gets the clock ID of the cpu-time clock for the given `pid`. 357 * 358 * Returns 0 on success, and returns -1 and returns an error number on failure. 359 */ 360 361 #if __BIONIC_AVAILABILITY_GUARD(23) 362 int clock_getcpuclockid(pid_t __pid, clockid_t* _Nonnull __clock) __INTRODUCED_IN(23); 363 #endif /* __BIONIC_AVAILABILITY_GUARD(23) */ 364 365 366 /** 367 * [clock_getres(2)](https://man7.org/linux/man-pages/man2/clock_getres.2.html) 368 * gets the resolution of the given clock. 369 * 370 * Returns 0 on success, and returns -1 and returns an error number on failure. 371 */ 372 int clock_getres(clockid_t __clock, struct timespec* _Nullable __resolution); 373 374 /** 375 * [clock_gettime(2)](https://man7.org/linux/man-pages/man2/clock_gettime.2.html) 376 * gets the time according to the given clock. 377 * 378 * Returns 0 on success, and returns -1 and returns an error number on failure. 379 */ 380 int clock_gettime(clockid_t __clock, struct timespec* _Nonnull __ts); 381 382 /** 383 * [clock_nanosleep(2)](https://man7.org/linux/man-pages/man2/clock_nanosleep.2.html) 384 * sleeps for the given time (or until the given time if the TIMER_ABSTIME flag 385 * is used), as measured by the given clock. 386 * 387 * Returns 0 on success, and returns -1 and returns an error number on failure. 388 * If the sleep was interrupted by a signal, the return value will be `EINTR` 389 * and `remainder` will be the amount of time remaining. 390 */ 391 int clock_nanosleep(clockid_t __clock, int __flags, const struct timespec* _Nonnull __time, struct timespec* _Nullable __remainder); 392 393 /** 394 * [clock_settime(2)](https://man7.org/linux/man-pages/man2/clock_settime.2.html) 395 * sets the time for the given clock. 396 * 397 * Returns 0 on success, and returns -1 and returns an error number on failure. 398 */ 399 int clock_settime(clockid_t __clock, const struct timespec* _Nonnull __ts); 400 401 /** 402 * [timer_create(2)](https://man7.org/linux/man-pages/man2/timer_create.2.html) 403 * creates a POSIX timer. 404 * 405 * Returns 0 on success, and returns -1 and sets `errno` on failure. 406 */ 407 int timer_create(clockid_t __clock, struct sigevent* _Nullable __event, timer_t _Nonnull * _Nonnull __timer_ptr); 408 409 /** 410 * [timer_delete(2)](https://man7.org/linux/man-pages/man2/timer_delete.2.html) 411 * destroys a POSIX timer. 412 * 413 * Returns 0 on success, and returns -1 and sets `errno` on failure. 414 */ 415 int timer_delete(timer_t _Nonnull __timer); 416 417 /** 418 * [timer_settime(2)](https://man7.org/linux/man-pages/man2/timer_settime.2.html) 419 * starts or stops a POSIX timer. 420 * 421 * Returns 0 on success, and returns -1 and sets `errno` on failure. 422 */ 423 int timer_settime(timer_t _Nonnull __timer, int __flags, const struct itimerspec* _Nonnull __new_value, struct itimerspec* _Nullable __old_value); 424 425 /** 426 * [timer_gettime(2)](https://man7.org/linux/man-pages/man2/timer_gettime.2.html) 427 * gets the time until the given timer next fires. 428 * 429 * Returns 0 on success, and returns -1 and sets `errno` on failure. 430 */ 431 int timer_gettime(timer_t _Nonnull _timer, struct itimerspec* _Nonnull __ts); 432 433 /** 434 * [timer_getoverrun(2)](https://man7.org/linux/man-pages/man2/timer_getoverrun.2.html) 435 * gets the overrun count (the number of times the timer should have fired, but 436 * didn't) for the last time the timer fired. 437 * 438 * Returns the overrun count on success, and returns -1 and sets `errno` on failure. 439 */ 440 int timer_getoverrun(timer_t _Nonnull __timer); 441 442 /** 443 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_REALTIME. 444 * 445 * Available since API level 29. 446 */ 447 #define TIME_UTC (CLOCK_REALTIME+1) 448 449 /** 450 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_MONOTONIC. 451 * 452 * Available since API level 35. 453 */ 454 #define TIME_MONOTONIC (CLOCK_MONOTONIC+1) 455 456 /** 457 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_PROCESS_CPUTIME_ID. 458 * 459 * Available since API level 35. 460 */ 461 #define TIME_ACTIVE (CLOCK_PROCESS_CPUTIME_ID+1) 462 463 /** 464 * The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_THREAD_CPUTIME_ID. 465 * 466 * Available since API level 35. 467 */ 468 #define TIME_THREAD_ACTIVE (CLOCK_THREAD_CPUTIME_ID+1) 469 470 /** 471 * timespec_get(3) is equivalent to clock_gettime() for the clock corresponding to the given base. 472 * 473 * Returns the base on success and returns 0 on failure. 474 * 475 * Available since API level 29 for TIME_UTC; other bases arrived later. 476 * Code for Android should prefer clock_gettime(). 477 */ 478 479 #if __BIONIC_AVAILABILITY_GUARD(29) 480 int timespec_get(struct timespec* _Nonnull __ts, int __base) __INTRODUCED_IN(29); 481 #endif /* __BIONIC_AVAILABILITY_GUARD(29) */ 482 483 484 /** 485 * timespec_getres(3) is equivalent to clock_getres() for the clock corresponding to the given base. 486 * 487 * Returns the base on success and returns 0 on failure. 488 * 489 * Available since API level 35. 490 * Code for Android should prefer clock_gettime(). 491 */ 492 493 #if __BIONIC_AVAILABILITY_GUARD(35) 494 int timespec_getres(struct timespec* _Nonnull __ts, int __base) __INTRODUCED_IN(35); 495 #endif /* __BIONIC_AVAILABILITY_GUARD(35) */ 496 497 498 __END_DECLS 499