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-2012, 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 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--     HP-UX
62--     GNU/Linux x86
63--     LynxOS x86
64--     Solaris x86
65--     Solaris sparc
66--     OpenVMS/Alpha
67--     OpenVMS/ia64
68--     VxWorks PowerPC
69--     VxWorks x86
70--     Windows NT/XP
71
72--  Note: see also GNAT.Traceback.Symbolic, a child unit in file g-trasym.ads
73--  providing symbolic trace back capability for a subset of the above targets.
74
75with System;
76with Ada.Exceptions.Traceback;
77
78package GNAT.Traceback is
79   pragma Elaborate_Body;
80
81   subtype Code_Loc is System.Address;
82   --  Code location used in building tracebacks
83
84   subtype Tracebacks_Array is Ada.Exceptions.Traceback.Tracebacks_Array;
85   --  Traceback array used to hold a generated traceback list
86
87   ----------------
88   -- Call_Chain --
89   ----------------
90
91   procedure Call_Chain (Traceback : out Tracebacks_Array; Len : out Natural);
92   --  Store up to Traceback'Length tracebacks corresponding to the current
93   --  call chain. The first entry stored corresponds to the deepest level
94   --  of subprogram calls. Len shows the number of traceback entries stored.
95   --  It will be equal to Traceback'Length unless the entire traceback is
96   --  shorter, in which case positions in Traceback past the Len position
97   --  are undefined on return.
98
99end GNAT.Traceback;
100