1Printexc(3)                      OCaml library                     Printexc(3)
2
3
4

NAME

6       Printexc  -  Facilities  for printing exceptions and inspecting current
7       call stack.
8

Module

10       Module   Printexc
11

Documentation

13       Module Printexc
14        : sig end
15
16
17       Facilities for printing exceptions and inspecting current call stack.
18
19
20
21
22
23       type t = exn = ..
24
25
26       The type of exception values.
27
28
29
30       val to_string : exn -> string
31
32
33       Printexc.to_string e returns a string representation of the exception e
34       .
35
36
37
38       val to_string_default : exn -> string
39
40
41       Printexc.to_string_default e returns a string representation of the ex‐
42       ception e , ignoring all registered exception printers.
43
44
45       Since 4.09
46
47
48
49       val print : ('a -> 'b) -> 'a -> 'b
50
51
52       Printexc.print fn x applies fn to x and returns  the  result.   If  the
53       evaluation  of  fn x raises any exception, the name of the exception is
54       printed on standard error output, and the exception  is  raised  again.
55       The  typical  use is to catch and report exceptions that escape a func‐
56       tion application.
57
58
59
60       val catch : ('a -> 'b) -> 'a -> 'b
61
62
63       Printexc.catch fn x is similar to Printexc.print , but aborts the  pro‐
64       gram  with  exit  code  2  after printing the uncaught exception.  This
65       function is deprecated: the runtime system is now  able  to  print  un‐
66       caught exceptions as precisely as Printexc.catch does.  Moreover, call‐
67       ing Printexc.catch makes it harder to track the location of the  excep‐
68       tion  using  the  debugger or the stack backtrace facility.  So, do not
69       use Printexc.catch in new code.
70
71
72
73       val print_backtrace : out_channel -> unit
74
75
76       Printexc.print_backtrace oc prints an exception backtrace on the output
77       channel  oc  .   The  backtrace  lists  the program locations where the
78       most-recently raised exception was raised and where it  was  propagated
79       through function calls.
80
81       If  the call is not inside an exception handler, the returned backtrace
82       is unspecified. If the call is after some exception-catching code  (be‐
83       fore  in the handler, or in a when-guard during the matching of the ex‐
84       ception handler), the backtrace may correspond  to  a  later  exception
85       than the handled one.
86
87
88       Since 3.11.0
89
90
91
92       val get_backtrace : unit -> string
93
94
95       Printexc.get_backtrace  ()  returns a string containing the same excep‐
96       tion backtrace that Printexc.print_backtrace would print. Same restric‐
97       tion usage than Printexc.print_backtrace .
98
99
100       Since 3.11.0
101
102
103
104       val record_backtrace : bool -> unit
105
106
107       Printexc.record_backtrace  b turns recording of exception backtraces on
108       (if b = true ) or off (if b = false ).  Initially, backtraces  are  not
109       recorded,  unless the b flag is given to the program through the OCAML‐
110       RUNPARAM variable.
111
112
113       Since 3.11.0
114
115
116
117       val backtrace_status : unit -> bool
118
119
120       Printexc.backtrace_status() returns true if  exception  backtraces  are
121       currently recorded, false if not.
122
123
124       Since 3.11.0
125
126
127
128       val register_printer : (exn -> string option) -> unit
129
130
131       Printexc.register_printer fn registers fn as an exception printer.  The
132       printer should return None or raise an exception if it  does  not  know
133       how to convert the passed exception, and Some
134            s  with s the resulting string if it can convert the passed excep‐
135       tion. Exceptions raised by the printer are ignored.
136
137       When converting an exception into a string, the printers  will  be  in‐
138       voked  in the reverse order of their registrations, until a printer re‐
139       turns a Some s value (if no such printer exists, the runtime will use a
140       generic printer).
141
142       When  using this mechanism, one should be aware that an exception back‐
143       trace is attached to the thread that saw it raised, rather than to  the
144       exception  itself.  Practically,  it  means that the code related to fn
145       should not use the backtrace if it has itself raised an  exception  be‐
146       fore.
147
148
149       Since 3.11.2
150
151
152
153       val use_printers : exn -> string option
154
155
156       Printexc.use_printers  e returns None if there are no registered print‐
157       ers and Some s with else as the resulting string otherwise.
158
159
160       Since 4.09
161
162
163
164
165   Raw backtraces
166       type raw_backtrace
167
168
169       The abstract type raw_backtrace stores a backtrace in a low-level  for‐
170       mat, instead of directly exposing them as string as the get_backtrace()
171       function does.
172
173       This allows delaying the formatting of backtraces to when they are  ac‐
174       tually  printed, which may be useful if you record more backtraces than
175       you print.
176
177       Raw backtraces cannot be  marshalled.  If  you  need  marshalling,  you
178       should  use  the  array returned by the backtrace_slots function of the
179       next section.
180
181
182       Since 4.01.0
183
184
185
186       val get_raw_backtrace : unit -> raw_backtrace
187
188
189       Printexc.get_raw_backtrace () returns the same exception backtrace that
190       Printexc.print_backtrace  would  print,  but  in a raw format. Same re‐
191       striction usage than Printexc.print_backtrace .
192
193
194       Since 4.01.0
195
196
197
198       val print_raw_backtrace : out_channel -> raw_backtrace -> unit
199
200       Print a raw backtrace in the same format Printexc.print_backtrace uses.
201
202
203       Since 4.01.0
204
205
206
207       val raw_backtrace_to_string : raw_backtrace -> string
208
209       Return a string from  a  raw  backtrace,  in  the  same  format  Print‐
210       exc.get_backtrace uses.
211
212
213       Since 4.01.0
214
215
216
217       val raise_with_backtrace : exn -> raw_backtrace -> 'a
218
219       Reraise  the  exception using the given raw_backtrace for the origin of
220       the exception
221
222
223       Since 4.05.0
224
225
226
227
228   Current call stack
229       val get_callstack : int -> raw_backtrace
230
231
232       Printexc.get_callstack n returns a description of the top of  the  call
233       stack  on  the  current program point (for the current thread), with at
234       most n entries.  (Note: this function is not related to  exceptions  at
235       all, despite being part of the Printexc module.)
236
237
238       Since 4.01.0
239
240
241
242
243   Uncaught exceptions
244       val default_uncaught_exception_handler : exn -> raw_backtrace -> unit
245
246
247       Printexc.default_uncaught_exception_handler  prints  the  exception and
248       backtrace on standard error output.
249
250
251       Since 4.11
252
253
254
255       val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit)  ->
256       unit
257
258
259       Printexc.set_uncaught_exception_handler  fn registers fn as the handler
260       for uncaught exceptions. The default  handler  is  Printexc.default_un‐
261       caught_exception_handler .
262
263       Note  that  when fn is called all the functions registered with at_exit
264       have already been called. Because of this you must make sure any output
265       channel fn writes on is flushed.
266
267       Also  note  that  exceptions  raised  by  user  code in the interactive
268       toplevel are not passed to this function as  they  are  caught  by  the
269       toplevel itself.
270
271       If  fn raises an exception, both the exceptions passed to fn and raised
272       by fn will be printed with their respective backtrace.
273
274
275       Since 4.02.0
276
277
278
279
280   Manipulation of backtrace information
281       These functions are used to traverse the slots of a raw  backtrace  and
282       extract information from them in a programmer-friendly format.
283
284       type backtrace_slot
285
286
287       The  abstract  type  backtrace_slot represents a single slot of a back‐
288       trace.
289
290
291       Since 4.02
292
293
294
295       val backtrace_slots : raw_backtrace -> backtrace_slot array option
296
297       Returns the slots of a raw backtrace, or None if none of  them  contain
298       useful information.
299
300       In the return array, the slot at index 0 corresponds to the most recent
301       function call, raise, or primitive get_backtrace call in the trace.
302
303       Some possible reasons for returning None are as follow:
304
305       -none of the slots in the trace come from modules compiled  with  debug
306       information ( -g )
307
308       -the  program is a bytecode program that has not been linked with debug
309       information enabled ( ocamlc -g )
310
311
312
313       Since 4.02.0
314
315
316       type location = {
317        filename : string ;
318        line_number : int ;
319        start_char : int ;
320        end_char : int ;
321        }
322
323
324       The type of location information found in backtraces.   start_char  and
325       end_char are positions relative to the beginning of the line.
326
327
328       Since 4.02
329
330
331       module Slot : sig end
332
333
334       Since 4.02.0
335
336
337
338
339   Raw backtrace slots
340       type raw_backtrace_slot
341
342
343       This type allows direct access to raw backtrace slots, without any con‐
344       version in an OCaml-usable data-structure. Being process-specific, they
345       must  absolutely not be marshalled, and are unsafe to use for this rea‐
346       son (marshalling them may not fail, but un-marshalling  and  using  the
347       result will result in undefined behavior).
348
349       Elements  of  this type can still be compared and hashed: when two ele‐
350       ments are equal, then they represent the same source location (the con‐
351       verse is not necessarily true in presence of inlining, for example).
352
353
354       Since 4.02.0
355
356
357
358       val raw_backtrace_length : raw_backtrace -> int
359
360
361       raw_backtrace_length  bckt returns the number of slots in the backtrace
362       bckt .
363
364
365       Since 4.02
366
367
368
369       val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
370
371
372       get_raw_backtrace_slot bckt pos returns the slot in position pos in the
373       backtrace bckt .
374
375
376       Since 4.02
377
378
379
380       val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
381
382       Extracts  the  user-friendly  backtrace_slot from a low-level raw_back‐
383       trace_slot .
384
385
386       Since 4.02
387
388
389
390       val  get_raw_backtrace_next_slot  :  raw_backtrace_slot  ->   raw_back‐
391       trace_slot option
392
393
394       get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
395
396       Sample code to iterate over all frames (inlined and non-inlined):
397             (* Iterate over inlined frames *)
398             let rec iter_raw_backtrace_slot f slot =
399               f slot;
400               match get_raw_backtrace_next_slot slot with
401               | None -> ()
402               | Some slot' -> iter_raw_backtrace_slot f slot'
403
404             (* Iterate over stack frames *)
405             let iter_raw_backtrace f bt =
406               for i = 0 to raw_backtrace_length bt - 1 do
407                 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
408               done
409
410
411
412       Since 4.04.0
413
414
415
416
417   Exception slots
418       val exn_slot_id : exn -> int
419
420
421       Printexc.exn_slot_id  returns  an integer which uniquely identifies the
422       constructor used to create the exception value exn (in the current run‐
423       time).
424
425
426       Since 4.02.0
427
428
429
430       val exn_slot_name : exn -> string
431
432
433       Printexc.exn_slot_name exn returns the internal name of the constructor
434       used to create the exception value exn .
435
436
437       Since 4.02.0
438
439
440
441
442
443OCamldoc                          2021-01-26                       Printexc(3)
Impressum