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 type raw_backtrace stores a backtrace in a low-level format,  which
170       can  be  converted to usable form using raw_backtrace_entries and back‐
171       trace_slots_of_raw_entry below.
172
173       Converting backtraces to backtrace_slot s is slower than capturing  the
174       backtraces. If an application processes many backtraces, it can be use‐
175       ful to use raw_backtrace to avoid or delay conversion.
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       type raw_backtrace_entry = private int
186
187
188       A raw_backtrace_entry is an element of a raw_backtrace .
189
190       Each raw_backtrace_entry is an opaque integer, whose value is not  sta‐
191       ble  between  different programs, or even between different runs of the
192       same binary.
193
194       A raw_backtrace_entry can be converted to a  usable  form  using  back‐
195       trace_slots_of_raw_entry  below.  Note  that, due to inlining, a single
196       raw_backtrace_entry may convert to several backtrace_slot s.  Since the
197       values  of  a  raw_backtrace_entry  are not stable, they cannot be mar‐
198       shalled. If they are to be converted, the conversion must  be  done  by
199       the process that generated them.
200
201       Again due to inlining, there may be multiple distinct raw_backtrace_en‐
202       try values that convert to equal  backtrace_slot  s.  However,  if  two
203       raw_backtrace_entry  s  are  equal as integers, then they represent the
204       same backtrace_slot s.
205
206
207       Since 4.12.0
208
209
210
211       val raw_backtrace_entries : raw_backtrace -> raw_backtrace_entry array
212
213       Since 4.12.0
214
215
216
217       val get_raw_backtrace : unit -> raw_backtrace
218
219
220       Printexc.get_raw_backtrace () returns the same exception backtrace that
221       Printexc.print_backtrace  would  print,  but  in a raw format. Same re‐
222       striction usage than Printexc.print_backtrace .
223
224
225       Since 4.01.0
226
227
228
229       val print_raw_backtrace : out_channel -> raw_backtrace -> unit
230
231       Print a raw backtrace in the same format Printexc.print_backtrace uses.
232
233
234       Since 4.01.0
235
236
237
238       val raw_backtrace_to_string : raw_backtrace -> string
239
240       Return a string from  a  raw  backtrace,  in  the  same  format  Print‐
241       exc.get_backtrace uses.
242
243
244       Since 4.01.0
245
246
247
248       val raise_with_backtrace : exn -> raw_backtrace -> 'a
249
250       Reraise  the  exception using the given raw_backtrace for the origin of
251       the exception
252
253
254       Since 4.05.0
255
256
257
258
259   Current call stack
260       val get_callstack : int -> raw_backtrace
261
262
263       Printexc.get_callstack n returns a description of the top of  the  call
264       stack  on  the  current program point (for the current thread), with at
265       most n entries.  (Note: this function is not related to  exceptions  at
266       all, despite being part of the Printexc module.)
267
268
269       Since 4.01.0
270
271
272
273
274   Uncaught exceptions
275       val default_uncaught_exception_handler : exn -> raw_backtrace -> unit
276
277
278       Printexc.default_uncaught_exception_handler  prints  the  exception and
279       backtrace on standard error output.
280
281
282       Since 4.11
283
284
285
286       val set_uncaught_exception_handler : (exn -> raw_backtrace -> unit)  ->
287       unit
288
289
290       Printexc.set_uncaught_exception_handler  fn registers fn as the handler
291       for uncaught exceptions. The default  handler  is  Printexc.default_un‐
292       caught_exception_handler .
293
294       Note  that  when fn is called all the functions registered with at_exit
295       have already been called. Because of this you must make sure any output
296       channel fn writes on is flushed.
297
298       Also  note  that  exceptions  raised  by  user  code in the interactive
299       toplevel are not passed to this function as  they  are  caught  by  the
300       toplevel itself.
301
302       If  fn raises an exception, both the exceptions passed to fn and raised
303       by fn will be printed with their respective backtrace.
304
305
306       Since 4.02.0
307
308
309
310
311   Manipulation of backtrace information
312       These functions are used to traverse the slots of a raw  backtrace  and
313       extract information from them in a programmer-friendly format.
314
315       type backtrace_slot
316
317
318       The  abstract  type  backtrace_slot represents a single slot of a back‐
319       trace.
320
321
322       Since 4.02
323
324
325
326       val backtrace_slots : raw_backtrace -> backtrace_slot array option
327
328       Returns the slots of a raw backtrace, or None if none of  them  contain
329       useful information.
330
331       In the return array, the slot at index 0 corresponds to the most recent
332       function call, raise, or primitive get_backtrace call in the trace.
333
334       Some possible reasons for returning None are as follow:
335
336       -none of the slots in the trace come from modules compiled  with  debug
337       information ( -g )
338
339       -the  program is a bytecode program that has not been linked with debug
340       information enabled ( ocamlc -g )
341
342
343
344       Since 4.02.0
345
346
347
348       val  backtrace_slots_of_raw_entry  :   raw_backtrace_entry   ->   back‐
349       trace_slot array option
350
351       Returns  the slots of a single raw backtrace entry, or None if this en‐
352       try lacks debug information.
353
354       Slots are returned in the same order as backtrace_slots : the  slot  at
355       index  0  is  the most recent call, raise, or primitive, and subsequent
356       slots represent callers.
357
358
359       Since 4.12
360
361
362       type location = {
363        filename : string ;
364        line_number : int ;
365        start_char : int ;
366        end_char : int ;
367        }
368
369
370       The type of location information found in backtraces.   start_char  and
371       end_char are positions relative to the beginning of the line.
372
373
374       Since 4.02
375
376
377       module Slot : sig end
378
379
380       Since 4.02.0
381
382
383
384
385   Raw backtrace slots
386       type raw_backtrace_slot
387
388
389       This  type  is used to iterate over the slots of a raw_backtrace .  For
390       most purposes, backtrace_slots_of_raw_entry is easier to use.
391
392       Like raw_backtrace_entry , values of this type are process-specific and
393       must  absolutely not be marshalled, and are unsafe to use for this rea‐
394       son (marshalling them may not fail, but un-marshalling  and  using  the
395       result will result in undefined behavior).
396
397       Elements  of  this type can still be compared and hashed: when two ele‐
398       ments are equal, then they represent the same source location (the con‐
399       verse is not necessarily true in presence of inlining, for example).
400
401
402       Since 4.02.0
403
404
405
406       val raw_backtrace_length : raw_backtrace -> int
407
408
409       raw_backtrace_length  bckt returns the number of slots in the backtrace
410       bckt .
411
412
413       Since 4.02
414
415
416
417       val get_raw_backtrace_slot : raw_backtrace -> int -> raw_backtrace_slot
418
419
420       get_raw_backtrace_slot bckt pos returns the slot in position pos in the
421       backtrace bckt .
422
423
424       Since 4.02
425
426
427
428       val convert_raw_backtrace_slot : raw_backtrace_slot -> backtrace_slot
429
430       Extracts  the  user-friendly  backtrace_slot from a low-level raw_back‐
431       trace_slot .
432
433
434       Since 4.02
435
436
437
438       val  get_raw_backtrace_next_slot  :  raw_backtrace_slot  ->   raw_back‐
439       trace_slot option
440
441
442       get_raw_backtrace_next_slot slot returns the next slot inlined, if any.
443
444       Sample code to iterate over all frames (inlined and non-inlined):
445             (* Iterate over inlined frames *)
446             let rec iter_raw_backtrace_slot f slot =
447               f slot;
448               match get_raw_backtrace_next_slot slot with
449               | None -> ()
450               | Some slot' -> iter_raw_backtrace_slot f slot'
451
452             (* Iterate over stack frames *)
453             let iter_raw_backtrace f bt =
454               for i = 0 to raw_backtrace_length bt - 1 do
455                 iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
456               done
457
458
459
460       Since 4.04.0
461
462
463
464
465   Exception slots
466       val exn_slot_id : exn -> int
467
468
469       Printexc.exn_slot_id  returns  an integer which uniquely identifies the
470       constructor used to create the exception value exn (in the current run‐
471       time).
472
473
474       Since 4.02.0
475
476
477
478       val exn_slot_name : exn -> string
479
480
481       Printexc.exn_slot_name exn returns the internal name of the constructor
482       used to create the exception value exn .
483
484
485       Since 4.02.0
486
487
488
489
490
491OCamldoc                          2023-01-23                       Printexc(3)
Impressum