File : s-stalib.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- S Y S T E M . S T A N D A R D _ L I B R A R Y --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1992-2015, Free Software Foundation, Inc. --
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 is included in all programs. It contains declarations that
33 -- are required to be part of every Ada program. A special mechanism is
34 -- required to ensure that these are loaded, since it may be the case in
35 -- some programs that the only references to these required packages are
36 -- from C code or from code generated directly by Gigi, and in both cases
37 -- the binder is not aware of such references.
38
39 -- System.Standard_Library also includes data that must be present in every
40 -- program, in particular data for all the standard exceptions, and also some
41 -- subprograms that must be present in every program.
42
43 -- The binder unconditionally includes s-stalib.ali, which ensures that this
44 -- package and the packages it references are included in all Ada programs,
45 -- together with the included data.
46
47 pragma Compiler_Unit_Warning;
48
49 pragma Polling (Off);
50 -- We must turn polling off for this unit, because otherwise we get
51 -- elaboration circularities with Ada.Exceptions if polling is on.
52
53 with Ada.Unchecked_Conversion;
54
55 package System.Standard_Library is
56
57 -- Historical note: pragma Preelaborate was surrounded by a pair of pragma
58 -- Warnings (Off/On) to circumvent a bootstrap issue.
59
60 pragma Preelaborate;
61
62 subtype Big_String is String (1 .. Positive'Last);
63 pragma Suppress_Initialization (Big_String);
64 -- Type used to obtain string access to given address. Initialization is
65 -- suppressed, since we never want to have variables of this type, and
66 -- we never want to attempt initialiazation of virtual variables of this
67 -- type (e.g. when pragma Normalize_Scalars is used).
68
69 type Big_String_Ptr is access all Big_String;
70 for Big_String_Ptr'Storage_Size use 0;
71 -- We use this access type to pass a pointer to an area of storage to be
72 -- accessed as a string. Of course when this pointer is used, it is the
73 -- responsibility of the accessor to ensure proper bounds. The storage
74 -- size clause ensures we do not allocate variables of this type.
75
76 function To_Ptr is
77 new Ada.Unchecked_Conversion (System.Address, Big_String_Ptr);
78
79 -------------------------------------
80 -- Exception Declarations and Data --
81 -------------------------------------
82
83 type Raise_Action is access procedure;
84 -- A pointer to a procedure used in the Raise_Hook field
85
86 type Exception_Data;
87 type Exception_Data_Ptr is access all Exception_Data;
88 -- An equivalent of Exception_Id that is public
89
90 -- The following record defines the underlying representation of exceptions
91
92 -- WARNING: Any changes to this may need to be reflected in the following
93 -- locations in the compiler and runtime code:
94
95 -- 1. The Internal_Exception routine in s-exctab.adb
96 -- 2. The processing in gigi that tests Not_Handled_By_Others
97 -- 3. Expand_N_Exception_Declaration in Exp_Ch11
98 -- 4. The construction of the exception type in Cstand
99
100 type Exception_Data is record
101 Not_Handled_By_Others : Boolean;
102 -- Normally set False, indicating that the exception is handled in the
103 -- usual way by others (i.e. an others handler handles the exception).
104 -- Set True to indicate that this exception is not caught by others
105 -- handlers, but must be explicitly named in a handler. This latter
106 -- setting is currently used by the Abort_Signal.
107
108 Lang : Character;
109 -- A character indicating the language raising the exception.
110 -- Set to "A" for exceptions defined by an Ada program.
111 -- Set to "C" for imported C++ exceptions.
112
113 Name_Length : Natural;
114 -- Length of fully expanded name of exception
115
116 Full_Name : System.Address;
117 -- Fully expanded name of exception, null terminated
118 -- You can use To_Ptr to convert this to a string.
119
120 HTable_Ptr : Exception_Data_Ptr;
121 -- Hash table pointer used to link entries together in the hash table
122 -- built (by Register_Exception in s-exctab.adb) for converting between
123 -- identities and names.
124
125 Foreign_Data : Address;
126 -- Data for imported exceptions. Not used in the Ada case. This
127 -- represents the address of the RTTI for the C++ case.
128
129 Raise_Hook : Raise_Action;
130 -- This field can be used to place a "hook" on an exception. If the
131 -- value is non-null, then it points to a procedure which is called
132 -- whenever the exception is raised. This call occurs immediately,
133 -- before any other actions taken by the raise (and in particular
134 -- before any unwinding of the stack occurs).
135 end record;
136
137 -- Definitions for standard predefined exceptions defined in Standard,
138
139 -- Why are the NULs necessary here, seems like they should not be
140 -- required, since Gigi is supposed to add a Nul to each name ???
141
142 Constraint_Error_Name : constant String := "CONSTRAINT_ERROR" & ASCII.NUL;
143 Program_Error_Name : constant String := "PROGRAM_ERROR" & ASCII.NUL;
144 Storage_Error_Name : constant String := "STORAGE_ERROR" & ASCII.NUL;
145 Tasking_Error_Name : constant String := "TASKING_ERROR" & ASCII.NUL;
146 Abort_Signal_Name : constant String := "_ABORT_SIGNAL" & ASCII.NUL;
147
148 Numeric_Error_Name : constant String := "NUMERIC_ERROR" & ASCII.NUL;
149 -- This is used only in the Ada 83 case, but it is not worth having a
150 -- separate version of s-stalib.ads for use in Ada 83 mode.
151
152 Constraint_Error_Def : aliased Exception_Data :=
153 (Not_Handled_By_Others => False,
154 Lang => 'A',
155 Name_Length => Constraint_Error_Name'Length,
156 Full_Name => Constraint_Error_Name'Address,
157 HTable_Ptr => null,
158 Foreign_Data => Null_Address,
159 Raise_Hook => null);
160
161 Numeric_Error_Def : aliased Exception_Data :=
162 (Not_Handled_By_Others => False,
163 Lang => 'A',
164 Name_Length => Numeric_Error_Name'Length,
165 Full_Name => Numeric_Error_Name'Address,
166 HTable_Ptr => null,
167 Foreign_Data => Null_Address,
168 Raise_Hook => null);
169
170 Program_Error_Def : aliased Exception_Data :=
171 (Not_Handled_By_Others => False,
172 Lang => 'A',
173 Name_Length => Program_Error_Name'Length,
174 Full_Name => Program_Error_Name'Address,
175 HTable_Ptr => null,
176 Foreign_Data => Null_Address,
177 Raise_Hook => null);
178
179 Storage_Error_Def : aliased Exception_Data :=
180 (Not_Handled_By_Others => False,
181 Lang => 'A',
182 Name_Length => Storage_Error_Name'Length,
183 Full_Name => Storage_Error_Name'Address,
184 HTable_Ptr => null,
185 Foreign_Data => Null_Address,
186 Raise_Hook => null);
187
188 Tasking_Error_Def : aliased Exception_Data :=
189 (Not_Handled_By_Others => False,
190 Lang => 'A',
191 Name_Length => Tasking_Error_Name'Length,
192 Full_Name => Tasking_Error_Name'Address,
193 HTable_Ptr => null,
194 Foreign_Data => Null_Address,
195 Raise_Hook => null);
196
197 Abort_Signal_Def : aliased Exception_Data :=
198 (Not_Handled_By_Others => True,
199 Lang => 'A',
200 Name_Length => Abort_Signal_Name'Length,
201 Full_Name => Abort_Signal_Name'Address,
202 HTable_Ptr => null,
203 Foreign_Data => Null_Address,
204 Raise_Hook => null);
205
206 pragma Export (C, Constraint_Error_Def, "constraint_error");
207 pragma Export (C, Numeric_Error_Def, "numeric_error");
208 pragma Export (C, Program_Error_Def, "program_error");
209 pragma Export (C, Storage_Error_Def, "storage_error");
210 pragma Export (C, Tasking_Error_Def, "tasking_error");
211 pragma Export (C, Abort_Signal_Def, "_abort_signal");
212
213 Local_Partition_ID : Natural := 0;
214 -- This variable contains the local Partition_ID that will be used when
215 -- building exception occurrences. In distributed mode, it will be
216 -- set by each partition to the correct value during the elaboration.
217
218 type Exception_Trace_Kind is
219 (RM_Convention,
220 -- No particular trace is requested, only unhandled exceptions
221 -- in the environment task (following the RM) will be printed.
222 -- This is the default behavior.
223
224 Every_Raise,
225 -- Denotes the initial raise event for any exception occurrence, either
226 -- explicit or due to a specific language rule, within the context of a
227 -- task or not.
228
229 Unhandled_Raise,
230 -- Denotes the raise events corresponding to exceptions for which there
231 -- is no user defined handler. This includes unhandled exceptions in
232 -- task bodies.
233
234 Unhandled_Raise_In_Main
235 -- Same as Unhandled_Raise, except exceptions in task bodies are not
236 -- included. Same as RM_Convention, except (1) the message is printed as
237 -- soon as the environment task completes due to an unhandled exception
238 -- (before awaiting the termination of dependent tasks, and before
239 -- library-level finalization), and (2) a symbolic traceback is given
240 -- if possible. This is the default behavior if the binder switch -E is
241 -- used.
242 );
243 -- Provide a way to denote different kinds of automatic traces related
244 -- to exceptions that can be requested.
245
246 Exception_Trace : Exception_Trace_Kind := RM_Convention;
247 pragma Atomic (Exception_Trace);
248 -- By default, follow the RM convention
249
250 -----------------
251 -- Subprograms --
252 -----------------
253
254 procedure Abort_Undefer_Direct;
255 pragma Inline (Abort_Undefer_Direct);
256 -- A little procedure that just calls Abort_Undefer.all, for use in
257 -- clean up procedures, which only permit a simple subprogram name.
258
259 procedure Adafinal;
260 -- Performs the Ada Runtime finalization the first time it is invoked.
261 -- All subsequent calls are ignored.
262
263 end System.Standard_Library;