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 Deprecated. This function is no longer needed.
61 Printexc.catch fn x is similar to Printexc.print , but aborts the pro‐
65 gram with exit code 2 after printing the uncaught exception. This
66 function is deprecated: the runtime system is now able to print un‐
67 caught exceptions as precisely as Printexc.catch does. Moreover, call‐
68 ing Printexc.catch makes it harder to track the location of the excep‐
69 tion using the debugger or the stack backtrace facility. So, do not
70 use Printexc.catch in new code.
71 val print_backtrace : out_channel -> unit
75 Printexc.print_backtrace oc prints an exception backtrace on the output
78 channel oc . The backtrace lists the program locations where the
79 most-recently raised exception was raised and where it was propagated
80 through function calls.
81 If the call is not inside an exception handler, the returned backtrace
83 is unspecified. If the call is after some exception-catching code (be‐
84 fore in the handler, or in a when-guard during the matching of the ex‐
85 ception handler), the backtrace may correspond to a later exception
86 than the handled one.
87 Since 3.11.0
90 val get_backtrace : unit -> string
94 Printexc.get_backtrace () returns a string containing the same excep‐
97 tion backtrace that Printexc.print_backtrace would print. Same restric‐
98 tion usage than Printexc.print_backtrace .
99 Since 3.11.0
102 val record_backtrace : bool -> unit
106 Printexc.record_backtrace b turns recording of exception backtraces on
109 (if b = true ) or off (if b = false ). Initially, backtraces are not
110 recorded, unless the b flag is given to the program through the OCAML‐
111 RUNPARAM variable.
112 Since 3.11.0
115 val backtrace_status : unit -> bool
119 Printexc.backtrace_status() returns true if exception backtraces are
122 currently recorded, false if not.
123 Since 3.11.0
126 val register_printer : (exn -> string option) -> unit
130 Printexc.register_printer fn registers fn as an exception printer. The
133 printer should return None or raise an exception if it does not know
134 how to convert the passed exception, and Some
135 s with s the resulting string if it can convert the passed excep‐
136 tion. Exceptions raised by the printer are ignored.
137 When converting an exception into a string, the printers will be in‐
139 voked in the reverse order of their registrations, until a printer re‐
140 turns a Some s value (if no such printer exists, the runtime will use a
141 generic printer).
142 When using this mechanism, one should be aware that an exception back‐
144 trace is attached to the thread that saw it raised, rather than to the
145 exception itself. Practically, it means that the code related to fn
146 should not use the backtrace if it has itself raised an exception be‐
147 fore.
148 Since 3.11.2
151 val use_printers : exn -> string option
155 Printexc.use_printers e returns None if there are no registered print‐
158 ers and Some s with else as the resulting string otherwise.
159 Since 4.09
162 Raw backtraces
167 type raw_backtrace
168 The type raw_backtrace stores a backtrace in a low-level format, which
171 can be converted to usable form using raw_backtrace_entries and back‐
172 trace_slots_of_raw_entry below.
173 Converting backtraces to backtrace_slot s is slower than capturing the
175 backtraces. If an application processes many backtraces, it can be use‐
176 ful to use raw_backtrace to avoid or delay conversion.
177 Raw backtraces cannot be marshalled. If you need marshalling, you
179 should use the array returned by the backtrace_slots function of the
180 next section.
181 Since 4.01.0
184 type raw_backtrace_entry = private int
187 A raw_backtrace_entry is an element of a raw_backtrace .
190 Each raw_backtrace_entry is an opaque integer, whose value is not sta‐
192 ble between different programs, or even between different runs of the
193 same binary.
194 A raw_backtrace_entry can be converted to a usable form using back‐
196 trace_slots_of_raw_entry below. Note that, due to inlining, a single
197 raw_backtrace_entry may convert to several backtrace_slot s. Since the
198 values of a raw_backtrace_entry are not stable, they cannot be mar‐
199 shalled. If they are to be converted, the conversion must be done by
200 the process that generated them.
201 Again due to inlining, there may be multiple distinct raw_backtrace_en‐
203 try values that convert to equal backtrace_slot s. However, if two
204 raw_backtrace_entry s are equal as integers, then they represent the
205 same backtrace_slot s.
206 Since 4.12.0
209 val raw_backtrace_entries : raw_backtrace -> raw_backtrace_entry array
213 Since 4.12.0
215 val get_raw_backtrace : unit -> raw_backtrace
219 Printexc.get_raw_backtrace () returns the same exception backtrace that
222 Printexc.print_backtrace would print, but in a raw format. Same re‐
223 striction usage than Printexc.print_backtrace .
224 Since 4.01.0
227 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
231 Print a raw backtrace in the same format Printexc.print_backtrace uses.
233 Since 4.01.0
236 val raw_backtrace_to_string : raw_backtrace -> string
240 Return a string from a raw backtrace, in the same format Print‐
242 exc.get_backtrace uses.
243 Since 4.01.0
246 val raise_with_backtrace : exn -> raw_backtrace -> 'a
250 Reraise the exception using the given raw_backtrace for the origin of
252 the exception
253 Since 4.05.0
256 Current call stack
261 val get_callstack : int -> raw_backtrace
262 Printexc.get_callstack n returns a description of the top of the call
265 stack on the current program point (for the current thread), with at
266 most n entries. (Note: this function is not related to exceptions at
267 all, despite being part of the Printexc module.)
268 Since 4.01.0
271 Uncaught exceptions
276 val default_uncaught_exception_handler : exn -> raw_backtrace -> unit
277 Printexc.default_uncaught_exception_handler prints the exception and
280 backtrace on standard error output.
281 Since 4.11
284 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
288 unit
289 Printexc.set_uncaught_exception_handler fn registers fn as the handler
292 for uncaught exceptions. The default handler is Printexc.default_un‐
293 caught_exception_handler .
294 Note that when fn is called all the functions registered with at_exit
296 have already been called. Because of this you must make sure any output
297 channel fn writes on is flushed.
298 Also note that exceptions raised by user code in the interactive
300 toplevel are not passed to this function as they are caught by the
301 toplevel itself.
302 If fn raises an exception, both the exceptions passed to fn and raised
304 by fn will be printed with their respective backtrace.
305 Since 4.02.0
308 Manipulation of backtrace information
313 These functions are used to traverse the slots of a raw backtrace and
314 extract information from them in a programmer-friendly format.
315 type backtrace_slot
317 The abstract type backtrace_slot represents a single slot of a back‐
320 trace.
321 Since 4.02
324 val backtrace_slots : raw_backtrace -> backtrace_slot array option
328 Returns the slots of a raw backtrace, or None if none of them contain
330 useful information.
331 In the return array, the slot at index 0 corresponds to the most recent
333 function call, raise, or primitive get_backtrace call in the trace.
334 Some possible reasons for returning None are as follow:
336 -none of the slots in the trace come from modules compiled with debug
338 information ( -g )
339 -the program is a bytecode program that has not been linked with debug
341 information enabled ( ocamlc -g )
342 Since 4.02.0
346 val backtrace_slots_of_raw_entry : raw_backtrace_entry -> back‐
350 trace_slot array option
351 Returns the slots of a single raw backtrace entry, or None if this en‐
353 try lacks debug information.
354 Slots are returned in the same order as backtrace_slots : the slot at
356 index 0 is the most recent call, raise, or primitive, and subsequent
357 slots represent callers.
358 Since 4.12
361 type location = {
364 filename : string ;
365 line_number : int ;
366 start_char : int ;
367 end_char : int ;
368 }
369 The type of location information found in backtraces. start_char and
372 end_char are positions relative to the beginning of the line.
373 Since 4.02
376 module Slot : sig end
379 Since 4.02.0
382 Raw backtrace slots
387 type raw_backtrace_slot
388 This type is used to iterate over the slots of a raw_backtrace . For
391 most purposes, backtrace_slots_of_raw_entry is easier to use.
392 Like raw_backtrace_entry , values of this type are process-specific and
394 must absolutely not be marshalled, and are unsafe to use for this rea‐
395 son (marshalling them may not fail, but un-marshalling and using the
396 result will result in undefined behavior).
397 Elements of this type can still be compared and hashed: when two ele‐
399 ments are equal, then they represent the same source location (the con‐
400 verse is not necessarily true in presence of inlining, for example).
401 Since 4.02.0
404 val raw_backtrace_length : raw_backtrace -> int
408 raw_backtrace_length bckt returns the number of slots in the backtrace
411 bckt .
412 Since 4.02
415 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
419 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
422 backtrace bckt .
423 Since 4.02
426 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
430 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
432 trace_slot .
433 Since 4.02
436 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
440 trace_slot option
441 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
444 Sample code to iterate over all frames (inlined and non-inlined):
446 (* Iterate over inlined frames *)
447 let rec iter_raw_backtrace_slot f slot =
448 f slot;
449 match get_raw_backtrace_next_slot slot with
450 | None -> ()
451 | Some slot' -> iter_raw_backtrace_slot f slot'
452 (* Iterate over stack frames *)
454 let iter_raw_backtrace f bt =
455 for i = 0 to raw_backtrace_length bt - 1 do
456 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
457 done
458 Since 4.04.0
462 Exception slots
467 val exn_slot_id : exn -> int
468 Printexc.exn_slot_id returns an integer which uniquely identifies the
471 constructor used to create the exception value exn (in the current run‐
472 time).
473 Since 4.02.0
476 val exn_slot_name : exn -> string
480 Printexc.exn_slot_name exn returns the internal name of the constructor
483 used to create the exception value exn .
484 Since 4.02.0
487OCamldoc 2023-07-20 Stdlib.Printexc(3)