<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Pervasives.html">
<link rel="next" href="Printf.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Arg" rel="Chapter" href="Arg.html">
<link title="Arith_status" rel="Chapter" href="Arith_status.html">
<link title="Array" rel="Chapter" href="Array.html">
<link title="ArrayLabels" rel="Chapter" href="ArrayLabels.html">
<link title="Big_int" rel="Chapter" href="Big_int.html">
<link title="Bigarray" rel="Chapter" href="Bigarray.html">
<link title="Buffer" rel="Chapter" href="Buffer.html">
<link title="Callback" rel="Chapter" href="Callback.html">
<link title="CamlinternalLazy" rel="Chapter" href="CamlinternalLazy.html">
<link title="CamlinternalMod" rel="Chapter" href="CamlinternalMod.html">
<link title="CamlinternalOO" rel="Chapter" href="CamlinternalOO.html">
<link title="Char" rel="Chapter" href="Char.html">
<link title="Complex" rel="Chapter" href="Complex.html">
<link title="Condition" rel="Chapter" href="Condition.html">
<link title="Digest" rel="Chapter" href="Digest.html">
<link title="Dynlink" rel="Chapter" href="Dynlink.html">
<link title="Event" rel="Chapter" href="Event.html">
<link title="Filename" rel="Chapter" href="Filename.html">
<link title="Format" rel="Chapter" href="Format.html">
<link title="Gc" rel="Chapter" href="Gc.html">
<link title="Genlex" rel="Chapter" href="Genlex.html">
<link title="Graphics" rel="Chapter" href="Graphics.html">
<link title="GraphicsX11" rel="Chapter" href="GraphicsX11.html">
<link title="Hashtbl" rel="Chapter" href="Hashtbl.html">
<link title="Int32" rel="Chapter" href="Int32.html">
<link title="Int64" rel="Chapter" href="Int64.html">
<link title="Lazy" rel="Chapter" href="Lazy.html">
<link title="Lexing" rel="Chapter" href="Lexing.html">
<link title="List" rel="Chapter" href="List.html">
<link title="ListLabels" rel="Chapter" href="ListLabels.html">
<link title="Map" rel="Chapter" href="Map.html">
<link title="Marshal" rel="Chapter" href="Marshal.html">
<link title="MoreLabels" rel="Chapter" href="MoreLabels.html">
<link title="Mutex" rel="Chapter" href="Mutex.html">
<link title="Nativeint" rel="Chapter" href="Nativeint.html">
<link title="Num" rel="Chapter" href="Num.html">
<link title="Obj" rel="Chapter" href="Obj.html">
<link title="Oo" rel="Chapter" href="Oo.html">
<link title="Parsing" rel="Chapter" href="Parsing.html">
<link title="Pervasives" rel="Chapter" href="Pervasives.html">
<link title="Printexc" rel="Chapter" href="Printexc.html">
<link title="Printf" rel="Chapter" href="Printf.html">
<link title="Queue" rel="Chapter" href="Queue.html">
<link title="Random" rel="Chapter" href="Random.html">
<link title="Ratio" rel="Chapter" href="Ratio.html">
<link title="Scanf" rel="Chapter" href="Scanf.html">
<link title="Set" rel="Chapter" href="Set.html">
<link title="Sort" rel="Chapter" href="Sort.html">
<link title="Stack" rel="Chapter" href="Stack.html">
<link title="StdLabels" rel="Chapter" href="StdLabels.html">
<link title="Str" rel="Chapter" href="Str.html">
<link title="Stream" rel="Chapter" href="Stream.html">
<link title="String" rel="Chapter" href="String.html">
<link title="StringLabels" rel="Chapter" href="StringLabels.html">
<link title="Sys" rel="Chapter" href="Sys.html">
<link title="Thread" rel="Chapter" href="Thread.html">
<link title="ThreadUnix" rel="Chapter" href="ThreadUnix.html">
<link title="Tk" rel="Chapter" href="Tk.html">
<link title="Unix" rel="Chapter" href="Unix.html">
<link title="UnixLabels" rel="Chapter" href="UnixLabels.html">
<link title="Weak" rel="Chapter" href="Weak.html"><link title="Raw backtraces" rel="Section" href="#6_Rawbacktraces">
<link title="Current call stack" rel="Section" href="#6_Currentcallstack">
<title>Printexc</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Pervasives.html" title="Pervasives">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Printf.html" title="Printf">Next</a>
</div>
<h1>Module <a href="type_Printexc.html">Printexc</a></h1>
<pre><span class="keyword">module</span> Printexc: <code class="code"><span class="keyword">sig</span></code> <a href="Printexc.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info module top">
Facilities for printing exceptions and inspecting current call stack.<br>
</div>
<hr width="100%">
<pre><span id="VALto_string"><span class="keyword">val</span> to_string</span> : <code class="type">exn -> string</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.to_string e</code> returns a string representation of
the exception <code class="code">e</code>.<br>
</div>
<pre><span id="VALprint"><span class="keyword">val</span> print</span> : <code class="type">('a -> 'b) -> 'a -> 'b</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.print fn x</code> applies <code class="code">fn</code> to <code class="code">x</code> and returns the result.
If the evaluation of <code class="code">fn x</code> raises any exception, the
name of the exception is printed on standard error output,
and the exception is raised again.
The typical use is to catch and report exceptions that
escape a function application.<br>
</div>
<pre><span id="VALcatch"><span class="keyword">val</span> catch</span> : <code class="type">('a -> 'b) -> 'a -> 'b</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.catch fn x</code> is similar to <a href="Printexc.html#VALprint"><code class="code"><span class="constructor">Printexc</span>.print</code></a>, but
aborts the program with exit code 2 after printing the
uncaught exception. This function is deprecated: the runtime
system is now able to print uncaught exceptions as precisely
as <code class="code"><span class="constructor">Printexc</span>.catch</code> does. Moreover, calling <code class="code"><span class="constructor">Printexc</span>.catch</code>
makes it harder to track the location of the exception
using the debugger or the stack backtrace facility.
So, do not use <code class="code"><span class="constructor">Printexc</span>.catch</code> in new code.<br>
</div>
<pre><span id="VALprint_backtrace"><span class="keyword">val</span> print_backtrace</span> : <code class="type"><a href="Pervasives.html#TYPEout_channel">out_channel</a> -> unit</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.print_backtrace oc</code> prints an exception backtrace
on the output channel <code class="code">oc</code>. The backtrace lists the program
locations where the most-recently raised exception was raised
and where it was propagated through function calls.<br>
<b>Since</b> 3.11.0<br>
</div>
<pre><span id="VALget_backtrace"><span class="keyword">val</span> get_backtrace</span> : <code class="type">unit -> string</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.get_backtrace ()</code> returns a string containing the
same exception backtrace that <code class="code"><span class="constructor">Printexc</span>.print_backtrace</code> would
print.<br>
<b>Since</b> 3.11.0<br>
</div>
<pre><span id="VALrecord_backtrace"><span class="keyword">val</span> record_backtrace</span> : <code class="type">bool -> unit</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.record_backtrace b</code> turns recording of exception backtraces
on (if <code class="code">b = <span class="keyword">true</span></code>) or off (if <code class="code">b = <span class="keyword">false</span></code>). Initially, backtraces
are not recorded, unless the <code class="code">b</code> flag is given to the program
through the <code class="code"><span class="constructor">OCAMLRUNPARAM</span></code> variable.<br>
<b>Since</b> 3.11.0<br>
</div>
<pre><span id="VALbacktrace_status"><span class="keyword">val</span> backtrace_status</span> : <code class="type">unit -> bool</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.backtrace_status()</code> returns <code class="code"><span class="keyword">true</span></code> if exception
backtraces are currently recorded, <code class="code"><span class="keyword">false</span></code> if not.<br>
<b>Since</b> 3.11.0<br>
</div>
<pre><span id="VALregister_printer"><span class="keyword">val</span> register_printer</span> : <code class="type">(exn -> string option) -> unit</code></pre><div class="info ">
<code class="code"><span class="constructor">Printexc</span>.register_printer fn</code> registers <code class="code">fn</code> as an exception
printer. The printer should return <code class="code"><span class="constructor">None</span></code> or raise an exception
if it does not know how to convert the passed exception, and <code class="code"><span class="constructor">Some</span>
s</code> with <code class="code">s</code> the resulting string if it can convert the passed
exception. Exceptions raised by the printer are ignored.
<p>
When converting an exception into a string, the printers will be invoked
in the reverse order of their registrations, until a printer returns
a <code class="code"><span class="constructor">Some</span> s</code> value (if no such printer exists, the runtime will use a
generic printer).
<p>
When using this mechanism, one should be aware that an exception backtrace
is attached to the thread that saw it raised, rather than to the exception
itself. Practically, it means that the code related to <code class="code">fn</code> should not use
the backtrace if it has itself raised an exception before.<br>
<b>Since</b> 3.11.2<br>
</div>
<br>
<h6 id="6_Rawbacktraces">Raw backtraces</h6><br>
<pre><span id="TYPEraw_backtrace"><span class="keyword">type</span> <code class="type"></code>raw_backtrace</span> </pre>
<br>
The abstract type <code class="code">backtrace</code> stores exception backtraces in
a low-level format, instead of directly exposing them as string as
the <code class="code">get_backtrace()</code> function does.
<p>
This allows to pay the performance overhead of representation
conversion and formatting only at printing time, which is useful
if you want to record more backtrace than you actually print.<br>
<pre><span id="VALget_raw_backtrace"><span class="keyword">val</span> get_raw_backtrace</span> : <code class="type">unit -> <a href="Printexc.html#TYPEraw_backtrace">raw_backtrace</a></code></pre>
<pre><span id="VALprint_raw_backtrace"><span class="keyword">val</span> print_raw_backtrace</span> : <code class="type"><a href="Pervasives.html#TYPEout_channel">out_channel</a> -> <a href="Printexc.html#TYPEraw_backtrace">raw_backtrace</a> -> unit</code></pre>
<pre><span id="VALraw_backtrace_to_string"><span class="keyword">val</span> raw_backtrace_to_string</span> : <code class="type"><a href="Printexc.html#TYPEraw_backtrace">raw_backtrace</a> -> string</code></pre><br>
<h6 id="6_Currentcallstack">Current call stack</h6><br>
<pre><span id="VALget_callstack"><span class="keyword">val</span> get_callstack</span> : <code class="type">int -> <a href="Printexc.html#TYPEraw_backtrace">raw_backtrace</a></code></pre><br>
<code class="code"><span class="constructor">Printexc</span>.get_callstack n</code> returns a description of the top of the
call stack on the current program point (for the current thread),
with at most <code class="code">n</code> entries. (Note: this function is not related to
exceptions at all, despite being part of the <code class="code"><span class="constructor">Printexc</span></code> module.)<br>
</body></html>
