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 print : ('a -> 'b) -> 'a -> 'b
37 Printexc.print fn x applies fn to x and returns the result. If the
40 evaluation of fn x raises any exception, the name of the exception is
41 printed on standard error output, and the exception is raised again.
42 The typical use is to catch and report exceptions that escape a func‐
43 tion application.
44 val catch : ('a -> 'b) -> 'a -> 'b
48 Printexc.catch fn x is similar to Printexc.print , but aborts the pro‐
51 gram with exit code 2 after printing the uncaught exception. This
52 function is deprecated: the runtime system is now able to print
53 uncaught exceptions as precisely as Printexc.catch does. Moreover,
54 calling Printexc.catch makes it harder to track the location of the
55 exception using the debugger or the stack backtrace facility. So, do
56 not use Printexc.catch in new code.
57 val print_backtrace : out_channel -> unit
61 Printexc.print_backtrace oc prints an exception backtrace on the output
64 channel oc . The backtrace lists the program locations where the
65 most-recently raised exception was raised and where it was propagated
66 through function calls.
67 If the call is not inside an exception handler, the returned backtrace
69 is unspecified. If the call is after some exception-catching code
70 (before in the handler, or in a when-guard during the matching of the
71 exception handler), the backtrace may correspond to a later exception
72 than the handled one.
73 Since 3.11.0
76 val get_backtrace : unit -> string
80 Printexc.get_backtrace () returns a string containing the same excep‐
83 tion backtrace that Printexc.print_backtrace would print. Same restric‐
84 tion usage than Printexc.print_backtrace .
85 Since 3.11.0
88 val record_backtrace : bool -> unit
92 Printexc.record_backtrace b turns recording of exception backtraces on
95 (if b = true ) or off (if b = false ). Initially, backtraces are not
96 recorded, unless the b flag is given to the program through the OCAML‐
97 RUNPARAM variable.
98 Since 3.11.0
101 val backtrace_status : unit -> bool
105 Printexc.backtrace_status() returns true if exception backtraces are
108 currently recorded, false if not.
109 Since 3.11.0
112 val register_printer : (exn -> string option) -> unit
116 Printexc.register_printer fn registers fn as an exception printer. The
119 printer should return None or raise an exception if it does not know
120 how to convert the passed exception, and Some s with s the resulting
121 string if it can convert the passed exception. Exceptions raised by the
122 printer are ignored.
123 When converting an exception into a string, the printers will be
125 invoked in the reverse order of their registrations, until a printer
126 returns a Some s value (if no such printer exists, the runtime will use
127 a generic printer).
128 When using this mechanism, one should be aware that an exception back‐
130 trace is attached to the thread that saw it raised, rather than to the
131 exception itself. Practically, it means that the code related to fn
132 should not use the backtrace if it has itself raised an exception
133 before.
134 Since 3.11.2
137 Raw backtraces
142 type raw_backtrace
143 The abstract type raw_backtrace stores a backtrace in a low-level for‐
146 mat, instead of directly exposing them as string as the get_backtrace()
147 function does.
148 This allows delaying the formatting of backtraces to when they are
150 actually printed, which may be useful if you record more backtraces
151 than you print.
152 Raw backtraces cannot be marshalled. If you need marshalling, you
154 should use the array returned by the backtrace_slots function of the
155 next section.
156 Since 4.01.0
159 val get_raw_backtrace : unit -> raw_backtrace
163 Printexc.get_raw_backtrace () returns the same exception backtrace that
166 Printexc.print_backtrace would print, but in a raw format. Same
167 restriction usage than Printexc.print_backtrace .
168 Since 4.01.0
171 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
175 Print a raw backtrace in the same format Printexc.print_backtrace uses.
177 Since 4.01.0
180 val raw_backtrace_to_string : raw_backtrace -> string
184 Return a string from a raw backtrace, in the same format Print‐
186 exc.get_backtrace uses.
187 Since 4.01.0
190 val raise_with_backtrace : exn -> raw_backtrace -> 'a
194 Reraise the exception using the given raw_backtrace for the origin of
196 the exception
197 Since 4.05.0
200 Current call stack
205 val get_callstack : int -> raw_backtrace
206 Printexc.get_callstack n returns a description of the top of the call
209 stack on the current program point (for the current thread), with at
210 most n entries. (Note: this function is not related to exceptions at
211 all, despite being part of the Printexc module.)
212 Since 4.01.0
215 Uncaught exceptions
220 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
221 unit
222 Printexc.set_uncaught_exception_handler fn registers fn as the handler
225 for uncaught exceptions. The default handler prints the exception and
226 backtrace on standard error output.
227 Note that when fn is called all the functions registered with at_exit
229 have already been called. Because of this you must make sure any output
230 channel fn writes on is flushed.
231 Also note that exceptions raised by user code in the interactive
233 toplevel are not passed to this function as they are caught by the
234 toplevel itself.
235 If fn raises an exception, both the exceptions passed to fn and raised
237 by fn will be printed with their respective backtrace.
238 Since 4.02.0
241 Manipulation of backtrace information
246 These functions are used to traverse the slots of a raw backtrace and
247 extract information from them in a programmer-friendly format.
248 type backtrace_slot
250 The abstract type backtrace_slot represents a single slot of a back‐
253 trace.
254 Since 4.02
257 val backtrace_slots : raw_backtrace -> backtrace_slot array option
261 Returns the slots of a raw backtrace, or None if none of them contain
263 useful information.
264 In the return array, the slot at index 0 corresponds to the most recent
266 function call, raise, or primitive get_backtrace call in the trace.
267 Some possible reasons for returning None are as follow:
269 -none of the slots in the trace come from modules compiled with debug
271 information ( -g )
272 -the program is a bytecode program that has not been linked with debug
274 information enabled ( ocamlc -g )
275 Since 4.02.0
279 type location = {
282 filename : string ;
283 line_number : int ;
284 start_char : int ;
285 end_char : int ;
286 }
287 The type of location information found in backtraces. start_char and
290 end_char are positions relative to the beginning of the line.
291 Since 4.02
294 module Slot : sig end
297 Since 4.02.0
300 Raw backtrace slots
305 type raw_backtrace_slot
306 This type allows direct access to raw backtrace slots, without any con‐
309 version in an OCaml-usable data-structure. Being process-specific, they
310 must absolutely not be marshalled, and are unsafe to use for this rea‐
311 son (marshalling them may not fail, but un-marshalling and using the
312 result will result in undefined behavior).
313 Elements of this type can still be compared and hashed: when two ele‐
315 ments are equal, then they represent the same source location (the con‐
316 verse is not necessarily true in presence of inlining, for example).
317 Since 4.02.0
320 val raw_backtrace_length : raw_backtrace -> int
324 raw_backtrace_length bckt returns the number of slots in the backtrace
327 bckt .
328 Since 4.02
331 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
335 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
338 backtrace bckt .
339 Since 4.02
342 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
346 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
348 trace_slot .
349 Since 4.02
352 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
356 trace_slot option
357 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
360 Sample code to iterate over all frames (inlined and non-inlined): (*
362 Iterate over inlined frames *) let rec iter_raw_backtrace_slot f slot =
363 f slot; match get_raw_backtrace_next_slot slot with | None -> () | Some
364 slot' -> iter_raw_backtrace_slot f slot' (* Iterate over stack frames
365 *) let iter_raw_backtrace f bt = for i = 0 to raw_backtrace_length bt -
366 1 do iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i) done
367 Since 4.04.0
371 Exception slots
376 val exn_slot_id : exn -> int
377 Printexc.exn_slot_id returns an integer which uniquely identifies the
380 constructor used to create the exception value exn (in the current run‐
381 time).
382 Since 4.02.0
385 val exn_slot_name : exn -> string
389 Printexc.exn_slot_name exn returns the internal name of the constructor
392 used to create the exception value exn .
393 Since 4.02.0
396OCamldoc 2019-07-30 Stdlib.Printexc(3)