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

FreeBSD Manual Pages


home | help
Printexc(3)			 OCaml library			   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.

       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.

       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.

       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

       === 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 Those function	allow to  tra-
       verse  the slots	of a raw backtrace, 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

       === 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_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

       === 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_id  exn  returns the internal name of the constructor
       used to create the exception value exn .

       Since 4.02.0

OCamldoc			  2017-04-30			   Printexc(3)

NAME | Module | Documentation

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

home | help