re PR libbacktrace/87529 (libbacktrace API forces users to have memory leaks)

	PR libbacktrace/87529
	* backtrace.h: Document that backtrace_create_state should be
	called only once.

From-SVN: r264871

libbacktrace/ChangeLog

+2018-10-05  Ian Lance Taylor  <iant@golang.org>
+
+	PR libbacktrace/87529
+	* backtrace.h: Document that backtrace_create_state should be
+	called only once.
+
 2018-08-05 Iain Buclaw  <ibuclaw@gdcproject.org>
 
 	* configure.ac: Move define of HAVE_ZLIB into check for -lz.

libbacktrace/backtrace.h

@@ -92,7 +92,13 @@ typedef void (*backtrace_error_callback) (void *data, const char *msg,
    use appropriate atomic operations.  If THREADED is zero the state
    may only be accessed by one thread at a time.  This returns a state
    pointer on success, NULL on error.  If an error occurs, this will
-   call the ERROR_CALLBACK routine.  */
+   call the ERROR_CALLBACK routine.
+
+   Calling this function allocates resources that can not be freed.
+   There is no backtrace_free_state function.  The state is used to
+   cache information that is expensive to recompute.  Programs are
+   expected to call this function at most once and to save the return
+   value for all later calls to backtrace functions.  */
 
 extern struct backtrace_state *backtrace_create_state (
     const char *filename, int threaded,