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