gcc/ada/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-2010, 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
  47 pragma Compiler_Unit;
  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    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    -- Type For Enumeration Image Index Tables --
  79    ---------------------------------------------
  80
  81    --  Note: these types are declared at the start of this unit, since
  82    --  they must appear before any enumeration types declared in this
  83    --  unit. Note that the spec of system is already elaborated at
  84    --  this point (since we are a child of system), which means that
  85    --  enumeration types in package System cannot use these types.
  86
  87    type Image_Index_Table_8 is
  88      array (Integer range <>) of Short_Short_Integer;
  89    type Image_Index_Table_16 is
  90      array (Integer range <>) of Short_Integer;
  91    type Image_Index_Table_32 is
  92      array (Integer range <>) of Integer;
  93    --  These types are used to generate the index vector used for enumeration
  94    --  type image tables. See spec of Exp_Imgv in the main GNAT sources for a
  95    --  full description of the data structures that are used here.
  96
  97    -------------------------------------
  98    -- Exception Declarations and Data --
  99    -------------------------------------
 100
 101    type Raise_Action is access procedure;
 102    --  A pointer to a procedure used in the Raise_Hook field
 103
 104    type Exception_Data;
 105    type Exception_Data_Ptr is access all Exception_Data;
 106    --  An equivalent of Exception_Id that is public
 107
 108    type Exception_Code is mod 2 ** Integer'Size;
 109    --  A scalar value bound to some exception data. Typically used for
 110    --  imported or exported exceptions on VMS. Having a separate type for this
 111    --  is useful to enforce consistency throughout the various run-time units
 112    --  handling such codes, and having it unsigned is the most appropriate
 113    --  choice for it's currently single use on VMS.
 114
 115    --  ??? The construction in Cstand has no way to access the proper type
 116    --  node for Exception_Code, and currently uses Standard_Unsigned as a
 117    --  fallback. The representations shall match, and the size clause below
 118    --  is aimed at ensuring that.
 119
 120    for Exception_Code'Size use Integer'Size;
 121
 122    --  The following record defines the underlying representation of exceptions
 123
 124    --  WARNING! Any changes to this may need to be reflected in the following
 125    --  locations in the compiler and runtime code:
 126
 127    --    1. The Internal_Exception routine in s-exctab.adb
 128    --    2. The processing in gigi that tests Not_Handled_By_Others
 129    --    3. Expand_N_Exception_Declaration in Exp_Ch11
 130    --    4. The construction of the exception type in Cstand
 131
 132    type Exception_Data is record
 133       Not_Handled_By_Others : Boolean;
 134       --  Normally set False, indicating that the exception is handled in the
 135       --  usual way by others (i.e. an others handler handles the exception).
 136       --  Set True to indicate that this exception is not caught by others
 137       --  handlers, but must be explicitly named in a handler. This latter
 138       --  setting is currently used by the Abort_Signal.
 139
 140       Lang : Character;
 141       --  A character indicating the language raising the exception.
 142       --  Set to "A" for exceptions defined by an Ada program.
 143       --  Set to "V" for imported VMS exceptions.
 144
 145       Name_Length : Natural;
 146       --  Length of fully expanded name of exception
 147
 148       Full_Name : System.Address;
 149       --  Fully expanded name of exception, null terminated
 150       --  You can use To_Ptr to convert this to a string.
 151
 152       HTable_Ptr : Exception_Data_Ptr;
 153       --  Hash table pointer used to link entries together in the hash table
 154       --  built (by Register_Exception in s-exctab.adb) for converting between
 155       --  identities and names.
 156
 157       Import_Code : Exception_Code;
 158       --  Value for imported exceptions. Needed only for the handling of
 159       --  Import/Export_Exception for the VMS case, but present in all
 160       --  implementations (we might well extend this mechanism for other
 161       --  systems in the future).
 162
 163       Raise_Hook : Raise_Action;
 164       --  This field can be used to place a "hook" on an exception. If the
 165       --  value is non-null, then it points to a procedure which is called
 166       --  whenever the exception is raised. This call occurs immediately,
 167       --  before any other actions taken by the raise (and in particular
 168       --  before any unwinding of the stack occurs).
 169    end record;
 170
 171    --  Definitions for standard predefined exceptions defined in Standard,
 172
 173    --  Why are the NULs necessary here, seems like they should not be
 174    --  required, since Gigi is supposed to add a Nul to each name ???
 175
 176    Constraint_Error_Name : constant String := "CONSTRAINT_ERROR" & ASCII.NUL;
 177    Program_Error_Name    : constant String := "PROGRAM_ERROR"    & ASCII.NUL;
 178    Storage_Error_Name    : constant String := "STORAGE_ERROR"    & ASCII.NUL;
 179    Tasking_Error_Name    : constant String := "TASKING_ERROR"    & ASCII.NUL;
 180    Abort_Signal_Name     : constant String := "_ABORT_SIGNAL"    & ASCII.NUL;
 181
 182    Numeric_Error_Name    : constant String := "NUMERIC_ERROR"    & ASCII.NUL;
 183    --  This is used only in the Ada 83 case, but it is not worth having a
 184    --  separate version of s-stalib.ads for use in Ada 83 mode.
 185
 186    Constraint_Error_Def : aliased Exception_Data :=
 187      (Not_Handled_By_Others => False,
 188       Lang                  => 'A',
 189       Name_Length           => Constraint_Error_Name'Length,
 190       Full_Name             => Constraint_Error_Name'Address,
 191       HTable_Ptr            => null,
 192       Import_Code           => 0,
 193       Raise_Hook            => null);
 194
 195    Numeric_Error_Def : aliased Exception_Data :=
 196      (Not_Handled_By_Others => False,
 197       Lang                  => 'A',
 198       Name_Length           => Numeric_Error_Name'Length,
 199       Full_Name             => Numeric_Error_Name'Address,
 200       HTable_Ptr            => null,
 201       Import_Code           => 0,
 202       Raise_Hook            => null);
 203
 204    Program_Error_Def : aliased Exception_Data :=
 205      (Not_Handled_By_Others => False,
 206       Lang                  => 'A',
 207       Name_Length           => Program_Error_Name'Length,
 208       Full_Name             => Program_Error_Name'Address,
 209       HTable_Ptr            => null,
 210       Import_Code           => 0,
 211       Raise_Hook            => null);
 212
 213    Storage_Error_Def : aliased Exception_Data :=
 214      (Not_Handled_By_Others => False,
 215       Lang                  => 'A',
 216       Name_Length           => Storage_Error_Name'Length,
 217       Full_Name             => Storage_Error_Name'Address,
 218       HTable_Ptr            => null,
 219       Import_Code           => 0,
 220       Raise_Hook            => null);
 221
 222    Tasking_Error_Def : aliased Exception_Data :=
 223      (Not_Handled_By_Others => False,
 224       Lang                  => 'A',
 225       Name_Length           => Tasking_Error_Name'Length,
 226       Full_Name             => Tasking_Error_Name'Address,
 227       HTable_Ptr            => null,
 228       Import_Code           => 0,
 229       Raise_Hook            => null);
 230
 231    Abort_Signal_Def : aliased Exception_Data :=
 232      (Not_Handled_By_Others => True,
 233       Lang                  => 'A',
 234       Name_Length           => Abort_Signal_Name'Length,
 235       Full_Name             => Abort_Signal_Name'Address,
 236       HTable_Ptr            => null,
 237       Import_Code           => 0,
 238       Raise_Hook            => null);
 239
 240    pragma Export (C, Constraint_Error_Def, "constraint_error");
 241    pragma Export (C, Numeric_Error_Def,    "numeric_error");
 242    pragma Export (C, Program_Error_Def,    "program_error");
 243    pragma Export (C, Storage_Error_Def,    "storage_error");
 244    pragma Export (C, Tasking_Error_Def,    "tasking_error");
 245    pragma Export (C, Abort_Signal_Def,     "_abort_signal");
 246
 247    Local_Partition_ID : Natural := 0;
 248    --  This variable contains the local Partition_ID that will be used when
 249    --  building exception occurrences. In distributed mode, it will be
 250    --  set by each partition to the correct value during the elaboration.
 251
 252    type Exception_Trace_Kind is
 253      (RM_Convention,
 254       --  No particular trace is requested, only unhandled exceptions
 255       --  in the environment task (following the RM) will be printed.
 256       --  This is the default behavior.
 257
 258       Every_Raise,
 259       --  Denotes every possible raise event, either explicit or due to
 260       --  a specific language rule, within the context of a task or not.
 261
 262       Unhandled_Raise
 263       --  Denotes the raise events corresponding to exceptions for which
 264       --  there is no user defined handler.
 265      );
 266    --  Provide a way to denote different kinds of automatic traces related
 267    --  to exceptions that can be requested.
 268
 269    Exception_Trace : Exception_Trace_Kind := RM_Convention;
 270    pragma Atomic (Exception_Trace);
 271    --  By default, follow the RM convention
 272
 273    -----------------
 274    -- Subprograms --
 275    -----------------
 276
 277    procedure Abort_Undefer_Direct;
 278    pragma Inline (Abort_Undefer_Direct);
 279    --  A little procedure that just calls Abort_Undefer.all, for use in
 280    --  clean up procedures, which only permit a simple subprogram name.
 281
 282    procedure Adafinal;
 283    --  Performs the Ada Runtime finalization the first time it is invoked.
 284    --  All subsequent calls are ignored.
 285
 286 end System.Standard_Library;