1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- S Y S T E M . T R A C E B A C K . S Y M B O L I C --
9 -- Copyright (C) 1999-2023, 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 3, 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. --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception, --
20 -- version 3.1, as published by the Free Software Foundation. --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
30 ------------------------------------------------------------------------------
32 -- Run-time symbolic traceback support
34 -- The full capability is currently supported on the following targets:
36 -- GNU/Linux x86, x86_64
37 -- Windows x86, x86_64
39 -- Note: on targets other than those listed above, a dummy implementation
40 -- of the body returns a series of LF separated strings of the form "0x..."
41 -- corresponding to the addresses.
43 -- The routines provided in this package assume that your application has been
44 -- compiled with debugging information turned on, since this information is
45 -- used to build a symbolic traceback.
47 -- If you want to retrieve tracebacks from exception occurrences, it is also
48 -- necessary to invoke the binder with -E switch. Please refer to the gnatbind
49 -- documentation for more information.
51 -- Note that it is also possible (and often recommended) to compute symbolic
52 -- traceback outside the program execution, which in addition allows you to
53 -- distribute the executable with no debug info:
55 -- - build your executable with debug info
56 -- - archive this executable
57 -- - strip a copy of the executable and distribute/deploy this version
58 -- - at run time, compute absolute traceback (-bargs -E) from your
59 -- executable and log it using Ada.Exceptions.Exception_Information
60 -- - off line, compute the symbolic traceback using the executable archived
61 -- with debug info and addr2line or gdb (using info line *<addr>) on the
62 -- absolute addresses logged by your application.
64 -- In order to retrieve symbolic information, functions in this package will
65 -- read on disk all the debug information of the executable file (found via
66 -- Argument (0), and looked in the PATH if needed) or shared libraries using
67 -- OS facilities, and load them in memory, causing a significant cpu and
70 -- Symbolic traceback from shared libraries is only supported for Windows and
71 -- Linux. On other targets symbolic tracebacks are only supported for the main
72 -- executable. You should consider using gdb to obtain symbolic traceback in
77 package System
.Traceback
.Symbolic
is
78 pragma Elaborate_Body
;
80 function Symbolic_Traceback
81 (Traceback
: System
.Traceback_Entries
.Tracebacks_Array
) return String;
82 function Symbolic_Traceback_No_Hex
83 (Traceback
: System
.Traceback_Entries
.Tracebacks_Array
) return String;
84 -- Build a string containing a symbolic traceback of the given call
85 -- chain. Note: These procedures may be installed by Set_Trace_Decorator,
86 -- to get a symbolic traceback on all exceptions raised (see
87 -- System.Exception_Traces).
89 function Symbolic_Traceback
90 (E
: Ada
.Exceptions
.Exception_Occurrence
) return String;
91 function Symbolic_Traceback_No_Hex
92 (E
: Ada
.Exceptions
.Exception_Occurrence
) return String;
93 -- Build string containing symbolic traceback of given exception occurrence
95 -- In the above, _No_Hex means do not print any hexadecimal addresses, even
96 -- if the symbol is not available. This is useful for getting deterministic
99 procedure Enable_Cache
(Include_Modules
: Boolean := False);
100 -- Read symbolic information from binary files and cache them in memory.
101 -- This will speed up the above functions but will require more memory. If
102 -- Include_Modules is true, shared modules (or DLL) will also be cached.
103 -- This procedure may do nothing if not supported. The profile of this
104 -- subprogram may change in the future (new parameters can be added
105 -- with default value), but backward compatibility for direct calls
108 end System
.Traceback
.Symbolic
;