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

NAME

6       Stdlib.Printexc - no description
7

Module

9       Module   Stdlib.Printexc
10

Documentation

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