Fix tzalloc(nullptr) and add a test.
This works (by reading /etc/localtime) on NetBSD, but not on Android
since we have no such file. Fix that by using our equivalent system
property instead.
Also s/time zone/timezone/ in documentation and comments. We've always
been inconsistent about this (as is upstream in code comments and
documentation) but it seems especially odd now we expose a _type_ that
spells it "timezone" to talk of "time zone" even as we're describing
that type and its associated functions.
Bug: https://github.com/chronotope/chrono/issues/499
Test: treehugger
Change-Id: I142995a3ab4deff1073a0aa9e63ce8eac850b93d
diff --git a/libc/include/time.h b/libc/include/time.h
index 5b76288..08f30ef 100644
--- a/libc/include/time.h
+++ b/libc/include/time.h
@@ -42,22 +42,22 @@
/* 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. */
+/** The `timezone_t` type that represents a timezone. */
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
+ * The name of the current timezone'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(). */
+/** Whether the current timezone ever uses daylight savings time. See tzset(). */
extern int daylight;
-/** The difference in seconds between UTC and the current time zone. See tzset(). */
+/** The difference in seconds between UTC and the current timezone. See tzset(). */
extern long int timezone;
struct sigevent;
@@ -86,7 +86,7 @@
int tm_isdst;
/** Offset from UTC (GMT) in seconds for this time. */
long int tm_gmtoff;
- /** Name of the time zone for this time. */
+ /** Name of the timezone for this time. */
const char* _Nullable tm_zone;
};
@@ -145,7 +145,7 @@
* [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()
+ * See tzset() for details of how the timezone is set, and mktime_rz()
* for an alternative.
*
* Returns the time in seconds on success, and returns -1 and sets `errno` on failure.
@@ -154,7 +154,7 @@
/**
* mktime_z(3) converts broken-down time `tm` into the number of seconds
- * since the Unix epoch, assuming the given time zone.
+ * since the Unix epoch, assuming the given timezone.
*
* Returns the time in seconds on success, and returns -1 and sets `errno` on failure.
*
@@ -178,7 +178,7 @@
* 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()
+ * See tzset() for details of how the timezone 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.
@@ -187,7 +187,7 @@
/**
* 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
+ * `t` to a broken-down time, assuming the given timezone. 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.
@@ -278,29 +278,36 @@
/**
* [tzset(3)](http://man7.org/linux/man-pages/man3/tzset.3.html) tells
- * libc that the time zone has changed.
+ * libc that the timezone 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.
+ * tzset() on Android looks at both the system property
+ * `persist.sys.timezone` and the environment variable `TZ`. The former is
+ * the device's current timezone 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.
+ * tzalloc(3) allocates a timezone corresponding to the given Olson ID.
*
- * Returns a time zone object on success, and returns NULL and sets `errno` on failure.
+ * A null `id` returns the system timezone (as seen in Settings) from
+ * the system property `persist.sys.timezone`, ignoring `$TZ`. Although
+ * tzset() honors `$TZ`, callers of tzalloc() can use `$TZ` themselves if
+ * that's the (thread-unsafe) behavior they want, but by ignoring `$TZ`
+ * tzalloc() is thread safe (though obviously the system timezone can
+ * change, especially if your mobile device is actually mobile!).
+ *
+ * Returns a timezone 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().
+ * tzfree(3) frees a timezone object returned by tzalloc().
*
* Available since API level 35.
*/
@@ -320,7 +327,7 @@
/**
* [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`.
+ * 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.
*/