Merge pull request #1453 from bjorng/bjorn/catch-warning/OTP-14401

Warn for potentially unsafe use of get_stacktrace/0

1 files changed, 26 insertions, 2 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 6f70ae4a52..6d165e9eff 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1813,8 +1813,9 @@ true</pre>
       <fsummary>Get the call stack back-trace of the last exception.</fsummary>
       <type name="stack_item"/>
       <desc>
-        <p>Gets the call stack back-trace (<em>stacktrace</em>) of the
-          last exception in the calling process as a list of
+        <p>Gets the call stack back-trace (<em>stacktrace</em>) for an
+          exception that has just been caught
+	  in the calling process as a list of
           <c>{<anno>Module</anno>,<anno>Function</anno>,<anno>Arity</anno>,<anno>Location</anno>}</c>
           tuples. Field <c><anno>Arity</anno></c> in the first tuple can be the
           argument list of that function call instead of an arity integer,
@@ -1822,6 +1823,29 @@ true</pre>
         <p>If there has not been any exceptions in a process, the
           stacktrace is <c>[]</c>. After a code change for the process,
           the stacktrace can also be reset to <c>[]</c>.</p>
+	<p><c>erlang:get_stacktrace/0</c> is only guaranteed to return
+	a stacktrace if called (directly or indirectly) from within the
+	scope of a <c>try</c> expression. That is, the following call works:</p>
+<pre>
+try Expr
+catch
+  C:R ->
+   {C,R,erlang:get_stacktrace()}
+end</pre>
+	<p>As does this call:</p>
+<pre>
+try Expr
+catch
+  C:R ->
+   {C,R,helper()}
+end
+
+helper() ->
+  erlang:get_stacktrace().</pre>
+
+        <warning><p>In a future release,
+        <c>erlang:get_stacktrace/0</c> will return <c>[]</c> if called
+        from outside a <c>try</c> expression.</p></warning>
         <p>The stacktrace is the same data as operator <c>catch</c>
           returns, for example:</p>
         <pre>