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 set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
243 unit
244 Printexc.set_uncaught_exception_handler fn registers fn as the handler
247 for uncaught exceptions. The default handler prints the exception and
248 backtrace on standard error output.
249 Note that when fn is called all the functions registered with at_exit
251 have already been called. Because of this you must make sure any output
252 channel fn writes on is flushed.
253 Also note that exceptions raised by user code in the interactive
255 toplevel are not passed to this function as they are caught by the
256 toplevel itself.
257 If fn raises an exception, both the exceptions passed to fn and raised
259 by fn will be printed with their respective backtrace.
260 Since 4.02.0
263 Manipulation of backtrace information
268 These functions are used to traverse the slots of a raw backtrace and
269 extract information from them in a programmer-friendly format.
270 type backtrace_slot
272 The abstract type backtrace_slot represents a single slot of a back‐
275 trace.
276 Since 4.02
279 val backtrace_slots : raw_backtrace -> backtrace_slot array option
283 Returns the slots of a raw backtrace, or None if none of them contain
285 useful information.
286 In the return array, the slot at index 0 corresponds to the most recent
288 function call, raise, or primitive get_backtrace call in the trace.
289 Some possible reasons for returning None are as follow:
291 -none of the slots in the trace come from modules compiled with debug
293 information ( -g )
294 -the program is a bytecode program that has not been linked with debug
296 information enabled ( ocamlc -g )
297 Since 4.02.0
301 type location = {
304 filename : string ;
305 line_number : int ;
306 start_char : int ;
307 end_char : int ;
308 }
309 The type of location information found in backtraces. start_char and
312 end_char are positions relative to the beginning of the line.
313 Since 4.02
316 module Slot : sig end
319 Since 4.02.0
322 Raw backtrace slots
327 type raw_backtrace_slot
328 This type allows direct access to raw backtrace slots, without any con‐
331 version in an OCaml-usable data-structure. Being process-specific, they
332 must absolutely not be marshalled, and are unsafe to use for this rea‐
333 son (marshalling them may not fail, but un-marshalling and using the
334 result will result in undefined behavior).
335 Elements of this type can still be compared and hashed: when two ele‐
337 ments are equal, then they represent the same source location (the con‐
338 verse is not necessarily true in presence of inlining, for example).
339 Since 4.02.0
342 val raw_backtrace_length : raw_backtrace -> int
346 raw_backtrace_length bckt returns the number of slots in the backtrace
349 bckt .
350 Since 4.02
353 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
357 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
360 backtrace bckt .
361 Since 4.02
364 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
368 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
370 trace_slot .
371 Since 4.02
374 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
378 trace_slot option
379 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
382 Sample code to iterate over all frames (inlined and non-inlined):
384 (* Iterate over inlined frames *)
385 let rec iter_raw_backtrace_slot f slot =
386 f slot;
387 match get_raw_backtrace_next_slot slot with
388 | None -> ()
389 | Some slot' -> iter_raw_backtrace_slot f slot'
390 (* Iterate over stack frames *)
392 let iter_raw_backtrace f bt =
393 for i = 0 to raw_backtrace_length bt - 1 do
394 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
395 done
396 Since 4.04.0
400 Exception slots
405 val exn_slot_id : exn -> int
406 Printexc.exn_slot_id returns an integer which uniquely identifies the
409 constructor used to create the exception value exn (in the current run‐
410 time).
411 Since 4.02.0
414 val exn_slot_name : exn -> string
418 Printexc.exn_slot_name exn returns the internal name of the constructor
421 used to create the exception value exn .
422 Since 4.02.0
425OCamldoc 2020-02-27 Stdlib.Printexc(3)