845 lines
12 KiB
HTML
845 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Printexc</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Printexc</H1>
|
|
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Printexc - Facilities for printing exceptions and inspecting current call stack.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>Module</H2>
|
|
|
|
Module Printexc
|
|
<A NAME="lbAD"> </A>
|
|
<H2>Documentation</H2>
|
|
|
|
<P>
|
|
Module
|
|
<B>Printexc</B>
|
|
|
|
<BR> :
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
Facilities for printing exceptions and inspecting current call stack.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>type t </I>
|
|
|
|
=
|
|
<B>exn</B>
|
|
|
|
= ..
|
|
<P>
|
|
<P>
|
|
The type of exception values.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val to_string </I>
|
|
|
|
:
|
|
<B>exn -> string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.to_string e</B>
|
|
|
|
returns a string representation of
|
|
the exception
|
|
<B>e</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print </I>
|
|
|
|
:
|
|
<B>('a -> 'b) -> 'a -> 'b</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.print fn x</B>
|
|
|
|
applies
|
|
<B>fn</B>
|
|
|
|
to
|
|
<B>x</B>
|
|
|
|
and returns the result.
|
|
If the evaluation of
|
|
<B>fn x</B>
|
|
|
|
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.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val catch </I>
|
|
|
|
:
|
|
<B>('a -> 'b) -> 'a -> 'b</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.catch fn x</B>
|
|
|
|
is similar to
|
|
<B>Printexc.print</B>
|
|
|
|
, 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
|
|
<B>Printexc.catch</B>
|
|
|
|
does. Moreover, calling
|
|
<B>Printexc.catch</B>
|
|
|
|
makes it harder to track the location of the exception
|
|
using the debugger or the stack backtrace facility.
|
|
So, do not use
|
|
<B>Printexc.catch</B>
|
|
|
|
in new code.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_backtrace </I>
|
|
|
|
:
|
|
<B>out_channel -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.print_backtrace oc</B>
|
|
|
|
prints an exception backtrace
|
|
on the output channel
|
|
<B>oc</B>
|
|
|
|
. The backtrace lists the program
|
|
locations where the most-recently raised exception was raised
|
|
and where it was propagated through function calls.
|
|
<P>
|
|
If the call is not inside an exception handler, the returned
|
|
backtrace is unspecified. If the call is after some
|
|
exception-catching code (before in the handler, or in a when-guard
|
|
during the matching of the exception handler), the backtrace may
|
|
correspond to a later exception than the handled one.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.11.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_backtrace </I>
|
|
|
|
:
|
|
<B>unit -> string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.get_backtrace ()</B>
|
|
|
|
returns a string containing the
|
|
same exception backtrace that
|
|
<B>Printexc.print_backtrace</B>
|
|
|
|
would
|
|
print. Same restriction usage than
|
|
<B>Printexc.print_backtrace</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.11.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val record_backtrace </I>
|
|
|
|
:
|
|
<B>bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.record_backtrace b</B>
|
|
|
|
turns recording of exception backtraces
|
|
on (if
|
|
<B>b = true</B>
|
|
|
|
) or off (if
|
|
<B>b = false</B>
|
|
|
|
). Initially, backtraces
|
|
are not recorded, unless the
|
|
<B>b</B>
|
|
|
|
flag is given to the program
|
|
through the
|
|
<B>OCAMLRUNPARAM</B>
|
|
|
|
variable.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.11.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val backtrace_status </I>
|
|
|
|
:
|
|
<B>unit -> bool</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.backtrace_status()</B>
|
|
|
|
returns
|
|
<B>true</B>
|
|
|
|
if exception
|
|
backtraces are currently recorded,
|
|
<B>false</B>
|
|
|
|
if not.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.11.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val register_printer </I>
|
|
|
|
:
|
|
<B>(exn -> string option) -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.register_printer fn</B>
|
|
|
|
registers
|
|
<B>fn</B>
|
|
|
|
as an exception
|
|
printer. The printer should return
|
|
<B>None</B>
|
|
|
|
or raise an exception
|
|
if it does not know how to convert the passed exception, and
|
|
<B>Some</B>
|
|
|
|
<B>s</B>
|
|
|
|
with
|
|
<B>s</B>
|
|
|
|
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
|
|
<B>Some s</B>
|
|
|
|
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
|
|
<B>fn</B>
|
|
|
|
should not use
|
|
the backtrace if it has itself raised an exception before.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.11.2
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Raw backtraces</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type raw_backtrace </I>
|
|
|
|
<P>
|
|
<P>
|
|
The abstract type
|
|
<B>raw_backtrace</B>
|
|
|
|
stores a backtrace in
|
|
a low-level format, instead of directly exposing them as string as
|
|
the
|
|
<B>get_backtrace()</B>
|
|
|
|
function does.
|
|
<P>
|
|
This allows delaying the formatting of backtraces to when they are
|
|
actually printed, which may be useful if you record more
|
|
backtraces than you print.
|
|
<P>
|
|
Raw backtraces cannot be marshalled. If you need marshalling, you
|
|
should use the array returned by the
|
|
<B>backtrace_slots</B>
|
|
|
|
function of
|
|
the next section.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_raw_backtrace </I>
|
|
|
|
:
|
|
<B>unit -> raw_backtrace</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.get_raw_backtrace ()</B>
|
|
|
|
returns the same exception
|
|
backtrace that
|
|
<B>Printexc.print_backtrace</B>
|
|
|
|
would print, but in
|
|
a raw format. Same restriction usage than
|
|
<B>Printexc.print_backtrace</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_raw_backtrace </I>
|
|
|
|
:
|
|
<B>out_channel -> raw_backtrace -> unit</B>
|
|
|
|
<P>
|
|
Print a raw backtrace in the same format
|
|
<B>Printexc.print_backtrace</B>
|
|
|
|
uses.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val raw_backtrace_to_string </I>
|
|
|
|
:
|
|
<B>raw_backtrace -> string</B>
|
|
|
|
<P>
|
|
Return a string from a raw backtrace, in the same format
|
|
<B>Printexc.get_backtrace</B>
|
|
|
|
uses.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val raise_with_backtrace </I>
|
|
|
|
:
|
|
<B>exn -> raw_backtrace -> 'a</B>
|
|
|
|
<P>
|
|
Reraise the exception using the given raw_backtrace for the
|
|
origin of the exception
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.05.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Current call stack</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val get_callstack </I>
|
|
|
|
:
|
|
<B>int -> raw_backtrace</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.get_callstack n</B>
|
|
|
|
returns a description of the top of the
|
|
call stack on the current program point (for the current thread),
|
|
with at most
|
|
<B>n</B>
|
|
|
|
entries. (Note: this function is not related to
|
|
exceptions at all, despite being part of the
|
|
<B>Printexc</B>
|
|
|
|
module.)
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Uncaught exceptions</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val set_uncaught_exception_handler </I>
|
|
|
|
:
|
|
<B>(exn -> raw_backtrace -> unit) -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.set_uncaught_exception_handler fn</B>
|
|
|
|
registers
|
|
<B>fn</B>
|
|
|
|
as the handler
|
|
for uncaught exceptions. The default handler prints the exception and
|
|
backtrace on standard error output.
|
|
<P>
|
|
Note that when
|
|
<B>fn</B>
|
|
|
|
is called all the functions registered with
|
|
<B>at_exit</B>
|
|
|
|
have already been called. Because of this you must
|
|
make sure any output channel
|
|
<B>fn</B>
|
|
|
|
writes on is flushed.
|
|
<P>
|
|
Also note that exceptions raised by user code in the interactive toplevel
|
|
are not passed to this function as they are caught by the toplevel itself.
|
|
<P>
|
|
If
|
|
<B>fn</B>
|
|
|
|
raises an exception, both the exceptions passed to
|
|
<B>fn</B>
|
|
|
|
and raised
|
|
by
|
|
<B>fn</B>
|
|
|
|
will be printed with their respective backtrace.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Manipulation of backtrace information</H3>
|
|
|
|
<P>
|
|
These functions are used to traverse the slots of a raw backtrace
|
|
and extract information from them in a programmer-friendly format.
|
|
<P>
|
|
|
|
<I>type backtrace_slot </I>
|
|
|
|
<P>
|
|
<P>
|
|
The abstract type
|
|
<B>backtrace_slot</B>
|
|
|
|
represents a single slot of
|
|
a backtrace.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val backtrace_slots </I>
|
|
|
|
:
|
|
<B>raw_backtrace -> backtrace_slot array option</B>
|
|
|
|
<P>
|
|
Returns the slots of a raw backtrace, or
|
|
<B>None</B>
|
|
|
|
if none of them
|
|
contain useful information.
|
|
<P>
|
|
In the return array, the slot at index
|
|
<B>0</B>
|
|
|
|
corresponds to the most
|
|
recent function call, raise, or primitive
|
|
<B>get_backtrace</B>
|
|
|
|
call in
|
|
the trace.
|
|
<P>
|
|
Some possible reasons for returning
|
|
<B>None</B>
|
|
|
|
are as follow:
|
|
<P>
|
|
-none of the slots in the trace come from modules compiled with
|
|
debug information (
|
|
<B>-g</B>
|
|
|
|
)
|
|
<P>
|
|
-the program is a bytecode program that has not been linked with
|
|
debug information enabled (
|
|
<B>ocamlc -g</B>
|
|
|
|
)
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<I>type location </I>
|
|
|
|
= {
|
|
<BR> filename :
|
|
<B>string</B>
|
|
|
|
;
|
|
<BR> line_number :
|
|
<B>int</B>
|
|
|
|
;
|
|
<BR> start_char :
|
|
<B>int</B>
|
|
|
|
;
|
|
<BR> end_char :
|
|
<B>int</B>
|
|
|
|
;
|
|
<BR> }
|
|
<P>
|
|
<P>
|
|
The type of location information found in backtraces.
|
|
<B>start_char</B>
|
|
|
|
and
|
|
<B>end_char</B>
|
|
|
|
are positions relative to the beginning of the
|
|
line.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02
|
|
<P>
|
|
<P>
|
|
<I>module Slot : </I>
|
|
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Raw backtrace slots</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type raw_backtrace_slot </I>
|
|
|
|
<P>
|
|
<P>
|
|
This type allows direct access to raw backtrace slots, without any
|
|
conversion in an OCaml-usable data-structure. Being
|
|
process-specific, they must absolutely not be marshalled, and are
|
|
unsafe to use for this reason (marshalling them may not fail, but
|
|
un-marshalling and using the result will result in
|
|
undefined behavior).
|
|
<P>
|
|
Elements of this type can still be compared and hashed: when two
|
|
elements are equal, then they represent the same source location
|
|
(the converse is not necessarily true in presence of inlining,
|
|
for example).
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val raw_backtrace_length </I>
|
|
|
|
:
|
|
<B>raw_backtrace -> int</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>raw_backtrace_length bckt</B>
|
|
|
|
returns the number of slots in the
|
|
backtrace
|
|
<B>bckt</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_raw_backtrace_slot </I>
|
|
|
|
:
|
|
<B>raw_backtrace -> int -> raw_backtrace_slot</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>get_raw_backtrace_slot bckt pos</B>
|
|
|
|
returns the slot in position
|
|
<B>pos</B>
|
|
|
|
in the
|
|
backtrace
|
|
<B>bckt</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val convert_raw_backtrace_slot </I>
|
|
|
|
:
|
|
<B>raw_backtrace_slot -> backtrace_slot</B>
|
|
|
|
<P>
|
|
Extracts the user-friendly
|
|
<B>backtrace_slot</B>
|
|
|
|
from a low-level
|
|
<B>raw_backtrace_slot</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_raw_backtrace_next_slot </I>
|
|
|
|
:
|
|
<B>raw_backtrace_slot -> raw_backtrace_slot option</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>get_raw_backtrace_next_slot slot</B>
|
|
|
|
returns the next slot inlined, if any.
|
|
<P>
|
|
Sample code to iterate over all frames (inlined and non-inlined):
|
|
<B>(* Iterate over inlined frames *)</B>
|
|
|
|
|
|
|
|
<B>let rec iter_raw_backtrace_slot f slot =</B>
|
|
|
|
<B>f slot;</B>
|
|
|
|
<B>match get_raw_backtrace_next_slot slot with</B>
|
|
|
|
<B>| None -> ()</B>
|
|
|
|
<B>| Some slot' -> iter_raw_backtrace_slot f slot'</B>
|
|
|
|
<B>(* Iterate over stack frames *)</B>
|
|
|
|
|
|
|
|
<B>let iter_raw_backtrace f bt =</B>
|
|
|
|
<B>for i = 0 to raw_backtrace_length bt - 1 do</B>
|
|
|
|
<B>iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)</B>
|
|
|
|
<B>done</B>
|
|
|
|
<B></B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.04.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Exception slots</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val exn_slot_id </I>
|
|
|
|
:
|
|
<B>exn -> int</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.exn_slot_id</B>
|
|
|
|
returns an integer which uniquely identifies
|
|
the constructor used to create the exception value
|
|
<B>exn</B>
|
|
|
|
(in the current runtime).
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val exn_slot_name </I>
|
|
|
|
:
|
|
<B>exn -> string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Printexc.exn_slot_name exn</B>
|
|
|
|
returns the internal name of the constructor
|
|
used to create the exception value
|
|
<B>exn</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">Module</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
|
|
<DL>
|
|
<DT id="4"><A HREF="#lbAE">Raw backtraces</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">Current call stack</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">Uncaught exceptions</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">Manipulation of backtrace information</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">Raw backtrace slots</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">Exception slots</A><DD>
|
|
</DL>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:52 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|