libbacktrace patch committed: backtrace_create_state should be called once

[Ian Lance Taylor]

This patch to libbacktrace expands the comment for
backtrace_create_state to make clear that it should be called only
once.  There is no backtrace_free_state function.  While it would be
nice to have such a function, it's hard to write completely accurately
as libbacktrace doesn't currently track all memory allocations.
Committed to mainline.

Ian

2018-10-05  Ian Lance Taylor  <iant@golang.org>

PR libbacktrace/87529
* backtrace.h: Document that backtrace_create_state should be
called only once.
-------------- next part --------------
Index: backtrace.h
===================================================================
--- backtrace.h	(revision 264813)
+++ backtrace.h	(working copy)
@@ -92,7 +92,13 @@ typedef void (*backtrace_error_callback)
    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,