tequilaOS/platform_bionic
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
platform_bionic/libc/include/time.h
Elliott Hughes 2bd4316bd6 Expose tzalloc()/localtime_rz()/mktime_z()/tzfree(). 
* Rationale

The question often comes up of how to use multiple time zones in C code.
If you're single-threaded, you can just use setenv() to manipulate $TZ.
toybox does this, for example. But that's not thread-safe in two
distinct ways: firstly, getenv() is not thread-safe with respect to
modifications to the environment (and between the way putenv() is
specified and the existence of environ, it's not obvious how to fully
fix that), and secondly the _caller_ needs to ensure that no other
threads are using tzset() or any function that behaves "as if" tzset()
was called (which is neither easy to determine nor easy to ensure).

This isn't a bigger problem because most of the time the right answer
is to stop pretending that libc is at all suitable for any i18n, and
switch to icu4c instead. (The NDK icu4c headers do not include ucal_*,
so this is not a realistic option for most applications.)

But what if you're somewhere in between? Like the rust chrono library,
for example? What then?

Currently their "least worst" option is to reinvent the entire wheel and
read our tzdata files. Which isn't a great solution for anyone, for
obvious maintainability reasons.

So it's probably time we broke the catch-22 here and joined NetBSD in
offering a less broken API than standard C has for the last 40 years.
Sure, any would-be caller will have to have a separate "is this
Android?" and even "is this API level >= 35?" path, but that will fix
itself sometime in the 2030s when developers can just assume "yes, it
is", whereas if we keep putting off exposing anything, this problem
never gets solved.

(No-one's bothered to try to implement the std::chrono::time_zone
functionality in libc++ yet, but they'll face a similar problem if/when
they do.)

* Implementation

The good news is that tzcode already implements these functions, so
there's relatively little here.

I've chosen not to expose `struct state` because `struct __timezone_t`
makes for clearer error messages, given that compiler diagnostics will
show the underlying type name (`struct __timezone_t*`) rather than the
typedef name (`timezone_t`) that's used in calling code.

I've moved us over to FreeBSD's wcsftime() rather than keep the OpenBSD
one building --- I've long wanted to only have one implementation here,
and FreeBSD is already doing the "convert back and forth, calling the
non-wide function in the middle" dance that I'd hoped to get round to
doing myself someday. This should mean that our strftime() and
wcsftime() behaviors can't easily diverge in future, plus macOS/iOS are
mostly FreeBSD, so any bugs will likely be interoperable with the other
major mobile operating system, so there's something nice for everyone
there!

The FreeBSD wcsftime() implementation includes a wcsftime_l()
implementation, so that's one stub we can remove. The flip side of that
is that it uses mbsrtowcs_l() and wcsrtombs_l() which we didn't
previously have. So expose those as aliases of mbsrtowcs() and
wcsrtombs().

Bug: https://github.com/chronotope/chrono/issues/499
Test: treehugger
Change-Id: Iee1b9d763ead15eef3d2c33666b3403b68940c3c
2023-06-16 08:10:47 -07:00

452 lines
16 KiB
C
Raw Blame History

/*
* Copyright (C) 2008 The Android Open Source Project
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#pragma once
/**
* @file time.h
* @brief Clock and timer functionality.
*/
#include <sys/cdefs.h>
#include <sys/time.h>
#include <xlocale.h>
__BEGIN_DECLS
/* If we just use void* in the typedef, the compiler exposes that in error messages. */
struct __timezone_t;
/** The `timezone_t` type that represents a time zone. */
typedef struct __timezone_t* timezone_t;
/** Divisor to compute seconds from the result of a call to clock(). */
#define CLOCKS_PER_SEC 1000000
/**
* The name of the current time zone's non-daylight savings (`tzname[0]`) and
* daylight savings (`tzname[1]`) variants. See tzset().
*/
extern char* _Nonnull tzname[];
/** Whether the current time zone ever uses daylight savings time. See tzset(). */
extern int daylight;
/** The difference in seconds between UTC and the current time zone. See tzset(). */
extern long int timezone;
struct sigevent;
/**
* A "broken-down" time, useful for parsing/formatting times for human consumption.
*/
struct tm {
/** Seconds, 0-60. (60 is a leap second.) */
int tm_sec;
/** Minutes, 0-59. */
int tm_min;
/** Hours, 0-23. */
int tm_hour;
/** Day of month, 1-31. */
int tm_mday;
/** Month of year, 0-11. (Not 1-12!) */
int tm_mon;
/** Years since 1900. (So 2023 is 123, not 2023!) */
int tm_year;
/** Day of week, 0-6. (Sunday is 0, Saturday is 6.) */
int tm_wday;
/** Day of year, 0-365. */
int tm_yday;
/** Daylight savings flag, positive for DST in effect, 0 for DST not in effect, and -1 for unknown. */
int tm_isdst;
/** Offset from UTC (GMT) in seconds for this time. */
long int tm_gmtoff;
/** Name of the time zone for this time. */
const char* _Nullable tm_zone;
};
/** Alternative name for `tm_zone` in `struct tm`. */
#define TM_ZONE tm_zone
/**
* [time(2)](http://man7.org/linux/man-pages/man2/time.2.html) returns
* the number of seconds since the Unix epoch (1970-01-01 00:00:00 +0000).
*
* Returns the time in seconds on success, and returns -1 and sets `errno` on failure.
*/
time_t time(time_t* _Nullable __t);
/**
* [nanosleep(2)](http://man7.org/linux/man-pages/man2/nanosleep.2.html) sleeps
* for at least the given time (or until a signal arrives).
*
* Returns 0 on success, and returns -1 and sets `errno` on failure. If the sleep
* was interrupted by a signal, `errno` will be `EINTR` and `remainder` will be
* the amount of time remaining.
*/
int nanosleep(const struct timespec* _Nonnull __request, struct timespec* _Nullable __remainder);
/**
* [asctime(3)](http://man7.org/linux/man-pages/man3/asctime.3p.html) formats
* the time `tm` as a string.
*
* Returns a pointer to a string on success, and returns NULL on failure.
*
* That string will be overwritten by later calls to this function.
*
* New code should prefer strftime().
*/
char* _Nullable asctime(const struct tm* _Nonnull __tm);
/**
* [asctime_r(3)](http://man7.org/linux/man-pages/man3/asctime_r.3p.html) formats
* the time `tm` as a string in the given buffer `buf`.
*
* Returns a pointer to a string on success, and returns NULL on failure.
*
* New code should prefer strftime().
*/
char* _Nullable asctime_r(const struct tm* _Nonnull __tm, char* _Nonnull __buf);
/**
* [difftime(3)](http://man7.org/linux/man-pages/man3/difftime.3.html) returns
* the difference between two times.
*
* Returns the difference in seconds.
*/
double difftime(time_t __lhs, time_t __rhs);
/**
* [mktime(3)](http://man7.org/linux/man-pages/man3/mktime.3p.html) converts
* broken-down time `tm` into the number of seconds since the Unix epoch.
*
* See tzset() for details of how the time zone is set, and mktime_rz()
* for an alternative.
*
* Returns the time in seconds on success, and returns -1 and sets `errno` on failure.
*/
time_t mktime(struct tm* _Nonnull __tm);
/**
* mktime_z(3) converts broken-down time `tm` into the number of seconds
* since the Unix epoch, assuming the given time zone.
*
* Returns the time in seconds on success, and returns -1 and sets `errno` on failure.
*
* Available since API level 35.
*/
time_t mktime_z(timezone_t _Nonnull __tz, struct tm* _Nonnull __tm) __INTRODUCED_IN(35);
/**
* [localtime(3)](http://man7.org/linux/man-pages/man3/localtime.3p.html) converts
* the number of seconds since the Unix epoch in `t` to a broken-down time, taking
* the device's timezone into account.
*
* That broken-down time will be overwritten by later calls to this function.
*
* Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure.
*/
struct tm* _Nullable localtime(const time_t* _Nonnull __t);
/**
* [localtime_r(3)](http://man7.org/linux/man-pages/man3/localtime_r.3p.html) converts
* the number of seconds since the Unix epoch in `t` to a broken-down time.
* That broken-down time will be written to the given struct `tm`.
*
* See tzset() for details of how the time zone is set, and localtime_rz()
* for an alternative.
*
* Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure.
*/
struct tm* _Nullable localtime_r(const time_t* _Nonnull __t, struct tm* _Nonnull __tm);
/**
* localtime_rz(3) converts the number of seconds since the Unix epoch in
* `t` to a broken-down time, assuming the given time zone. That broken-down
* time will be written to the given struct `tm`.
*
* Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure.
*
* Available since API level 35.
*/
struct tm* _Nullable localtime_rz(timezone_t _Nonnull __tz, const time_t* _Nonnull __t, struct tm* _Nonnull __tm) __INTRODUCED_IN(35);
/**
* Inverse of localtime().
*/
time_t timelocal(struct tm* _Nonnull __tm);
/**
* [gmtime(3)](http://man7.org/linux/man-pages/man3/gmtime.3p.html) converts
* the number of seconds since the Unix epoch in `t` to a broken-down time, using
* UTC (historically also known as GMT).
*
* That broken-down time will be overwritten by later calls to this function.
*
* Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure.
*/
struct tm* _Nullable gmtime(const time_t* _Nonnull __t);
/**
* [gmtime_r(3)](http://man7.org/linux/man-pages/man3/gmtime_r.3p.html) converts
* the number of seconds since the Unix epoch in `t` to a broken-down time, using
* UTC (historically also known as GMT).
*
* That broken-down time will be written to the provided struct `tm`.
*
* Returns a pointer to a broken-down time on success, and returns null and sets `errno` on failure.
*/
struct tm* _Nullable gmtime_r(const time_t* _Nonnull __t, struct tm* _Nonnull __tm);
/**
* Inverse of gmtime().
*/
time_t timegm(struct tm* _Nonnull __tm);
/**
* [strptime(3)](http://man7.org/linux/man-pages/man3/strptime.3.html) parses
* a string `s` assuming format `fmt` into broken-down time `tm`.
*
* Returns a pointer to the first character _not_ parsed, or null if no characters were parsed.
*/
char* _Nullable strptime(const char* _Nonnull __s, const char* _Nonnull __fmt, struct tm* _Nonnull __tm) __strftimelike(2);
/**
* Equivalent to strptime() on Android where only C/POSIX locales are available.
*/
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);
/**
* [strftime(3)](http://man7.org/linux/man-pages/man3/strftime.3.html) formats
* a broken-down time `tm` into the buffer `buf` using format `fmt`.
*
* Returns a pointer to the first character _not_ parsed, or null if no characters were parsed.
*/
size_t strftime(char* _Nonnull __buf, size_t __n, const char* _Nonnull __fmt, const struct tm* _Nullable __tm) __strftimelike(3);
/**
* Equivalent to strftime() on Android where only C/POSIX locales are available.
*/
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) __INTRODUCED_IN(21);
/**
* [ctime(3)](http://man7.org/linux/man-pages/man3/ctime.3p.html) formats
* the time `tm` as a string.
*
* Returns a pointer to a string on success, and returns NULL on failure.
*
* That string will be overwritten by later calls to this function.
*
* New code should prefer strftime().
*/
char* _Nullable ctime(const time_t* _Nonnull __t);
/**
* [ctime_r(3)](http://man7.org/linux/man-pages/man3/ctime.3p.html) formats
* the time `tm` as a string in the given buffer `buf`.
*
* Returns a pointer to a string on success, and returns NULL on failure.
*
* New code should prefer strftime().
*/
char* _Nullable ctime_r(const time_t* _Nonnull __t, char* _Nonnull __buf);
/**
* [tzset(3)](http://man7.org/linux/man-pages/man3/tzset.3.html) tells
* libc that the time zone has changed.
*
* Android looks at both the system property `persist.sys.timezone` and the
* environment variable `TZ`. The former is the device's current time zone
* as shown in Settings, while the latter is usually unset but can be used
* to override the global setting. This is a bad idea outside of unit tests
* or single-threaded programs because it's inherently thread-unsafe.
* See tzalloc(), localtime_rz(), mktime_z(), and tzfree() for an
* alternative.
*/
void tzset(void);
/**
* tzalloc(3) allocates a time zone corresponding to the given Olson id.
*
* Returns a time zone object on success, and returns NULL and sets `errno` on failure.
*
* Available since API level 35.
*/
timezone_t _Nullable tzalloc(const char* _Nullable __id) __INTRODUCED_IN(35);
/**
* tzfree(3) frees a time zone object returned by tzalloc().
*
* Available since API level 35.
*/
void tzfree(timezone_t _Nullable __tz) __INTRODUCED_IN(35);
/**
* [clock(3)](http://man7.org/linux/man-pages/man3/clock.3.html)
* returns an approximation of CPU time used, equivalent to
* `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)` but with more confusing
* units. Use `CLOCKS_PER_SEC` to convert the result to seconds.
*
* Returns the time in seconds on success, and returns -1 and sets `errno` on failure.
*
* New code should prefer `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)`.
*/
clock_t clock(void);
/**
* [clock_getcpuclockid(3)](http://man7.org/linux/man-pages/man3/clock_getcpuclockid.3.html)
* gets the clock id of the cpu-time clock for the given `pid`.
*
* Returns 0 on success, and returns -1 and returns an error number on failure.
*/
int clock_getcpuclockid(pid_t __pid, clockid_t* _Nonnull __clock) __INTRODUCED_IN(23);
/**
* [clock_getres(2)](http://man7.org/linux/man-pages/man2/clock_getres.2.html)
* gets the resolution of the given clock.
*
* Returns 0 on success, and returns -1 and returns an error number on failure.
*/
int clock_getres(clockid_t __clock, struct timespec* _Nullable __resolution);
/**
* [clock_gettime(2)](http://man7.org/linux/man-pages/man2/clock_gettime.2.html)
* gets the time according to the given clock.
*
* Returns 0 on success, and returns -1 and returns an error number on failure.
*/
int clock_gettime(clockid_t __clock, struct timespec* _Nonnull __ts);
/**
* [clock_nanosleep(2)](http://man7.org/linux/man-pages/man2/clock_nanosleep.2.html)
* sleeps for the given time as measured by the given clock.
*
* Returns 0 on success, and returns -1 and returns an error number on failure.
* If the sleep was interrupted by a signal, the return value will be `EINTR`
* and `remainder` will be the amount of time remaining.
*/
int clock_nanosleep(clockid_t __clock, int __flags, const struct timespec* _Nonnull __request, struct timespec* _Nullable __remainder);
/**
* [clock_settime(2)](http://man7.org/linux/man-pages/man2/clock_settime.2.html)
* sets the time for the given clock.
*
* Returns 0 on success, and returns -1 and returns an error number on failure.
*/
int clock_settime(clockid_t __clock, const struct timespec* _Nonnull __ts);
/**
* [timer_create(2)](http://man7.org/linux/man-pages/man2/timer_create.2.html)
* creates a POSIX timer.
*
* Returns 0 on success, and returns -1 and sets `errno` on failure.
*/
int timer_create(clockid_t __clock, struct sigevent* _Nullable __event, timer_t _Nonnull * _Nonnull __timer_ptr);
/**
* [timer_delete(2)](http://man7.org/linux/man-pages/man2/timer_delete.2.html)
* destroys a POSIX timer.
*
* Returns 0 on success, and returns -1 and sets `errno` on failure.
*/
int timer_delete(timer_t _Nonnull __timer);
/**
* [timer_settime(2)](http://man7.org/linux/man-pages/man2/timer_settime.2.html)
* starts or stops a POSIX timer.
*
* Returns 0 on success, and returns -1 and sets `errno` on failure.
*/
int timer_settime(timer_t _Nonnull __timer, int __flags, const struct itimerspec* _Nonnull __new_value, struct itimerspec* _Nullable __old_value);
/**
* [timer_gettime(2)](http://man7.org/linux/man-pages/man2/timer_gettime.2.html)
* gets the time until the given timer next fires.
*
* Returns 0 on success, and returns -1 and sets `errno` on failure.
*/
int timer_gettime(timer_t _Nonnull _timer, struct itimerspec* _Nonnull __ts);
/**
* [timer_getoverrun(2)](http://man7.org/linux/man-pages/man2/timer_getoverrun.2.html)
* gets the overrun count (the number of times the timer should have fired, but
* didn't) for the last time the timer fired.
*
* Returns the overrun count on success, and returns -1 and sets `errno` on failure.
*/
int timer_getoverrun(timer_t _Nonnull __timer);
/**
* The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_REALTIME.
*
* Available since API level 29.
*/
#define TIME_UTC (CLOCK_REALTIME+1)
/**
* The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_MONOTONIC.
*
* Available since API level 35.
*/
#define TIME_MONOTONIC (CLOCK_MONOTONIC+1)
/**
* The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_PROCESS_CPUTIME_ID.
*
* Available since API level 35.
*/
#define TIME_ACTIVE (CLOCK_PROCESS_CPUTIME_ID+1)
/**
* The timebase for timespec_get() and timespec_getres() corresponding to CLOCK_THREAD_CPUTIME_ID.
*
* Available since API level 35.
*/
#define TIME_THREAD_ACTIVE (CLOCK_THREAD_CPUTIME_ID+1)
/**
* timespec_get(3) is equivalent to clock_gettime() for the clock corresponding to the given base.
*
* Returns the base on success and returns 0 on failure.
*
* Available since API level 29 for TIME_UTC; other bases arrived later.
* Code for Android should prefer clock_gettime().
*/
int timespec_get(struct timespec* _Nonnull __ts, int __base) __INTRODUCED_IN(29);
/**
* timespec_getres(3) is equivalent to clock_getres() for the clock corresponding to the given base.
*
* Returns the base on success and returns 0 on failure.
*
* Available since API level 35.
* Code for Android should prefer clock_gettime().
*/
int timespec_getres(struct timespec* _Nonnull __ts, int __base) __INTRODUCED_IN(35);
__END_DECLS
Reference in a new issue View git blame Copy permalink