File : g-traceb.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME COMPONENTS --
4 -- --
5 -- G N A T . T R A C E B A C K --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1999-2016, 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 non-symbolic traceback support
33
34 -- This package provides a method for generating a traceback of the
35 -- current execution location. The traceback shows the locations of
36 -- calls in the call chain, up to either the top or a designated
37 -- number of levels.
38
39 -- The traceback information is in the form of absolute code locations.
40 -- These code locations may be converted to corresponding source locations
41 -- using the external addr2line utility, or from within GDB.
42
43 -- In order to use this facility, in some cases the binder must be invoked
44 -- with -E switch (store the backtrace with exception occurrence). Please
45 -- refer to gnatbind documentation for more information.
46
47 -- To analyze the code locations later using addr2line or gdb, the necessary
48 -- units must be compiled with the debugging switch -g in the usual manner.
49 -- Note that it is not necessary to compile with -g to use Call_Chain. In
50 -- other words, the following sequence of steps can be used:
51
52 -- Compile without -g
53 -- Run the program, and call Call_Chain
54 -- Recompile with -g
55 -- Use addr2line to interpret the absolute call locations (note that
56 -- addr2line expects addresses in hexadecimal format).
57
58 -- This capability is currently supported on the following targets:
59
60 -- AiX PowerPC
61 -- GNU/Linux x86
62 -- GNU/Linux PowerPC
63 -- LynxOS x86
64 -- LynxOS 178 xcoff PowerPC
65 -- LynxOS 178 elf PowerPC
66 -- Solaris x86
67 -- Solaris sparc
68 -- VxWorks ARM
69 -- VxWorks7 ARM
70 -- VxWorks PowerPC
71 -- VxWorks x86
72 -- Windows XP
73
74 -- Note: see also GNAT.Traceback.Symbolic, a child unit in file g-trasym.ads
75 -- providing symbolic trace back capability for a subset of the above targets.
76
77 with System;
78 with Ada.Exceptions.Traceback;
79
80 package GNAT.Traceback is
81 pragma Elaborate_Body;
82
83 subtype Code_Loc is System.Address;
84 -- Code location used in building tracebacks
85
86 subtype Tracebacks_Array is Ada.Exceptions.Traceback.Tracebacks_Array;
87 -- Traceback array used to hold a generated traceback list
88
89 ----------------
90 -- Call_Chain --
91 ----------------
92
93 procedure Call_Chain (Traceback : out Tracebacks_Array; Len : out Natural);
94 -- Store up to Traceback'Length tracebacks corresponding to the current
95 -- call chain. The first entry stored corresponds to the deepest level
96 -- of subprogram calls. Len shows the number of traceback entries stored.
97 -- It will be equal to Traceback'Length unless the entire traceback is
98 -- shorter, in which case positions in Traceback past the Len position
99 -- are undefined on return.
100
101 end GNAT.Traceback;