1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- G N A T . T R A C E B A C K . S Y M B O L I C --
9 -- Copyright (C) 1999-2008, AdaCore --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
20 -- Boston, MA 02110-1301, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
34 -- Run-time symbolic traceback support
36 -- This capability is currently supported on the following targets:
45 -- Windows NT/XP/Vista
47 -- The routines provided in this package assume that your application has
48 -- been compiled with debugging information turned on, since this information
49 -- is used to build a symbolic traceback.
51 -- If you want to retrieve tracebacks from exception occurrences, it is also
52 -- necessary to invoke the binder with -E switch. Please refer to the gnatbind
53 -- documentation for more information.
55 -- Note that it is also possible (and often recommended) to compute symbolic
56 -- traceback outside the program execution, which in addition allows you
57 -- to distribute the executable with no debug info:
59 -- - build your executable with debug info
60 -- - archive this executable
61 -- - strip a copy of the executable and distribute/deploy this version
62 -- - at run time, compute absolute traceback (-bargs -E) from your
63 -- executable and log it using Ada.Exceptions.Exception_Information
64 -- - off line, compute the symbolic traceback using the executable archived
65 -- with debug info and addr2line or gdb (using info line *<addr>) on the
66 -- absolute addresses logged by your application.
68 -- In order to retrieve symbolic information, functions in this package will
69 -- read on disk all the debug information of the executable file (found via
70 -- Argument (0), and looked in the PATH if needed), and load them in memory,
71 -- causing a significant cpu and memory overhead.
73 -- On all platforms except VMS, this package is not intended to be used
74 -- within a shared library, symbolic tracebacks are only supported for the
75 -- main executable and not for shared libraries. You should consider using
76 -- gdb to obtain symbolic traceback in such cases.
78 -- On VMS, there is no restriction on using this facility with shared
79 -- libraries. However, the OS should be at least v7.3-1 and OS patch
80 -- VMS731_TRACE-V0100 must be applied in order to use this package.
82 with Ada
.Exceptions
; use Ada
.Exceptions
;
84 package GNAT
.Traceback
.Symbolic
is
85 pragma Elaborate_Body
;
87 function Symbolic_Traceback
(Traceback
: Tracebacks_Array
) return String;
88 -- Build a string containing a symbolic traceback of the given call chain
90 -- Note: This procedure may be installed by Set_Trace_Decorator, to get a
91 -- symbolic traceback on all exceptions raised (see GNAT.Exception_Traces).
93 function Symbolic_Traceback
(E
: Exception_Occurrence
) return String;
94 -- Build string containing symbolic traceback of given exception occurrence
96 end GNAT
.Traceback
.Symbolic
;