Printexc - Facilities for printing exceptions and inspecting current call stack.

       Module Printexc
        : sigend

       Facilities for printing exceptions and inspecting current call stack.

       typet = exn = ..

       The type of exception values.

       valto_string : exn->stringPrintexc.to_stringe returns a string representation of the exception e .

       valto_string_default : exn->stringPrintexc.to_string_defaulte returns a string representation of the exception e , ignoring all registered
       exception printers.

       Since 4.09

       valprint : ('a->'b)->'a->'bPrintexc.printfnx  applies  fn  to  x  and  returns the result.  If the evaluation of fnx 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.

       valcatch : ('a->'b)->'a->'bDeprecated.  This function is no longer needed.

       Printexc.catchfnx 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.

       valprint_backtrace : out_channel->unitPrintexc.print_backtraceoc 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

       valget_backtrace : unit->stringPrintexc.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

       valrecord_backtrace : bool->unitPrintexc.record_backtraceb 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

       valbacktrace_status : unit->boolPrintexc.backtrace_status() returns true if exception backtraces are currently recorded, false if not.

       Since 3.11

       valregister_printer : (exn->stringoption)->unitPrintexc.register_printerfn 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 Somes  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 Somes 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

       valuse_printers : exn->stringoptionPrintexc.use_printerse returns None if there are no registered printers and Somes with s the resulting
       string otherwise.

       Since 4.09

   Rawbacktracestyperaw_backtrace

       The type raw_backtrace stores a backtrace in a low-level format, which can be converted  to  usable  form
       using raw_backtrace_entries and backtrace_slots_of_raw_entry below.

       Converting  backtraces  to  backtrace_slot  s  is slower than capturing the backtraces. If an application
       processes many backtraces, it can be useful to use raw_backtrace to avoid or delay conversion.

       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

       typeraw_backtrace_entry = private int

       A raw_backtrace_entry is an element of a raw_backtrace .

       Each  raw_backtrace_entry  is an opaque integer, whose value is not stable between different programs, or
       even between different runs of the same binary.

       A raw_backtrace_entry can be converted to a usable form using  backtrace_slots_of_raw_entry  below.  Note
       that,  due  to inlining, a single raw_backtrace_entry may convert to several backtrace_slot s.  Since the
       values of a raw_backtrace_entry are not stable, they cannot be marshalled. If they are to  be  converted,
       the conversion must be done by the process that generated them.

       Again  due  to  inlining, there may be multiple distinct raw_backtrace_entry values that convert to equal
       backtrace_slot s. However, if two raw_backtrace_entry s are equal as integers, then  they  represent  the
       same backtrace_slot s.

       Since 4.12

       valraw_backtrace_entries : raw_backtrace->raw_backtrace_entryarraySince 4.12

       valget_raw_backtrace : unit->raw_backtracePrintexc.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

       valprint_raw_backtrace : out_channel->raw_backtrace->unit

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

       Since 4.01

       valraw_backtrace_to_string : raw_backtrace->string

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

       Since 4.01

       valraise_with_backtrace : exn->raw_backtrace->'a

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

       Since 4.05

   Currentcallstackvalget_callstack : int->raw_backtracePrintexc.get_callstackn 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

   Uncaughtexceptionsvaldefault_uncaught_exception_handler : exn->raw_backtrace->unitPrintexc.default_uncaught_exception_handler prints the exception and backtrace on standard error output.

       Since 4.11

       valset_uncaught_exception_handler : (exn->raw_backtrace->unit)->unitPrintexc.set_uncaught_exception_handlerfn registers fn as  the  handler  for  uncaught  exceptions.  The
       default handler is Printexc.default_uncaught_exception_handler .

       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

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

       typebacktrace_slot

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

       Since 4.02

       valbacktrace_slots : raw_backtrace->backtrace_slotarrayoption

       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

       valbacktrace_slots_of_raw_entry : raw_backtrace_entry->backtrace_slotarrayoption

       Returns the slots of a single raw backtrace entry, or None if this entry lacks debug information.

       Slots  are  returned  in the same order as backtrace_slots : the slot at index 0 is the most recent call,
       raise, or primitive, and subsequent slots represent callers.

       Since 4.12

       typelocation = {
        filename : string ;
        line_number : int ;
        start_char : int ;
        end_char : int ;
        end_line : int ;  (* .B "Since" 5.2
        *)
        end_col : int ;  (* .B "Since" 5.2
        *)
        }

       The type of location information found in backtraces.  start_char and end_char are positions relative  to
       the beginning of line_number .  end_col is relative to the beginning of end_line .

       Since 4.02

       moduleSlot:sigendSince 4.02

   Rawbacktraceslotstyperaw_backtrace_slot

       This   type   is   used   to   iterate   over  the  slots  of  a  raw_backtrace  .   For  most  purposes,
       backtrace_slots_of_raw_entry is easier to use.

       Like raw_backtrace_entry ,  values  of  this  type  are  process-specific  and  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

       valraw_backtrace_length : raw_backtrace->intraw_backtrace_lengthbckt returns the number of slots in the backtrace bckt .

       Since 4.02

       valget_raw_backtrace_slot : raw_backtrace->int->raw_backtrace_slotget_raw_backtrace_slotbcktpos returns the slot in position pos in the backtrace bckt .

       Since 4.02

       valconvert_raw_backtrace_slot : raw_backtrace_slot->backtrace_slot

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

       Since 4.02

       valget_raw_backtrace_next_slot : raw_backtrace_slot->raw_backtrace_slotoptionget_raw_backtrace_next_slotslot returns the next slot inlined, if any.

       Sample code to iterate over all frames (inlined and non-inlined):
             (*Iterateoverinlinedframes*)letreciter_raw_backtrace_slotfslot=fslot;matchget_raw_backtrace_next_slotslotwith|None->()|Someslot'->iter_raw_backtrace_slotfslot'(*Iterateoverstackframes*)letiter_raw_backtracefbt=fori=0toraw_backtrace_lengthbt-1doiter_raw_backtrace_slotf(get_raw_backtrace_slotbti)doneSince 4.04

   Exceptionslotsvalexn_slot_id : exn->intPrintexc.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

       valexn_slot_name : exn->stringPrintexc.exn_slot_nameexn returns the internal name of the constructor  used  to  create  the  exception
       value exn .

       Since 4.02

OCamldoc                                           2025-06-12                                       Printexc(3o)

       Module   Printexc

       Printexc - Facilities for printing exceptions and inspecting current call stack.