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 print : ('a -> 'b) -> 'a -> 'b
39 Printexc.print fn x applies fn to x and returns the result. If the
42 evaluation of fn x raises any exception, the name of the exception is
43 printed on standard error output, and the exception is raised again.
44 The typical use is to catch and report exceptions that escape a func‐
45 tion application.
46 val catch : ('a -> 'b) -> 'a -> 'b
50 Printexc.catch fn x is similar to Printexc.print , but aborts the pro‐
53 gram with exit code 2 after printing the uncaught exception. This
54 function is deprecated: the runtime system is now able to print
55 uncaught exceptions as precisely as Printexc.catch does. Moreover,
56 calling Printexc.catch makes it harder to track the location of the
57 exception using the debugger or the stack backtrace facility. So, do
58 not use Printexc.catch in new code.
59 val print_backtrace : out_channel -> unit
63 Printexc.print_backtrace oc prints an exception backtrace on the output
66 channel oc . The backtrace lists the program locations where the
67 most-recently raised exception was raised and where it was propagated
68 through function calls.
69 If the call is not inside an exception handler, the returned backtrace
71 is unspecified. If the call is after some exception-catching code
72 (before in the handler, or in a when-guard during the matching of the
73 exception handler), the backtrace may correspond to a later exception
74 than the handled one.
75 Since 3.11.0
78 val get_backtrace : unit -> string
82 Printexc.get_backtrace () returns a string containing the same excep‐
85 tion backtrace that Printexc.print_backtrace would print. Same restric‐
86 tion usage than Printexc.print_backtrace .
87 Since 3.11.0
90 val record_backtrace : bool -> unit
94 Printexc.record_backtrace b turns recording of exception backtraces on
97 (if b = true ) or off (if b = false ). Initially, backtraces are not
98 recorded, unless the b flag is given to the program through the OCAML‐
99 RUNPARAM variable.
100 Since 3.11.0
103 val backtrace_status : unit -> bool
107 Printexc.backtrace_status() returns true if exception backtraces are
110 currently recorded, false if not.
111 Since 3.11.0
114 val register_printer : (exn -> string option) -> unit
118 Printexc.register_printer fn registers fn as an exception printer. The
121 printer should return None or raise an exception if it does not know
122 how to convert the passed exception, and Some s with s the resulting
123 string if it can convert the passed exception. Exceptions raised by the
124 printer are ignored.
125 When converting an exception into a string, the printers will be
127 invoked in the reverse order of their registrations, until a printer
128 returns a Some s value (if no such printer exists, the runtime will use
129 a generic printer).
130 When using this mechanism, one should be aware that an exception back‐
132 trace is attached to the thread that saw it raised, rather than to the
133 exception itself. Practically, it means that the code related to fn
134 should not use the backtrace if it has itself raised an exception
135 before.
136 Since 3.11.2
139 Raw backtraces
144 type raw_backtrace
145 The abstract type raw_backtrace stores a backtrace in a low-level for‐
148 mat, instead of directly exposing them as string as the get_backtrace()
149 function does.
150 This allows delaying the formatting of backtraces to when they are
152 actually printed, which may be useful if you record more backtraces
153 than you print.
154 Raw backtraces cannot be marshalled. If you need marshalling, you
156 should use the array returned by the backtrace_slots function of the
157 next section.
158 Since 4.01.0
161 val get_raw_backtrace : unit -> raw_backtrace
165 Printexc.get_raw_backtrace () returns the same exception backtrace that
168 Printexc.print_backtrace would print, but in a raw format. Same
169 restriction usage than Printexc.print_backtrace .
170 Since 4.01.0
173 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
177 Print a raw backtrace in the same format Printexc.print_backtrace uses.
179 Since 4.01.0
182 val raw_backtrace_to_string : raw_backtrace -> string
186 Return a string from a raw backtrace, in the same format Print‐
188 exc.get_backtrace uses.
189 Since 4.01.0
192 val raise_with_backtrace : exn -> raw_backtrace -> 'a
196 Reraise the exception using the given raw_backtrace for the origin of
198 the exception
199 Since 4.05.0
202 Current call stack
207 val get_callstack : int -> raw_backtrace
208 Printexc.get_callstack n returns a description of the top of the call
211 stack on the current program point (for the current thread), with at
212 most n entries. (Note: this function is not related to exceptions at
213 all, despite being part of the Printexc module.)
214 Since 4.01.0
217 Uncaught exceptions
222 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
223 unit
224 Printexc.set_uncaught_exception_handler fn registers fn as the handler
227 for uncaught exceptions. The default handler prints the exception and
228 backtrace on standard error output.
229 Note that when fn is called all the functions registered with at_exit
231 have already been called. Because of this you must make sure any output
232 channel fn writes on is flushed.
233 Also note that exceptions raised by user code in the interactive
235 toplevel are not passed to this function as they are caught by the
236 toplevel itself.
237 If fn raises an exception, both the exceptions passed to fn and raised
239 by fn will be printed with their respective backtrace.
240 Since 4.02.0
243 Manipulation of backtrace information
248 These functions are used to traverse the slots of a raw backtrace and
249 extract information from them in a programmer-friendly format.
250 type backtrace_slot
252 The abstract type backtrace_slot represents a single slot of a back‐
255 trace.
256 Since 4.02
259 val backtrace_slots : raw_backtrace -> backtrace_slot array option
263 Returns the slots of a raw backtrace, or None if none of them contain
265 useful information.
266 In the return array, the slot at index 0 corresponds to the most recent
268 function call, raise, or primitive get_backtrace call in the trace.
269 Some possible reasons for returning None are as follow:
271 -none of the slots in the trace come from modules compiled with debug
273 information ( -g )
274 -the program is a bytecode program that has not been linked with debug
276 information enabled ( ocamlc -g )
277 Since 4.02.0
281 type location = {
284 filename : string ;
285 line_number : int ;
286 start_char : int ;
287 end_char : int ;
288 }
289 The type of location information found in backtraces. start_char and
292 end_char are positions relative to the beginning of the line.
293 Since 4.02
296 module Slot : sig end
299 Since 4.02.0
302 Raw backtrace slots
307 type raw_backtrace_slot
308 This type allows direct access to raw backtrace slots, without any con‐
311 version in an OCaml-usable data-structure. Being process-specific, they
312 must absolutely not be marshalled, and are unsafe to use for this rea‐
313 son (marshalling them may not fail, but un-marshalling and using the
314 result will result in undefined behavior).
315 Elements of this type can still be compared and hashed: when two ele‐
317 ments are equal, then they represent the same source location (the con‐
318 verse is not necessarily true in presence of inlining, for example).
319 Since 4.02.0
322 val raw_backtrace_length : raw_backtrace -> int
326 raw_backtrace_length bckt returns the number of slots in the backtrace
329 bckt .
330 Since 4.02
333 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
337 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
340 backtrace bckt .
341 Since 4.02
344 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
348 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
350 trace_slot .
351 Since 4.02
354 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
358 trace_slot option
359 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
362 Sample code to iterate over all frames (inlined and non-inlined): (*
364 Iterate over inlined frames *) let rec iter_raw_backtrace_slot f slot =
365 f slot; match get_raw_backtrace_next_slot slot with | None -> () | Some
366 slot' -> iter_raw_backtrace_slot f slot' (* Iterate over stack frames
367 *) let iter_raw_backtrace f bt = for i = 0 to raw_backtrace_length bt -
368 1 do iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i) done
369 Since 4.04.0
373 Exception slots
378 val exn_slot_id : exn -> int
379 Printexc.exn_slot_id returns an integer which uniquely identifies the
382 constructor used to create the exception value exn (in the current run‐
383 time).
384 Since 4.02.0
387 val exn_slot_name : exn -> string
391 Printexc.exn_slot_name exn returns the internal name of the constructor
394 used to create the exception value exn .
395 Since 4.02.0
398OCamldoc 2019-07-30 Printexc(3)