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-2013, 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-- 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--  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
47pragma Compiler_Unit_Warning;
48
49pragma 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
53with Ada.Unchecked_Conversion;
54
55package System.Standard_Library is
56   pragma Warnings (Off);
57   pragma Preelaborate_05;
58   pragma Warnings (On);
59
60   subtype Big_String is String (1 .. Positive'Last);
61   pragma Suppress_Initialization (Big_String);
62   --  Type used to obtain string access to given address. Initialization is
63   --  suppressed, since we never want to have variables of this type, and
64   --  we never want to attempt initialiazation of virtual variables of this
65   --  type (e.g. when pragma Normalize_Scalars is used).
66
67   type Big_String_Ptr is access all Big_String;
68   for Big_String_Ptr'Storage_Size use 0;
69   --  We use this access type to pass a pointer to an area of storage to be
70   --  accessed as a string. Of course when this pointer is used, it is the
71   --  responsibility of the accessor to ensure proper bounds. The storage
72   --  size clause ensures we do not allocate variables of this type.
73
74   function To_Ptr is
75     new Ada.Unchecked_Conversion (System.Address, Big_String_Ptr);
76
77   -------------------------------------
78   -- Exception Declarations and Data --
79   -------------------------------------
80
81   type Raise_Action is access procedure;
82   --  A pointer to a procedure used in the Raise_Hook field
83
84   type Exception_Data;
85   type Exception_Data_Ptr is access all Exception_Data;
86   --  An equivalent of Exception_Id that is public
87
88   --  The following record defines the underlying representation of exceptions
89
90   --  WARNING: Any changes to this may need to be reflected in the following
91   --  locations in the compiler and runtime code:
92
93   --    1. The Internal_Exception routine in s-exctab.adb
94   --    2. The processing in gigi that tests Not_Handled_By_Others
95   --    3. Expand_N_Exception_Declaration in Exp_Ch11
96   --    4. The construction of the exception type in Cstand
97
98   type Exception_Data is record
99      Not_Handled_By_Others : Boolean;
100      --  Normally set False, indicating that the exception is handled in the
101      --  usual way by others (i.e. an others handler handles the exception).
102      --  Set True to indicate that this exception is not caught by others
103      --  handlers, but must be explicitly named in a handler. This latter
104      --  setting is currently used by the Abort_Signal.
105
106      Lang : Character;
107      --  A character indicating the language raising the exception.
108      --  Set to "A" for exceptions defined by an Ada program.
109      --  Set to "V" for imported VMS exceptions.
110      --  Set to "C" for imported C++ exceptions.
111
112      Name_Length : Natural;
113      --  Length of fully expanded name of exception
114
115      Full_Name : System.Address;
116      --  Fully expanded name of exception, null terminated
117      --  You can use To_Ptr to convert this to a string.
118
119      HTable_Ptr : Exception_Data_Ptr;
120      --  Hash table pointer used to link entries together in the hash table
121      --  built (by Register_Exception in s-exctab.adb) for converting between
122      --  identities and names.
123
124      Foreign_Data : Address;
125      --  Data for imported exceptions. This represents the exception code
126      --  for the handling of Import/Export_Exception for the VMS case.
127      --  This 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 every possible raise event, either explicit or due to
226      --  a specific language rule, within the context of a task or not.
227
228      Unhandled_Raise
229      --  Denotes the raise events corresponding to exceptions for which
230      --  there is no user defined handler.
231     );
232   --  Provide a way to denote different kinds of automatic traces related
233   --  to exceptions that can be requested.
234
235   Exception_Trace : Exception_Trace_Kind := RM_Convention;
236   pragma Atomic (Exception_Trace);
237   --  By default, follow the RM convention
238
239   -----------------
240   -- Subprograms --
241   -----------------
242
243   procedure Abort_Undefer_Direct;
244   pragma Inline (Abort_Undefer_Direct);
245   --  A little procedure that just calls Abort_Undefer.all, for use in
246   --  clean up procedures, which only permit a simple subprogram name.
247
248   procedure Adafinal;
249   --  Performs the Ada Runtime finalization the first time it is invoked.
250   --  All subsequent calls are ignored.
251
252end System.Standard_Library;
253