NAME

       Stdlib.Printexc - no description

Module

       Module   Stdlib.Printexc

Documentation

       Module Printexc
        : (module Stdlib__printexc)

       type t = exn = ..

       The type of exception values.

       val to_string : exn -> string

       Printexc.to_string e returns a string representation of the exception e .

       val print : ('a -> 'b) -> 'a -> 'b

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

       val catch : ('a -> 'b) -> 'a -> 'b

       Printexc.catch fn x is similar to 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  Printexc.catch  does.   Moreover,
       calling  Printexc.catch  makes  it harder to track the location of the exception using the
       debugger or the stack backtrace facility.  So, do not use Printexc.catch in new code.

       val print_backtrace : out_channel -> unit

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

       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.

       Since 3.11.0

       val get_backtrace : unit -> string

       Printexc.get_backtrace  ()  returns  a string containing the same exception backtrace that
       Printexc.print_backtrace would print. Same restriction usage than Printexc.print_backtrace
       .

       Since 3.11.0

       val record_backtrace : bool -> unit

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

       Since 3.11.0

       val backtrace_status : unit -> bool

       Printexc.backtrace_status()  returns  true if exception backtraces are currently recorded,
       false if not.

       Since 3.11.0

       val register_printer : (exn -> string option) -> unit

       Printexc.register_printer fn registers fn as an exception  printer.   The  printer  should
       return None or raise an exception if it does not know how to convert the passed exception,
       and Some s with s the resulting string if it can convert the passed exception.  Exceptions
       raised by the printer are ignored.

       When  converting  an  exception into a string, the printers will be invoked in the reverse
       order of their registrations, until a printer returns a Some s value (if no  such  printer
       exists, the runtime will use a generic printer).

       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  fn  should  not use the backtrace if it has itself raised an
       exception before.

       Since 3.11.2

   Raw backtraces
       type raw_backtrace

       The abstract type raw_backtrace stores a backtrace  in  a  low-level  format,  instead  of
       directly exposing them as string as the get_backtrace() function does.

       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.

       Raw backtraces cannot be marshalled. If you need marshalling, you  should  use  the  array
       returned by the backtrace_slots function of the next section.

       Since 4.01.0

       val get_raw_backtrace : unit -> raw_backtrace

       Printexc.get_raw_backtrace    ()    returns    the    same    exception   backtrace   that
       Printexc.print_backtrace would print, but in a raw format.  Same  restriction  usage  than
       Printexc.print_backtrace .

       Since 4.01.0

       val print_raw_backtrace : out_channel -> raw_backtrace -> unit

       Print a raw backtrace in the same format Printexc.print_backtrace uses.

       Since 4.01.0

       val raw_backtrace_to_string : raw_backtrace -> string

       Return a string from a raw backtrace, in the same format Printexc.get_backtrace uses.

       Since 4.01.0

       val raise_with_backtrace : exn -> raw_backtrace -> 'a

       Reraise the exception using the given raw_backtrace for the origin of the exception

       Since 4.05.0

   Current call stack
       val get_callstack : int -> raw_backtrace

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

       Since 4.01.0

   Uncaught exceptions
       val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) -> unit

       Printexc.set_uncaught_exception_handler  fn  registers  fn  as  the  handler  for uncaught
       exceptions. The default handler prints the  exception  and  backtrace  on  standard  error
       output.

       Note  that  when  fn is called all the functions registered with at_exit have already been
       called. Because of this you must make sure any output channel fn writes on is flushed.

       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.

       If  fn  raises  an  exception,  both  the exceptions passed to fn and raised by fn will be
       printed with their respective backtrace.

       Since 4.02.0

   Manipulation of backtrace information
       These functions are used to traverse the slots of a raw backtrace and extract  information
       from them in a programmer-friendly format.

       type backtrace_slot

       The abstract type backtrace_slot represents a single slot of a backtrace.

       Since 4.02

       val backtrace_slots : raw_backtrace -> backtrace_slot array option

       Returns the slots of a raw backtrace, or None if none of them contain useful information.

       In  the  return  array,  the slot at index 0 corresponds to the most recent function call,
       raise, or primitive get_backtrace call in the trace.

       Some possible reasons for returning None are as follow:

       -none of the slots in the trace come from modules compiled with debug information ( -g )

       -the program is a bytecode program that has not been linked with debug information enabled
       ( ocamlc -g )

       Since 4.02.0

       type location = {
        filename : string ;
        line_number : int ;
        start_char : int ;
        end_char : int ;
        }

       The  type  of  location  information  found  in  backtraces.   start_char and end_char are
       positions relative to the beginning of the line.

       Since 4.02

       module Slot : sig end

       Since 4.02.0

   Raw backtrace slots
       type raw_backtrace_slot

       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).

       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).

       Since 4.02.0

       val raw_backtrace_length : raw_backtrace -> int

       raw_backtrace_length bckt returns the number of slots in the backtrace bckt .

       Since 4.02

       val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot

       get_raw_backtrace_slot bckt pos returns the slot in position pos in the backtrace bckt .

       Since 4.02

       val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot

       Extracts the user-friendly backtrace_slot from a low-level raw_backtrace_slot .

       Since 4.02

       val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_backtrace_slot option

       get_raw_backtrace_next_slot slot returns the next slot inlined, if any.

       Sample  code to iterate over all frames (inlined and non-inlined): (* Iterate over inlined
       frames   *)   let   rec   iter_raw_backtrace_slot    f    slot    =    f    slot;    match
       get_raw_backtrace_next_slot slot with | None -> () | Some slot' -> iter_raw_backtrace_slot
       f slot' (* Iterate over stack frames *) let iter_raw_backtrace  f  bt  =  for  i  =  0  to
       raw_backtrace_length  bt  -  1  do iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
       done

       Since 4.04.0

   Exception slots
       val exn_slot_id : exn -> int

       Printexc.exn_slot_id returns an integer which uniquely identifies the constructor used  to
       create the exception value exn (in the current runtime).

       Since 4.02.0

       val exn_slot_name : exn -> string

       Printexc.exn_slot_name exn returns the internal name of the constructor used to create the
       exception value exn .

       Since 4.02.0