1Stdlib.Printexc(3) OCaml library Stdlib.Printexc(3)
2
3
4
6 Stdlib.Printexc - no description
7
9 Module Stdlib.Printexc
10
12 Module Printexc
13 : (module Stdlib__printexc)
14
15
16
17
18
19
20
21 type t = exn = ..
22
23
24 The type of exception values.
25
26
27
28 val to_string : exn -> string
29
30
31 Printexc.to_string e returns a string representation of the exception e
32 .
33
34
35
36 val to_string_default : exn -> string
37
38
39 Printexc.to_string_default e returns a string representation of the
40 exception e , ignoring all registered exception printers.
41
42
43 Since 4.09
44
45
46
47 val print : ('a -> 'b) -> 'a -> 'b
48
49
50 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
56
57
58 val catch : ('a -> 'b) -> 'a -> 'b
59
60
61 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
69
70
71 val print_backtrace : out_channel -> unit
72
73
74 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
79 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
85
86 Since 3.11.0
87
88
89
90 val get_backtrace : unit -> string
91
92
93 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
97
98 Since 3.11.0
99
100
101
102 val record_backtrace : bool -> unit
103
104
105 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
110
111 Since 3.11.0
112
113
114
115 val backtrace_status : unit -> bool
116
117
118 Printexc.backtrace_status() returns true if exception backtraces are
119 currently recorded, false if not.
120
121
122 Since 3.11.0
123
124
125
126 val register_printer : (exn -> string option) -> unit
127
128
129 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
135 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
140 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
146
147 Since 3.11.2
148
149
150
151 val use_printers : exn -> string option
152
153
154 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
157
158 Since 4.09
159
160
161
162
163 Raw backtraces
164 type raw_backtrace
165
166
167 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
171 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
175 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
179
180 Since 4.01.0
181
182
183
184 val get_raw_backtrace : unit -> raw_backtrace
185
186
187 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
191
192 Since 4.01.0
193
194
195
196 val print_raw_backtrace : out_channel -> raw_backtrace -> unit
197
198 Print a raw backtrace in the same format Printexc.print_backtrace uses.
199
200
201 Since 4.01.0
202
203
204
205 val raw_backtrace_to_string : raw_backtrace -> string
206
207 Return a string from a raw backtrace, in the same format Print‐
208 exc.get_backtrace uses.
209
210
211 Since 4.01.0
212
213
214
215 val raise_with_backtrace : exn -> raw_backtrace -> 'a
216
217 Reraise the exception using the given raw_backtrace for the origin of
218 the exception
219
220
221 Since 4.05.0
222
223
224
225
226 Current call stack
227 val get_callstack : int -> raw_backtrace
228
229
230 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
235
236 Since 4.01.0
237
238
239
240
241 Uncaught exceptions
242 val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit) ->
243 unit
244
245
246 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
250 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
254 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
258 If fn raises an exception, both the exceptions passed to fn and raised
259 by fn will be printed with their respective backtrace.
260
261
262 Since 4.02.0
263
264
265
266
267 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
271 type backtrace_slot
272
273
274 The abstract type backtrace_slot represents a single slot of a back‐
275 trace.
276
277
278 Since 4.02
279
280
281
282 val backtrace_slots : raw_backtrace -> backtrace_slot array option
283
284 Returns the slots of a raw backtrace, or None if none of them contain
285 useful information.
286
287 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
290 Some possible reasons for returning None are as follow:
291
292 -none of the slots in the trace come from modules compiled with debug
293 information ( -g )
294
295 -the program is a bytecode program that has not been linked with debug
296 information enabled ( ocamlc -g )
297
298
299
300 Since 4.02.0
301
302
303 type location = {
304 filename : string ;
305 line_number : int ;
306 start_char : int ;
307 end_char : int ;
308 }
309
310
311 The type of location information found in backtraces. start_char and
312 end_char are positions relative to the beginning of the line.
313
314
315 Since 4.02
316
317
318 module Slot : sig end
319
320
321 Since 4.02.0
322
323
324
325
326 Raw backtrace slots
327 type raw_backtrace_slot
328
329
330 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
336 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
340
341 Since 4.02.0
342
343
344
345 val raw_backtrace_length : raw_backtrace -> int
346
347
348 raw_backtrace_length bckt returns the number of slots in the backtrace
349 bckt .
350
351
352 Since 4.02
353
354
355
356 val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
357
358
359 get_raw_backtrace_slot bckt pos returns the slot in position pos in the
360 backtrace bckt .
361
362
363 Since 4.02
364
365
366
367 val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
368
369 Extracts the user-friendly backtrace_slot from a low-level raw_back‐
370 trace_slot .
371
372
373 Since 4.02
374
375
376
377 val get_raw_backtrace_next_slot : raw_backtrace_slot -> raw_back‐
378 trace_slot option
379
380
381 get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
382
383 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
391 (* 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
397
398
399 Since 4.04.0
400
401
402
403
404 Exception slots
405 val exn_slot_id : exn -> int
406
407
408 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
412
413 Since 4.02.0
414
415
416
417 val exn_slot_name : exn -> string
418
419
420 Printexc.exn_slot_name exn returns the internal name of the constructor
421 used to create the exception value exn .
422
423
424 Since 4.02.0
425
426
427
428
429
430OCamldoc 2020-02-27 Stdlib.Printexc(3)