1------------------------------------------------------------------------------ 2-- -- 3-- GNAT RUN-TIME COMPONENTS -- 4-- -- 5-- S Y S T E M . T R A C E B A C K . S Y M B O L I C -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1999-2018, AdaCore -- 10-- -- 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. -- 17-- -- 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. -- 21-- -- 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/>. -- 26-- -- 27-- GNAT was originally developed by the GNAT team at New York University. -- 28-- Extensive contributions were provided by Ada Core Technologies Inc. -- 29-- -- 30------------------------------------------------------------------------------ 31 32-- Run-time symbolic traceback support 33 34-- The full capability is currently supported on the following targets: 35 36-- GNU/Linux x86, x86_64, ia64 37 38-- Note: on targets other than those listed above, a dummy implementation 39-- of the body returns a series of LF separated strings of the form "0x..." 40-- corresponding to the addresses. 41 42-- The routines provided in this package assume that your application has been 43-- compiled with debugging information turned on, since this information is 44-- used to build a symbolic traceback. 45 46-- If you want to retrieve tracebacks from exception occurrences, it is also 47-- necessary to invoke the binder with -E switch. Please refer to the gnatbind 48-- documentation for more information. 49 50-- Note that it is also possible (and often recommended) to compute symbolic 51-- traceback outside the program execution, which in addition allows you to 52-- distribute the executable with no debug info: 53-- 54-- - build your executable with debug info 55-- - archive this executable 56-- - strip a copy of the executable and distribute/deploy this version 57-- - at run time, compute absolute traceback (-bargs -E) from your 58-- executable and log it using Ada.Exceptions.Exception_Information 59-- - off line, compute the symbolic traceback using the executable archived 60-- with debug info and addr2line or gdb (using info line *<addr>) on the 61-- absolute addresses logged by your application. 62 63-- In order to retrieve symbolic information, functions in this package will 64-- read on disk all the debug information of the executable file (found via 65-- Argument (0), and looked in the PATH if needed) or shared libraries using 66-- OS facilities, and load them in memory, causing a significant cpu and 67-- memory overhead. 68 69-- Symbolic traceback from shared libraries is only supported for Windows and 70-- Linux. On other targets symbolic tracebacks are only supported for the main 71-- executable. You should consider using gdb to obtain symbolic traceback in 72-- such cases. 73 74pragma Polling (Off); 75-- We must turn polling off for this unit, because otherwise we can get 76-- elaboration circularities when polling is turned on. 77 78with Ada.Exceptions; 79 80package System.Traceback.Symbolic is 81 pragma Elaborate_Body; 82 83 function Symbolic_Traceback 84 (Traceback : System.Traceback_Entries.Tracebacks_Array) return String; 85 function Symbolic_Traceback_No_Hex 86 (Traceback : System.Traceback_Entries.Tracebacks_Array) return String; 87 -- Build a string containing a symbolic traceback of the given call 88 -- chain. Note: These procedures may be installed by Set_Trace_Decorator, 89 -- to get a symbolic traceback on all exceptions raised (see 90 -- System.Exception_Traces). 91 92 function Symbolic_Traceback 93 (E : Ada.Exceptions.Exception_Occurrence) return String; 94 function Symbolic_Traceback_No_Hex 95 (E : Ada.Exceptions.Exception_Occurrence) return String; 96 -- Build string containing symbolic traceback of given exception occurrence 97 98 -- In the above, _No_Hex means do not print any hexadecimal addresses, even 99 -- if the symbol is not available. This is useful for getting deterministic 100 -- output from tests. 101 102 procedure Enable_Cache (Include_Modules : Boolean := False); 103 -- Read symbolic information from binary files and cache them in memory. 104 -- This will speed up the above functions but will require more memory. If 105 -- Include_Modules is true, shared modules (or DLL) will also be cached. 106 -- This procedure may do nothing if not supported. The profile of this 107 -- subprogram may change in the future (new parameters can be added 108 -- with default value), but backward compatibility for direct calls 109 -- is supported. 110 111end System.Traceback.Symbolic; 112