PR libbacktrace/87529

	* backtrace.h: Document that backtrace_create_state should be
	called only once.

git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@264871 138bc75d-0d04-0410-961f-82ee72b054a4

diff --git a/libbacktrace/ChangeLog b/libbacktrace/ChangeLog
index ea43f145c3d2e90cca9d96234a47c18e163802f1..75745aa1796a0457a3e32813e1f00d424d817afd 100644 (file)
--- a/libbacktrace/ChangeLog
+++ b/libbacktrace/ChangeLog
@@ -1,3 +1,9 @@
+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.

diff --git a/libbacktrace/backtrace.h b/libbacktrace/backtrace.h
index f07fa6c585ecfe47cf406b1054fcb22d65fd1836..83439ffadce51e65cb75c3ea5120c4fa67e40aa0 100644 (file)
--- a/libbacktrace/backtrace.h
+++ b/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,