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 ex‐
42 ception 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 un‐
66 caught exceptions as precisely as Printexc.catch does. Moreover, call‐
67 ing Printexc.catch makes it harder to track the location of the excep‐
68 tion using the debugger or the stack backtrace facility. So, do not
69 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 (be‐
83 fore in the handler, or in a when-guard during the matching of the ex‐
84 ception 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 in‐
138 voked in the reverse order of their registrations, until a printer re‐
139 turns a Some s value (if no such printer exists, the runtime will use a
140 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 be‐
146 fore.
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 type raw_backtrace stores a backtrace in a low-level format, which
170 can be converted to usable form using raw_backtrace_entries and back‐
171 trace_slots_of_raw_entry below.
172 Converting backtraces to backtrace_slot s is slower than capturing the
174 backtraces. If an application processes many backtraces, it can be use‐
175 ful to use raw_backtrace to avoid or delay conversion.
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 type raw_backtrace_entry = private int
186 A raw_backtrace_entry is an element of a raw_backtrace .
189 Each raw_backtrace_entry is an opaque integer, whose value is not sta‐
191 ble between different programs, or even between different runs of the
192 same binary.
193 A raw_backtrace_entry can be converted to a usable form using back‐
195 trace_slots_of_raw_entry below. Note that, due to inlining, a single
196 raw_backtrace_entry may convert to several backtrace_slot s. Since the
197 values of a raw_backtrace_entry are not stable, they cannot be mar‐
198 shalled. If they are to be converted, the conversion must be done by
199 the process that generated them.
200 Again due to inlining, there may be multiple distinct raw_backtrace_en‐
202 try values that convert to equal backtrace_slot s. However, if two
203 raw_backtrace_entry s are equal as integers, then they represent the
204 same backtrace_slot s.
205 Since 4.12.0
208 val raw_backtrace_entries : raw_backtrace -> raw_backtrace_entry array
212 Since 4.12.0
214 val get_raw_backtrace : unit -> raw_backtrace
218 Printexc.get_raw_backtrace () returns the same exception backtrace that
221 Printexc.print_backtrace would print, but in a raw format. Same re‐
222 striction usage than Printexc.print_backtrace .
223 Since 4.01.0
226 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
230 Print a raw backtrace in the same format Printexc.print_backtrace uses.
232 Since 4.01.0
235 val raw_backtrace_to_string : raw_backtrace -> string
239 Return a string from a raw backtrace, in the same format Print‐
241 exc.get_backtrace uses.
242 Since 4.01.0
245 val raise_with_backtrace : exn -> raw_backtrace -> 'a
249 Reraise the exception using the given raw_backtrace for the origin of
251 the exception
252 Since 4.05.0
255 Current call stack
260 val get_callstack : int -> raw_backtrace
261 Printexc.get_callstack n returns a description of the top of the call
264 stack on the current program point (for the current thread), with at
265 most n entries. (Note: this function is not related to exceptions at
266 all, despite being part of the Printexc module.)
267 Since 4.01.0
270 Uncaught exceptions
275 val default_uncaught_exception_handler : exn -> raw_backtrace -> unit
276 Printexc.default_uncaught_exception_handler prints the exception and
279 backtrace on standard error output.
280 Since 4.11
283 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
287 unit
288 Printexc.set_uncaught_exception_handler fn registers fn as the handler
291 for uncaught exceptions. The default handler is Printexc.default_un‐
292 caught_exception_handler .
293 Note that when fn is called all the functions registered with at_exit
295 have already been called. Because of this you must make sure any output
296 channel fn writes on is flushed.
297 Also note that exceptions raised by user code in the interactive
299 toplevel are not passed to this function as they are caught by the
300 toplevel itself.
301 If fn raises an exception, both the exceptions passed to fn and raised
303 by fn will be printed with their respective backtrace.
304 Since 4.02.0
307 Manipulation of backtrace information
312 These functions are used to traverse the slots of a raw backtrace and
313 extract information from them in a programmer-friendly format.
314 type backtrace_slot
316 The abstract type backtrace_slot represents a single slot of a back‐
319 trace.
320 Since 4.02
323 val backtrace_slots : raw_backtrace -> backtrace_slot array option
327 Returns the slots of a raw backtrace, or None if none of them contain
329 useful information.
330 In the return array, the slot at index 0 corresponds to the most recent
332 function call, raise, or primitive get_backtrace call in the trace.
333 Some possible reasons for returning None are as follow:
335 -none of the slots in the trace come from modules compiled with debug
337 information ( -g )
338 -the program is a bytecode program that has not been linked with debug
340 information enabled ( ocamlc -g )
341 Since 4.02.0
345 val backtrace_slots_of_raw_entry : raw_backtrace_entry -> back‐
349 trace_slot array option
350 Returns the slots of a single raw backtrace entry, or None if this en‐
352 try lacks debug information.
353 Slots are returned in the same order as backtrace_slots : the slot at
355 index 0 is the most recent call, raise, or primitive, and subsequent
356 slots represent callers.
357 Since 4.12
360 type location = {
363 filename : string ;
364 line_number : int ;
365 start_char : int ;
366 end_char : int ;
367 }
368 The type of location information found in backtraces. start_char and
371 end_char are positions relative to the beginning of the line.
372 Since 4.02
375 module Slot : sig end
378 Since 4.02.0
381 Raw backtrace slots
386 type raw_backtrace_slot
387 This type is used to iterate over the slots of a raw_backtrace . For
390 most purposes, backtrace_slots_of_raw_entry is easier to use.
391 Like raw_backtrace_entry , values of this type are process-specific and
393 must absolutely not be marshalled, and are unsafe to use for this rea‐
394 son (marshalling them may not fail, but un-marshalling and using the
395 result will result in undefined behavior).
396 Elements of this type can still be compared and hashed: when two ele‐
398 ments are equal, then they represent the same source location (the con‐
399 verse is not necessarily true in presence of inlining, for example).
400 Since 4.02.0
403 val raw_backtrace_length : raw_backtrace -> int
407 raw_backtrace_length bckt returns the number of slots in the backtrace
410 bckt .
411 Since 4.02
414 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
418 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
421 backtrace bckt .
422 Since 4.02
425 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
429 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
431 trace_slot .
432 Since 4.02
435 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
439 trace_slot option
440 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
443 Sample code to iterate over all frames (inlined and non-inlined):
445 (* Iterate over inlined frames *)
446 let rec iter_raw_backtrace_slot f slot =
447 f slot;
448 match get_raw_backtrace_next_slot slot with
449 | None -> ()
450 | Some slot' -> iter_raw_backtrace_slot f slot'
451 (* Iterate over stack frames *)
453 let iter_raw_backtrace f bt =
454 for i = 0 to raw_backtrace_length bt - 1 do
455 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
456 done
457 Since 4.04.0
461 Exception slots
466 val exn_slot_id : exn -> int
467 Printexc.exn_slot_id returns an integer which uniquely identifies the
470 constructor used to create the exception value exn (in the current run‐
471 time).
472 Since 4.02.0
475 val exn_slot_name : exn -> string
479 Printexc.exn_slot_name exn returns the internal name of the constructor
482 used to create the exception value exn .
483 Since 4.02.0
486OCamldoc 2023-01-23 Printexc(3)