1Printexc(3) OCaml library Printexc(3)
2
6 Printexc - Facilities for printing exceptions and inspecting current
7 call stack.
8
10 Module Printexc
11
13 Module Printexc
14 : sig end
15 Facilities for printing exceptions and inspecting current call stack.
18 type t = exn = ..
24 The type of exception values.
27 val to_string : exn -> string
31 Printexc.to_string e returns a string representation of the exception e
34 .
35 val to_string_default : exn -> string
39 Printexc.to_string_default e returns a string representation of the
42 exception e , ignoring all registered exception printers.
43 Since 4.09
46 val print : ('a -> 'b) -> 'a -> 'b
50 Printexc.print fn x applies fn to x and returns the result. If the
53 evaluation of fn x raises any exception, the name of the exception is
54 printed on standard error output, and the exception is raised again.
55 The typical use is to catch and report exceptions that escape a func‐
56 tion application.
57 val catch : ('a -> 'b) -> 'a -> 'b
61 Printexc.catch fn x is similar to Printexc.print , but aborts the pro‐
64 gram with exit code 2 after printing the uncaught exception. This
65 function is deprecated: the runtime system is now able to print
66 uncaught exceptions as precisely as Printexc.catch does. Moreover,
67 calling Printexc.catch makes it harder to track the location of the
68 exception using the debugger or the stack backtrace facility. So, do
69 not use Printexc.catch in new code.
70 val print_backtrace : out_channel -> unit
74 Printexc.print_backtrace oc prints an exception backtrace on the output
77 channel oc . The backtrace lists the program locations where the
78 most-recently raised exception was raised and where it was propagated
79 through function calls.
80 If the call is not inside an exception handler, the returned backtrace
82 is unspecified. If the call is after some exception-catching code
83 (before in the handler, or in a when-guard during the matching of the
84 exception handler), the backtrace may correspond to a later exception
85 than the handled one.
86 Since 3.11.0
89 val get_backtrace : unit -> string
93 Printexc.get_backtrace () returns a string containing the same excep‐
96 tion backtrace that Printexc.print_backtrace would print. Same restric‐
97 tion usage than Printexc.print_backtrace .
98 Since 3.11.0
101 val record_backtrace : bool -> unit
105 Printexc.record_backtrace b turns recording of exception backtraces on
108 (if b = true ) or off (if b = false ). Initially, backtraces are not
109 recorded, unless the b flag is given to the program through the OCAML‐
110 RUNPARAM variable.
111 Since 3.11.0
114 val backtrace_status : unit -> bool
118 Printexc.backtrace_status() returns true if exception backtraces are
121 currently recorded, false if not.
122 Since 3.11.0
125 val register_printer : (exn -> string option) -> unit
129 Printexc.register_printer fn registers fn as an exception printer. The
132 printer should return None or raise an exception if it does not know
133 how to convert the passed exception, and Some
134 s with s the resulting string if it can convert the passed excep‐
135 tion. Exceptions raised by the printer are ignored.
136 When converting an exception into a string, the printers will be
138 invoked in the reverse order of their registrations, until a printer
139 returns a Some s value (if no such printer exists, the runtime will use
140 a generic printer).
141 When using this mechanism, one should be aware that an exception back‐
143 trace is attached to the thread that saw it raised, rather than to the
144 exception itself. Practically, it means that the code related to fn
145 should not use the backtrace if it has itself raised an exception
146 before.
147 Since 3.11.2
150 val use_printers : exn -> string option
154 Printexc.use_printers e returns None if there are no registered print‐
157 ers and Some s with else as the resulting string otherwise.
158 Since 4.09
161 Raw backtraces
166 type raw_backtrace
167 The abstract type raw_backtrace stores a backtrace in a low-level for‐
170 mat, instead of directly exposing them as string as the get_backtrace()
171 function does.
172 This allows delaying the formatting of backtraces to when they are
174 actually printed, which may be useful if you record more backtraces
175 than you print.
176 Raw backtraces cannot be marshalled. If you need marshalling, you
178 should use the array returned by the backtrace_slots function of the
179 next section.
180 Since 4.01.0
183 val get_raw_backtrace : unit -> raw_backtrace
187 Printexc.get_raw_backtrace () returns the same exception backtrace that
190 Printexc.print_backtrace would print, but in a raw format. Same
191 restriction usage than Printexc.print_backtrace .
192 Since 4.01.0
195 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
199 Print a raw backtrace in the same format Printexc.print_backtrace uses.
201 Since 4.01.0
204 val raw_backtrace_to_string : raw_backtrace -> string
208 Return a string from a raw backtrace, in the same format Print‐
210 exc.get_backtrace uses.
211 Since 4.01.0
214 val raise_with_backtrace : exn -> raw_backtrace -> 'a
218 Reraise the exception using the given raw_backtrace for the origin of
220 the exception
221 Since 4.05.0
224 Current call stack
229 val get_callstack : int -> raw_backtrace
230 Printexc.get_callstack n returns a description of the top of the call
233 stack on the current program point (for the current thread), with at
234 most n entries. (Note: this function is not related to exceptions at
235 all, despite being part of the Printexc module.)
236 Since 4.01.0
239 Uncaught exceptions
244 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
245 unit
246 Printexc.set_uncaught_exception_handler fn registers fn as the handler
249 for uncaught exceptions. The default handler prints the exception and
250 backtrace on standard error output.
251 Note that when fn is called all the functions registered with at_exit
253 have already been called. Because of this you must make sure any output
254 channel fn writes on is flushed.
255 Also note that exceptions raised by user code in the interactive
257 toplevel are not passed to this function as they are caught by the
258 toplevel itself.
259 If fn raises an exception, both the exceptions passed to fn and raised
261 by fn will be printed with their respective backtrace.
262 Since 4.02.0
265 Manipulation of backtrace information
270 These functions are used to traverse the slots of a raw backtrace and
271 extract information from them in a programmer-friendly format.
272 type backtrace_slot
274 The abstract type backtrace_slot represents a single slot of a back‐
277 trace.
278 Since 4.02
281 val backtrace_slots : raw_backtrace -> backtrace_slot array option
285 Returns the slots of a raw backtrace, or None if none of them contain
287 useful information.
288 In the return array, the slot at index 0 corresponds to the most recent
290 function call, raise, or primitive get_backtrace call in the trace.
291 Some possible reasons for returning None are as follow:
293 -none of the slots in the trace come from modules compiled with debug
295 information ( -g )
296 -the program is a bytecode program that has not been linked with debug
298 information enabled ( ocamlc -g )
299 Since 4.02.0
303 type location = {
306 filename : string ;
307 line_number : int ;
308 start_char : int ;
309 end_char : int ;
310 }
311 The type of location information found in backtraces. start_char and
314 end_char are positions relative to the beginning of the line.
315 Since 4.02
318 module Slot : sig end
321 Since 4.02.0
324 Raw backtrace slots
329 type raw_backtrace_slot
330 This type allows direct access to raw backtrace slots, without any con‐
333 version in an OCaml-usable data-structure. Being process-specific, they
334 must absolutely not be marshalled, and are unsafe to use for this rea‐
335 son (marshalling them may not fail, but un-marshalling and using the
336 result will result in undefined behavior).
337 Elements of this type can still be compared and hashed: when two ele‐
339 ments are equal, then they represent the same source location (the con‐
340 verse is not necessarily true in presence of inlining, for example).
341 Since 4.02.0
344 val raw_backtrace_length : raw_backtrace -> int
348 raw_backtrace_length bckt returns the number of slots in the backtrace
351 bckt .
352 Since 4.02
355 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
359 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
362 backtrace bckt .
363 Since 4.02
366 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
370 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
372 trace_slot .
373 Since 4.02
376 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
380 trace_slot option
381 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
384 Sample code to iterate over all frames (inlined and non-inlined):
386 (* Iterate over inlined frames *)
387 let rec iter_raw_backtrace_slot f slot =
388 f slot;
389 match get_raw_backtrace_next_slot slot with
390 | None -> ()
391 | Some slot' -> iter_raw_backtrace_slot f slot'
392 (* Iterate over stack frames *)
394 let iter_raw_backtrace f bt =
395 for i = 0 to raw_backtrace_length bt - 1 do
396 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
397 done
398 Since 4.04.0
402 Exception slots
407 val exn_slot_id : exn -> int
408 Printexc.exn_slot_id returns an integer which uniquely identifies the
411 constructor used to create the exception value exn (in the current run‐
412 time).
413 Since 4.02.0
416 val exn_slot_name : exn -> string
420 Printexc.exn_slot_name exn returns the internal name of the constructor
423 used to create the exception value exn .
424 Since 4.02.0
427OCamldoc 2020-02-27 Printexc(3)