1Stdlib.Printexc(3) OCaml library Stdlib.Printexc(3)
2
6 Stdlib.Printexc - no description
7
9 Module Stdlib.Printexc
10
12 Module Printexc
13 : (module Stdlib__printexc)
14 type t = exn = ..
22 The type of exception values.
25 val to_string : exn -> string
29 Printexc.to_string e returns a string representation of the exception e
32 .
33 val to_string_default : exn -> string
37 Printexc.to_string_default e returns a string representation of the
40 exception e , ignoring all registered exception printers.
41 Since 4.09
44 val print : ('a -> 'b) -> 'a -> 'b
48 Printexc.print fn x applies fn to x and returns the result. If the
51 evaluation of fn x raises any exception, the name of the exception is
52 printed on standard error output, and the exception is raised again.
53 The typical use is to catch and report exceptions that escape a func‐
54 tion application.
55 val catch : ('a -> 'b) -> 'a -> 'b
59 Printexc.catch fn x is similar to Printexc.print , but aborts the pro‐
62 gram with exit code 2 after printing the uncaught exception. This
63 function is deprecated: the runtime system is now able to print
64 uncaught exceptions as precisely as Printexc.catch does. Moreover,
65 calling Printexc.catch makes it harder to track the location of the
66 exception using the debugger or the stack backtrace facility. So, do
67 not use Printexc.catch in new code.
68 val print_backtrace : out_channel -> unit
72 Printexc.print_backtrace oc prints an exception backtrace on the output
75 channel oc . The backtrace lists the program locations where the
76 most-recently raised exception was raised and where it was propagated
77 through function calls.
78 If the call is not inside an exception handler, the returned backtrace
80 is unspecified. If the call is after some exception-catching code
81 (before in the handler, or in a when-guard during the matching of the
82 exception handler), the backtrace may correspond to a later exception
83 than the handled one.
84 Since 3.11.0
87 val get_backtrace : unit -> string
91 Printexc.get_backtrace () returns a string containing the same excep‐
94 tion backtrace that Printexc.print_backtrace would print. Same restric‐
95 tion usage than Printexc.print_backtrace .
96 Since 3.11.0
99 val record_backtrace : bool -> unit
103 Printexc.record_backtrace b turns recording of exception backtraces on
106 (if b = true ) or off (if b = false ). Initially, backtraces are not
107 recorded, unless the b flag is given to the program through the OCAML‐
108 RUNPARAM variable.
109 Since 3.11.0
112 val backtrace_status : unit -> bool
116 Printexc.backtrace_status() returns true if exception backtraces are
119 currently recorded, false if not.
120 Since 3.11.0
123 val register_printer : (exn -> string option) -> unit
127 Printexc.register_printer fn registers fn as an exception printer. The
130 printer should return None or raise an exception if it does not know
131 how to convert the passed exception, and Some
132 s with s the resulting string if it can convert the passed excep‐
133 tion. Exceptions raised by the printer are ignored.
134 When converting an exception into a string, the printers will be
136 invoked in the reverse order of their registrations, until a printer
137 returns a Some s value (if no such printer exists, the runtime will use
138 a generic printer).
139 When using this mechanism, one should be aware that an exception back‐
141 trace is attached to the thread that saw it raised, rather than to the
142 exception itself. Practically, it means that the code related to fn
143 should not use the backtrace if it has itself raised an exception
144 before.
145 Since 3.11.2
148 val use_printers : exn -> string option
152 Printexc.use_printers e returns None if there are no registered print‐
155 ers and Some s with else as the resulting string otherwise.
156 Since 4.09
159 Raw backtraces
164 type raw_backtrace
165 The abstract type raw_backtrace stores a backtrace in a low-level for‐
168 mat, instead of directly exposing them as string as the get_backtrace()
169 function does.
170 This allows delaying the formatting of backtraces to when they are
172 actually printed, which may be useful if you record more backtraces
173 than you print.
174 Raw backtraces cannot be marshalled. If you need marshalling, you
176 should use the array returned by the backtrace_slots function of the
177 next section.
178 Since 4.01.0
181 val get_raw_backtrace : unit -> raw_backtrace
185 Printexc.get_raw_backtrace () returns the same exception backtrace that
188 Printexc.print_backtrace would print, but in a raw format. Same
189 restriction usage than Printexc.print_backtrace .
190 Since 4.01.0
193 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
197 Print a raw backtrace in the same format Printexc.print_backtrace uses.
199 Since 4.01.0
202 val raw_backtrace_to_string : raw_backtrace -> string
206 Return a string from a raw backtrace, in the same format Print‐
208 exc.get_backtrace uses.
209 Since 4.01.0
212 val raise_with_backtrace : exn -> raw_backtrace -> 'a
216 Reraise the exception using the given raw_backtrace for the origin of
218 the exception
219 Since 4.05.0
222 Current call stack
227 val get_callstack : int -> raw_backtrace
228 Printexc.get_callstack n returns a description of the top of the call
231 stack on the current program point (for the current thread), with at
232 most n entries. (Note: this function is not related to exceptions at
233 all, despite being part of the Printexc module.)
234 Since 4.01.0
237 Uncaught exceptions
242 val default_uncaught_exception_handler : exn -> raw_backtrace -> unit
243 Printexc.default_uncaught_exception_handler prints the exception and
246 backtrace on standard error output.
247 Since 4.11
250 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
254 unit
255 Printexc.set_uncaught_exception_handler fn registers fn as the handler
258 for uncaught exceptions. The default handler is Print‐
259 exc.default_uncaught_exception_handler .
260 Note that when fn is called all the functions registered with at_exit
262 have already been called. Because of this you must make sure any output
263 channel fn writes on is flushed.
264 Also note that exceptions raised by user code in the interactive
266 toplevel are not passed to this function as they are caught by the
267 toplevel itself.
268 If fn raises an exception, both the exceptions passed to fn and raised
270 by fn will be printed with their respective backtrace.
271 Since 4.02.0
274 Manipulation of backtrace information
279 These functions are used to traverse the slots of a raw backtrace and
280 extract information from them in a programmer-friendly format.
281 type backtrace_slot
283 The abstract type backtrace_slot represents a single slot of a back‐
286 trace.
287 Since 4.02
290 val backtrace_slots : raw_backtrace -> backtrace_slot array option
294 Returns the slots of a raw backtrace, or None if none of them contain
296 useful information.
297 In the return array, the slot at index 0 corresponds to the most recent
299 function call, raise, or primitive get_backtrace call in the trace.
300 Some possible reasons for returning None are as follow:
302 -none of the slots in the trace come from modules compiled with debug
304 information ( -g )
305 -the program is a bytecode program that has not been linked with debug
307 information enabled ( ocamlc -g )
308 Since 4.02.0
312 type location = {
315 filename : string ;
316 line_number : int ;
317 start_char : int ;
318 end_char : int ;
319 }
320 The type of location information found in backtraces. start_char and
323 end_char are positions relative to the beginning of the line.
324 Since 4.02
327 module Slot : sig end
330 Since 4.02.0
333 Raw backtrace slots
338 type raw_backtrace_slot
339 This type allows direct access to raw backtrace slots, without any con‐
342 version in an OCaml-usable data-structure. Being process-specific, they
343 must absolutely not be marshalled, and are unsafe to use for this rea‐
344 son (marshalling them may not fail, but un-marshalling and using the
345 result will result in undefined behavior).
346 Elements of this type can still be compared and hashed: when two ele‐
348 ments are equal, then they represent the same source location (the con‐
349 verse is not necessarily true in presence of inlining, for example).
350 Since 4.02.0
353 val raw_backtrace_length : raw_backtrace -> int
357 raw_backtrace_length bckt returns the number of slots in the backtrace
360 bckt .
361 Since 4.02
364 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
368 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
371 backtrace bckt .
372 Since 4.02
375 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
379 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
381 trace_slot .
382 Since 4.02
385 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
389 trace_slot option
390 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
393 Sample code to iterate over all frames (inlined and non-inlined):
395 (* Iterate over inlined frames *)
396 let rec iter_raw_backtrace_slot f slot =
397 f slot;
398 match get_raw_backtrace_next_slot slot with
399 | None -> ()
400 | Some slot' -> iter_raw_backtrace_slot f slot'
401 (* Iterate over stack frames *)
403 let iter_raw_backtrace f bt =
404 for i = 0 to raw_backtrace_length bt - 1 do
405 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
406 done
407 Since 4.04.0
411 Exception slots
416 val exn_slot_id : exn -> int
417 Printexc.exn_slot_id returns an integer which uniquely identifies the
420 constructor used to create the exception value exn (in the current run‐
421 time).
422 Since 4.02.0
425 val exn_slot_name : exn -> string
429 Printexc.exn_slot_name exn returns the internal name of the constructor
432 used to create the exception value exn .
433 Since 4.02.0
436OCamldoc 2020-09-01 Stdlib.Printexc(3)