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 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 ac‐
174 tually printed, which may be useful if you record more backtraces than
175 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 re‐
191 striction 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 default_uncaught_exception_handler : exn -> raw_backtrace -> unit
245 Printexc.default_uncaught_exception_handler prints the exception and
248 backtrace on standard error output.
249 Since 4.11
252 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
256 unit
257 Printexc.set_uncaught_exception_handler fn registers fn as the handler
260 for uncaught exceptions. The default handler is Printexc.default_un‐
261 caught_exception_handler .
262 Note that when fn is called all the functions registered with at_exit
264 have already been called. Because of this you must make sure any output
265 channel fn writes on is flushed.
266 Also note that exceptions raised by user code in the interactive
268 toplevel are not passed to this function as they are caught by the
269 toplevel itself.
270 If fn raises an exception, both the exceptions passed to fn and raised
272 by fn will be printed with their respective backtrace.
273 Since 4.02.0
276 Manipulation of backtrace information
281 These functions are used to traverse the slots of a raw backtrace and
282 extract information from them in a programmer-friendly format.
283 type backtrace_slot
285 The abstract type backtrace_slot represents a single slot of a back‐
288 trace.
289 Since 4.02
292 val backtrace_slots : raw_backtrace -> backtrace_slot array option
296 Returns the slots of a raw backtrace, or None if none of them contain
298 useful information.
299 In the return array, the slot at index 0 corresponds to the most recent
301 function call, raise, or primitive get_backtrace call in the trace.
302 Some possible reasons for returning None are as follow:
304 -none of the slots in the trace come from modules compiled with debug
306 information ( -g )
307 -the program is a bytecode program that has not been linked with debug
309 information enabled ( ocamlc -g )
310 Since 4.02.0
314 type location = {
317 filename : string ;
318 line_number : int ;
319 start_char : int ;
320 end_char : int ;
321 }
322 The type of location information found in backtraces. start_char and
325 end_char are positions relative to the beginning of the line.
326 Since 4.02
329 module Slot : sig end
332 Since 4.02.0
335 Raw backtrace slots
340 type raw_backtrace_slot
341 This type allows direct access to raw backtrace slots, without any con‐
344 version in an OCaml-usable data-structure. Being process-specific, they
345 must absolutely not be marshalled, and are unsafe to use for this rea‐
346 son (marshalling them may not fail, but un-marshalling and using the
347 result will result in undefined behavior).
348 Elements of this type can still be compared and hashed: when two ele‐
350 ments are equal, then they represent the same source location (the con‐
351 verse is not necessarily true in presence of inlining, for example).
352 Since 4.02.0
355 val raw_backtrace_length : raw_backtrace -> int
359 raw_backtrace_length bckt returns the number of slots in the backtrace
362 bckt .
363 Since 4.02
366 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
370 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
373 backtrace bckt .
374 Since 4.02
377 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
381 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
383 trace_slot .
384 Since 4.02
387 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
391 trace_slot option
392 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
395 Sample code to iterate over all frames (inlined and non-inlined):
397 (* Iterate over inlined frames *)
398 let rec iter_raw_backtrace_slot f slot =
399 f slot;
400 match get_raw_backtrace_next_slot slot with
401 | None -> ()
402 | Some slot' -> iter_raw_backtrace_slot f slot'
403 (* Iterate over stack frames *)
405 let iter_raw_backtrace f bt =
406 for i = 0 to raw_backtrace_length bt - 1 do
407 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
408 done
409 Since 4.04.0
413 Exception slots
418 val exn_slot_id : exn -> int
419 Printexc.exn_slot_id returns an integer which uniquely identifies the
422 constructor used to create the exception value exn (in the current run‐
423 time).
424 Since 4.02.0
427 val exn_slot_name : exn -> string
431 Printexc.exn_slot_name exn returns the internal name of the constructor
434 used to create the exception value exn .
435 Since 4.02.0
438OCamldoc 2021-01-26 Printexc(3)