[PATCH 11/28] Thread safety documentation.

[Alexandre Oliva <aoliva at redhat dot com>]

for ChangeLog

	* manual/debug.texi: Document thread safety properties.
---
 manual/debug.texi |   18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/manual/debug.texi b/manual/debug.texi
index 1db9c18..ce0c263 100644
--- a/manual/debug.texi
+++ b/manual/debug.texi
@@ -36,6 +36,8 @@ and manipulate backtraces of the current thread.
 @comment execinfo.h
 @comment GNU
 @deftypefun int backtrace (void **@var{buffer}, int @var{size})
+@safety{@mtsafe{}@assafe{}@acsafe{}}
+@c Pointer chasing within the local stack.
 The @code{backtrace} function obtains a backtrace for the current
 thread, as a list of pointers, and places the information into
 @var{buffer}.  The argument @var{size} should be the number of
@@ -56,6 +58,17 @@ interpreting the stack contents correctly.
 @comment execinfo.h
 @comment GNU
 @deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size})
+@safety{@mtsafe{}@asunsafe{asmalloc}@acunsafe{memleak, lockleak}}
+@c Collects info returned by _dl_addr in auto array, allocates memory
+@c for the whole return buffer with malloc then sprintfs into it storing
+@c pointers to the strings into the array entries in the buffer.
+@c _dl_addr takes the recursive dl_load_lock then calls
+@c _dl_find_dso_for_object and determine_info.
+@c _dl_find_dso_for_object calls _dl-addr_inside_object.
+@c All of them are safe as long as the lock is held.
+@c asynconsist?  It doesn't looke like the dynamic loader's data
+@c structures could be in an inconsistent state that would cause
+@c malfunction here.
 The @code{backtrace_symbols} function translates the information
 obtained from the @code{backtrace} function into an array of strings.
 The argument @var{buffer} should be a pointer to an array of addresses
@@ -88,6 +101,11 @@ cannot be obtained.
 @comment execinfo.h
 @comment GNU
 @deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd})
+@safety{@mtsafe{}@assafe{}@acunsafe{lockleak}}
+@c Single loop of _dl_addr over addresses, collecting info into an iovec
+@c written out with a writev call per iteration.  Addresses and offsets
+@c are converted to hex in auto buffers, so the only potential issue
+@c here is leaking the dl lock in case of cancellation.
 The @code{backtrace_symbols_fd} function performs the same translation
 as the function @code{backtrace_symbols} function.  Instead of returning
 the strings to the caller, it writes the strings to the file descriptor