File : g-curexc.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT LIBRARY COMPONENTS --
4 -- --
5 -- G N A T . C U R R E N T _ E X C E P T I O N --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1996-2010, 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 -- This package provides routines for obtaining the current exception
33 -- information in Ada 83 style. In Ada 83, there was no official method
34 -- for obtaining exception information, but a number of vendors supplied
35 -- routines for this purpose, and this package closely approximates the
36 -- interfaces supplied by DEC Ada 83 and VADS Ada.
37
38 -- The routines in this package are associated with a particular exception
39 -- handler, and can only be called from within an exception handler. See
40 -- also the package GNAT.Most_Recent_Exception, which provides access to
41 -- the most recently raised exception, and is not limited to static calls
42 -- from an exception handler.
43
44 package GNAT.Current_Exception is
45 pragma Pure;
46
47 -----------------
48 -- Subprograms --
49 -----------------
50
51 -- Note: the lower bound of returned String values is always one
52
53 function Exception_Information return String;
54 -- Returns the result of calling Ada.Exceptions.Exception_Information
55 -- with an argument that is the Exception_Occurrence corresponding to
56 -- the current exception. Returns the null string if called from outside
57 -- an exception handler.
58
59 function Exception_Message return String;
60 -- Returns the result of calling Ada.Exceptions.Exception_Message with
61 -- an argument that is the Exception_Occurrence corresponding to the
62 -- current exception. Returns the null string if called from outside an
63 -- exception handler.
64
65 function Exception_Name return String;
66 -- Returns the result of calling Ada.Exceptions.Exception_Name with
67 -- an argument that is the Exception_Occurrence corresponding to the
68 -- current exception. Returns the null string if called from outside
69 -- an exception handler.
70
71 -- Note: all these functions return useful information only if
72 -- called statically from within an exception handler, and they
73 -- return information about the exception corresponding to the
74 -- handler in which they appear. This is NOT the same as the most
75 -- recently raised exception. Consider the example:
76
77 -- exception
78 -- when Constraint_Error =>
79 -- begin
80 -- ...
81 -- exception
82 -- when Tasking_Error => ...
83 -- end;
84 --
85 -- -- Exception_xxx at this point returns the information about
86 -- -- the constraint error, not about any exception raised within
87 -- -- the nested block since it is the static nesting that counts.
88
89 -----------------------------------
90 -- Use of Library Level Renaming --
91 -----------------------------------
92
93 -- For greater compatibility with existing legacy software, library
94 -- level renaming may be used to create a function with a name matching
95 -- one that is in use. For example, some versions of VADS Ada provided
96 -- a function called Current_Exception whose semantics was identical to
97 -- that of GNAT. The following library level renaming declaration:
98
99 -- with GNAT.Current_Exception;
100 -- function Current_Exception
101 -- renames GNAT.Current_Exception.Exception_Name;
102
103 -- placed in a file called current_exception.ads and compiled into the
104 -- application compilation environment, will make the function available
105 -- in a manner exactly compatible with that in VADS Ada 83.
106
107 private
108 pragma Import (Intrinsic, Exception_Information);
109 pragma Import (intrinsic, Exception_Message);
110 pragma Import (Intrinsic, Exception_Name);
111
112 end GNAT.Current_Exception;