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