aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/errors.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2017-11-16 06:10:12 +0100
committerBjörn Gustavsson <[email protected]>2017-11-30 12:46:51 +0100
commit01f96ee6197a7b5a2c64353a3b38260994ce5ad5 (patch)
tree97f5feee2f1277d83d9287dd922b03104307c7c4 /system/doc/reference_manual/errors.xml
parent38e4dfbd281cae0fb58211b63861b037ad121231 (diff)
downloadotp-01f96ee6197a7b5a2c64353a3b38260994ce5ad5.tar.gz
otp-01f96ee6197a7b5a2c64353a3b38260994ce5ad5.tar.bz2
otp-01f96ee6197a7b5a2c64353a3b38260994ce5ad5.zip
Add documentation for the new stacktrace syntax
Diffstat (limited to 'system/doc/reference_manual/errors.xml')
-rw-r--r--system/doc/reference_manual/errors.xml47
1 files changed, 44 insertions, 3 deletions
diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml
index b16c5da6eb..16d3e7590e 100644
--- a/system/doc/reference_manual/errors.xml
+++ b/system/doc/reference_manual/errors.xml
@@ -108,14 +108,55 @@
(see <seealso marker="#exit_reasons">Exit Reason</seealso>),
and a stack trace (which aids in finding the code location of
the exception).</p>
- <p>The stack trace can be retrieved using
- <c>erlang:get_stacktrace/0</c>
- from within a <c>try</c> expression, and is returned for
+ <p>The stack trace can be be bound to a variable from within
+ a <c>try</c> expression, and is returned for
exceptions of class <c>error</c> from a <c>catch</c> expression.</p>
<p>An exception of class <c>error</c> is also known as a run-time
error.</p>
+
+ <section>
+ <title>The call-stack back trace (stacktrace)</title>
+ <p>The stack back-trace (<em>stacktrace</em>) is a list of
+ <c>{Module,Function,Arity,Location}</c>
+ tuples. The field <c>Arity</c> in the first tuple can be the
+ argument list of that function call instead of an arity integer,
+ depending on the exception.</p>
+
+ <p><c>Location</c> is a (possibly empty) list of two-tuples
+ that can indicate the location in the source code of the
+ function. The first element is an atom describing the type of
+ information in the second element. The following items can
+ occur:</p>
+ <taglist>
+ <tag><c>file</c></tag>
+ <item>The second element of the tuple is a string (list of
+ characters) representing the filename of the source file
+ of the function.
+ </item>
+ <tag><c>line</c></tag>
+ <item>The second element of the tuple is the line number
+ (an integer &gt; 0) in the source file
+ where the exception occurred or the function was called.
+ </item>
+ </taglist>
+ <warning><p>Developers should rely on stacktrace entries only for
+ debugging purposes.</p>
+ <p>The VM performs tail call optimization, which
+ does not add new entries to the stacktrace, and also limits stacktraces
+ to a certain depth. Furthermore, compiler options, optimizations and
+ future changes may add or remove stacktrace entries, causing any code
+ that expects the stacktrace to be in a certain order or contain specific
+ items to fail.</p>
+ <p>The only exception to this rule is the class <c>error</c> with the
+ reason <c>undef</c> which is guaranteed to include the <c>Module</c>,
+ <c>Function</c> and <c>Arity</c> of the attempted
+ function as the first stacktrace entry.</p>
+ </warning>
+ </section>
+
</section>
+
<section>
<title>Handling of Run-time Errors in Erlang</title>