Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Printexc(3)			   OCamldoc			   Printexc(3)

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

       Module	Printexc

       Module Printexc
	: sig end

       Facilities for printing exceptions and inspecting current call stack.

       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	 func-
       tion application.

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

       Printexc.catch  fn x is similar to Printexc.print , but aborts the pro-
       gram with exit code 2 after  printing  the  uncaught  exception.	  This
       function	 is  deprecated:  the  runtime system is now able to print un-
       caught exceptions as precisely as Printexc.catch	does.  Moreover, call-
       ing  Printexc.catch makes it harder to track the	location of the	excep-
       tion using the debugger or the stack backtrace facility.	  So,  do  not
       use Printexc.catch in new code.

       val print_backtrace : Pervasives.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 (be-
       fore in the handler, or in a when-guard during the matching of the  ex-
       ception	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	excep-
       tion backtrace that Printexc.print_backtrace would print. Same restric-
       tion 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	OCAML-
       RUNPARAM	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  in-
       voked  in the reverse order of their registrations, until a printer re-
       turns 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 back-
       trace 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  be-

       Since 3.11.2

       === Raw backtraces ===

       type raw_backtrace

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

       This  allows delaying the formatting of backtraces to when they are ac-
       tually 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  re-
       striction usage than Printexc.print_backtrace .

       Since 4.01.0

       val  print_raw_backtrace	 :  Pervasives.out_channel -> raw_backtrace ->

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

       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	Perva-
       sives.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 back-

       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 con-
       version in an OCaml-usable data-structure. Being	process-specific, they
       must  absolutely	not be marshalled, and are unsafe to use for this rea-
       son (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 ele-
       ments are equal,	then they represent the	same source location (the con-
       verse 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_back-
       trace_slot .

       Since 4.02

       val  get_raw_backtrace_next_slot	 :  raw_backtrace_slot	->   raw_back-
       trace_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 run-

       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

2021-03-01			    source:			   Printexc(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:

home | help