.TH "Printexc" 3o 2014-10-30 OCamldoc "OCaml library"
.SH NAME
Printexc \- Facilities for printing exceptions and inspecting current call stack.
.SH Module
Module   Printexc
.SH Documentation
.sp
Module
.BI "Printexc"
 : 
.B sig  end

.sp
Facilities for printing exceptions and inspecting current call stack\&.
.sp

.sp

.sp
.sp

.I val to_string 
: 
.B exn -> string
.sp

.B Printexc\&.to_string e
returns a string representation of
the exception 
.B e
\&.
.sp

.sp

.I val print 
: 
.B ('a -> 'b) -> 'a -> 'b
.sp

.B Printexc\&.print fn x
applies 
.B fn
to 
.B x
and returns the result\&.
If the evaluation of 
.B fn x
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\&.
.sp

.sp

.I val catch 
: 
.B ('a -> 'b) -> 'a -> 'b
.sp

.B Printexc\&.catch fn x
is similar to 
.B Printexc\&.print
, 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
does\&.  Moreover, calling 
.B Printexc\&.catch
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
in new code\&.
.sp

.sp

.I val print_backtrace 
: 
.B Pervasives.out_channel -> unit
.sp

.B Printexc\&.print_backtrace oc
prints an exception backtrace
on the output channel 
.B oc
\&.  The backtrace lists the program
locations where the most\-recently raised exception was raised
and where it was propagated through function calls\&.
.sp
.B "Since"
3.11.0
.sp

.sp

.I val get_backtrace 
: 
.B unit -> string
.sp

.B Printexc\&.get_backtrace ()
returns a string containing the
same exception backtrace that 
.B Printexc\&.print_backtrace
would
print\&.
.sp
.B "Since"
3.11.0
.sp

.sp

.I val record_backtrace 
: 
.B bool -> unit
.sp

.B Printexc\&.record_backtrace b
turns recording of exception backtraces
on (if 
.B b = true
) or off (if 
.B b = false
)\&.  Initially, backtraces
are not recorded, unless the 
.B b
flag is given to the program
through the 
.B OCAMLRUNPARAM
variable\&.
.sp
.B "Since"
3.11.0
.sp

.sp

.I val backtrace_status 
: 
.B unit -> bool
.sp

.B Printexc\&.backtrace_status()
returns 
.B true
if exception
backtraces are currently recorded, 
.B false
if not\&.
.sp
.B "Since"
3.11.0
.sp

.sp

.I val register_printer 
: 
.B (exn -> string option) -> unit
.sp

.B Printexc\&.register_printer fn
registers 
.B fn
as an exception
printer\&.  The printer should return 
.B None
or raise an exception
if it does not know how to convert the passed exception, and 
.B Some
.B     s
with 
.B s
the resulting string if it can convert the passed
exception\&. Exceptions raised by the printer are ignored\&.
.sp
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
value (if no such printer exists, the runtime will use a
generic printer)\&.
.sp
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
should not use
the backtrace if it has itself raised an exception before\&.
.sp
.B "Since"
3.11.2
.sp

.sp

.PP

.B === 
.B Raw backtraces
.B  ===

.PP
.I type raw_backtrace 

.sp

.sp

.PP

.B === The abstract type backtrace stores exception backtraces in
.B     a low\-level format, instead of directly exposing them as string as
.B     the get_backtrace() function does\&.
.B 
.B     This allows delaying the formatting of backtraces to when they are
.B     actually printed, which might be useful if you record more
.B     backtraces than you print\&. ===

.PP

.I val get_raw_backtrace 
: 
.B unit -> raw_backtrace
.sp

.sp

.I val print_raw_backtrace 
: 
.B Pervasives.out_channel -> raw_backtrace -> unit
.sp

.sp

.I val raw_backtrace_to_string 
: 
.B raw_backtrace -> string
.sp

.sp

.PP

.B === 
.B Current call stack
.B  ===

.PP

.I val get_callstack 
: 
.B int -> raw_backtrace
.sp

.sp

.PP

.B === Printexc\&.get_callstack n returns a description of the top of the
.B     call stack on the current program point (for the current thread),
.B     with at most n entries\&.  (Note: this function is not related to
.B     exceptions at all, despite being part of the Printexc module\&.) ===

.PP