Document how to use tzalloc()/tzfree() with std::unique_ptr.
The hidden pointer makes this trickier than the usual incantation, so
leave some copy & paste lying around for anyone trying to work this out.
Test: treehugger
Change-Id: I26e94bf7a74ce3e43de587edc52ab63e36d1d86b
diff --git a/libc/include/time.h b/libc/include/time.h
index 08f30ef..31c2050 100644
--- a/libc/include/time.h
+++ b/libc/include/time.h
@@ -42,7 +42,13 @@
/* 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 timezone. */
+/**
+ * The `timezone_t` type that represents a timezone.
+ *
+ * To use this with std::unique_ptr you'll want something like
+ * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};`
+ * to remove the pointer.
+ */
typedef struct __timezone_t* timezone_t;
/** Divisor to compute seconds from the result of a call to clock(). */
@@ -300,6 +306,10 @@
* tzalloc() is thread safe (though obviously the system timezone can
* change, especially if your mobile device is actually mobile!).
*
+ * To use this with std::unique_ptr you'll want something like
+ * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};`
+ * to remove the pointer.
+ *
* Returns a timezone object on success, and returns NULL and sets `errno` on failure.
*
* Available since API level 35.
@@ -309,6 +319,10 @@
/**
* tzfree(3) frees a timezone object returned by tzalloc().
*
+ * To use this with std::unique_ptr you'll want something like
+ * `std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"), tzfree};`
+ * to remove the pointer.
+ *
* Available since API level 35.
*/
void tzfree(timezone_t _Nullable __tz) __INTRODUCED_IN(35);