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 Deprecated. This function is no longer needed.
63 Printexc.catch fn x is similar to Printexc.print , but aborts the pro‐
67 gram with exit code 2 after printing the uncaught exception. This
68 function is deprecated: the runtime system is now able to print un‐
69 caught exceptions as precisely as Printexc.catch does. Moreover, call‐
70 ing Printexc.catch makes it harder to track the location of the excep‐
71 tion using the debugger or the stack backtrace facility. So, do not
72 use Printexc.catch in new code.
73 val print_backtrace : out_channel -> unit
77 Printexc.print_backtrace oc prints an exception backtrace on the output
80 channel oc . The backtrace lists the program locations where the
81 most-recently raised exception was raised and where it was propagated
82 through function calls.
83 If the call is not inside an exception handler, the returned backtrace
85 is unspecified. If the call is after some exception-catching code (be‐
86 fore in the handler, or in a when-guard during the matching of the ex‐
87 ception handler), the backtrace may correspond to a later exception
88 than the handled one.
89 Since 3.11.0
92 val get_backtrace : unit -> string
96 Printexc.get_backtrace () returns a string containing the same excep‐
99 tion backtrace that Printexc.print_backtrace would print. Same restric‐
100 tion usage than Printexc.print_backtrace .
101 Since 3.11.0
104 val record_backtrace : bool -> unit
108 Printexc.record_backtrace b turns recording of exception backtraces on
111 (if b = true ) or off (if b = false ). Initially, backtraces are not
112 recorded, unless the b flag is given to the program through the OCAML‐
113 RUNPARAM variable.
114 Since 3.11.0
117 val backtrace_status : unit -> bool
121 Printexc.backtrace_status() returns true if exception backtraces are
124 currently recorded, false if not.
125 Since 3.11.0
128 val register_printer : (exn -> string option) -> unit
132 Printexc.register_printer fn registers fn as an exception printer. The
135 printer should return None or raise an exception if it does not know
136 how to convert the passed exception, and Some
137 s with s the resulting string if it can convert the passed excep‐
138 tion. Exceptions raised by the printer are ignored.
139 When converting an exception into a string, the printers will be in‐
141 voked in the reverse order of their registrations, until a printer re‐
142 turns a Some s value (if no such printer exists, the runtime will use a
143 generic printer).
144 When using this mechanism, one should be aware that an exception back‐
146 trace is attached to the thread that saw it raised, rather than to the
147 exception itself. Practically, it means that the code related to fn
148 should not use the backtrace if it has itself raised an exception be‐
149 fore.
150 Since 3.11.2
153 val use_printers : exn -> string option
157 Printexc.use_printers e returns None if there are no registered print‐
160 ers and Some s with else as the resulting string otherwise.
161 Since 4.09
164 Raw backtraces
169 type raw_backtrace
170 The type raw_backtrace stores a backtrace in a low-level format, which
173 can be converted to usable form using raw_backtrace_entries and back‐
174 trace_slots_of_raw_entry below.
175 Converting backtraces to backtrace_slot s is slower than capturing the
177 backtraces. If an application processes many backtraces, it can be use‐
178 ful to use raw_backtrace to avoid or delay conversion.
179 Raw backtraces cannot be marshalled. If you need marshalling, you
181 should use the array returned by the backtrace_slots function of the
182 next section.
183 Since 4.01.0
186 type raw_backtrace_entry = private int
189 A raw_backtrace_entry is an element of a raw_backtrace .
192 Each raw_backtrace_entry is an opaque integer, whose value is not sta‐
194 ble between different programs, or even between different runs of the
195 same binary.
196 A raw_backtrace_entry can be converted to a usable form using back‐
198 trace_slots_of_raw_entry below. Note that, due to inlining, a single
199 raw_backtrace_entry may convert to several backtrace_slot s. Since the
200 values of a raw_backtrace_entry are not stable, they cannot be mar‐
201 shalled. If they are to be converted, the conversion must be done by
202 the process that generated them.
203 Again due to inlining, there may be multiple distinct raw_backtrace_en‐
205 try values that convert to equal backtrace_slot s. However, if two
206 raw_backtrace_entry s are equal as integers, then they represent the
207 same backtrace_slot s.
208 Since 4.12.0
211 val raw_backtrace_entries : raw_backtrace -> raw_backtrace_entry array
215 Since 4.12.0
217 val get_raw_backtrace : unit -> raw_backtrace
221 Printexc.get_raw_backtrace () returns the same exception backtrace that
224 Printexc.print_backtrace would print, but in a raw format. Same re‐
225 striction usage than Printexc.print_backtrace .
226 Since 4.01.0
229 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
233 Print a raw backtrace in the same format Printexc.print_backtrace uses.
235 Since 4.01.0
238 val raw_backtrace_to_string : raw_backtrace -> string
242 Return a string from a raw backtrace, in the same format Print‐
244 exc.get_backtrace uses.
245 Since 4.01.0
248 val raise_with_backtrace : exn -> raw_backtrace -> 'a
252 Reraise the exception using the given raw_backtrace for the origin of
254 the exception
255 Since 4.05.0
258 Current call stack
263 val get_callstack : int -> raw_backtrace
264 Printexc.get_callstack n returns a description of the top of the call
267 stack on the current program point (for the current thread), with at
268 most n entries. (Note: this function is not related to exceptions at
269 all, despite being part of the Printexc module.)
270 Since 4.01.0
273 Uncaught exceptions
278 val default_uncaught_exception_handler : exn -> raw_backtrace -> unit
279 Printexc.default_uncaught_exception_handler prints the exception and
282 backtrace on standard error output.
283 Since 4.11
286 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
290 unit
291 Printexc.set_uncaught_exception_handler fn registers fn as the handler
294 for uncaught exceptions. The default handler is Printexc.default_un‐
295 caught_exception_handler .
296 Note that when fn is called all the functions registered with at_exit
298 have already been called. Because of this you must make sure any output
299 channel fn writes on is flushed.
300 Also note that exceptions raised by user code in the interactive
302 toplevel are not passed to this function as they are caught by the
303 toplevel itself.
304 If fn raises an exception, both the exceptions passed to fn and raised
306 by fn will be printed with their respective backtrace.
307 Since 4.02.0
310 Manipulation of backtrace information
315 These functions are used to traverse the slots of a raw backtrace and
316 extract information from them in a programmer-friendly format.
317 type backtrace_slot
319 The abstract type backtrace_slot represents a single slot of a back‐
322 trace.
323 Since 4.02
326 val backtrace_slots : raw_backtrace -> backtrace_slot array option
330 Returns the slots of a raw backtrace, or None if none of them contain
332 useful information.
333 In the return array, the slot at index 0 corresponds to the most recent
335 function call, raise, or primitive get_backtrace call in the trace.
336 Some possible reasons for returning None are as follow:
338 -none of the slots in the trace come from modules compiled with debug
340 information ( -g )
341 -the program is a bytecode program that has not been linked with debug
343 information enabled ( ocamlc -g )
344 Since 4.02.0
348 val backtrace_slots_of_raw_entry : raw_backtrace_entry -> back‐
352 trace_slot array option
353 Returns the slots of a single raw backtrace entry, or None if this en‐
355 try lacks debug information.
356 Slots are returned in the same order as backtrace_slots : the slot at
358 index 0 is the most recent call, raise, or primitive, and subsequent
359 slots represent callers.
360 Since 4.12
363 type location = {
366 filename : string ;
367 line_number : int ;
368 start_char : int ;
369 end_char : int ;
370 }
371 The type of location information found in backtraces. start_char and
374 end_char are positions relative to the beginning of the line.
375 Since 4.02
378 module Slot : sig end
381 Since 4.02.0
384 Raw backtrace slots
389 type raw_backtrace_slot
390 This type is used to iterate over the slots of a raw_backtrace . For
393 most purposes, backtrace_slots_of_raw_entry is easier to use.
394 Like raw_backtrace_entry , values of this type are process-specific and
396 must absolutely not be marshalled, and are unsafe to use for this rea‐
397 son (marshalling them may not fail, but un-marshalling and using the
398 result will result in undefined behavior).
399 Elements of this type can still be compared and hashed: when two ele‐
401 ments are equal, then they represent the same source location (the con‐
402 verse is not necessarily true in presence of inlining, for example).
403 Since 4.02.0
406 val raw_backtrace_length : raw_backtrace -> int
410 raw_backtrace_length bckt returns the number of slots in the backtrace
413 bckt .
414 Since 4.02
417 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
421 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
424 backtrace bckt .
425 Since 4.02
428 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
432 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
434 trace_slot .
435 Since 4.02
438 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
442 trace_slot option
443 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
446 Sample code to iterate over all frames (inlined and non-inlined):
448 (* Iterate over inlined frames *)
449 let rec iter_raw_backtrace_slot f slot =
450 f slot;
451 match get_raw_backtrace_next_slot slot with
452 | None -> ()
453 | Some slot' -> iter_raw_backtrace_slot f slot'
454 (* Iterate over stack frames *)
456 let iter_raw_backtrace f bt =
457 for i = 0 to raw_backtrace_length bt - 1 do
458 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
459 done
460 Since 4.04.0
464 Exception slots
469 val exn_slot_id : exn -> int
470 Printexc.exn_slot_id returns an integer which uniquely identifies the
473 constructor used to create the exception value exn (in the current run‐
474 time).
475 Since 4.02.0
478 val exn_slot_name : exn -> string
482 Printexc.exn_slot_name exn returns the internal name of the constructor
485 used to create the exception value exn .
486 Since 4.02.0
489OCamldoc 2023-07-20 Printexc(3)