File : s-trasym.ads
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-2015, 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 -- --
19 -- --
20 -- --
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 -- HP-UX ia64
37 -- GNU/Linux x86, x86_64, ia64
38 -- FreeBSD x86, x86_64
39 -- Solaris sparc and x86
40 -- Windows
41
42 -- Note: on targets other than those listed above, a dummy implementation of
43 -- the body returns a series of LF separated strings of the form "0x..."
44 -- corresponding to the addresses.
45
46 -- The routines provided in this package assume that your application has
47 -- been compiled with debugging information turned on, since this information
48 -- is used to build a symbolic traceback.
49
50 -- If you want to retrieve tracebacks from exception occurrences, it is also
51 -- necessary to invoke the binder with -E switch. Please refer to the gnatbind
52 -- documentation for more information.
53
54 -- Note that it is also possible (and often recommended) to compute symbolic
55 -- traceback outside the program execution, which in addition allows you
56 -- to distribute the executable with no debug info:
57 --
58 -- - build your executable with debug info
59 -- - archive this executable
60 -- - strip a copy of the executable and distribute/deploy this version
61 -- - at run time, compute absolute traceback (-bargs -E) from your
62 -- executable and log it using Ada.Exceptions.Exception_Information
63 -- - off line, compute the symbolic traceback using the executable archived
64 -- with debug info and addr2line or gdb (using info line *<addr>) on the
65 -- absolute addresses logged by your application.
66
67 -- In order to retrieve symbolic information, functions in this package will
68 -- read on disk all the debug information of the executable file (found via
69 -- Argument (0), and looked in the PATH if needed) or shared libraries using
70 -- OS facilities, and load them in memory, causing a significant cpu and
71 -- memory overhead.
72
73 -- Symbolic traceback from shared libraries is only supported for Windows and
74 -- Linux. On other targets symbolic tracebacks are only supported for the main
75 -- executable. You should consider using gdb to obtain symbolic traceback in
76 -- such cases.
77
78 -- On platforms where the full capability is not supported, function
79 -- Symbolic_Traceback return a list of addresses expressed as "0x..."
80 -- separated by line feed.
81
82 pragma Polling (Off);
83 -- We must turn polling off for this unit, because otherwise we can get
84 -- elaboration circularities when polling is turned on.
85
86 with Ada.Exceptions;
87
88 package System.Traceback.Symbolic is
89 pragma Elaborate_Body;
90
91 function Symbolic_Traceback
92 (Traceback : System.Traceback_Entries.Tracebacks_Array) return String;
93 -- Build a string containing a symbolic traceback of the given call chain.
94 -- Note: This procedure may be installed by Set_Trace_Decorator, to get a
95 -- symbolic traceback on all exceptions raised (see
96 -- System.Exception_Traces).
97
98 function Symbolic_Traceback
99 (E : Ada.Exceptions.Exception_Occurrence) return String;
100 -- Build string containing symbolic traceback of given exception occurrence
101
102 end System.Traceback.Symbolic;