Merge "Document how to use tzalloc()/tzfree() with std::unique_ptr." am: 8995672880 am: 5aeec3b87d am: d301fe1a1f am: 7ea8a9ea53

Original change: https://android-review.googlesource.com/c/platform/bionic/+/2636324

Change-Id: Idfe21dc4ce0e4e233e56352d7503b7de1a6ffa74
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>

libc/include/time.h

@@ -42,7 +42,13 @@ __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 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 @@ void tzset(void);
  * 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 @@ timezone_t _Nullable tzalloc(const char* _Nullable __id) __INTRODUCED_IN(35);
 /**
  * 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);

tests/time_test.cpp

@@ -1452,3 +1452,12 @@ TEST(time, tzalloc_nullptr) {
   GTEST_SKIP() << "glibc doesn't have timezone_t";
 #endif
 }
+
+TEST(time, tzalloc_unique_ptr) {
+#if __BIONIC__
+  std::unique_ptr<std::remove_pointer_t<timezone_t>, decltype(&tzfree)> tz{tzalloc("Asia/Seoul"),
+                                                                           tzfree};
+#else
+  GTEST_SKIP() << "glibc doesn't have timezone_t";
+#endif
+}