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 val to_string : exn -> string
25 Printexc.to_string e returns a string representation of the exception e
28 .
29 val print : ('a -> 'b) -> 'a -> 'b
33 Printexc.print fn x applies fn to x and returns the result. If the
36 evaluation of fn x raises any exception, the name of the exception is
37 printed on standard error output, and the exception is raised again.
38 The typical use is to catch and report exceptions that escape a func‐
39 tion application.
40 val catch : ('a -> 'b) -> 'a -> 'b
44 Printexc.catch fn x is similar to Printexc.print , but aborts the pro‐
47 gram with exit code 2 after printing the uncaught exception. This
48 function is deprecated: the runtime system is now able to print
49 uncaught exceptions as precisely as Printexc.catch does. Moreover,
50 calling Printexc.catch makes it harder to track the location of the
51 exception using the debugger or the stack backtrace facility. So, do
52 not use Printexc.catch in new code.
53 val print_backtrace : Pervasives.out_channel -> unit
57 Printexc.print_backtrace oc prints an exception backtrace on the output
60 channel oc . The backtrace lists the program locations where the
61 most-recently raised exception was raised and where it was propagated
62 through function calls.
63 If the call is not inside an exception handler, the returned backtrace
65 is unspecified. If the call is after some exception-catching code
66 (before in the handler, or in a when-guard during the matching of the
67 exception handler), the backtrace may correspond to a later exception
68 than the handled one.
69 Since 3.11.0
72 val get_backtrace : unit -> string
76 Printexc.get_backtrace () returns a string containing the same excep‐
79 tion backtrace that Printexc.print_backtrace would print. Same restric‐
80 tion usage than Printexc.print_backtrace .
81 Since 3.11.0
84 val record_backtrace : bool -> unit
88 Printexc.record_backtrace b turns recording of exception backtraces on
91 (if b = true ) or off (if b = false ). Initially, backtraces are not
92 recorded, unless the b flag is given to the program through the OCAML‐
93 RUNPARAM variable.
94 Since 3.11.0
97 val backtrace_status : unit -> bool
101 Printexc.backtrace_status() returns true if exception backtraces are
104 currently recorded, false if not.
105 Since 3.11.0
108 val register_printer : (exn -> string option) -> unit
112 Printexc.register_printer fn registers fn as an exception printer. The
115 printer should return None or raise an exception if it does not know
116 how to convert the passed exception, and Some s with s the resulting
117 string if it can convert the passed exception. Exceptions raised by the
118 printer are ignored.
119 When converting an exception into a string, the printers will be
121 invoked in the reverse order of their registrations, until a printer
122 returns a Some s value (if no such printer exists, the runtime will use
123 a generic printer).
124 When using this mechanism, one should be aware that an exception back‐
126 trace is attached to the thread that saw it raised, rather than to the
127 exception itself. Practically, it means that the code related to fn
128 should not use the backtrace if it has itself raised an exception
129 before.
130 Since 3.11.2
133 === Raw backtraces ===
138 type raw_backtrace
141 The abstract type raw_backtrace stores a backtrace in a low-level for‐
144 mat, instead of directly exposing them as string as the get_backtrace()
145 function does.
146 This allows delaying the formatting of backtraces to when they are
148 actually printed, which may be useful if you record more backtraces
149 than you print.
150 Raw backtraces cannot be marshalled. If you need marshalling, you
152 should use the array returned by the backtrace_slots function of the
153 next section.
154 Since 4.01.0
157 val get_raw_backtrace : unit -> raw_backtrace
161 Printexc.get_raw_backtrace () returns the same exception backtrace that
164 Printexc.print_backtrace would print, but in a raw format. Same
165 restriction usage than Printexc.print_backtrace .
166 Since 4.01.0
169 val print_raw_backtrace : Pervasives.out_channel -> raw_backtrace ->
173 unit
174 Print a raw backtrace in the same format Printexc.print_backtrace uses.
176 Since 4.01.0
179 val raw_backtrace_to_string : raw_backtrace -> string
183 Return a string from a raw backtrace, in the same format Print‐
185 exc.get_backtrace uses.
186 Since 4.01.0
189 val raise_with_backtrace : exn -> raw_backtrace -> 'a
193 Reraise the exception using the given raw_backtrace for the origin of
195 the exception
196 Since 4.05.0
199 === Current call stack ===
204 val get_callstack : int -> raw_backtrace
207 Printexc.get_callstack n returns a description of the top of the call
210 stack on the current program point (for the current thread), with at
211 most n entries. (Note: this function is not related to exceptions at
212 all, despite being part of the Printexc module.)
213 Since 4.01.0
216 === Uncaught exceptions ===
221 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
224 unit
225 Printexc.set_uncaught_exception_handler fn registers fn as the handler
228 for uncaught exceptions. The default handler prints the exception and
229 backtrace on standard error output.
230 Note that when fn is called all the functions registered with Perva‐
232 sives.at_exit have already been called. Because of this you must make
233 sure any output channel fn writes on is flushed.
234 Also note that exceptions raised by user code in the interactive
236 toplevel are not passed to this function as they are caught by the
237 toplevel itself.
238 If fn raises an exception, both the exceptions passed to fn and raised
240 by fn will be printed with their respective backtrace.
241 Since 4.02.0
244 === Manipulation of backtrace information These functions are used to
249 traverse the slots of a raw backtrace and extract information from them
250 in a programmer-friendly format. ===
251 type backtrace_slot
254 The abstract type backtrace_slot represents a single slot of a back‐
257 trace.
258 Since 4.02
261 val backtrace_slots : raw_backtrace -> backtrace_slot array option
265 Returns the slots of a raw backtrace, or None if none of them contain
267 useful information.
268 In the return array, the slot at index 0 corresponds to the most recent
270 function call, raise, or primitive get_backtrace call in the trace.
271 Some possible reasons for returning None are as follow:
273 -none of the slots in the trace come from modules compiled with debug
275 information ( -g )
276 -the program is a bytecode program that has not been linked with debug
278 information enabled ( ocamlc -g )
279 Since 4.02.0
283 type location = {
286 filename : string ;
287 line_number : int ;
288 start_char : int ;
289 end_char : int ;
290 }
291 The type of location information found in backtraces. start_char and
294 end_char are positions relative to the beginning of the line.
295 Since 4.02
298 module Slot : sig end
301 Since 4.02.0
304 === Raw backtrace slots ===
309 type raw_backtrace_slot
312 This type allows direct access to raw backtrace slots, without any con‐
315 version in an OCaml-usable data-structure. Being process-specific, they
316 must absolutely not be marshalled, and are unsafe to use for this rea‐
317 son (marshalling them may not fail, but un-marshalling and using the
318 result will result in undefined behavior).
319 Elements of this type can still be compared and hashed: when two ele‐
321 ments are equal, then they represent the same source location (the con‐
322 verse is not necessarily true in presence of inlining, for example).
323 Since 4.02.0
326 val raw_backtrace_length : raw_backtrace -> int
330 raw_backtrace_length bckt returns the number of slots in the backtrace
333 bckt .
334 Since 4.02
337 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
341 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
344 backtrace bckt .
345 Since 4.02
348 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
352 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
354 trace_slot .
355 Since 4.02
358 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
362 trace_slot option
363 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
366 Sample code to iterate over all frames (inlined and non-inlined): (*
368 Iterate over inlined frames *) let rec iter_raw_backtrace_slot f slot =
369 f slot; match get_raw_backtrace_next_slot slot with | None -> () | Some
370 slot' -> iter_raw_backtrace_slot f slot' (* Iterate over stack frames
371 *) let iter_raw_backtrace f bt = for i = 0 to raw_backtrace_length bt -
372 1 do iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i) done
373 Since 4.04.0
377 === Exception slots ===
382 val exn_slot_id : exn -> int
385 Printexc.exn_slot_id returns an integer which uniquely identifies the
388 constructor used to create the exception value exn (in the current run‐
389 time).
390 Since 4.02.0
393 val exn_slot_name : exn -> string
397 Printexc.exn_slot_name exn returns the internal name of the constructor
400 used to create the exception value exn .
401 Since 4.02.0
404OCamldoc 2019-02-02 Printexc(3)