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 ex‐
40 ception 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 un‐
64 caught exceptions as precisely as Printexc.catch does. Moreover, call‐
65 ing Printexc.catch makes it harder to track the location of the excep‐
66 tion using the debugger or the stack backtrace facility. So, do not
67 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 (be‐
81 fore in the handler, or in a when-guard during the matching of the ex‐
82 ception 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 in‐
136 voked in the reverse order of their registrations, until a printer re‐
137 turns a Some s value (if no such printer exists, the runtime will use a
138 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 be‐
144 fore.
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 type raw_backtrace stores a backtrace in a low-level format, which
168 can be converted to usable form using raw_backtrace_entries and back‐
169 trace_slots_of_raw_entry below.
170 Converting backtraces to backtrace_slot s is slower than capturing the
172 backtraces. If an application processes many backtraces, it can be use‐
173 ful to use raw_backtrace to avoid or delay conversion.
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 type raw_backtrace_entry = private int
184 A raw_backtrace_entry is an element of a raw_backtrace .
187 Each raw_backtrace_entry is an opaque integer, whose value is not sta‐
189 ble between different programs, or even between different runs of the
190 same binary.
191 A raw_backtrace_entry can be converted to a usable form using back‐
193 trace_slots_of_raw_entry below. Note that, due to inlining, a single
194 raw_backtrace_entry may convert to several backtrace_slot s. Since the
195 values of a raw_backtrace_entry are not stable, they cannot be mar‐
196 shalled. If they are to be converted, the conversion must be done by
197 the process that generated them.
198 Again due to inlining, there may be multiple distinct raw_backtrace_en‐
200 try values that convert to equal backtrace_slot s. However, if two
201 raw_backtrace_entry s are equal as integers, then they represent the
202 same backtrace_slot s.
203 Since 4.12.0
206 val raw_backtrace_entries : raw_backtrace -> raw_backtrace_entry array
210 Since 4.12.0
212 val get_raw_backtrace : unit -> raw_backtrace
216 Printexc.get_raw_backtrace () returns the same exception backtrace that
219 Printexc.print_backtrace would print, but in a raw format. Same re‐
220 striction usage than Printexc.print_backtrace .
221 Since 4.01.0
224 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
228 Print a raw backtrace in the same format Printexc.print_backtrace uses.
230 Since 4.01.0
233 val raw_backtrace_to_string : raw_backtrace -> string
237 Return a string from a raw backtrace, in the same format Print‐
239 exc.get_backtrace uses.
240 Since 4.01.0
243 val raise_with_backtrace : exn -> raw_backtrace -> 'a
247 Reraise the exception using the given raw_backtrace for the origin of
249 the exception
250 Since 4.05.0
253 Current call stack
258 val get_callstack : int -> raw_backtrace
259 Printexc.get_callstack n returns a description of the top of the call
262 stack on the current program point (for the current thread), with at
263 most n entries. (Note: this function is not related to exceptions at
264 all, despite being part of the Printexc module.)
265 Since 4.01.0
268 Uncaught exceptions
273 val default_uncaught_exception_handler : exn -> raw_backtrace -> unit
274 Printexc.default_uncaught_exception_handler prints the exception and
277 backtrace on standard error output.
278 Since 4.11
281 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
285 unit
286 Printexc.set_uncaught_exception_handler fn registers fn as the handler
289 for uncaught exceptions. The default handler is Printexc.default_un‐
290 caught_exception_handler .
291 Note that when fn is called all the functions registered with at_exit
293 have already been called. Because of this you must make sure any output
294 channel fn writes on is flushed.
295 Also note that exceptions raised by user code in the interactive
297 toplevel are not passed to this function as they are caught by the
298 toplevel itself.
299 If fn raises an exception, both the exceptions passed to fn and raised
301 by fn will be printed with their respective backtrace.
302 Since 4.02.0
305 Manipulation of backtrace information
310 These functions are used to traverse the slots of a raw backtrace and
311 extract information from them in a programmer-friendly format.
312 type backtrace_slot
314 The abstract type backtrace_slot represents a single slot of a back‐
317 trace.
318 Since 4.02
321 val backtrace_slots : raw_backtrace -> backtrace_slot array option
325 Returns the slots of a raw backtrace, or None if none of them contain
327 useful information.
328 In the return array, the slot at index 0 corresponds to the most recent
330 function call, raise, or primitive get_backtrace call in the trace.
331 Some possible reasons for returning None are as follow:
333 -none of the slots in the trace come from modules compiled with debug
335 information ( -g )
336 -the program is a bytecode program that has not been linked with debug
338 information enabled ( ocamlc -g )
339 Since 4.02.0
343 val backtrace_slots_of_raw_entry : raw_backtrace_entry -> back‐
347 trace_slot array option
348 Returns the slots of a single raw backtrace entry, or None if this en‐
350 try lacks debug information.
351 Slots are returned in the same order as backtrace_slots : the slot at
353 index 0 is the most recent call, raise, or primitive, and subsequent
354 slots represent callers.
355 Since 4.12
358 type location = {
361 filename : string ;
362 line_number : int ;
363 start_char : int ;
364 end_char : int ;
365 }
366 The type of location information found in backtraces. start_char and
369 end_char are positions relative to the beginning of the line.
370 Since 4.02
373 module Slot : sig end
376 Since 4.02.0
379 Raw backtrace slots
384 type raw_backtrace_slot
385 This type is used to iterate over the slots of a raw_backtrace . For
388 most purposes, backtrace_slots_of_raw_entry is easier to use.
389 Like raw_backtrace_entry , values of this type are process-specific and
391 must absolutely not be marshalled, and are unsafe to use for this rea‐
392 son (marshalling them may not fail, but un-marshalling and using the
393 result will result in undefined behavior).
394 Elements of this type can still be compared and hashed: when two ele‐
396 ments are equal, then they represent the same source location (the con‐
397 verse is not necessarily true in presence of inlining, for example).
398 Since 4.02.0
401 val raw_backtrace_length : raw_backtrace -> int
405 raw_backtrace_length bckt returns the number of slots in the backtrace
408 bckt .
409 Since 4.02
412 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
416 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
419 backtrace bckt .
420 Since 4.02
423 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
427 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
429 trace_slot .
430 Since 4.02
433 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
437 trace_slot option
438 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
441 Sample code to iterate over all frames (inlined and non-inlined):
443 (* Iterate over inlined frames *)
444 let rec iter_raw_backtrace_slot f slot =
445 f slot;
446 match get_raw_backtrace_next_slot slot with
447 | None -> ()
448 | Some slot' -> iter_raw_backtrace_slot f slot'
449 (* Iterate over stack frames *)
451 let iter_raw_backtrace f bt =
452 for i = 0 to raw_backtrace_length bt - 1 do
453 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
454 done
455 Since 4.04.0
459 Exception slots
464 val exn_slot_id : exn -> int
465 Printexc.exn_slot_id returns an integer which uniquely identifies the
468 constructor used to create the exception value exn (in the current run‐
469 time).
470 Since 4.02.0
473 val exn_slot_name : exn -> string
477 Printexc.exn_slot_name exn returns the internal name of the constructor
480 used to create the exception value exn .
481 Since 4.02.0
484OCamldoc 2022-02-04 Stdlib.Printexc(3)