aboutsummaryrefslogtreecommitdiffstats
path: root/gcc-4.4.3/gcc/ada/gnat_rm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'gcc-4.4.3/gcc/ada/gnat_rm.texi')
-rw-r--r--gcc-4.4.3/gcc/ada/gnat_rm.texi16816
1 files changed, 0 insertions, 16816 deletions
diff --git a/gcc-4.4.3/gcc/ada/gnat_rm.texi b/gcc-4.4.3/gcc/ada/gnat_rm.texi
deleted file mode 100644
index a768528d4..000000000
--- a/gcc-4.4.3/gcc/ada/gnat_rm.texi
+++ /dev/null
@@ -1,16816 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-
-@c %**start of header
-
-@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
-@c o
-@c GNAT DOCUMENTATION o
-@c o
-@c G N A T _ RM o
-@c o
-@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
-@c o
-@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
-
-@setfilename gnat_rm.info
-
-@copying
-Copyright @copyright{} 1995-2008, Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``GNAT Reference
-Manual'', and with no Back-Cover Texts. A copy of the license is
-included in the section entitled ``GNU Free Documentation License''.
-@end copying
-
-@set EDITION GNAT
-@set DEFAULTLANGUAGEVERSION Ada 2005
-@set NONDEFAULTLANGUAGEVERSION Ada 95
-
-@settitle GNAT Reference Manual
-
-@setchapternewpage odd
-@syncodeindex fn cp
-
-@include gcc-common.texi
-
-@dircategory GNU Ada tools
-@direntry
-* GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools.
-@end direntry
-
-@titlepage
-@title GNAT Reference Manual
-@subtitle GNAT, The GNU Ada Compiler
-@versionsubtitle
-@author AdaCore
-@page
-@vskip 0pt plus 1filll
-
-@insertcopying
-
-@end titlepage
-
-@ifnottex
-@node Top, About This Guide, (dir), (dir)
-@top GNAT Reference Manual
-
-@noindent
-GNAT Reference Manual
-
-@noindent
-GNAT, The GNU Ada Compiler@*
-GCC version @value{version-GCC}@*
-
-@noindent
-AdaCore
-
-@menu
-* About This Guide::
-* Implementation Defined Pragmas::
-* Implementation Defined Attributes::
-* Implementation Advice::
-* Implementation Defined Characteristics::
-* Intrinsic Subprograms::
-* Representation Clauses and Pragmas::
-* Standard Library Routines::
-* The Implementation of Standard I/O::
-* The GNAT Library::
-* Interfacing to Other Languages::
-* Specialized Needs Annexes::
-* Implementation of Specific Ada Features::
-* Project File Reference::
-* Obsolescent Features::
-* GNU Free Documentation License::
-* Index::
-
- --- The Detailed Node Listing ---
-
-About This Guide
-
-* What This Reference Manual Contains::
-* Related Information::
-
-Implementation Defined Pragmas
-
-* Pragma Abort_Defer::
-* Pragma Ada_83::
-* Pragma Ada_95::
-* Pragma Ada_05::
-* Pragma Ada_2005::
-* Pragma Annotate::
-* Pragma Assert::
-* Pragma Ast_Entry::
-* Pragma C_Pass_By_Copy::
-* Pragma Check::
-* Pragma Check_Name::
-* Pragma Check_Policy::
-* Pragma Comment::
-* Pragma Common_Object::
-* Pragma Compile_Time_Error::
-* Pragma Compile_Time_Warning::
-* Pragma Complete_Representation::
-* Pragma Complex_Representation::
-* Pragma Component_Alignment::
-* Pragma Convention_Identifier::
-* Pragma CPP_Class::
-* Pragma CPP_Constructor::
-* Pragma CPP_Virtual::
-* Pragma CPP_Vtable::
-* Pragma Debug::
-* Pragma Debug_Policy::
-* Pragma Detect_Blocking::
-* Pragma Elaboration_Checks::
-* Pragma Eliminate::
-* Pragma Export_Exception::
-* Pragma Export_Function::
-* Pragma Export_Object::
-* Pragma Export_Procedure::
-* Pragma Export_Value::
-* Pragma Export_Valued_Procedure::
-* Pragma Extend_System::
-* Pragma External::
-* Pragma External_Name_Casing::
-* Pragma Fast_Math::
-* Pragma Favor_Top_Level::
-* Pragma Finalize_Storage_Only::
-* Pragma Float_Representation::
-* Pragma Ident::
-* Pragma Implemented_By_Entry::
-* Pragma Implicit_Packing::
-* Pragma Import_Exception::
-* Pragma Import_Function::
-* Pragma Import_Object::
-* Pragma Import_Procedure::
-* Pragma Import_Valued_Procedure::
-* Pragma Initialize_Scalars::
-* Pragma Inline_Always::
-* Pragma Inline_Generic::
-* Pragma Interface::
-* Pragma Interface_Name::
-* Pragma Interrupt_Handler::
-* Pragma Interrupt_State::
-* Pragma Keep_Names::
-* Pragma License::
-* Pragma Link_With::
-* Pragma Linker_Alias::
-* Pragma Linker_Constructor::
-* Pragma Linker_Destructor::
-* Pragma Linker_Section::
-* Pragma Long_Float::
-* Pragma Machine_Attribute::
-* Pragma Main::
-* Pragma Main_Storage::
-* Pragma No_Body::
-* Pragma No_Return::
-* Pragma No_Strict_Aliasing ::
-* Pragma Normalize_Scalars::
-* Pragma Obsolescent::
-* Pragma Optimize_Alignment::
-* Pragma Passive::
-* Pragma Persistent_BSS::
-* Pragma Polling::
-* Pragma Postcondition::
-* Pragma Precondition::
-* Pragma Profile (Ravenscar)::
-* Pragma Profile (Restricted)::
-* Pragma Psect_Object::
-* Pragma Pure_Function::
-* Pragma Restriction_Warnings::
-* Pragma Shared::
-* Pragma Source_File_Name::
-* Pragma Source_File_Name_Project::
-* Pragma Source_Reference::
-* Pragma Stream_Convert::
-* Pragma Style_Checks::
-* Pragma Subtitle::
-* Pragma Suppress::
-* Pragma Suppress_All::
-* Pragma Suppress_Exception_Locations::
-* Pragma Suppress_Initialization::
-* Pragma Task_Info::
-* Pragma Task_Name::
-* Pragma Task_Storage::
-* Pragma Time_Slice::
-* Pragma Title::
-* Pragma Unchecked_Union::
-* Pragma Unimplemented_Unit::
-* Pragma Universal_Aliasing ::
-* Pragma Universal_Data::
-* Pragma Unmodified::
-* Pragma Unreferenced::
-* Pragma Unreferenced_Objects::
-* Pragma Unreserve_All_Interrupts::
-* Pragma Unsuppress::
-* Pragma Use_VADS_Size::
-* Pragma Validity_Checks::
-* Pragma Volatile::
-* Pragma Warnings::
-* Pragma Weak_External::
-* Pragma Wide_Character_Encoding::
-
-Implementation Defined Attributes
-
-* Abort_Signal::
-* Address_Size::
-* Asm_Input::
-* Asm_Output::
-* AST_Entry::
-* Bit::
-* Bit_Position::
-* Code_Address::
-* Default_Bit_Order::
-* Elaborated::
-* Elab_Body::
-* Elab_Spec::
-* Emax::
-* Enabled::
-* Enum_Rep::
-* Enum_Val::
-* Epsilon::
-* Fixed_Value::
-* Has_Access_Values::
-* Has_Discriminants::
-* Img::
-* Integer_Value::
-* Invalid_Value::
-* Large::
-* Machine_Size::
-* Mantissa::
-* Max_Interrupt_Priority::
-* Max_Priority::
-* Maximum_Alignment::
-* Mechanism_Code::
-* Null_Parameter::
-* Object_Size::
-* Old::
-* Passed_By_Reference::
-* Pool_Address::
-* Range_Length::
-* Safe_Emax::
-* Safe_Large::
-* Small::
-* Storage_Unit::
-* Stub_Type::
-* Target_Name::
-* Tick::
-* To_Address::
-* Type_Class::
-* UET_Address::
-* Unconstrained_Array::
-* Universal_Literal_String::
-* Unrestricted_Access::
-* VADS_Size::
-* Value_Size::
-* Wchar_T_Size::
-* Word_Size::
-
-The Implementation of Standard I/O
-
-* Standard I/O Packages::
-* FORM Strings::
-* Direct_IO::
-* Sequential_IO::
-* Text_IO::
-* Wide_Text_IO::
-* Wide_Wide_Text_IO::
-* Stream_IO::
-* Shared Files::
-* Filenames encoding::
-* Open Modes::
-* Operations on C Streams::
-* Interfacing to C Streams::
-
-The GNAT Library
-
-* Ada.Characters.Latin_9 (a-chlat9.ads)::
-* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
-* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
-* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
-* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
-* Ada.Command_Line.Environment (a-colien.ads)::
-* Ada.Command_Line.Remove (a-colire.ads)::
-* Ada.Command_Line.Response_File (a-clrefi.ads)::
-* Ada.Direct_IO.C_Streams (a-diocst.ads)::
-* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
-* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
-* Ada.Exceptions.Traceback (a-exctra.ads)::
-* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
-* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
-* Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
-* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
-* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
-* Ada.Text_IO.C_Streams (a-tiocst.ads)::
-* Ada.Wide_Characters.Unicode (a-wichun.ads)::
-* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
-* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
-* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
-* GNAT.Altivec (g-altive.ads)::
-* GNAT.Altivec.Conversions (g-altcon.ads)::
-* GNAT.Altivec.Vector_Operations (g-alveop.ads)::
-* GNAT.Altivec.Vector_Types (g-alvety.ads)::
-* GNAT.Altivec.Vector_Views (g-alvevi.ads)::
-* GNAT.Array_Split (g-arrspl.ads)::
-* GNAT.AWK (g-awk.ads)::
-* GNAT.Bounded_Buffers (g-boubuf.ads)::
-* GNAT.Bounded_Mailboxes (g-boumai.ads)::
-* GNAT.Bubble_Sort (g-bubsor.ads)::
-* GNAT.Bubble_Sort_A (g-busora.ads)::
-* GNAT.Bubble_Sort_G (g-busorg.ads)::
-* GNAT.Byte_Order_Mark (g-byorma.ads)::
-* GNAT.Byte_Swapping (g-bytswa.ads)::
-* GNAT.Calendar (g-calend.ads)::
-* GNAT.Calendar.Time_IO (g-catiio.ads)::
-* GNAT.Case_Util (g-casuti.ads)::
-* GNAT.CGI (g-cgi.ads)::
-* GNAT.CGI.Cookie (g-cgicoo.ads)::
-* GNAT.CGI.Debug (g-cgideb.ads)::
-* GNAT.Command_Line (g-comlin.ads)::
-* GNAT.Compiler_Version (g-comver.ads)::
-* GNAT.Ctrl_C (g-ctrl_c.ads)::
-* GNAT.CRC32 (g-crc32.ads)::
-* GNAT.Current_Exception (g-curexc.ads)::
-* GNAT.Debug_Pools (g-debpoo.ads)::
-* GNAT.Debug_Utilities (g-debuti.ads)::
-* GNAT.Decode_String (g-decstr.ads)::
-* GNAT.Decode_UTF8_String (g-deutst.ads)::
-* GNAT.Directory_Operations (g-dirope.ads)::
-* GNAT.Directory_Operations.Iteration (g-diopit.ads)::
-* GNAT.Dynamic_HTables (g-dynhta.ads)::
-* GNAT.Dynamic_Tables (g-dyntab.ads)::
-* GNAT.Encode_String (g-encstr.ads)::
-* GNAT.Encode_UTF8_String (g-enutst.ads)::
-* GNAT.Exception_Actions (g-excact.ads)::
-* GNAT.Exception_Traces (g-exctra.ads)::
-* GNAT.Exceptions (g-except.ads)::
-* GNAT.Expect (g-expect.ads)::
-* GNAT.Float_Control (g-flocon.ads)::
-* GNAT.Heap_Sort (g-heasor.ads)::
-* GNAT.Heap_Sort_A (g-hesora.ads)::
-* GNAT.Heap_Sort_G (g-hesorg.ads)::
-* GNAT.HTable (g-htable.ads)::
-* GNAT.IO (g-io.ads)::
-* GNAT.IO_Aux (g-io_aux.ads)::
-* GNAT.Lock_Files (g-locfil.ads)::
-* GNAT.MD5 (g-md5.ads)::
-* GNAT.Memory_Dump (g-memdum.ads)::
-* GNAT.Most_Recent_Exception (g-moreex.ads)::
-* GNAT.OS_Lib (g-os_lib.ads)::
-* GNAT.Perfect_Hash_Generators (g-pehage.ads)::
-* GNAT.Random_Numbers (g-rannum.ads)::
-* GNAT.Regexp (g-regexp.ads)::
-* GNAT.Registry (g-regist.ads)::
-* GNAT.Regpat (g-regpat.ads)::
-* GNAT.Secondary_Stack_Info (g-sestin.ads)::
-* GNAT.Semaphores (g-semaph.ads)::
-* GNAT.Serial_Communications (g-sercom.ads)::
-* GNAT.SHA1 (g-sha1.ads)::
-* GNAT.Signals (g-signal.ads)::
-* GNAT.Sockets (g-socket.ads)::
-* GNAT.Source_Info (g-souinf.ads)::
-* GNAT.Spelling_Checker (g-speche.ads)::
-* GNAT.Spelling_Checker_Generic (g-spchge.ads)::
-* GNAT.Spitbol.Patterns (g-spipat.ads)::
-* GNAT.Spitbol (g-spitbo.ads)::
-* GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
-* GNAT.Spitbol.Table_Integer (g-sptain.ads)::
-* GNAT.Spitbol.Table_VString (g-sptavs.ads)::
-* GNAT.Strings (g-string.ads)::
-* GNAT.String_Split (g-strspl.ads)::
-* GNAT.Table (g-table.ads)::
-* GNAT.Task_Lock (g-tasloc.ads)::
-* GNAT.Threads (g-thread.ads)::
-* GNAT.Time_Stamp (g-timsta.ads)::
-* GNAT.Traceback (g-traceb.ads)::
-* GNAT.Traceback.Symbolic (g-trasym.ads)::
-* GNAT.UTF_32 (g-utf_32.ads)::
-* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
-* GNAT.Wide_Spelling_Checker (g-wispch.ads)::
-* GNAT.Wide_String_Split (g-wistsp.ads)::
-* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
-* GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
-* Interfaces.C.Extensions (i-cexten.ads)::
-* Interfaces.C.Streams (i-cstrea.ads)::
-* Interfaces.CPP (i-cpp.ads)::
-* Interfaces.Packed_Decimal (i-pacdec.ads)::
-* Interfaces.VxWorks (i-vxwork.ads)::
-* Interfaces.VxWorks.IO (i-vxwoio.ads)::
-* System.Address_Image (s-addima.ads)::
-* System.Assertions (s-assert.ads)::
-* System.Memory (s-memory.ads)::
-* System.Partition_Interface (s-parint.ads)::
-* System.Pool_Global (s-pooglo.ads)::
-* System.Pool_Local (s-pooloc.ads)::
-* System.Restrictions (s-restri.ads)::
-* System.Rident (s-rident.ads)::
-* System.Task_Info (s-tasinf.ads)::
-* System.Wch_Cnv (s-wchcnv.ads)::
-* System.Wch_Con (s-wchcon.ads)::
-
-Text_IO
-
-* Text_IO Stream Pointer Positioning::
-* Text_IO Reading and Writing Non-Regular Files::
-* Get_Immediate::
-* Treating Text_IO Files as Streams::
-* Text_IO Extensions::
-* Text_IO Facilities for Unbounded Strings::
-
-Wide_Text_IO
-
-* Wide_Text_IO Stream Pointer Positioning::
-* Wide_Text_IO Reading and Writing Non-Regular Files::
-
-Wide_Wide_Text_IO
-
-* Wide_Wide_Text_IO Stream Pointer Positioning::
-* Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
-
-Interfacing to Other Languages
-
-* Interfacing to C::
-* Interfacing to C++::
-* Interfacing to COBOL::
-* Interfacing to Fortran::
-* Interfacing to non-GNAT Ada code::
-
-Specialized Needs Annexes
-
-Implementation of Specific Ada Features
-* Machine Code Insertions::
-* GNAT Implementation of Tasking::
-* GNAT Implementation of Shared Passive Packages::
-* Code Generation for Array Aggregates::
-* The Size of Discriminated Records with Default Discriminants::
-* Strict Conformance to the Ada Reference Manual::
-
-Project File Reference
-
-Obsolescent Features
-
-GNU Free Documentation License
-
-Index
-@end menu
-
-@end ifnottex
-
-@node About This Guide
-@unnumbered About This Guide
-
-@noindent
-This manual contains useful information in writing programs using the
-@value{EDITION} compiler. It includes information on implementation dependent
-characteristics of @value{EDITION}, including all the information required by
-Annex M of the Ada language standard.
-
-@value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in
-Ada 83 compatibility mode.
-By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
-but you can override with a compiler switch
-to explicitly specify the language version.
-(Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn,
-@value{EDITION} User's Guide}, for details on these switches.)
-Throughout this manual, references to ``Ada'' without a year suffix
-apply to both the Ada 95 and Ada 2005 versions of the language.
-
-Ada is designed to be highly portable.
-In general, a program will have the same effect even when compiled by
-different compilers on different platforms.
-However, since Ada is designed to be used in a
-wide variety of applications, it also contains a number of system
-dependent features to be used in interfacing to the external world.
-@cindex Implementation-dependent features
-@cindex Portability
-
-Note: Any program that makes use of implementation-dependent features
-may be non-portable. You should follow good programming practice and
-isolate and clearly document any sections of your program that make use
-of these features in a non-portable manner.
-
-@ifset PROEDITION
-For ease of exposition, ``GNAT Pro'' will be referred to simply as
-``GNAT'' in the remainder of this document.
-@end ifset
-
-@menu
-* What This Reference Manual Contains::
-* Conventions::
-* Related Information::
-@end menu
-
-@node What This Reference Manual Contains
-@unnumberedsec What This Reference Manual Contains
-
-@noindent
-This reference manual contains the following chapters:
-
-@itemize @bullet
-@item
-@ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent
-pragmas, which can be used to extend and enhance the functionality of the
-compiler.
-
-@item
-@ref{Implementation Defined Attributes}, lists GNAT
-implementation-dependent attributes which can be used to extend and
-enhance the functionality of the compiler.
-
-@item
-@ref{Implementation Advice}, provides information on generally
-desirable behavior which are not requirements that all compilers must
-follow since it cannot be provided on all systems, or which may be
-undesirable on some systems.
-
-@item
-@ref{Implementation Defined Characteristics}, provides a guide to
-minimizing implementation dependent features.
-
-@item
-@ref{Intrinsic Subprograms}, describes the intrinsic subprograms
-implemented by GNAT, and how they can be imported into user
-application programs.
-
-@item
-@ref{Representation Clauses and Pragmas}, describes in detail the
-way that GNAT represents data, and in particular the exact set
-of representation clauses and pragmas that is accepted.
-
-@item
-@ref{Standard Library Routines}, provides a listing of packages and a
-brief description of the functionality that is provided by Ada's
-extensive set of standard library routines as implemented by GNAT@.
-
-@item
-@ref{The Implementation of Standard I/O}, details how the GNAT
-implementation of the input-output facilities.
-
-@item
-@ref{The GNAT Library}, is a catalog of packages that complement
-the Ada predefined library.
-
-@item
-@ref{Interfacing to Other Languages}, describes how programs
-written in Ada using GNAT can be interfaced to other programming
-languages.
-
-@ref{Specialized Needs Annexes}, describes the GNAT implementation of all
-of the specialized needs annexes.
-
-@item
-@ref{Implementation of Specific Ada Features}, discusses issues related
-to GNAT's implementation of machine code insertions, tasking, and several
-other features.
-
-@item
-@ref{Project File Reference}, presents the syntax and semantics
-of project files.
-
-@item
-@ref{Obsolescent Features} documents implementation dependent features,
-including pragmas and attributes, which are considered obsolescent, since
-there are other preferred ways of achieving the same results. These
-obsolescent forms are retained for backwards compatibility.
-
-@end itemize
-
-@cindex Ada 95 Language Reference Manual
-@cindex Ada 2005 Language Reference Manual
-@noindent
-This reference manual assumes a basic familiarity with the Ada 95 language, as
-described in the International Standard ANSI/ISO/IEC-8652:1995,
-January 1995.
-It does not require knowledge of the new features introduced by Ada 2005,
-(officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1
-and Amendment 1).
-Both reference manuals are included in the GNAT documentation
-package.
-
-@node Conventions
-@unnumberedsec Conventions
-@cindex Conventions, typographical
-@cindex Typographical conventions
-
-@noindent
-Following are examples of the typographical and graphic conventions used
-in this guide:
-
-@itemize @bullet
-@item
-@code{Functions}, @code{utility program names}, @code{standard names},
-and @code{classes}.
-
-@item
-@code{Option flags}
-
-@item
-@file{File names}, @samp{button names}, and @samp{field names}.
-
-@item
-@code{Variables}, @env{environment variables}, and @var{metasyntactic
-variables}.
-
-@item
-@emph{Emphasis}.
-
-@item
-[optional information or parameters]
-
-@item
-Examples are described by text
-@smallexample
-and then shown this way.
-@end smallexample
-@end itemize
-
-@noindent
-Commands that are entered by the user are preceded in this manual by the
-characters @samp{$ } (dollar sign followed by space). If your system uses this
-sequence as a prompt, then the commands will appear exactly as you see them
-in the manual. If your system uses some other prompt, then the command will
-appear with the @samp{$} replaced by whatever prompt character you are using.
-
-@node Related Information
-@unnumberedsec Related Information
-@noindent
-See the following documents for further information on GNAT:
-
-@itemize @bullet
-@item
-@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn,
-@value{EDITION} User's Guide}, which provides information on how to use the
-GNAT compiler system.
-
-@item
-@cite{Ada 95 Reference Manual}, which contains all reference
-material for the Ada 95 programming language.
-
-@item
-@cite{Ada 95 Annotated Reference Manual}, which is an annotated version
-of the Ada 95 standard. The annotations describe
-detailed aspects of the design decision, and in particular contain useful
-sections on Ada 83 compatibility.
-
-@item
-@cite{Ada 2005 Reference Manual}, which contains all reference
-material for the Ada 2005 programming language.
-
-@item
-@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
-of the Ada 2005 standard. The annotations describe
-detailed aspects of the design decision, and in particular contain useful
-sections on Ada 83 and Ada 95 compatibility.
-
-@item
-@cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
-which contains specific information on compatibility between GNAT and
-DEC Ada 83 systems.
-
-@item
-@cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
-describes in detail the pragmas and attributes provided by the DEC Ada 83
-compiler system.
-
-@end itemize
-
-@node Implementation Defined Pragmas
-@chapter Implementation Defined Pragmas
-
-@noindent
-Ada defines a set of pragmas that can be used to supply additional
-information to the compiler. These language defined pragmas are
-implemented in GNAT and work as described in the Ada Reference
-Manual.
-
-In addition, Ada allows implementations to define additional pragmas
-whose meaning is defined by the implementation. GNAT provides a number
-of these implementation-defined pragmas, which can be used to extend
-and enhance the functionality of the compiler. This section of the GNAT
-Reference Manual describes these additional pragmas.
-
-Note that any program using these pragmas might not be portable to other
-compilers (although GNAT implements this set of pragmas on all
-platforms). Therefore if portability to other compilers is an important
-consideration, the use of these pragmas should be minimized.
-
-@menu
-* Pragma Abort_Defer::
-* Pragma Ada_83::
-* Pragma Ada_95::
-* Pragma Ada_05::
-* Pragma Ada_2005::
-* Pragma Annotate::
-* Pragma Assert::
-* Pragma Ast_Entry::
-* Pragma C_Pass_By_Copy::
-* Pragma Check::
-* Pragma Check_Name::
-* Pragma Check_Policy::
-* Pragma Comment::
-* Pragma Common_Object::
-* Pragma Compile_Time_Error::
-* Pragma Compile_Time_Warning::
-* Pragma Complete_Representation::
-* Pragma Complex_Representation::
-* Pragma Component_Alignment::
-* Pragma Convention_Identifier::
-* Pragma CPP_Class::
-* Pragma CPP_Constructor::
-* Pragma CPP_Virtual::
-* Pragma CPP_Vtable::
-* Pragma Debug::
-* Pragma Debug_Policy::
-* Pragma Detect_Blocking::
-* Pragma Elaboration_Checks::
-* Pragma Eliminate::
-* Pragma Export_Exception::
-* Pragma Export_Function::
-* Pragma Export_Object::
-* Pragma Export_Procedure::
-* Pragma Export_Value::
-* Pragma Export_Valued_Procedure::
-* Pragma Extend_System::
-* Pragma External::
-* Pragma External_Name_Casing::
-* Pragma Fast_Math::
-* Pragma Favor_Top_Level::
-* Pragma Finalize_Storage_Only::
-* Pragma Float_Representation::
-* Pragma Ident::
-* Pragma Implemented_By_Entry::
-* Pragma Implicit_Packing::
-* Pragma Import_Exception::
-* Pragma Import_Function::
-* Pragma Import_Object::
-* Pragma Import_Procedure::
-* Pragma Import_Valued_Procedure::
-* Pragma Initialize_Scalars::
-* Pragma Inline_Always::
-* Pragma Inline_Generic::
-* Pragma Interface::
-* Pragma Interface_Name::
-* Pragma Interrupt_Handler::
-* Pragma Interrupt_State::
-* Pragma Keep_Names::
-* Pragma License::
-* Pragma Link_With::
-* Pragma Linker_Alias::
-* Pragma Linker_Constructor::
-* Pragma Linker_Destructor::
-* Pragma Linker_Section::
-* Pragma Long_Float::
-* Pragma Machine_Attribute::
-* Pragma Main::
-* Pragma Main_Storage::
-* Pragma No_Body::
-* Pragma No_Return::
-* Pragma No_Strict_Aliasing::
-* Pragma Normalize_Scalars::
-* Pragma Obsolescent::
-* Pragma Optimize_Alignment::
-* Pragma Passive::
-* Pragma Persistent_BSS::
-* Pragma Polling::
-* Pragma Postcondition::
-* Pragma Precondition::
-* Pragma Profile (Ravenscar)::
-* Pragma Profile (Restricted)::
-* Pragma Psect_Object::
-* Pragma Pure_Function::
-* Pragma Restriction_Warnings::
-* Pragma Shared::
-* Pragma Source_File_Name::
-* Pragma Source_File_Name_Project::
-* Pragma Source_Reference::
-* Pragma Stream_Convert::
-* Pragma Style_Checks::
-* Pragma Subtitle::
-* Pragma Suppress::
-* Pragma Suppress_All::
-* Pragma Suppress_Exception_Locations::
-* Pragma Suppress_Initialization::
-* Pragma Task_Info::
-* Pragma Task_Name::
-* Pragma Task_Storage::
-* Pragma Time_Slice::
-* Pragma Title::
-* Pragma Unchecked_Union::
-* Pragma Unimplemented_Unit::
-* Pragma Universal_Aliasing ::
-* Pragma Universal_Data::
-* Pragma Unmodified::
-* Pragma Unreferenced::
-* Pragma Unreferenced_Objects::
-* Pragma Unreserve_All_Interrupts::
-* Pragma Unsuppress::
-* Pragma Use_VADS_Size::
-* Pragma Validity_Checks::
-* Pragma Volatile::
-* Pragma Warnings::
-* Pragma Weak_External::
-* Pragma Wide_Character_Encoding::
-@end menu
-
-@node Pragma Abort_Defer
-@unnumberedsec Pragma Abort_Defer
-@findex Abort_Defer
-@cindex Deferring aborts
-@noindent
-Syntax:
-@smallexample
-pragma Abort_Defer;
-@end smallexample
-
-@noindent
-This pragma must appear at the start of the statement sequence of a
-handled sequence of statements (right after the @code{begin}). It has
-the effect of deferring aborts for the sequence of statements (but not
-for the declarations or handlers, if any, associated with this statement
-sequence).
-
-@node Pragma Ada_83
-@unnumberedsec Pragma Ada_83
-@findex Ada_83
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Ada_83;
-@end smallexample
-
-@noindent
-A configuration pragma that establishes Ada 83 mode for the unit to
-which it applies, regardless of the mode set by the command line
-switches. In Ada 83 mode, GNAT attempts to be as compatible with
-the syntax and semantics of Ada 83, as defined in the original Ada
-83 Reference Manual as possible. In particular, the keywords added by Ada 95
-and Ada 2005 are not recognized, optional package bodies are allowed,
-and generics may name types with unknown discriminants without using
-the @code{(<>)} notation. In addition, some but not all of the additional
-restrictions of Ada 83 are enforced.
-
-Ada 83 mode is intended for two purposes. Firstly, it allows existing
-Ada 83 code to be compiled and adapted to GNAT with less effort.
-Secondly, it aids in keeping code backwards compatible with Ada 83.
-However, there is no guarantee that code that is processed correctly
-by GNAT in Ada 83 mode will in fact compile and execute with an Ada
-83 compiler, since GNAT does not enforce all the additional checks
-required by Ada 83.
-
-@node Pragma Ada_95
-@unnumberedsec Pragma Ada_95
-@findex Ada_95
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Ada_95;
-@end smallexample
-
-@noindent
-A configuration pragma that establishes Ada 95 mode for the unit to which
-it applies, regardless of the mode set by the command line switches.
-This mode is set automatically for the @code{Ada} and @code{System}
-packages and their children, so you need not specify it in these
-contexts. This pragma is useful when writing a reusable component that
-itself uses Ada 95 features, but which is intended to be usable from
-either Ada 83 or Ada 95 programs.
-
-@node Pragma Ada_05
-@unnumberedsec Pragma Ada_05
-@findex Ada_05
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Ada_05;
-@end smallexample
-
-@noindent
-A configuration pragma that establishes Ada 2005 mode for the unit to which
-it applies, regardless of the mode set by the command line switches.
-This mode is set automatically for the @code{Ada} and @code{System}
-packages and their children, so you need not specify it in these
-contexts. This pragma is useful when writing a reusable component that
-itself uses Ada 2005 features, but which is intended to be usable from
-either Ada 83 or Ada 95 programs.
-
-@node Pragma Ada_2005
-@unnumberedsec Pragma Ada_2005
-@findex Ada_2005
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Ada_2005;
-@end smallexample
-
-@noindent
-This configuration pragma is a synonym for pragma Ada_05 and has the
-same syntax and effect.
-
-@node Pragma Annotate
-@unnumberedsec Pragma Annotate
-@findex Annotate
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Annotate (IDENTIFIER @{, ARG@});
-
-ARG ::= NAME | EXPRESSION
-@end smallexample
-
-@noindent
-This pragma is used to annotate programs. @var{identifier} identifies
-the type of annotation. GNAT verifies that it is an identifier, but does
-not otherwise analyze it. The @var{arg} argument
-can be either a string literal or an
-expression. String literals are assumed to be of type
-@code{Standard.String}. Names of entities are simply analyzed as entity
-names. All other expressions are analyzed as expressions, and must be
-unambiguous.
-
-The analyzed pragma is retained in the tree, but not otherwise processed
-by any part of the GNAT compiler. This pragma is intended for use by
-external tools, including ASIS@.
-
-@node Pragma Assert
-@unnumberedsec Pragma Assert
-@findex Assert
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Assert (
- boolean_EXPRESSION
- [, string_EXPRESSION]);
-@end smallexample
-
-@noindent
-The effect of this pragma depends on whether the corresponding command
-line switch is set to activate assertions. The pragma expands into code
-equivalent to the following:
-
-@smallexample @c ada
-if assertions-enabled then
- if not boolean_EXPRESSION then
- System.Assertions.Raise_Assert_Failure
- (string_EXPRESSION);
- end if;
-end if;
-@end smallexample
-
-@noindent
-The string argument, if given, is the message that will be associated
-with the exception occurrence if the exception is raised. If no second
-argument is given, the default message is @samp{@var{file}:@var{nnn}},
-where @var{file} is the name of the source file containing the assert,
-and @var{nnn} is the line number of the assert. A pragma is not a
-statement, so if a statement sequence contains nothing but a pragma
-assert, then a null statement is required in addition, as in:
-
-@smallexample @c ada
-@dots{}
-if J > 3 then
- pragma Assert (K > 3, "Bad value for K");
- null;
-end if;
-@end smallexample
-
-@noindent
-Note that, as with the @code{if} statement to which it is equivalent, the
-type of the expression is either @code{Standard.Boolean}, or any type derived
-from this standard type.
-
-If assertions are disabled (switch @option{-gnata} not used), then there
-is no run-time effect (and in particular, any side effects from the
-expression will not occur at run time). (The expression is still
-analyzed at compile time, and may cause types to be frozen if they are
-mentioned here for the first time).
-
-If assertions are enabled, then the given expression is tested, and if
-it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
-which results in the raising of @code{Assert_Failure} with the given message.
-
-You should generally avoid side effects in the expression arguments of
-this pragma, because these side effects will turn on and off with the
-setting of the assertions mode, resulting in assertions that have an
-effect on the program. However, the expressions are analyzed for
-semantic correctness whether or not assertions are enabled, so turning
-assertions on and off cannot affect the legality of a program.
-
-@node Pragma Ast_Entry
-@unnumberedsec Pragma Ast_Entry
-@cindex OpenVMS
-@findex Ast_Entry
-@noindent
-Syntax:
-@smallexample @c ada
-pragma AST_Entry (entry_IDENTIFIER);
-@end smallexample
-
-@noindent
-This pragma is implemented only in the OpenVMS implementation of GNAT@. The
-argument is the simple name of a single entry; at most one @code{AST_Entry}
-pragma is allowed for any given entry. This pragma must be used in
-conjunction with the @code{AST_Entry} attribute, and is only allowed after
-the entry declaration and in the same task type specification or single task
-as the entry to which it applies. This pragma specifies that the given entry
-may be used to handle an OpenVMS asynchronous system trap (@code{AST})
-resulting from an OpenVMS system service call. The pragma does not affect
-normal use of the entry. For further details on this pragma, see the
-DEC Ada Language Reference Manual, section 9.12a.
-
-@node Pragma C_Pass_By_Copy
-@unnumberedsec Pragma C_Pass_By_Copy
-@cindex Passing by copy
-@findex C_Pass_By_Copy
-@noindent
-Syntax:
-@smallexample @c ada
-pragma C_Pass_By_Copy
- ([Max_Size =>] static_integer_EXPRESSION);
-@end smallexample
-
-@noindent
-Normally the default mechanism for passing C convention records to C
-convention subprograms is to pass them by reference, as suggested by RM
-B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
-this default, by requiring that record formal parameters be passed by
-copy if all of the following conditions are met:
-
-@itemize @bullet
-@item
-The size of the record type does not exceed the value specified for
-@code{Max_Size}.
-@item
-The record type has @code{Convention C}.
-@item
-The formal parameter has this record type, and the subprogram has a
-foreign (non-Ada) convention.
-@end itemize
-
-@noindent
-If these conditions are met the argument is passed by copy, i.e.@: in a
-manner consistent with what C expects if the corresponding formal in the
-C prototype is a struct (rather than a pointer to a struct).
-
-You can also pass records by copy by specifying the convention
-@code{C_Pass_By_Copy} for the record type, or by using the extended
-@code{Import} and @code{Export} pragmas, which allow specification of
-passing mechanisms on a parameter by parameter basis.
-
-@node Pragma Check
-@unnumberedsec Pragma Check
-@cindex Assertions
-@cindex Named assertions
-@findex Check
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Check (
- [Name =>] Identifier,
- [Check =>] Boolean_EXPRESSION
- [, [Message =>] string_EXPRESSION] );
-@end smallexample
-
-@noindent
-This pragma is similar to the predefined pragma @code{Assert} except that an
-extra identifier argument is present. In conjunction with pragma
-@code{Check_Policy}, this can be used to define groups of assertions that can
-be independently controlled. The identifier @code{Assertion} is special, it
-refers to the normal set of pragma @code{Assert} statements. The identifiers
-@code{Precondition} and @code{Postcondition} correspond to the pragmas of these
-names, so these three names would normally not be used directly in a pragma
-@code{Check}.
-
-Checks introduced by this pragma are normally deactivated by default. They can
-be activated either by the command line option @option{-gnata}, which turns on
-all checks, or individually controlled using pragma @code{Check_Policy}.
-
-@node Pragma Check_Name
-@unnumberedsec Pragma Check_Name
-@cindex Defining check names
-@cindex Check names, defining
-@findex Check_Name
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Check_Name (check_name_IDENTIFIER);
-@end smallexample
-
-@noindent
-This is a configuration pragma that defines a new implementation
-defined check name (unless IDENTIFIER matches one of the predefined
-check names, in which case the pragma has no effect). Check names
-are global to a partition, so if two or more configuration pragmas
-are present in a partition mentioning the same name, only one new
-check name is introduced.
-
-An implementation defined check name introduced with this pragma may
-be used in only three contexts: @code{pragma Suppress},
-@code{pragma Unsuppress},
-and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
-any of these three cases, the check name must be visible. A check
-name is visible if it is in the configuration pragmas applying to
-the current unit, or if it appears at the start of any unit that
-is part of the dependency set of the current unit (e.g., units that
-are mentioned in @code{with} clauses).
-
-@node Pragma Check_Policy
-@unnumberedsec Pragma Check_Policy
-@cindex Controlling assertions
-@cindex Assertions, control
-@cindex Check pragma control
-@cindex Named assertions
-@findex Check
-@noindent
-Syntax:
-@smallexample @c ada
-pragma Check_Policy ([Name =>] Identifier, POLICY_IDENTIFIER);
-
-POLICY_IDENTIFIER ::= On | Off | Check | Ignore
-@end smallexample
-
-@noindent
-This pragma is similar to the predefined pragma @code{Assertion_Policy},
-except that it controls sets of named assertions introduced using the
-@code{Check} pragmas. It can be used as a configuration pragma or (unlike
-@code{Assertion_Policy}) can be used within a declarative part, in which case
-it controls the status to the end of the corresponding construct (in a manner
-identical to pragma @code{Suppress)}.
-
-The identifier given as the first argument corresponds to a name used in
-associated @code{Check} pragmas. For example, if the pragma:
-
-@smallexample @c ada
-pragma Check_Policy (Critical_Error, Off);
-@end smallexample
-
-@noindent
-is given, then subsequent @code{Check} pragmas whose first argument is also
-@code{Critical_Error} will be disabled. The special identifier @code{Assertion}
-controls the behavior of normal @code{Assert} pragmas (thus a pragma
-@code{Check_Policy} with this identifier is similar to the normal
-@code{Assertion_Policy} pragma except that it can appear within a
-declarative part).
-
-The special identifiers @code{Precondition} and @code{Postcondition} control
-the status of preconditions and postconditions. If a @code{Precondition} pragma
-is encountered, it is ignored if turned off by a @code{Check_Policy} specifying
-that @code{Precondition} checks are @code{Off} or @code{Ignored}. Similarly use
-of the name @code{Postcondition} controls whether @code{Postcondition} pragmas
-are recognized.
-
-The check policy is @code{Off} to turn off corresponding checks, and @code{On}
-to turn on corresponding checks. The default for a set of checks for which no
-@code{Check_Policy} is given is @code{Off} unless the compiler switch
-@option{-gnata} is given, which turns on all checks by default.
-
-The check policy settings @code{Check} and @code{Ignore} are also recognized
-as synonyms for @code{On} and @code{Off}. These synonyms are provided for
-compatibility with the standard @code{Assertion_Policy} pragma.
-
-@node Pragma Comment
-@unnumberedsec Pragma Comment
-@findex Comment
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Comment (static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-This is almost identical in effect to pragma @code{Ident}. It allows the
-placement of a comment into the object file and hence into the
-executable file if the operating system permits such usage. The
-difference is that @code{Comment}, unlike @code{Ident}, has
-no limitations on placement of the pragma (it can be placed
-anywhere in the main source unit), and if more than one pragma
-is used, all comments are retained.
-
-@node Pragma Common_Object
-@unnumberedsec Pragma Common_Object
-@findex Common_Object
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Common_Object (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Size =>] EXTERNAL_SYMBOL] );
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma enables the shared use of variables stored in overlaid
-linker areas corresponding to the use of @code{COMMON}
-in Fortran. The single
-object @var{LOCAL_NAME} is assigned to the area designated by
-the @var{External} argument.
-You may define a record to correspond to a series
-of fields. The @var{Size} argument
-is syntax checked in GNAT, but otherwise ignored.
-
-@code{Common_Object} is not supported on all platforms. If no
-support is available, then the code generator will issue a message
-indicating that the necessary attribute for implementation of this
-pragma is not available.
-
-@node Pragma Compile_Time_Error
-@unnumberedsec Pragma Compile_Time_Error
-@findex Compile_Time_Error
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Compile_Time_Error
- (boolean_EXPRESSION, static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-This pragma can be used to generate additional compile time
-error messages. It
-is particularly useful in generics, where errors can be issued for
-specific problematic instantiations. The first parameter is a boolean
-expression. The pragma is effective only if the value of this expression
-is known at compile time, and has the value True. The set of expressions
-whose values are known at compile time includes all static boolean
-expressions, and also other values which the compiler can determine
-at compile time (e.g., the size of a record type set by an explicit
-size representation clause, or the value of a variable which was
-initialized to a constant and is known not to have been modified).
-If these conditions are met, an error message is generated using
-the value given as the second argument. This string value may contain
-embedded ASCII.LF characters to break the message into multiple lines.
-
-@node Pragma Compile_Time_Warning
-@unnumberedsec Pragma Compile_Time_Warning
-@findex Compile_Time_Warning
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Compile_Time_Warning
- (boolean_EXPRESSION, static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-Same as pragma Compile_Time_Error, except a warning is issued instead
-of an error message. Note that if this pragma is used in a package that
-is with'ed by a client, the client will get the warning even though it
-is issued by a with'ed package (normally warnings in with'ed units are
-suppressed, but this is a special exception to that rule).
-
-One typical use is within a generic where compile time known characteristics
-of formal parameters are tested, and warnings given appropriately. Another use
-with a first parameter of True is to warn a client about use of a package,
-for example that it is not fully implemented.
-
-@node Pragma Complete_Representation
-@unnumberedsec Pragma Complete_Representation
-@findex Complete_Representation
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Complete_Representation;
-@end smallexample
-
-@noindent
-This pragma must appear immediately within a record representation
-clause. Typical placements are before the first component clause
-or after the last component clause. The effect is to give an error
-message if any component is missing a component clause. This pragma
-may be used to ensure that a record representation clause is
-complete, and that this invariant is maintained if fields are
-added to the record in the future.
-
-@node Pragma Complex_Representation
-@unnumberedsec Pragma Complex_Representation
-@findex Complex_Representation
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Complex_Representation
- ([Entity =>] LOCAL_NAME);
-@end smallexample
-
-@noindent
-The @var{Entity} argument must be the name of a record type which has
-two fields of the same floating-point type. The effect of this pragma is
-to force gcc to use the special internal complex representation form for
-this record, which may be more efficient. Note that this may result in
-the code for this type not conforming to standard ABI (application
-binary interface) requirements for the handling of record types. For
-example, in some environments, there is a requirement for passing
-records by pointer, and the use of this pragma may result in passing
-this type in floating-point registers.
-
-@node Pragma Component_Alignment
-@unnumberedsec Pragma Component_Alignment
-@cindex Alignments of components
-@findex Component_Alignment
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Component_Alignment (
- [Form =>] ALIGNMENT_CHOICE
- [, [Name =>] type_LOCAL_NAME]);
-
-ALIGNMENT_CHOICE ::=
- Component_Size
-| Component_Size_4
-| Storage_Unit
-| Default
-@end smallexample
-
-@noindent
-Specifies the alignment of components in array or record types.
-The meaning of the @var{Form} argument is as follows:
-
-@table @code
-@findex Component_Size
-@item Component_Size
-Aligns scalar components and subcomponents of the array or record type
-on boundaries appropriate to their inherent size (naturally
-aligned). For example, 1-byte components are aligned on byte boundaries,
-2-byte integer components are aligned on 2-byte boundaries, 4-byte
-integer components are aligned on 4-byte boundaries and so on. These
-alignment rules correspond to the normal rules for C compilers on all
-machines except the VAX@.
-
-@findex Component_Size_4
-@item Component_Size_4
-Naturally aligns components with a size of four or fewer
-bytes. Components that are larger than 4 bytes are placed on the next
-4-byte boundary.
-
-@findex Storage_Unit
-@item Storage_Unit
-Specifies that array or record components are byte aligned, i.e.@:
-aligned on boundaries determined by the value of the constant
-@code{System.Storage_Unit}.
-
-@cindex OpenVMS
-@item Default
-Specifies that array or record components are aligned on default
-boundaries, appropriate to the underlying hardware or operating system or
-both. For OpenVMS VAX systems, the @code{Default} choice is the same as
-the @code{Storage_Unit} choice (byte alignment). For all other systems,
-the @code{Default} choice is the same as @code{Component_Size} (natural
-alignment).
-@end table
-
-@noindent
-If the @code{Name} parameter is present, @var{type_LOCAL_NAME} must
-refer to a local record or array type, and the specified alignment
-choice applies to the specified type. The use of
-@code{Component_Alignment} together with a pragma @code{Pack} causes the
-@code{Component_Alignment} pragma to be ignored. The use of
-@code{Component_Alignment} together with a record representation clause
-is only effective for fields not specified by the representation clause.
-
-If the @code{Name} parameter is absent, the pragma can be used as either
-a configuration pragma, in which case it applies to one or more units in
-accordance with the normal rules for configuration pragmas, or it can be
-used within a declarative part, in which case it applies to types that
-are declared within this declarative part, or within any nested scope
-within this declarative part. In either case it specifies the alignment
-to be applied to any record or array type which has otherwise standard
-representation.
-
-If the alignment for a record or array type is not specified (using
-pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
-clause), the GNAT uses the default alignment as described previously.
-
-@node Pragma Convention_Identifier
-@unnumberedsec Pragma Convention_Identifier
-@findex Convention_Identifier
-@cindex Conventions, synonyms
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Convention_Identifier (
- [Name =>] IDENTIFIER,
- [Convention =>] convention_IDENTIFIER);
-@end smallexample
-
-@noindent
-This pragma provides a mechanism for supplying synonyms for existing
-convention identifiers. The @code{Name} identifier can subsequently
-be used as a synonym for the given convention in other pragmas (including
-for example pragma @code{Import} or another @code{Convention_Identifier}
-pragma). As an example of the use of this, suppose you had legacy code
-which used Fortran77 as the identifier for Fortran. Then the pragma:
-
-@smallexample @c ada
-pragma Convention_Identifier (Fortran77, Fortran);
-@end smallexample
-
-@noindent
-would allow the use of the convention identifier @code{Fortran77} in
-subsequent code, avoiding the need to modify the sources. As another
-example, you could use this to parametrize convention requirements
-according to systems. Suppose you needed to use @code{Stdcall} on
-windows systems, and @code{C} on some other system, then you could
-define a convention identifier @code{Library} and use a single
-@code{Convention_Identifier} pragma to specify which convention
-would be used system-wide.
-
-@node Pragma CPP_Class
-@unnumberedsec Pragma CPP_Class
-@findex CPP_Class
-@cindex Interfacing with C++
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma CPP_Class ([Entity =>] LOCAL_NAME);
-@end smallexample
-
-@noindent
-The argument denotes an entity in the current declarative region that is
-declared as a tagged record type. It indicates that the type corresponds
-to an externally declared C++ class type, and is to be laid out the same
-way that C++ would lay out the type.
-
-Types for which @code{CPP_Class} is specified do not have assignment or
-equality operators defined (such operations can be imported or declared
-as subprograms as required). Initialization is allowed only by constructor
-functions (see pragma @code{CPP_Constructor}). Such types are implicitly
-limited if not explicitly declared as limited or derived from a limited
-type, and a warning is issued in that case.
-
-Pragma @code{CPP_Class} is intended primarily for automatic generation
-using an automatic binding generator tool.
-See @ref{Interfacing to C++} for related information.
-
-Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
-for backward compatibility but its functionality is available
-using pragma @code{Import} with @code{Convention} = @code{CPP}.
-
-@node Pragma CPP_Constructor
-@unnumberedsec Pragma CPP_Constructor
-@cindex Interfacing with C++
-@findex CPP_Constructor
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma CPP_Constructor ([Entity =>] LOCAL_NAME
- [, [External_Name =>] static_string_EXPRESSION ]
- [, [Link_Name =>] static_string_EXPRESSION ]);
-@end smallexample
-
-@noindent
-This pragma identifies an imported function (imported in the usual way
-with pragma @code{Import}) as corresponding to a C++ constructor. If
-@code{External_Name} and @code{Link_Name} are not specified then the
-@code{Entity} argument is a name that must have been previously mentioned
-in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
-must be of one of the following forms:
-
-@itemize @bullet
-@item
-@code{function @var{Fname} return @var{T}'Class}
-
-@item
-@code{function @var{Fname} (@dots{}) return @var{T}'Class}
-@end itemize
-
-@noindent
-where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies.
-
-The first form is the default constructor, used when an object of type
-@var{T} is created on the Ada side with no explicit constructor. Other
-constructors (including the copy constructor, which is simply a special
-case of the second form in which the one and only argument is of type
-@var{T}), can only appear in two contexts:
-
-@itemize @bullet
-@item
-On the right side of an initialization of an object of type @var{T}.
-@item
-In an extension aggregate for an object of a type derived from @var{T}.
-@end itemize
-
-@noindent
-Although the constructor is described as a function that returns a value
-on the Ada side, it is typically a procedure with an extra implicit
-argument (the object being initialized) at the implementation
-level. GNAT issues the appropriate call, whatever it is, to get the
-object properly initialized.
-
-In the case of derived objects, you may use one of two possible forms
-for declaring and creating an object:
-
-@itemize @bullet
-@item @code{New_Object : Derived_T}
-@item @code{New_Object : Derived_T := (@var{constructor-call with} @dots{})}
-@end itemize
-
-@noindent
-In the first case the default constructor is called and extension fields
-if any are initialized according to the default initialization
-expressions in the Ada declaration. In the second case, the given
-constructor is called and the extension aggregate indicates the explicit
-values of the extension fields.
-
-If no constructors are imported, it is impossible to create any objects
-on the Ada side. If no default constructor is imported, only the
-initialization forms using an explicit call to a constructor are
-permitted.
-
-Pragma @code{CPP_Constructor} is intended primarily for automatic generation
-using an automatic binding generator tool.
-See @ref{Interfacing to C++} for more related information.
-
-@node Pragma CPP_Virtual
-@unnumberedsec Pragma CPP_Virtual
-@cindex Interfacing to C++
-@findex CPP_Virtual
-@noindent
-This pragma is now obsolete has has no effect because GNAT generates
-the same object layout than the G++ compiler.
-
-See @ref{Interfacing to C++} for related information.
-
-@node Pragma CPP_Vtable
-@unnumberedsec Pragma CPP_Vtable
-@cindex Interfacing with C++
-@findex CPP_Vtable
-@noindent
-This pragma is now obsolete has has no effect because GNAT generates
-the same object layout than the G++ compiler.
-
-See @ref{Interfacing to C++} for related information.
-
-@node Pragma Debug
-@unnumberedsec Pragma Debug
-@findex Debug
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
-
-PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
- PROCEDURE_NAME
-| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
-@end smallexample
-
-@noindent
-The procedure call argument has the syntactic form of an expression, meeting
-the syntactic requirements for pragmas.
-
-If debug pragmas are not enabled or if the condition is present and evaluates
-to False, this pragma has no effect. If debug pragmas are enabled, the
-semantics of the pragma is exactly equivalent to the procedure call statement
-corresponding to the argument with a terminating semicolon. Pragmas are
-permitted in sequences of declarations, so you can use pragma @code{Debug} to
-intersperse calls to debug procedures in the middle of declarations. Debug
-pragmas can be enabled either by use of the command line switch @option{-gnata}
-or by use of the configuration pragma @code{Debug_Policy}.
-
-@node Pragma Debug_Policy
-@unnumberedsec Pragma Debug_Policy
-@findex Debug_Policy
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Debug_Policy (CHECK | IGNORE);
-@end smallexample
-
-@noindent
-If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
-If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
-This pragma overrides the effect of the @option{-gnata} switch on the
-command line.
-
-@node Pragma Detect_Blocking
-@unnumberedsec Pragma Detect_Blocking
-@findex Detect_Blocking
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Detect_Blocking;
-@end smallexample
-
-@noindent
-This is a configuration pragma that forces the detection of potentially
-blocking operations within a protected operation, and to raise Program_Error
-if that happens.
-
-@node Pragma Elaboration_Checks
-@unnumberedsec Pragma Elaboration_Checks
-@cindex Elaboration control
-@findex Elaboration_Checks
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Elaboration_Checks (Dynamic | Static);
-@end smallexample
-
-@noindent
-This is a configuration pragma that provides control over the
-elaboration model used by the compilation affected by the
-pragma. If the parameter is @code{Dynamic},
-then the dynamic elaboration
-model described in the Ada Reference Manual is used, as though
-the @option{-gnatE} switch had been specified on the command
-line. If the parameter is @code{Static}, then the default GNAT static
-model is used. This configuration pragma overrides the setting
-of the command line. For full details on the elaboration models
-used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,,
-gnat_ugn, @value{EDITION} User's Guide}.
-
-@node Pragma Eliminate
-@unnumberedsec Pragma Eliminate
-@cindex Elimination of unused subprograms
-@findex Eliminate
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Eliminate (
- [Unit_Name =>] IDENTIFIER |
- SELECTED_COMPONENT);
-
-pragma Eliminate (
- [Unit_Name =>] IDENTIFIER |
- SELECTED_COMPONENT,
- [Entity =>] IDENTIFIER |
- SELECTED_COMPONENT |
- STRING_LITERAL
- [,OVERLOADING_RESOLUTION]);
-
-OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE |
- SOURCE_LOCATION
-
-PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE |
- FUNCTION_PROFILE
-
-PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES
-
-FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,]
- Result_Type => result_SUBTYPE_NAME]
-
-PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@})
-SUBTYPE_NAME ::= STRING_VALUE
-
-SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE
-SOURCE_TRACE ::= STRING_VALUE
-
-STRING_VALUE ::= STRING_LITERAL @{& STRING_LITERAL@}
-@end smallexample
-
-@noindent
-This pragma indicates that the given entity is not used outside the
-compilation unit it is defined in. The entity must be an explicitly declared
-subprogram; this includes generic subprogram instances and
-subprograms declared in generic package instances.
-
-If the entity to be eliminated is a library level subprogram, then
-the first form of pragma @code{Eliminate} is used with only a single argument.
-In this form, the @code{Unit_Name} argument specifies the name of the
-library level unit to be eliminated.
-
-In all other cases, both @code{Unit_Name} and @code{Entity} arguments
-are required. If item is an entity of a library package, then the first
-argument specifies the unit name, and the second argument specifies
-the particular entity. If the second argument is in string form, it must
-correspond to the internal manner in which GNAT stores entity names (see
-compilation unit Namet in the compiler sources for details).
-
-The remaining parameters (OVERLOADING_RESOLUTION) are optionally used
-to distinguish between overloaded subprograms. If a pragma does not contain
-the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded
-subprograms denoted by the first two parameters.
-
-Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram
-to be eliminated in a manner similar to that used for the extended
-@code{Import} and @code{Export} pragmas, except that the subtype names are
-always given as strings. At the moment, this form of distinguishing
-overloaded subprograms is implemented only partially, so we do not recommend
-using it for practical subprogram elimination.
-
-Note that in case of a parameterless procedure its profile is represented
-as @code{Parameter_Types => ("")}
-
-Alternatively, the @code{Source_Location} parameter is used to specify
-which overloaded alternative is to be eliminated by pointing to the
-location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the
-source text. The string literal (or concatenation of string literals)
-given as SOURCE_TRACE must have the following format:
-
-@smallexample @c ada
-SOURCE_TRACE ::= SOURCE_LOCATION@{LBRACKET SOURCE_LOCATION RBRACKET@}
-
-LBRACKET ::= [
-RBRACKET ::= ]
-
-SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER
-FILE_NAME ::= STRING_LITERAL
-LINE_NUMBER ::= DIGIT @{DIGIT@}
-@end smallexample
-
-SOURCE_TRACE should be the short name of the source file (with no directory
-information), and LINE_NUMBER is supposed to point to the line where the
-defining name of the subprogram is located.
-
-For the subprograms that are not a part of generic instantiations, only one
-SOURCE_LOCATION is used. If a subprogram is declared in a package
-instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is
-the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the
-second one denotes the declaration of the corresponding subprogram in the
-generic package. This approach is recursively used to create SOURCE_LOCATIONs
-in case of nested instantiations.
-
-The effect of the pragma is to allow the compiler to eliminate
-the code or data associated with the named entity. Any reference to
-an eliminated entity outside the compilation unit it is defined in,
-causes a compile time or link time error.
-
-The intention of pragma @code{Eliminate} is to allow a program to be compiled
-in a system independent manner, with unused entities eliminated, without
-the requirement of modifying the source text. Normally the required set
-of @code{Eliminate} pragmas is constructed automatically using the gnatelim
-tool. Elimination of unused entities local to a compilation unit is
-automatic, without requiring the use of pragma @code{Eliminate}.
-
-Note that the reason this pragma takes string literals where names might
-be expected is that a pragma @code{Eliminate} can appear in a context where the
-relevant names are not visible.
-
-Note that any change in the source files that includes removing, splitting of
-adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION
-parameter illegal.
-
-It is legal to use pragma Eliminate where the referenced entity is a
-dispatching operation, but it is not clear what this would mean, since
-in general the call does not know which entity is actually being called.
-Consequently, a pragma Eliminate for a dispatching operation is ignored.
-
-@node Pragma Export_Exception
-@unnumberedsec Pragma Export_Exception
-@cindex OpenVMS
-@findex Export_Exception
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Export_Exception (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Form =>] Ada | VMS]
- [, [Code =>] static_integer_EXPRESSION]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma is implemented only in the OpenVMS implementation of GNAT@. It
-causes the specified exception to be propagated outside of the Ada program,
-so that it can be handled by programs written in other OpenVMS languages.
-This pragma establishes an external name for an Ada exception and makes the
-name available to the OpenVMS Linker as a global symbol. For further details
-on this pragma, see the
-DEC Ada Language Reference Manual, section 13.9a3.2.
-
-@node Pragma Export_Function
-@unnumberedsec Pragma Export_Function
-@cindex Argument passing mechanisms
-@findex Export_Function
-
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Export_Function (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Parameter_Types =>] PARAMETER_TYPES]
- [, [Result_Type =>] result_SUBTYPE_MARK]
- [, [Mechanism =>] MECHANISM]
- [, [Result_Mechanism =>] MECHANISM_NAME]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-| ""
-
-PARAMETER_TYPES ::=
- null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
- subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
- MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
- [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::=
- Value
-| Reference
-| Descriptor [([Class =>] CLASS_NAME)]
-| Short_Descriptor [([Class =>] CLASS_NAME)]
-
-CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
-@end smallexample
-
-@noindent
-Use this pragma to make a function externally callable and optionally
-provide information on mechanisms to be used for passing parameter and
-result values. We recommend, for the purposes of improving portability,
-this pragma always be used in conjunction with a separate pragma
-@code{Export}, which must precede the pragma @code{Export_Function}.
-GNAT does not require a separate pragma @code{Export}, but if none is
-present, @code{Convention Ada} is assumed, which is usually
-not what is wanted, so it is usually appropriate to use this
-pragma in conjunction with a @code{Export} or @code{Convention}
-pragma that specifies the desired foreign convention.
-Pragma @code{Export_Function}
-(and @code{Export}, if present) must appear in the same declarative
-region as the function to which they apply.
-
-@var{internal_name} must uniquely designate the function to which the
-pragma applies. If more than one function name exists of this name in
-the declarative part you must use the @code{Parameter_Types} and
-@code{Result_Type} parameters is mandatory to achieve the required
-unique designation. @var{subtype_mark}s in these parameters must
-exactly match the subtypes in the corresponding function specification,
-using positional notation to match parameters with subtype marks.
-The form with an @code{'Access} attribute can be used to match an
-anonymous access parameter.
-
-@cindex OpenVMS
-@cindex Passing by descriptor
-Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
-The default behavior for Export_Function is to accept either 64bit or
-32bit descriptors unless short_descriptor is specified, then only 32bit
-descriptors are accepted.
-
-@cindex Suppressing external name
-Special treatment is given if the EXTERNAL is an explicit null
-string or a static string expressions that evaluates to the null
-string. In this case, no external name is generated. This form
-still allows the specification of parameter mechanisms.
-
-@node Pragma Export_Object
-@unnumberedsec Pragma Export_Object
-@findex Export_Object
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Export_Object
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Size =>] EXTERNAL_SYMBOL]
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma designates an object as exported, and apart from the
-extended rules for external symbols, is identical in effect to the use of
-the normal @code{Export} pragma applied to an object. You may use a
-separate Export pragma (and you probably should from the point of view
-of portability), but it is not required. @var{Size} is syntax checked,
-but otherwise ignored by GNAT@.
-
-@node Pragma Export_Procedure
-@unnumberedsec Pragma Export_Procedure
-@findex Export_Procedure
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Export_Procedure (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Parameter_Types =>] PARAMETER_TYPES]
- [, [Mechanism =>] MECHANISM]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-| ""
-
-PARAMETER_TYPES ::=
- null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
- subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
- MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
- [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::=
- Value
-| Reference
-| Descriptor [([Class =>] CLASS_NAME)]
-| Short_Descriptor [([Class =>] CLASS_NAME)]
-
-CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
-@end smallexample
-
-@noindent
-This pragma is identical to @code{Export_Function} except that it
-applies to a procedure rather than a function and the parameters
-@code{Result_Type} and @code{Result_Mechanism} are not permitted.
-GNAT does not require a separate pragma @code{Export}, but if none is
-present, @code{Convention Ada} is assumed, which is usually
-not what is wanted, so it is usually appropriate to use this
-pragma in conjunction with a @code{Export} or @code{Convention}
-pragma that specifies the desired foreign convention.
-
-@cindex OpenVMS
-@cindex Passing by descriptor
-Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
-The default behavior for Export_Procedure is to accept either 64bit or
-32bit descriptors unless short_descriptor is specified, then only 32bit
-descriptors are accepted.
-
-@cindex Suppressing external name
-Special treatment is given if the EXTERNAL is an explicit null
-string or a static string expressions that evaluates to the null
-string. In this case, no external name is generated. This form
-still allows the specification of parameter mechanisms.
-
-@node Pragma Export_Value
-@unnumberedsec Pragma Export_Value
-@findex Export_Value
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Export_Value (
- [Value =>] static_integer_EXPRESSION,
- [Link_Name =>] static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-This pragma serves to export a static integer value for external use.
-The first argument specifies the value to be exported. The Link_Name
-argument specifies the symbolic name to be associated with the integer
-value. This pragma is useful for defining a named static value in Ada
-that can be referenced in assembly language units to be linked with
-the application. This pragma is currently supported only for the
-AAMP target and is ignored for other targets.
-
-@node Pragma Export_Valued_Procedure
-@unnumberedsec Pragma Export_Valued_Procedure
-@findex Export_Valued_Procedure
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Export_Valued_Procedure (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Parameter_Types =>] PARAMETER_TYPES]
- [, [Mechanism =>] MECHANISM]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-| ""
-
-PARAMETER_TYPES ::=
- null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
- subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
- MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
- [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::=
- Value
-| Reference
-| Descriptor [([Class =>] CLASS_NAME)]
-| Short_Descriptor [([Class =>] CLASS_NAME)]
-
-CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
-@end smallexample
-
-@noindent
-This pragma is identical to @code{Export_Procedure} except that the
-first parameter of @var{LOCAL_NAME}, which must be present, must be of
-mode @code{OUT}, and externally the subprogram is treated as a function
-with this parameter as the result of the function. GNAT provides for
-this capability to allow the use of @code{OUT} and @code{IN OUT}
-parameters in interfacing to external functions (which are not permitted
-in Ada functions).
-GNAT does not require a separate pragma @code{Export}, but if none is
-present, @code{Convention Ada} is assumed, which is almost certainly
-not what is wanted since the whole point of this pragma is to interface
-with foreign language functions, so it is usually appropriate to use this
-pragma in conjunction with a @code{Export} or @code{Convention}
-pragma that specifies the desired foreign convention.
-
-@cindex OpenVMS
-@cindex Passing by descriptor
-Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
-The default behavior for Export_Valued_Procedure is to accept either 64bit or
-32bit descriptors unless short_descriptor is specified, then only 32bit
-descriptors are accepted.
-
-@cindex Suppressing external name
-Special treatment is given if the EXTERNAL is an explicit null
-string or a static string expressions that evaluates to the null
-string. In this case, no external name is generated. This form
-still allows the specification of parameter mechanisms.
-
-@node Pragma Extend_System
-@unnumberedsec Pragma Extend_System
-@cindex @code{system}, extending
-@cindex Dec Ada 83
-@findex Extend_System
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Extend_System ([Name =>] IDENTIFIER);
-@end smallexample
-
-@noindent
-This pragma is used to provide backwards compatibility with other
-implementations that extend the facilities of package @code{System}. In
-GNAT, @code{System} contains only the definitions that are present in
-the Ada RM@. However, other implementations, notably the DEC Ada 83
-implementation, provide many extensions to package @code{System}.
-
-For each such implementation accommodated by this pragma, GNAT provides a
-package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
-implementation, which provides the required additional definitions. You
-can use this package in two ways. You can @code{with} it in the normal
-way and access entities either by selection or using a @code{use}
-clause. In this case no special processing is required.
-
-However, if existing code contains references such as
-@code{System.@var{xxx}} where @var{xxx} is an entity in the extended
-definitions provided in package @code{System}, you may use this pragma
-to extend visibility in @code{System} in a non-standard way that
-provides greater compatibility with the existing code. Pragma
-@code{Extend_System} is a configuration pragma whose single argument is
-the name of the package containing the extended definition
-(e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
-control of this pragma will be processed using special visibility
-processing that looks in package @code{System.Aux_@var{xxx}} where
-@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
-package @code{System}, but not found in package @code{System}.
-
-You can use this pragma either to access a predefined @code{System}
-extension supplied with the compiler, for example @code{Aux_DEC} or
-you can construct your own extension unit following the above
-definition. Note that such a package is a child of @code{System}
-and thus is considered part of the implementation. To compile
-it you will have to use the appropriate switch for compiling
-system units. @xref{Top, @value{EDITION} User's Guide, About This
-Guide,, gnat_ugn, @value{EDITION} User's Guide}, for details.
-
-@node Pragma External
-@unnumberedsec Pragma External
-@findex External
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma External (
- [ Convention =>] convention_IDENTIFIER,
- [ Entity =>] LOCAL_NAME
- [, [External_Name =>] static_string_EXPRESSION ]
- [, [Link_Name =>] static_string_EXPRESSION ]);
-@end smallexample
-
-@noindent
-This pragma is identical in syntax and semantics to pragma
-@code{Export} as defined in the Ada Reference Manual. It is
-provided for compatibility with some Ada 83 compilers that
-used this pragma for exactly the same purposes as pragma
-@code{Export} before the latter was standardized.
-
-@node Pragma External_Name_Casing
-@unnumberedsec Pragma External_Name_Casing
-@cindex Dec Ada 83 casing compatibility
-@cindex External Names, casing
-@cindex Casing of External names
-@findex External_Name_Casing
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma External_Name_Casing (
- Uppercase | Lowercase
- [, Uppercase | Lowercase | As_Is]);
-@end smallexample
-
-@noindent
-This pragma provides control over the casing of external names associated
-with Import and Export pragmas. There are two cases to consider:
-
-@table @asis
-@item Implicit external names
-Implicit external names are derived from identifiers. The most common case
-arises when a standard Ada Import or Export pragma is used with only two
-arguments, as in:
-
-@smallexample @c ada
- pragma Import (C, C_Routine);
-@end smallexample
-
-@noindent
-Since Ada is a case-insensitive language, the spelling of the identifier in
-the Ada source program does not provide any information on the desired
-casing of the external name, and so a convention is needed. In GNAT the
-default treatment is that such names are converted to all lower case
-letters. This corresponds to the normal C style in many environments.
-The first argument of pragma @code{External_Name_Casing} can be used to
-control this treatment. If @code{Uppercase} is specified, then the name
-will be forced to all uppercase letters. If @code{Lowercase} is specified,
-then the normal default of all lower case letters will be used.
-
-This same implicit treatment is also used in the case of extended DEC Ada 83
-compatible Import and Export pragmas where an external name is explicitly
-specified using an identifier rather than a string.
-
-@item Explicit external names
-Explicit external names are given as string literals. The most common case
-arises when a standard Ada Import or Export pragma is used with three
-arguments, as in:
-
-@smallexample @c ada
-pragma Import (C, C_Routine, "C_routine");
-@end smallexample
-
-@noindent
-In this case, the string literal normally provides the exact casing required
-for the external name. The second argument of pragma
-@code{External_Name_Casing} may be used to modify this behavior.
-If @code{Uppercase} is specified, then the name
-will be forced to all uppercase letters. If @code{Lowercase} is specified,
-then the name will be forced to all lowercase letters. A specification of
-@code{As_Is} provides the normal default behavior in which the casing is
-taken from the string provided.
-@end table
-
-@noindent
-This pragma may appear anywhere that a pragma is valid. In particular, it
-can be used as a configuration pragma in the @file{gnat.adc} file, in which
-case it applies to all subsequent compilations, or it can be used as a program
-unit pragma, in which case it only applies to the current unit, or it can
-be used more locally to control individual Import/Export pragmas.
-
-It is primarily intended for use with OpenVMS systems, where many
-compilers convert all symbols to upper case by default. For interfacing to
-such compilers (e.g.@: the DEC C compiler), it may be convenient to use
-the pragma:
-
-@smallexample @c ada
-pragma External_Name_Casing (Uppercase, Uppercase);
-@end smallexample
-
-@noindent
-to enforce the upper casing of all external symbols.
-
-@node Pragma Fast_Math
-@unnumberedsec Pragma Fast_Math
-@findex Fast_Math
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Fast_Math;
-@end smallexample
-
-@noindent
-This is a configuration pragma which activates a mode in which speed is
-considered more important for floating-point operations than absolutely
-accurate adherence to the requirements of the standard. Currently the
-following operations are affected:
-
-@table @asis
-@item Complex Multiplication
-The normal simple formula for complex multiplication can result in intermediate
-overflows for numbers near the end of the range. The Ada standard requires that
-this situation be detected and corrected by scaling, but in Fast_Math mode such
-cases will simply result in overflow. Note that to take advantage of this you
-must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
-under control of the pragma, rather than use the preinstantiated versions.
-@end table
-
-@node Pragma Favor_Top_Level
-@unnumberedsec Pragma Favor_Top_Level
-@findex Favor_Top_Level
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Favor_Top_Level (type_NAME);
-@end smallexample
-
-@noindent
-The named type must be an access-to-subprogram type. This pragma is an
-efficiency hint to the compiler, regarding the use of 'Access or
-'Unrestricted_Access on nested (non-library-level) subprograms. The
-pragma means that nested subprograms are not used with this type, or
-are rare, so that the generated code should be efficient in the
-top-level case. When this pragma is used, dynamically generated
-trampolines may be used on some targets for nested subprograms.
-See also the No_Implicit_Dynamic_Code restriction.
-
-@node Pragma Finalize_Storage_Only
-@unnumberedsec Pragma Finalize_Storage_Only
-@findex Finalize_Storage_Only
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
-@end smallexample
-
-@noindent
-This pragma allows the compiler not to emit a Finalize call for objects
-defined at the library level. This is mostly useful for types where
-finalization is only used to deal with storage reclamation since in most
-environments it is not necessary to reclaim memory just before terminating
-execution, hence the name.
-
-@node Pragma Float_Representation
-@unnumberedsec Pragma Float_Representation
-@cindex OpenVMS
-@findex Float_Representation
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
-
-FLOAT_REP ::= VAX_Float | IEEE_Float
-@end smallexample
-
-@noindent
-In the one argument form, this pragma is a configuration pragma which
-allows control over the internal representation chosen for the predefined
-floating point types declared in the packages @code{Standard} and
-@code{System}. On all systems other than OpenVMS, the argument must
-be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
-argument may be @code{VAX_Float} to specify the use of the VAX float
-format for the floating-point types in Standard. This requires that
-the standard runtime libraries be recompiled. @xref{The GNAT Run-Time
-Library Builder gnatlbr,,, gnat_ugn, @value{EDITION} User's Guide
-OpenVMS}, for a description of the @code{GNAT LIBRARY} command.
-
-The two argument form specifies the representation to be used for
-the specified floating-point type. On all systems other than OpenVMS,
-the argument must
-be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
-argument may be @code{VAX_Float} to specify the use of the VAX float
-format, as follows:
-
-@itemize @bullet
-@item
-For digits values up to 6, F float format will be used.
-@item
-For digits values from 7 to 9, G float format will be used.
-@item
-For digits values from 10 to 15, F float format will be used.
-@item
-Digits values above 15 are not allowed.
-@end itemize
-
-@node Pragma Ident
-@unnumberedsec Pragma Ident
-@findex Ident
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Ident (static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-This pragma provides a string identification in the generated object file,
-if the system supports the concept of this kind of identification string.
-This pragma is allowed only in the outermost declarative part or
-declarative items of a compilation unit. If more than one @code{Ident}
-pragma is given, only the last one processed is effective.
-@cindex OpenVMS
-On OpenVMS systems, the effect of the pragma is identical to the effect of
-the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the
-maximum allowed length is 31 characters, so if it is important to
-maintain compatibility with this compiler, you should obey this length
-limit.
-
-@node Pragma Implemented_By_Entry
-@unnumberedsec Pragma Implemented_By_Entry
-@findex Implemented_By_Entry
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Implemented_By_Entry (LOCAL_NAME);
-@end smallexample
-
-@noindent
-This is a representation pragma which applies to protected, synchronized and
-task interface primitives. If the pragma is applied to primitive operation Op
-of interface Iface, it is illegal to override Op in a type that implements
-Iface, with anything other than an entry.
-
-@smallexample @c ada
-type Iface is protected interface;
-procedure Do_Something (Object : in out Iface) is abstract;
-pragma Implemented_By_Entry (Do_Something);
-
-protected type P is new Iface with
- procedure Do_Something; -- Illegal
-end P;
-
-task type T is new Iface with
- entry Do_Something; -- Legal
-end T;
-@end smallexample
-
-@noindent
-NOTE: The pragma is still in its design stage by the Ada Rapporteur Group. It
-is intended to be used in conjunction with dispatching requeue statements as
-described in AI05-0030. Should the ARG decide on an official name and syntax,
-this pragma will become language-defined rather than GNAT-specific.
-
-@node Pragma Implicit_Packing
-@unnumberedsec Pragma Implicit_Packing
-@findex Implicit_Packing
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Implicit_Packing;
-@end smallexample
-
-@noindent
-This is a configuration pragma that requests implicit packing for packed
-arrays for which a size clause is given but no explicit pragma Pack or
-specification of Component_Size is present. Consider this example:
-
-@smallexample @c ada
-type R is array (0 .. 7) of Boolean;
-for R'Size use 8;
-@end smallexample
-
-@noindent
-In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
-does not change the layout of a composite object. So the Size clause in the
-above example is normally rejected, since the default layout of the array uses
-8-bit components, and thus the array requires a minimum of 64 bits.
-
-If this declaration is compiled in a region of code covered by an occurrence
-of the configuration pragma Implicit_Packing, then the Size clause in this
-and similar examples will cause implicit packing and thus be accepted. For
-this implicit packing to occur, the type in question must be an array of small
-components whose size is known at compile time, and the Size clause must
-specify the exact size that corresponds to the length of the array multiplied
-by the size in bits of the component type.
-@cindex Array packing
-
-@node Pragma Import_Exception
-@unnumberedsec Pragma Import_Exception
-@cindex OpenVMS
-@findex Import_Exception
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Import_Exception (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Form =>] Ada | VMS]
- [, [Code =>] static_integer_EXPRESSION]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma is implemented only in the OpenVMS implementation of GNAT@.
-It allows OpenVMS conditions (for example, from OpenVMS system services or
-other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
-The pragma specifies that the exception associated with an exception
-declaration in an Ada program be defined externally (in non-Ada code).
-For further details on this pragma, see the
-DEC Ada Language Reference Manual, section 13.9a.3.1.
-
-@node Pragma Import_Function
-@unnumberedsec Pragma Import_Function
-@findex Import_Function
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Import_Function (
- [Internal =>] LOCAL_NAME,
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Parameter_Types =>] PARAMETER_TYPES]
- [, [Result_Type =>] SUBTYPE_MARK]
- [, [Mechanism =>] MECHANISM]
- [, [Result_Mechanism =>] MECHANISM_NAME]
- [, [First_Optional_Parameter =>] IDENTIFIER]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-
-PARAMETER_TYPES ::=
- null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
- subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
- MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
- [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::=
- Value
-| Reference
-| Descriptor [([Class =>] CLASS_NAME)]
-| Short_Descriptor [([Class =>] CLASS_NAME)]
-
-CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
-@end smallexample
-
-@noindent
-This pragma is used in conjunction with a pragma @code{Import} to
-specify additional information for an imported function. The pragma
-@code{Import} (or equivalent pragma @code{Interface}) must precede the
-@code{Import_Function} pragma and both must appear in the same
-declarative part as the function specification.
-
-The @var{Internal} argument must uniquely designate
-the function to which the
-pragma applies. If more than one function name exists of this name in
-the declarative part you must use the @code{Parameter_Types} and
-@var{Result_Type} parameters to achieve the required unique
-designation. Subtype marks in these parameters must exactly match the
-subtypes in the corresponding function specification, using positional
-notation to match parameters with subtype marks.
-The form with an @code{'Access} attribute can be used to match an
-anonymous access parameter.
-
-You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
-parameters to specify passing mechanisms for the
-parameters and result. If you specify a single mechanism name, it
-applies to all parameters. Otherwise you may specify a mechanism on a
-parameter by parameter basis using either positional or named
-notation. If the mechanism is not specified, the default mechanism
-is used.
-
-@cindex OpenVMS
-@cindex Passing by descriptor
-Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
-The default behavior for Import_Function is to pass a 64bit descriptor
-unless short_descriptor is specified, then a 32bit descriptor is passed.
-
-@code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
-It specifies that the designated parameter and all following parameters
-are optional, meaning that they are not passed at the generated code
-level (this is distinct from the notion of optional parameters in Ada
-where the parameters are passed anyway with the designated optional
-parameters). All optional parameters must be of mode @code{IN} and have
-default parameter values that are either known at compile time
-expressions, or uses of the @code{'Null_Parameter} attribute.
-
-@node Pragma Import_Object
-@unnumberedsec Pragma Import_Object
-@findex Import_Object
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Import_Object
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Size =>] EXTERNAL_SYMBOL]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma designates an object as imported, and apart from the
-extended rules for external symbols, is identical in effect to the use of
-the normal @code{Import} pragma applied to an object. Unlike the
-subprogram case, you need not use a separate @code{Import} pragma,
-although you may do so (and probably should do so from a portability
-point of view). @var{size} is syntax checked, but otherwise ignored by
-GNAT@.
-
-@node Pragma Import_Procedure
-@unnumberedsec Pragma Import_Procedure
-@findex Import_Procedure
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Import_Procedure (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Parameter_Types =>] PARAMETER_TYPES]
- [, [Mechanism =>] MECHANISM]
- [, [First_Optional_Parameter =>] IDENTIFIER]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-
-PARAMETER_TYPES ::=
- null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
- subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
- MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
- [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::=
- Value
-| Reference
-| Descriptor [([Class =>] CLASS_NAME)]
-| Short_Descriptor [([Class =>] CLASS_NAME)]
-
-CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
-@end smallexample
-
-@noindent
-This pragma is identical to @code{Import_Function} except that it
-applies to a procedure rather than a function and the parameters
-@code{Result_Type} and @code{Result_Mechanism} are not permitted.
-
-@node Pragma Import_Valued_Procedure
-@unnumberedsec Pragma Import_Valued_Procedure
-@findex Import_Valued_Procedure
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Import_Valued_Procedure (
- [Internal =>] LOCAL_NAME
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Parameter_Types =>] PARAMETER_TYPES]
- [, [Mechanism =>] MECHANISM]
- [, [First_Optional_Parameter =>] IDENTIFIER]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-
-PARAMETER_TYPES ::=
- null
-| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
-
-TYPE_DESIGNATOR ::=
- subtype_NAME
-| subtype_Name ' Access
-
-MECHANISM ::=
- MECHANISM_NAME
-| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
-
-MECHANISM_ASSOCIATION ::=
- [formal_parameter_NAME =>] MECHANISM_NAME
-
-MECHANISM_NAME ::=
- Value
-| Reference
-| Descriptor [([Class =>] CLASS_NAME)]
-| Short_Descriptor [([Class =>] CLASS_NAME)]
-
-CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
-@end smallexample
-
-@noindent
-This pragma is identical to @code{Import_Procedure} except that the
-first parameter of @var{LOCAL_NAME}, which must be present, must be of
-mode @code{OUT}, and externally the subprogram is treated as a function
-with this parameter as the result of the function. The purpose of this
-capability is to allow the use of @code{OUT} and @code{IN OUT}
-parameters in interfacing to external functions (which are not permitted
-in Ada functions). You may optionally use the @code{Mechanism}
-parameters to specify passing mechanisms for the parameters.
-If you specify a single mechanism name, it applies to all parameters.
-Otherwise you may specify a mechanism on a parameter by parameter
-basis using either positional or named notation. If the mechanism is not
-specified, the default mechanism is used.
-
-Note that it is important to use this pragma in conjunction with a separate
-pragma Import that specifies the desired convention, since otherwise the
-default convention is Ada, which is almost certainly not what is required.
-
-@node Pragma Initialize_Scalars
-@unnumberedsec Pragma Initialize_Scalars
-@findex Initialize_Scalars
-@cindex debugging with Initialize_Scalars
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Initialize_Scalars;
-@end smallexample
-
-@noindent
-This pragma is similar to @code{Normalize_Scalars} conceptually but has
-two important differences. First, there is no requirement for the pragma
-to be used uniformly in all units of a partition, in particular, it is fine
-to use this just for some or all of the application units of a partition,
-without needing to recompile the run-time library.
-
-In the case where some units are compiled with the pragma, and some without,
-then a declaration of a variable where the type is defined in package
-Standard or is locally declared will always be subject to initialization,
-as will any declaration of a scalar variable. For composite variables,
-whether the variable is initialized may also depend on whether the package
-in which the type of the variable is declared is compiled with the pragma.
-
-The other important difference is that you can control the value used
-for initializing scalar objects. At bind time, you can select several
-options for initialization. You can
-initialize with invalid values (similar to Normalize_Scalars, though for
-Initialize_Scalars it is not always possible to determine the invalid
-values in complex cases like signed component fields with non-standard
-sizes). You can also initialize with high or
-low values, or with a specified bit pattern. See the users guide for binder
-options for specifying these cases.
-
-This means that you can compile a program, and then without having to
-recompile the program, you can run it with different values being used
-for initializing otherwise uninitialized values, to test if your program
-behavior depends on the choice. Of course the behavior should not change,
-and if it does, then most likely you have an erroneous reference to an
-uninitialized value.
-
-It is even possible to change the value at execution time eliminating even
-the need to rebind with a different switch using an environment variable.
-See the GNAT users guide for details.
-
-Note that pragma @code{Initialize_Scalars} is particularly useful in
-conjunction with the enhanced validity checking that is now provided
-in GNAT, which checks for invalid values under more conditions.
-Using this feature (see description of the @option{-gnatV} flag in the
-users guide) in conjunction with pragma @code{Initialize_Scalars}
-provides a powerful new tool to assist in the detection of problems
-caused by uninitialized variables.
-
-Note: the use of @code{Initialize_Scalars} has a fairly extensive
-effect on the generated code. This may cause your code to be
-substantially larger. It may also cause an increase in the amount
-of stack required, so it is probably a good idea to turn on stack
-checking (see description of stack checking in the GNAT users guide)
-when using this pragma.
-
-@node Pragma Inline_Always
-@unnumberedsec Pragma Inline_Always
-@findex Inline_Always
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Inline_Always (NAME [, NAME]);
-@end smallexample
-
-@noindent
-Similar to pragma @code{Inline} except that inlining is not subject to
-the use of option @option{-gnatn} and the inlining happens regardless of
-whether this option is used.
-
-@node Pragma Inline_Generic
-@unnumberedsec Pragma Inline_Generic
-@findex Inline_Generic
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Inline_Generic (generic_package_NAME);
-@end smallexample
-
-@noindent
-This is implemented for compatibility with DEC Ada 83 and is recognized,
-but otherwise ignored, by GNAT@. All generic instantiations are inlined
-by default when using GNAT@.
-
-@node Pragma Interface
-@unnumberedsec Pragma Interface
-@findex Interface
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Interface (
- [Convention =>] convention_identifier,
- [Entity =>] local_NAME
- [, [External_Name =>] static_string_expression]
- [, [Link_Name =>] static_string_expression]);
-@end smallexample
-
-@noindent
-This pragma is identical in syntax and semantics to
-the standard Ada pragma @code{Import}. It is provided for compatibility
-with Ada 83. The definition is upwards compatible both with pragma
-@code{Interface} as defined in the Ada 83 Reference Manual, and also
-with some extended implementations of this pragma in certain Ada 83
-implementations.
-
-@node Pragma Interface_Name
-@unnumberedsec Pragma Interface_Name
-@findex Interface_Name
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Interface_Name (
- [Entity =>] LOCAL_NAME
- [, [External_Name =>] static_string_EXPRESSION]
- [, [Link_Name =>] static_string_EXPRESSION]);
-@end smallexample
-
-@noindent
-This pragma provides an alternative way of specifying the interface name
-for an interfaced subprogram, and is provided for compatibility with Ada
-83 compilers that use the pragma for this purpose. You must provide at
-least one of @var{External_Name} or @var{Link_Name}.
-
-@node Pragma Interrupt_Handler
-@unnumberedsec Pragma Interrupt_Handler
-@findex Interrupt_Handler
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Interrupt_Handler (procedure_LOCAL_NAME);
-@end smallexample
-
-@noindent
-This program unit pragma is supported for parameterless protected procedures
-as described in Annex C of the Ada Reference Manual. On the AAMP target
-the pragma can also be specified for nonprotected parameterless procedures
-that are declared at the library level (which includes procedures
-declared at the top level of a library package). In the case of AAMP,
-when this pragma is applied to a nonprotected procedure, the instruction
-@code{IERET} is generated for returns from the procedure, enabling
-maskable interrupts, in place of the normal return instruction.
-
-@node Pragma Interrupt_State
-@unnumberedsec Pragma Interrupt_State
-@findex Interrupt_State
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER);
-@end smallexample
-
-@noindent
-Normally certain interrupts are reserved to the implementation. Any attempt
-to attach an interrupt causes Program_Error to be raised, as described in
-RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
-many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
-reserved to the implementation, so that @kbd{Ctrl-C} can be used to
-interrupt execution. Additionally, signals such as @code{SIGSEGV},
-@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
-Ada exceptions, or used to implement run-time functions such as the
-@code{abort} statement and stack overflow checking.
-
-Pragma @code{Interrupt_State} provides a general mechanism for overriding
-such uses of interrupts. It subsumes the functionality of pragma
-@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
-available on OS/2, Windows or VMS. On all other platforms than VxWorks,
-it applies to signals; on VxWorks, it applies to vectored hardware interrupts
-and may be used to mark interrupts required by the board support package
-as reserved.
-
-Interrupts can be in one of three states:
-@itemize @bullet
-@item System
-
-The interrupt is reserved (no Ada handler can be installed), and the
-Ada run-time may not install a handler. As a result you are guaranteed
-standard system default action if this interrupt is raised.
-
-@item Runtime
-
-The interrupt is reserved (no Ada handler can be installed). The run time
-is allowed to install a handler for internal control purposes, but is
-not required to do so.
-
-@item User
-
-The interrupt is unreserved. The user may install a handler to provide
-some other action.
-@end itemize
-
-@noindent
-These states are the allowed values of the @code{State} parameter of the
-pragma. The @code{Name} parameter is a value of the type
-@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
-@code{Ada.Interrupts.Names}.
-
-This is a configuration pragma, and the binder will check that there
-are no inconsistencies between different units in a partition in how a
-given interrupt is specified. It may appear anywhere a pragma is legal.
-
-The effect is to move the interrupt to the specified state.
-
-By declaring interrupts to be SYSTEM, you guarantee the standard system
-action, such as a core dump.
-
-By declaring interrupts to be USER, you guarantee that you can install
-a handler.
-
-Note that certain signals on many operating systems cannot be caught and
-handled by applications. In such cases, the pragma is ignored. See the
-operating system documentation, or the value of the array @code{Reserved}
-declared in the spec of package @code{System.OS_Interface}.
-
-Overriding the default state of signals used by the Ada runtime may interfere
-with an application's runtime behavior in the cases of the synchronous signals,
-and in the case of the signal used to implement the @code{abort} statement.
-
-@node Pragma Keep_Names
-@unnumberedsec Pragma Keep_Names
-@findex Keep_Names
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
-@end smallexample
-
-@noindent
-The @var{LOCAL_NAME} argument
-must refer to an enumeration first subtype
-in the current declarative part. The effect is to retain the enumeration
-literal names for use by @code{Image} and @code{Value} even if a global
-@code{Discard_Names} pragma applies. This is useful when you want to
-generally suppress enumeration literal names and for example you therefore
-use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you
-want to retain the names for specific enumeration types.
-
-@node Pragma License
-@unnumberedsec Pragma License
-@findex License
-@cindex License checking
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
-@end smallexample
-
-@noindent
-This pragma is provided to allow automated checking for appropriate license
-conditions with respect to the standard and modified GPL@. A pragma
-@code{License}, which is a configuration pragma that typically appears at
-the start of a source file or in a separate @file{gnat.adc} file, specifies
-the licensing conditions of a unit as follows:
-
-@itemize @bullet
-@item Unrestricted
-This is used for a unit that can be freely used with no license restrictions.
-Examples of such units are public domain units, and units from the Ada
-Reference Manual.
-
-@item GPL
-This is used for a unit that is licensed under the unmodified GPL, and which
-therefore cannot be @code{with}'ed by a restricted unit.
-
-@item Modified_GPL
-This is used for a unit licensed under the GNAT modified GPL that includes
-a special exception paragraph that specifically permits the inclusion of
-the unit in programs without requiring the entire program to be released
-under the GPL@.
-
-@item Restricted
-This is used for a unit that is restricted in that it is not permitted to
-depend on units that are licensed under the GPL@. Typical examples are
-proprietary code that is to be released under more restrictive license
-conditions. Note that restricted units are permitted to @code{with} units
-which are licensed under the modified GPL (this is the whole point of the
-modified GPL).
-
-@end itemize
-
-@noindent
-Normally a unit with no @code{License} pragma is considered to have an
-unknown license, and no checking is done. However, standard GNAT headers
-are recognized, and license information is derived from them as follows.
-
-@itemize @bullet
-
-A GNAT license header starts with a line containing 78 hyphens. The following
-comment text is searched for the appearance of any of the following strings.
-
-If the string ``GNU General Public License'' is found, then the unit is assumed
-to have GPL license, unless the string ``As a special exception'' follows, in
-which case the license is assumed to be modified GPL@.
-
-If one of the strings
-``This specification is adapted from the Ada Semantic Interface'' or
-``This specification is derived from the Ada Reference Manual'' is found
-then the unit is assumed to be unrestricted.
-@end itemize
-
-@noindent
-These default actions means that a program with a restricted license pragma
-will automatically get warnings if a GPL unit is inappropriately
-@code{with}'ed. For example, the program:
-
-@smallexample @c ada
-with Sem_Ch3;
-with GNAT.Sockets;
-procedure Secret_Stuff is
- @dots{}
-end Secret_Stuff
-@end smallexample
-
-@noindent
-if compiled with pragma @code{License} (@code{Restricted}) in a
-@file{gnat.adc} file will generate the warning:
-
-@smallexample
-1. with Sem_Ch3;
- |
- >>> license of withed unit "Sem_Ch3" is incompatible
-
-2. with GNAT.Sockets;
-3. procedure Secret_Stuff is
-@end smallexample
-
-@noindent
-Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
-compiler and is licensed under the
-GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
-run time, and is therefore licensed under the modified GPL@.
-
-@node Pragma Link_With
-@unnumberedsec Pragma Link_With
-@findex Link_With
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
-@end smallexample
-
-@noindent
-This pragma is provided for compatibility with certain Ada 83 compilers.
-It has exactly the same effect as pragma @code{Linker_Options} except
-that spaces occurring within one of the string expressions are treated
-as separators. For example, in the following case:
-
-@smallexample @c ada
-pragma Link_With ("-labc -ldef");
-@end smallexample
-
-@noindent
-results in passing the strings @code{-labc} and @code{-ldef} as two
-separate arguments to the linker. In addition pragma Link_With allows
-multiple arguments, with the same effect as successive pragmas.
-
-@node Pragma Linker_Alias
-@unnumberedsec Pragma Linker_Alias
-@findex Linker_Alias
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Linker_Alias (
- [Entity =>] LOCAL_NAME,
- [Target =>] static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-@var{LOCAL_NAME} must refer to an object that is declared at the library
-level. This pragma establishes the given entity as a linker alias for the
-given target. It is equivalent to @code{__attribute__((alias))} in GNU C
-and causes @var{LOCAL_NAME} to be emitted as an alias for the symbol
-@var{static_string_EXPRESSION} in the object file, that is to say no space
-is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved
-to the same address as @var{static_string_EXPRESSION} by the linker.
-
-The actual linker name for the target must be used (e.g.@: the fully
-encoded name with qualification in Ada, or the mangled name in C++),
-or it must be declared using the C convention with @code{pragma Import}
-or @code{pragma Export}.
-
-Not all target machines support this pragma. On some of them it is accepted
-only if @code{pragma Weak_External} has been applied to @var{LOCAL_NAME}.
-
-@smallexample @c ada
--- Example of the use of pragma Linker_Alias
-
-package p is
- i : Integer := 1;
- pragma Export (C, i);
-
- new_name_for_i : Integer;
- pragma Linker_Alias (new_name_for_i, "i");
-end p;
-@end smallexample
-
-@node Pragma Linker_Constructor
-@unnumberedsec Pragma Linker_Constructor
-@findex Linker_Constructor
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Linker_Constructor (procedure_LOCAL_NAME);
-@end smallexample
-
-@noindent
-@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
-is declared at the library level. A procedure to which this pragma is
-applied will be treated as an initialization routine by the linker.
-It is equivalent to @code{__attribute__((constructor))} in GNU C and
-causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
-of the executable is called (or immediately after the shared library is
-loaded if the procedure is linked in a shared library), in particular
-before the Ada run-time environment is set up.
-
-Because of these specific contexts, the set of operations such a procedure
-can perform is very limited and the type of objects it can manipulate is
-essentially restricted to the elementary types. In particular, it must only
-contain code to which pragma Restrictions (No_Elaboration_Code) applies.
-
-This pragma is used by GNAT to implement auto-initialization of shared Stand
-Alone Libraries, which provides a related capability without the restrictions
-listed above. Where possible, the use of Stand Alone Libraries is preferable
-to the use of this pragma.
-
-@node Pragma Linker_Destructor
-@unnumberedsec Pragma Linker_Destructor
-@findex Linker_Destructor
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Linker_Destructor (procedure_LOCAL_NAME);
-@end smallexample
-
-@noindent
-@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
-is declared at the library level. A procedure to which this pragma is
-applied will be treated as a finalization routine by the linker.
-It is equivalent to @code{__attribute__((destructor))} in GNU C and
-causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
-of the executable has exited (or immediately before the shared library
-is unloaded if the procedure is linked in a shared library), in particular
-after the Ada run-time environment is shut down.
-
-See @code{pragma Linker_Constructor} for the set of restrictions that apply
-because of these specific contexts.
-
-@node Pragma Linker_Section
-@unnumberedsec Pragma Linker_Section
-@findex Linker_Section
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Linker_Section (
- [Entity =>] LOCAL_NAME,
- [Section =>] static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-@var{LOCAL_NAME} must refer to an object that is declared at the library
-level. This pragma specifies the name of the linker section for the given
-entity. It is equivalent to @code{__attribute__((section))} in GNU C and
-causes @var{LOCAL_NAME} to be placed in the @var{static_string_EXPRESSION}
-section of the executable (assuming the linker doesn't rename the section).
-
-The compiler normally places library-level objects in standard sections
-depending on their type: procedures and functions generally go in the
-@code{.text} section, initialized variables in the @code{.data} section
-and uninitialized variables in the @code{.bss} section.
-
-Other, special sections may exist on given target machines to map special
-hardware, for example I/O ports or flash memory. This pragma is a means to
-defer the final layout of the executable to the linker, thus fully working
-at the symbolic level with the compiler.
-
-Some file formats do not support arbitrary sections so not all target
-machines support this pragma. The use of this pragma may cause a program
-execution to be erroneous if it is used to place an entity into an
-inappropriate section (e.g.@: a modified variable into the @code{.text}
-section). See also @code{pragma Persistent_BSS}.
-
-@smallexample @c ada
--- Example of the use of pragma Linker_Section
-
-package IO_Card is
- Port_A : Integer;
- pragma Volatile (Port_A);
- pragma Linker_Section (Port_A, ".bss.port_a");
-
- Port_B : Integer;
- pragma Volatile (Port_B);
- pragma Linker_Section (Port_B, ".bss.port_b");
-end IO_Card;
-@end smallexample
-
-@node Pragma Long_Float
-@unnumberedsec Pragma Long_Float
-@cindex OpenVMS
-@findex Long_Float
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Long_Float (FLOAT_FORMAT);
-
-FLOAT_FORMAT ::= D_Float | G_Float
-@end smallexample
-
-@noindent
-This pragma is implemented only in the OpenVMS implementation of GNAT@.
-It allows control over the internal representation chosen for the predefined
-type @code{Long_Float} and for floating point type representations with
-@code{digits} specified in the range 7 through 15.
-For further details on this pragma, see the
-@cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use
-this pragma, the standard runtime libraries must be recompiled.
-@xref{The GNAT Run-Time Library Builder gnatlbr,,, gnat_ugn,
-@value{EDITION} User's Guide OpenVMS}, for a description of the
-@code{GNAT LIBRARY} command.
-
-@node Pragma Machine_Attribute
-@unnumberedsec Pragma Machine_Attribute
-@findex Machine_Attribute
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Machine_Attribute (
- [Entity =>] LOCAL_NAME,
- [Attribute_Name =>] static_string_EXPRESSION
- [, [Info =>] static_string_EXPRESSION] );
-@end smallexample
-
-@noindent
-Machine-dependent attributes can be specified for types and/or
-declarations. This pragma is semantically equivalent to
-@code{__attribute__((@var{attribute_name}))} (if @var{info} is not
-specified) or @code{__attribute__((@var{attribute_name}(@var{info})))}
-in GNU C, where @code{@var{attribute_name}} is recognized by the
-target macro @code{TARGET_ATTRIBUTE_TABLE} which is defined for each
-machine. The optional parameter @var{info} is transformed into an
-identifier, which may make this pragma unusable for some attributes
-(parameter of some attributes must be a number or a string).
-@xref{Target Attributes,, Defining target-specific uses of
-@code{__attribute__}, gccint, GNU Compiler Colletion (GCC) Internals},
-further information. It is not possible to specify
-attributes defined by other languages, only attributes defined by the
-machine the code is intended to run on.
-
-@node Pragma Main
-@unnumberedsec Pragma Main
-@cindex OpenVMS
-@findex Main
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Main
- (MAIN_OPTION [, MAIN_OPTION]);
-
-MAIN_OPTION ::=
- [STACK_SIZE =>] static_integer_EXPRESSION
-| [TASK_STACK_SIZE_DEFAULT =>] static_integer_EXPRESSION
-| [TIME_SLICING_ENABLED =>] static_boolean_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma is provided for compatibility with OpenVMS VAX Systems. It has
-no effect in GNAT, other than being syntax checked.
-
-@node Pragma Main_Storage
-@unnumberedsec Pragma Main_Storage
-@cindex OpenVMS
-@findex Main_Storage
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Main_Storage
- (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
-
-MAIN_STORAGE_OPTION ::=
- [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
-| [TOP_GUARD =>] static_SIMPLE_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma is provided for compatibility with OpenVMS VAX Systems. It has
-no effect in GNAT, other than being syntax checked. Note that the pragma
-also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
-
-@node Pragma No_Body
-@unnumberedsec Pragma No_Body
-@findex No_Body
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma No_Body;
-@end smallexample
-
-@noindent
-There are a number of cases in which a package spec does not require a body,
-and in fact a body is not permitted. GNAT will not permit the spec to be
-compiled if there is a body around. The pragma No_Body allows you to provide
-a body file, even in a case where no body is allowed. The body file must
-contain only comments and a single No_Body pragma. This is recognized by
-the compiler as indicating that no body is logically present.
-
-This is particularly useful during maintenance when a package is modified in
-such a way that a body needed before is no longer needed. The provision of a
-dummy body with a No_Body pragma ensures that there is no interference from
-earlier versions of the package body.
-
-@node Pragma No_Return
-@unnumberedsec Pragma No_Return
-@findex No_Return
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
-@end smallexample
-
-@noindent
-Each @var{procedure_LOCAL_NAME} argument must refer to one or more procedure
-declarations in the current declarative part. A procedure to which this
-pragma is applied may not contain any explicit @code{return} statements.
-In addition, if the procedure contains any implicit returns from falling
-off the end of a statement sequence, then execution of that implicit
-return will cause Program_Error to be raised.
-
-One use of this pragma is to identify procedures whose only purpose is to raise
-an exception. Another use of this pragma is to suppress incorrect warnings
-about missing returns in functions, where the last statement of a function
-statement sequence is a call to such a procedure.
-
-Note that in Ada 2005 mode, this pragma is part of the language, and is
-identical in effect to the pragma as implemented in Ada 95 mode.
-
-@node Pragma No_Strict_Aliasing
-@unnumberedsec Pragma No_Strict_Aliasing
-@findex No_Strict_Aliasing
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
-@end smallexample
-
-@noindent
-@var{type_LOCAL_NAME} must refer to an access type
-declaration in the current declarative part. The effect is to inhibit
-strict aliasing optimization for the given type. The form with no
-arguments is a configuration pragma which applies to all access types
-declared in units to which the pragma applies. For a detailed
-description of the strict aliasing optimization, and the situations
-in which it must be suppressed, see @ref{Optimization and Strict
-Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
-
-@node Pragma Normalize_Scalars
-@unnumberedsec Pragma Normalize_Scalars
-@findex Normalize_Scalars
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Normalize_Scalars;
-@end smallexample
-
-@noindent
-This is a language defined pragma which is fully implemented in GNAT@. The
-effect is to cause all scalar objects that are not otherwise initialized
-to be initialized. The initial values are implementation dependent and
-are as follows:
-
-@table @code
-@item Standard.Character
-@noindent
-Objects whose root type is Standard.Character are initialized to
-Character'Last unless the subtype range excludes NUL (in which case
-NUL is used). This choice will always generate an invalid value if
-one exists.
-
-@item Standard.Wide_Character
-@noindent
-Objects whose root type is Standard.Wide_Character are initialized to
-Wide_Character'Last unless the subtype range excludes NUL (in which case
-NUL is used). This choice will always generate an invalid value if
-one exists.
-
-@item Standard.Wide_Wide_Character
-@noindent
-Objects whose root type is Standard.Wide_Wide_Character are initialized to
-the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
-which case NUL is used). This choice will always generate an invalid value if
-one exists.
-
-@item Integer types
-@noindent
-Objects of an integer type are treated differently depending on whether
-negative values are present in the subtype. If no negative values are
-present, then all one bits is used as the initial value except in the
-special case where zero is excluded from the subtype, in which case
-all zero bits are used. This choice will always generate an invalid
-value if one exists.
-
-For subtypes with negative values present, the largest negative number
-is used, except in the unusual case where this largest negative number
-is in the subtype, and the largest positive number is not, in which case
-the largest positive value is used. This choice will always generate
-an invalid value if one exists.
-
-@item Floating-Point Types
-Objects of all floating-point types are initialized to all 1-bits. For
-standard IEEE format, this corresponds to a NaN (not a number) which is
-indeed an invalid value.
-
-@item Fixed-Point Types
-Objects of all fixed-point types are treated as described above for integers,
-with the rules applying to the underlying integer value used to represent
-the fixed-point value.
-
-@item Modular types
-Objects of a modular type are initialized to all one bits, except in
-the special case where zero is excluded from the subtype, in which
-case all zero bits are used. This choice will always generate an
-invalid value if one exists.
-
-@item Enumeration types
-Objects of an enumeration type are initialized to all one-bits, i.e.@: to
-the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
-whose Pos value is zero, in which case a code of zero is used. This choice
-will always generate an invalid value if one exists.
-
-@end table
-
-@node Pragma Obsolescent
-@unnumberedsec Pragma Obsolescent
-@findex Obsolescent
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Obsolescent
- [(Entity => NAME [, static_string_EXPRESSION [,Ada_05]])];
-@end smallexample
-
-@noindent
-This pragma can occur immediately following a declaration of an entity,
-including the case of a record component, and usually the Entity name
-must match the name of the entity declared by this declaration.
-Alternatively, the pragma can immediately follow an
-enumeration type declaration, where the entity argument names one of the
-enumeration literals.
-
-This pragma is used to indicate that the named entity
-is considered obsolescent and should not be used. Typically this is
-used when an API must be modified by eventually removing or modifying
-existing subprograms or other entities. The pragma can be used at an
-intermediate stage when the entity is still present, but will be
-removed later.
-
-The effect of this pragma is to output a warning message on
-a call to a program thus marked that the
-subprogram is obsolescent if the appropriate warning option in the
-compiler is activated. If the string parameter is present, then a second
-warning message is given containing this text.
-In addition, a call to such a program is considered a violation of
-pragma Restrictions (No_Obsolescent_Features).
-
-This pragma can also be used as a program unit pragma for a package,
-in which case the entity name is the name of the package, and the
-pragma indicates that the entire package is considered
-obsolescent. In this case a client @code{with}'ing such a package
-violates the restriction, and the @code{with} statement is
-flagged with warnings if the warning option is set.
-
-If the optional third parameter is present (which must be exactly
-the identifier Ada_05, no other argument is allowed), then the
-indication of obsolescence applies only when compiling in Ada 2005
-mode. This is primarily intended for dealing with the situations
-in the predefined library where subprograms or packages
-have become defined as obsolescent in Ada 2005
-(e.g.@: in Ada.Characters.Handling), but may be used anywhere.
-
-The following examples show typical uses of this pragma:
-
-@smallexample @c ada
-package p is
- pragma Obsolescent
- (Entity => p, "use pp instead of p");
-end p;
-
-package q is
- procedure q2;
- pragma Obsolescent
- (Entity => q2, "use q2new instead");
-
- type R is new integer;
- pragma Obsolescent
- (Entity => R, "use RR in Ada 2005", Ada_05);
-
- type M is record
- F1 : Integer;
- F2 : Integer;
- pragma Obsolescent (Entity => F2);
- F3 : Integer;
- end record;
-
- type E is (a, bc, 'd', quack);
- pragma Obsolescent (Entity => bc)
- pragma Obsolescent (Entity => 'd')
-
- function "+"
- (a, b : character) return character;
- pragma Obsolescent (Entity => "+");
-end;
-@end smallexample
-
-@noindent
-In an earlier version of GNAT, the Entity parameter was not required,
-and this form is still accepted for compatibility purposes. If the
-Entity parameter is omitted, then the pragma applies to the declaration
-immediately preceding the pragma (this form cannot be used for the
-enumeration literal case).
-
-@node Pragma Optimize_Alignment
-@unnumberedsec Pragma Optimize_Alignment
-@findex Optimize_Alignment
-@cindex Alignment, default settings
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Optimize_Alignment (TIME | SPACE | OFF);
-@end smallexample
-
-@noindent
-This is a configuration pragma which affects the choice of default alignments
-for types where no alignment is explicitly specified. There is a time/space
-trade-off in the selection of these values. Large alignments result in more
-efficient code, at the expense of larger data space, since sizes have to be
-increased to match these alignments. Smaller alignments save space, but the
-access code is slower. The normal choice of default alignments (which is what
-you get if you do not use this pragma, or if you use an argument of OFF),
-tries to balance these two requirements.
-
-Specifying SPACE causes smaller default alignments to be chosen in two cases.
-First any packed record is given an alignment of 1. Second, if a size is given
-for the type, then the alignment is chosen to avoid increasing this size. For
-example, consider:
-
-@smallexample @c ada
- type R is record
- X : Integer;
- Y : Character;
- end record;
-
- for R'Size use 5*8;
-@end smallexample
-
-@noindent
-In the default mode, this type gets an alignment of 4, so that access to the
-Integer field X are efficient. But this means that objects of the type end up
-with a size of 8 bytes. This is a valid choice, since sizes of objects are
-allowed to be bigger than the size of the type, but it can waste space if for
-example fields of type R appear in an enclosing record. If the above type is
-compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
-
-Specifying TIME causes larger default alignments to be chosen in the case of
-small types with sizes that are not a power of 2. For example, consider:
-
-@smallexample @c ada
- type R is record
- A : Character;
- B : Character;
- C : Boolean;
- end record;
-
- pragma Pack (R);
- for R'Size use 17;
-@end smallexample
-
-@noindent
-The default alignment for this record is normally 1, but if this type is
-compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
-to 4, which wastes space for objects of the type, since they are now 4 bytes
-long, but results in more efficient access when the whole record is referenced.
-
-As noted above, this is a configuration pragma, and there is a requirement
-that all units in a partition be compiled with a consistent setting of the
-optimization setting. This would normally be achieved by use of a configuration
-pragma file containing the appropriate setting. The exception to this rule is
-that units with an explicit configuration pragma in the same file as the source
-unit are excluded from the consistency check, as are all predefined units. The
-latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
-pragma appears at the start of the file.
-
-@node Pragma Passive
-@unnumberedsec Pragma Passive
-@findex Passive
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Passive [(Semaphore | No)];
-@end smallexample
-
-@noindent
-Syntax checked, but otherwise ignored by GNAT@. This is recognized for
-compatibility with DEC Ada 83 implementations, where it is used within a
-task definition to request that a task be made passive. If the argument
-@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
-treats the pragma as an assertion that the containing task is passive
-and that optimization of context switch with this task is permitted and
-desired. If the argument @code{No} is present, the task must not be
-optimized. GNAT does not attempt to optimize any tasks in this manner
-(since protected objects are available in place of passive tasks).
-
-@node Pragma Persistent_BSS
-@unnumberedsec Pragma Persistent_BSS
-@findex Persistent_BSS
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Persistent_BSS [(LOCAL_NAME)]
-@end smallexample
-
-@noindent
-This pragma allows selected objects to be placed in the @code{.persistent_bss}
-section. On some targets the linker and loader provide for special
-treatment of this section, allowing a program to be reloaded without
-affecting the contents of this data (hence the name persistent).
-
-There are two forms of usage. If an argument is given, it must be the
-local name of a library level object, with no explicit initialization
-and whose type is potentially persistent. If no argument is given, then
-the pragma is a configuration pragma, and applies to all library level
-objects with no explicit initialization of potentially persistent types.
-
-A potentially persistent type is a scalar type, or a non-tagged,
-non-discriminated record, all of whose components have no explicit
-initialization and are themselves of a potentially persistent type,
-or an array, all of whose constraints are static, and whose component
-type is potentially persistent.
-
-If this pragma is used on a target where this feature is not supported,
-then the pragma will be ignored. See also @code{pragma Linker_Section}.
-
-@node Pragma Polling
-@unnumberedsec Pragma Polling
-@findex Polling
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Polling (ON | OFF);
-@end smallexample
-
-@noindent
-This pragma controls the generation of polling code. This is normally off.
-If @code{pragma Polling (ON)} is used then periodic calls are generated to
-the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
-runtime library, and can be found in file @file{a-excpol.adb}.
-
-Pragma @code{Polling} can appear as a configuration pragma (for example it
-can be placed in the @file{gnat.adc} file) to enable polling globally, or it
-can be used in the statement or declaration sequence to control polling
-more locally.
-
-A call to the polling routine is generated at the start of every loop and
-at the start of every subprogram call. This guarantees that the @code{Poll}
-routine is called frequently, and places an upper bound (determined by
-the complexity of the code) on the period between two @code{Poll} calls.
-
-The primary purpose of the polling interface is to enable asynchronous
-aborts on targets that cannot otherwise support it (for example Windows
-NT), but it may be used for any other purpose requiring periodic polling.
-The standard version is null, and can be replaced by a user program. This
-will require re-compilation of the @code{Ada.Exceptions} package that can
-be found in files @file{a-except.ads} and @file{a-except.adb}.
-
-A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
-distribution) is used to enable the asynchronous abort capability on
-targets that do not normally support the capability. The version of
-@code{Poll} in this file makes a call to the appropriate runtime routine
-to test for an abort condition.
-
-Note that polling can also be enabled by use of the @option{-gnatP} switch.
-@xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for
-details.
-
-@node Pragma Postcondition
-@unnumberedsec Pragma Postcondition
-@cindex Postconditions
-@cindex Checks, postconditions
-@findex Postconditions
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Postcondition (
- [Check =>] Boolean_Expression
- [,[Message =>] String_Expression]);
-@end smallexample
-
-@noindent
-The @code{Postcondition} pragma allows specification of automatic
-postcondition checks for subprograms. These checks are similar to
-assertions, but are automatically inserted just prior to the return
-statements of the subprogram with which they are associated.
-Furthermore, the boolean expression which is the condition which
-must be true may contain references to function'Result in the case
-of a function to refer to the returned value.
-
-@code{Postcondition} pragmas may appear either immediate following the
-(separate) declaration of a subprogram, or at the start of the
-declarations of a subprogram body. Only other pragmas may intervene
-(that is appear between the subprogram declaration and its
-postconditions, or appear before the postcondition in the
-declaration sequence in a subprogram body). In the case of a
-postcondition appearing after a subprogram declaration, the
-formal arguments of the subprogram are visible, and can be
-referenced in the postcondition expressions.
-
-The postconditions are collected and automatically tested just
-before any return (implicit or explicit) in the subprogram body.
-A postcondition is only recognized if postconditions are active
-at the time the pragma is encountered. The compiler switch @option{gnata}
-turns on all postconditions by default, and pragma @code{Check_Policy}
-with an identifier of @code{Postcondition} can also be used to
-control whether postconditions are active.
-
-The general approach is that postconditions are placed in the spec
-if they represent functional aspects which make sense to the client.
-For example we might have:
-
-@smallexample @c ada
- function Direction return Integer;
- pragma Postcondition
- (Direction'Result = +1
- or else
- Direction'Result = -1);
-@end smallexample
-
-@noindent
-which serves to document that the result must be +1 or -1, and
-will test that this is the case at run time if postcondition
-checking is active.
-
-Postconditions within the subprogram body can be used to
-check that some internal aspect of the implementation,
-not visible to the client, is operating as expected.
-For instance if a square root routine keeps an internal
-counter of the number of times it is called, then we
-might have the following postcondition:
-
-@smallexample @c ada
- Sqrt_Calls : Natural := 0;
-
- function Sqrt (Arg : Float) return Float is
- pragma Postcondition
- (Sqrt_Calls = Sqrt_Calls'Old + 1);
- ...
- end Sqrt
-@end smallexample
-
-@noindent
-As this example, shows, the use of the @code{Old} attribute
-is often useful in postconditions to refer to the state on
-entry to the subprogram.
-
-Note that postconditions are only checked on normal returns
-from the subprogram. If an abnormal return results from
-raising an exception, then the postconditions are not checked.
-
-If a postcondition fails, then the exception
-@code{System.Assertions.Assert_Failure} is raised. If
-a message argument was supplied, then the given string
-will be used as the exception message. If no message
-argument was supplied, then the default message has
-the form "Postcondition failed at file:line". The
-exception is raised in the context of the subprogram
-body, so it is possible to catch postcondition failures
-within the subprogram body itself.
-
-Within a package spec, normal visibility rules
-in Ada would prevent forward references within a
-postcondition pragma to functions defined later in
-the same package. This would introduce undesirable
-ordering constraints. To avoid this problem, all
-postcondition pragmas are analyzed at the end of
-the package spec, allowing forward references.
-
-The following example shows that this even allows
-mutually recursive postconditions as in:
-
-@smallexample @c ada
-package Parity_Functions is
- function Odd (X : Natural) return Boolean;
- pragma Postcondition
- (Odd'Result =
- (x = 1
- or else
- (x /= 0 and then Even (X - 1))));
-
- function Even (X : Natural) return Boolean;
- pragma Postcondition
- (Even'Result =
- (x = 0
- or else
- (x /= 1 and then Odd (X - 1))));
-
-end Parity_Functions;
-@end smallexample
-
-@noindent
-There are no restrictions on the complexity or form of
-conditions used within @code{Postcondition} pragmas.
-The following example shows that it is even possible
-to verify performance behavior.
-
-@smallexample @c ada
-package Sort is
-
- Performance : constant Float;
- -- Performance constant set by implementation
- -- to match target architecture behavior.
-
- procedure Treesort (Arg : String);
- -- Sorts characters of argument using N*logN sort
- pragma Postcondition
- (Float (Clock - Clock'Old) <=
- Float (Arg'Length) *
- log (Float (Arg'Length)) *
- Performance);
-end Sort;
-@end smallexample
-
-@noindent
-Note: postcondition pragmas associated with subprograms that are
-marked as Inline_Always, or those marked as Inline with front-end
-inlining (-gnatN option set) are accepted and legality-checked
-by the compiler, but are ignored at run-time even if postcondition
-checking is enabled.
-
-@node Pragma Precondition
-@unnumberedsec Pragma Precondition
-@cindex Preconditions
-@cindex Checks, preconditions
-@findex Preconditions
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Precondition (
- [Check =>] Boolean_Expression
- [,[Message =>] String_Expression]);
-@end smallexample
-
-@noindent
-The @code{Precondition} pragma is similar to @code{Postcondition}
-except that the corresponding checks take place immediately upon
-entry to the subprogram, and if a precondition fails, the exception
-is raised in the context of the caller, and the attribute 'Result
-cannot be used within the precondition expression.
-
-Otherwise, the placement and visibility rules are identical to those
-described for postconditions. The following is an example of use
-within a package spec:
-
-@smallexample @c ada
-package Math_Functions is
- ...
- function Sqrt (Arg : Float) return Float;
- pragma Precondition (Arg >= 0.0)
- ...
-end Math_Functions;
-@end smallexample
-
-@noindent
-@code{Precondition} pragmas may appear either immediate following the
-(separate) declaration of a subprogram, or at the start of the
-declarations of a subprogram body. Only other pragmas may intervene
-(that is appear between the subprogram declaration and its
-postconditions, or appear before the postcondition in the
-declaration sequence in a subprogram body).
-
-Note: postcondition pragmas associated with subprograms that are
-marked as Inline_Always, or those marked as Inline with front-end
-inlining (-gnatN option set) are accepted and legality-checked
-by the compiler, but are ignored at run-time even if postcondition
-checking is enabled.
-
-
-
-@node Pragma Profile (Ravenscar)
-@unnumberedsec Pragma Profile (Ravenscar)
-@findex Ravenscar
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Profile (Ravenscar);
-@end smallexample
-
-@noindent
-A configuration pragma that establishes the following set of configuration
-pragmas:
-
-@table @code
-@item Task_Dispatching_Policy (FIFO_Within_Priorities)
-[RM D.2.2] Tasks are dispatched following a preemptive
-priority-ordered scheduling policy.
-
-@item Locking_Policy (Ceiling_Locking)
-[RM D.3] While tasks and interrupts execute a protected action, they inherit
-the ceiling priority of the corresponding protected object.
-@c
-@c @item Detect_Blocking
-@c This pragma forces the detection of potentially blocking operations within a
-@c protected operation, and to raise Program_Error if that happens.
-@end table
-@noindent
-
-plus the following set of restrictions:
-
-@table @code
-@item Max_Entry_Queue_Length = 1
-Defines the maximum number of calls that are queued on a (protected) entry.
-Note that this restrictions is checked at run time. Violation of this
-restriction results in the raising of Program_Error exception at the point of
-the call. For the Profile (Ravenscar) the value of Max_Entry_Queue_Length is
-always 1 and hence no task can be queued on a protected entry.
-
-@item Max_Protected_Entries = 1
-[RM D.7] Specifies the maximum number of entries per protected type. The
-bounds of every entry family of a protected unit shall be static, or shall be
-defined by a discriminant of a subtype whose corresponding bound is static.
-For the Profile (Ravenscar) the value of Max_Protected_Entries is always 1.
-
-@item Max_Task_Entries = 0
-[RM D.7] Specifies the maximum number of entries
-per task. The bounds of every entry family
-of a task unit shall be static, or shall be
-defined by a discriminant of a subtype whose
-corresponding bound is static. A value of zero
-indicates that no rendezvous are possible. For
-the Profile (Ravenscar), the value of Max_Task_Entries is always
-0 (zero).
-
-@item No_Abort_Statements
-[RM D.7] There are no abort_statements, and there are
-no calls to Task_Identification.Abort_Task.
-
-@item No_Asynchronous_Control
-There are no semantic dependences on the package
-Asynchronous_Task_Control.
-
-@item No_Calendar
-There are no semantic dependencies on the package Ada.Calendar.
-
-@item No_Dynamic_Attachment
-There is no call to any of the operations defined in package Ada.Interrupts
-(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
-Detach_Handler, and Reference).
-
-@item No_Dynamic_Priorities
-[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
-
-@item No_Implicit_Heap_Allocations
-[RM D.7] No constructs are allowed to cause implicit heap allocation.
-
-@item No_Local_Protected_Objects
-Protected objects and access types that designate
-such objects shall be declared only at library level.
-
-@item No_Local_Timing_Events
-[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are
-declared at the library level.
-
-@item No_Protected_Type_Allocators
-There are no allocators for protected types or
-types containing protected subcomponents.
-
-@item No_Relative_Delay
-There are no delay_relative statements.
-
-@item No_Requeue_Statements
-Requeue statements are not allowed.
-
-@item No_Select_Statements
-There are no select_statements.
-
-@item No_Specific_Termination_Handlers
-[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
-or to Ada.Task_Termination.Specific_Handler.
-
-@item No_Task_Allocators
-[RM D.7] There are no allocators for task types
-or types containing task subcomponents.
-
-@item No_Task_Attributes_Package
-There are no semantic dependencies on the Ada.Task_Attributes package.
-
-@item No_Task_Hierarchy
-[RM D.7] All (non-environment) tasks depend
-directly on the environment task of the partition.
-
-@item No_Task_Termination
-Tasks which terminate are erroneous.
-
-@item No_Unchecked_Conversion
-There are no semantic dependencies on the Ada.Unchecked_Conversion package.
-
-@item No_Unchecked_Deallocation
-There are no semantic dependencies on the Ada.Unchecked_Deallocation package.
-
-@item Simple_Barriers
-Entry barrier condition expressions shall be either static
-boolean expressions or boolean objects which are declared in
-the protected type which contains the entry.
-@end table
-
-@noindent
-This set of configuration pragmas and restrictions correspond to the
-definition of the ``Ravenscar Profile'' for limited tasking, devised and
-published by the @cite{International Real-Time Ada Workshop}, 1997,
-and whose most recent description is available at
-@url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
-
-The original definition of the profile was revised at subsequent IRTAW
-meetings. It has been included in the ISO
-@cite{Guide for the Use of the Ada Programming Language in High
-Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in
-the next revision of the standard. The formal definition given by
-the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
-AI-305) available at
-@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00249.TXT} and
-@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00305.TXT}
-respectively.
-
-The above set is a superset of the restrictions provided by pragma
-@code{Profile (Restricted)}, it includes six additional restrictions
-(@code{Simple_Barriers}, @code{No_Select_Statements},
-@code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
-@code{No_Relative_Delay} and @code{No_Task_Termination}). This means
-that pragma @code{Profile (Ravenscar)}, like the pragma
-@code{Profile (Restricted)},
-automatically causes the use of a simplified,
-more efficient version of the tasking run-time system.
-
-@node Pragma Profile (Restricted)
-@unnumberedsec Pragma Profile (Restricted)
-@findex Restricted Run Time
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Profile (Restricted);
-@end smallexample
-
-@noindent
-A configuration pragma that establishes the following set of restrictions:
-
-@itemize @bullet
-@item No_Abort_Statements
-@item No_Entry_Queue
-@item No_Task_Hierarchy
-@item No_Task_Allocators
-@item No_Dynamic_Priorities
-@item No_Terminate_Alternatives
-@item No_Dynamic_Attachment
-@item No_Protected_Type_Allocators
-@item No_Local_Protected_Objects
-@item No_Requeue_Statements
-@item No_Task_Attributes_Package
-@item Max_Asynchronous_Select_Nesting = 0
-@item Max_Task_Entries = 0
-@item Max_Protected_Entries = 1
-@item Max_Select_Alternatives = 0
-@end itemize
-
-@noindent
-This set of restrictions causes the automatic selection of a simplified
-version of the run time that provides improved performance for the
-limited set of tasking functionality permitted by this set of restrictions.
-
-@node Pragma Psect_Object
-@unnumberedsec Pragma Psect_Object
-@findex Psect_Object
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Psect_Object (
- [Internal =>] LOCAL_NAME,
- [, [External =>] EXTERNAL_SYMBOL]
- [, [Size =>] EXTERNAL_SYMBOL]);
-
-EXTERNAL_SYMBOL ::=
- IDENTIFIER
-| static_string_EXPRESSION
-@end smallexample
-
-@noindent
-This pragma is identical in effect to pragma @code{Common_Object}.
-
-@node Pragma Pure_Function
-@unnumberedsec Pragma Pure_Function
-@findex Pure_Function
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
-@end smallexample
-
-@noindent
-This pragma appears in the same declarative part as a function
-declaration (or a set of function declarations if more than one
-overloaded declaration exists, in which case the pragma applies
-to all entities). It specifies that the function @code{Entity} is
-to be considered pure for the purposes of code generation. This means
-that the compiler can assume that there are no side effects, and
-in particular that two calls with identical arguments produce the
-same result. It also means that the function can be used in an
-address clause.
-
-Note that, quite deliberately, there are no static checks to try
-to ensure that this promise is met, so @code{Pure_Function} can be used
-with functions that are conceptually pure, even if they do modify
-global variables. For example, a square root function that is
-instrumented to count the number of times it is called is still
-conceptually pure, and can still be optimized, even though it
-modifies a global variable (the count). Memo functions are another
-example (where a table of previous calls is kept and consulted to
-avoid re-computation).
-
-@findex Pure
-Note: Most functions in a @code{Pure} package are automatically pure, and
-there is no need to use pragma @code{Pure_Function} for such functions. One
-exception is any function that has at least one formal of type
-@code{System.Address} or a type derived from it. Such functions are not
-considered pure by default, since the compiler assumes that the
-@code{Address} parameter may be functioning as a pointer and that the
-referenced data may change even if the address value does not.
-Similarly, imported functions are not considered to be pure by default,
-since there is no way of checking that they are in fact pure. The use
-of pragma @code{Pure_Function} for such a function will override these default
-assumption, and cause the compiler to treat a designated subprogram as pure
-in these cases.
-
-Note: If pragma @code{Pure_Function} is applied to a renamed function, it
-applies to the underlying renamed function. This can be used to
-disambiguate cases of overloading where some but not all functions
-in a set of overloaded functions are to be designated as pure.
-
-If pragma @code{Pure_Function} is applied to a library level function, the
-function is also considered pure from an optimization point of view, but the
-unit is not a Pure unit in the categorization sense. So for example, a function
-thus marked is free to @code{with} non-pure units.
-
-@node Pragma Restriction_Warnings
-@unnumberedsec Pragma Restriction_Warnings
-@findex Restriction_Warnings
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Restriction_Warnings
- (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
-@end smallexample
-
-@noindent
-This pragma allows a series of restriction identifiers to be
-specified (the list of allowed identifiers is the same as for
-pragma @code{Restrictions}). For each of these identifiers
-the compiler checks for violations of the restriction, but
-generates a warning message rather than an error message
-if the restriction is violated.
-
-@node Pragma Shared
-@unnumberedsec Pragma Shared
-@findex Shared
-
-@noindent
-This pragma is provided for compatibility with Ada 83. The syntax and
-semantics are identical to pragma Atomic.
-
-@node Pragma Source_File_Name
-@unnumberedsec Pragma Source_File_Name
-@findex Source_File_Name
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Source_File_Name (
- [Unit_Name =>] unit_NAME,
- Spec_File_Name => STRING_LITERAL);
-
-pragma Source_File_Name (
- [Unit_Name =>] unit_NAME,
- Body_File_Name => STRING_LITERAL);
-@end smallexample
-
-@noindent
-Use this to override the normal naming convention. It is a configuration
-pragma, and so has the usual applicability of configuration pragmas
-(i.e.@: it applies to either an entire partition, or to all units in a
-compilation, or to a single unit, depending on how it is used.
-@var{unit_name} is mapped to @var{file_name_literal}. The identifier for
-the second argument is required, and indicates whether this is the file
-name for the spec or for the body.
-
-Another form of the @code{Source_File_Name} pragma allows
-the specification of patterns defining alternative file naming schemes
-to apply to all files.
-
-@smallexample @c ada
-pragma Source_File_Name
- (Spec_File_Name => STRING_LITERAL
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
-
-pragma Source_File_Name
- (Body_File_Name => STRING_LITERAL
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
-
-pragma Source_File_Name
- (Subunit_File_Name => STRING_LITERAL
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
-
-CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
-@end smallexample
-
-@noindent
-The first argument is a pattern that contains a single asterisk indicating
-the point at which the unit name is to be inserted in the pattern string
-to form the file name. The second argument is optional. If present it
-specifies the casing of the unit name in the resulting file name string.
-The default is lower case. Finally the third argument allows for systematic
-replacement of any dots in the unit name by the specified string literal.
-
-A pragma Source_File_Name cannot appear after a
-@ref{Pragma Source_File_Name_Project}.
-
-For more details on the use of the @code{Source_File_Name} pragma,
-@xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide},
-and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION}
-User's Guide}.
-
-@node Pragma Source_File_Name_Project
-@unnumberedsec Pragma Source_File_Name_Project
-@findex Source_File_Name_Project
-@noindent
-
-This pragma has the same syntax and semantics as pragma Source_File_Name.
-It is only allowed as a stand alone configuration pragma.
-It cannot appear after a @ref{Pragma Source_File_Name}, and
-most importantly, once pragma Source_File_Name_Project appears,
-no further Source_File_Name pragmas are allowed.
-
-The intention is that Source_File_Name_Project pragmas are always
-generated by the Project Manager in a manner consistent with the naming
-specified in a project file, and when naming is controlled in this manner,
-it is not permissible to attempt to modify this naming scheme using
-Source_File_Name pragmas (which would not be known to the project manager).
-
-@node Pragma Source_Reference
-@unnumberedsec Pragma Source_Reference
-@findex Source_Reference
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
-@end smallexample
-
-@noindent
-This pragma must appear as the first line of a source file.
-@var{integer_literal} is the logical line number of the line following
-the pragma line (for use in error messages and debugging
-information). @var{string_literal} is a static string constant that
-specifies the file name to be used in error messages and debugging
-information. This is most notably used for the output of @code{gnatchop}
-with the @option{-r} switch, to make sure that the original unchopped
-source file is the one referred to.
-
-The second argument must be a string literal, it cannot be a static
-string expression other than a string literal. This is because its value
-is needed for error messages issued by all phases of the compiler.
-
-@node Pragma Stream_Convert
-@unnumberedsec Pragma Stream_Convert
-@findex Stream_Convert
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Stream_Convert (
- [Entity =>] type_LOCAL_NAME,
- [Read =>] function_NAME,
- [Write =>] function_NAME);
-@end smallexample
-
-@noindent
-This pragma provides an efficient way of providing stream functions for
-types defined in packages. Not only is it simpler to use than declaring
-the necessary functions with attribute representation clauses, but more
-significantly, it allows the declaration to made in such a way that the
-stream packages are not loaded unless they are needed. The use of
-the Stream_Convert pragma adds no overhead at all, unless the stream
-attributes are actually used on the designated type.
-
-The first argument specifies the type for which stream functions are
-provided. The second parameter provides a function used to read values
-of this type. It must name a function whose argument type may be any
-subtype, and whose returned type must be the type given as the first
-argument to the pragma.
-
-The meaning of the @var{Read}
-parameter is that if a stream attribute directly
-or indirectly specifies reading of the type given as the first parameter,
-then a value of the type given as the argument to the Read function is
-read from the stream, and then the Read function is used to convert this
-to the required target type.
-
-Similarly the @var{Write} parameter specifies how to treat write attributes
-that directly or indirectly apply to the type given as the first parameter.
-It must have an input parameter of the type specified by the first parameter,
-and the return type must be the same as the input type of the Read function.
-The effect is to first call the Write function to convert to the given stream
-type, and then write the result type to the stream.
-
-The Read and Write functions must not be overloaded subprograms. If necessary
-renamings can be supplied to meet this requirement.
-The usage of this attribute is best illustrated by a simple example, taken
-from the GNAT implementation of package Ada.Strings.Unbounded:
-
-@smallexample @c ada
-function To_Unbounded (S : String)
- return Unbounded_String
- renames To_Unbounded_String;
-
-pragma Stream_Convert
- (Unbounded_String, To_Unbounded, To_String);
-@end smallexample
-
-@noindent
-The specifications of the referenced functions, as given in the Ada
-Reference Manual are:
-
-@smallexample @c ada
-function To_Unbounded_String (Source : String)
- return Unbounded_String;
-
-function To_String (Source : Unbounded_String)
- return String;
-@end smallexample
-
-@noindent
-The effect is that if the value of an unbounded string is written to a
-stream, then the representation of the item in the stream is in the same
-format used for @code{Standard.String}, and this same representation is
-expected when a value of this type is read from the stream.
-
-@node Pragma Style_Checks
-@unnumberedsec Pragma Style_Checks
-@findex Style_Checks
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Style_Checks (string_LITERAL | ALL_CHECKS |
- On | Off [, LOCAL_NAME]);
-@end smallexample
-
-@noindent
-This pragma is used in conjunction with compiler switches to control the
-built in style checking provided by GNAT@. The compiler switches, if set,
-provide an initial setting for the switches, and this pragma may be used
-to modify these settings, or the settings may be provided entirely by
-the use of the pragma. This pragma can be used anywhere that a pragma
-is legal, including use as a configuration pragma (including use in
-the @file{gnat.adc} file).
-
-The form with a string literal specifies which style options are to be
-activated. These are additive, so they apply in addition to any previously
-set style check options. The codes for the options are the same as those
-used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}.
-For example the following two methods can be used to enable
-layout checking:
-
-@itemize @bullet
-@item
-@smallexample @c ada
-pragma Style_Checks ("l");
-@end smallexample
-
-@item
-@smallexample
-gcc -c -gnatyl @dots{}
-@end smallexample
-@end itemize
-
-@noindent
-The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @code{gnaty} switch with no options. @xref{Top,
-@value{EDITION} User's Guide, About This Guide, gnat_ugn,
-@value{EDITION} User's Guide}, for details.
-
-The forms with @code{Off} and @code{On}
-can be used to temporarily disable style checks
-as shown in the following example:
-
-@smallexample @c ada
-@iftex
-@leftskip=0cm
-@end iftex
-pragma Style_Checks ("k"); -- requires keywords in lower case
-pragma Style_Checks (Off); -- turn off style checks
-NULL; -- this will not generate an error message
-pragma Style_Checks (On); -- turn style checks back on
-NULL; -- this will generate an error message
-@end smallexample
-
-@noindent
-Finally the two argument form is allowed only if the first argument is
-@code{On} or @code{Off}. The effect is to turn of semantic style checks
-for the specified entity, as shown in the following example:
-
-@smallexample @c ada
-@iftex
-@leftskip=0cm
-@end iftex
-pragma Style_Checks ("r"); -- require consistency of identifier casing
-Arg : Integer;
-Rf1 : Integer := ARG; -- incorrect, wrong case
-pragma Style_Checks (Off, Arg);
-Rf2 : Integer := ARG; -- OK, no error
-@end smallexample
-
-@node Pragma Subtitle
-@unnumberedsec Pragma Subtitle
-@findex Subtitle
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Subtitle ([Subtitle =>] STRING_LITERAL);
-@end smallexample
-
-@noindent
-This pragma is recognized for compatibility with other Ada compilers
-but is ignored by GNAT@.
-
-@node Pragma Suppress
-@unnumberedsec Pragma Suppress
-@findex Suppress
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Suppress (Identifier [, [On =>] Name]);
-@end smallexample
-
-@noindent
-This is a standard pragma, and supports all the check names required in
-the RM. It is included here because GNAT recognizes one additional check
-name: @code{Alignment_Check} which can be used to suppress alignment checks
-on addresses used in address clauses. Such checks can also be suppressed
-by suppressing range checks, but the specific use of @code{Alignment_Check}
-allows suppression of alignment checks without suppressing other range checks.
-
-Note that pragma Suppress gives the compiler permission to omit
-checks, but does not require the compiler to omit checks. The compiler
-will generate checks if they are essentially free, even when they are
-suppressed. In particular, if the compiler can prove that a certain
-check will necessarily fail, it will generate code to do an
-unconditional ``raise'', even if checks are suppressed. The compiler
-warns in this case.
-
-Of course, run-time checks are omitted whenever the compiler can prove
-that they will not fail, whether or not checks are suppressed.
-
-@node Pragma Suppress_All
-@unnumberedsec Pragma Suppress_All
-@findex Suppress_All
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Suppress_All;
-@end smallexample
-
-@noindent
-This pragma can only appear immediately following a compilation
-unit. The effect is to apply @code{Suppress (All_Checks)} to the unit
-which it follows. This pragma is implemented for compatibility with DEC
-Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal
-configuration pragma is the preferred usage in GNAT@.
-
-@node Pragma Suppress_Exception_Locations
-@unnumberedsec Pragma Suppress_Exception_Locations
-@findex Suppress_Exception_Locations
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Suppress_Exception_Locations;
-@end smallexample
-
-@noindent
-In normal mode, a raise statement for an exception by default generates
-an exception message giving the file name and line number for the location
-of the raise. This is useful for debugging and logging purposes, but this
-entails extra space for the strings for the messages. The configuration
-pragma @code{Suppress_Exception_Locations} can be used to suppress the
-generation of these strings, with the result that space is saved, but the
-exception message for such raises is null. This configuration pragma may
-appear in a global configuration pragma file, or in a specific unit as
-usual. It is not required that this pragma be used consistently within
-a partition, so it is fine to have some units within a partition compiled
-with this pragma and others compiled in normal mode without it.
-
-@node Pragma Suppress_Initialization
-@unnumberedsec Pragma Suppress_Initialization
-@findex Suppress_Initialization
-@cindex Suppressing initialization
-@cindex Initialization, suppression of
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Suppress_Initialization ([Entity =>] type_Name);
-@end smallexample
-
-@noindent
-This pragma suppresses any implicit or explicit initialization
-associated with the given type name for all variables of this type.
-
-@node Pragma Task_Info
-@unnumberedsec Pragma Task_Info
-@findex Task_Info
-@noindent
-Syntax
-
-@smallexample @c ada
-pragma Task_Info (EXPRESSION);
-@end smallexample
-
-@noindent
-This pragma appears within a task definition (like pragma
-@code{Priority}) and applies to the task in which it appears. The
-argument must be of type @code{System.Task_Info.Task_Info_Type}.
-The @code{Task_Info} pragma provides system dependent control over
-aspects of tasking implementation, for example, the ability to map
-tasks to specific processors. For details on the facilities available
-for the version of GNAT that you are using, see the documentation
-in the spec of package System.Task_Info in the runtime
-library.
-
-@node Pragma Task_Name
-@unnumberedsec Pragma Task_Name
-@findex Task_Name
-@noindent
-Syntax
-
-@smallexample @c ada
-pragma Task_Name (string_EXPRESSION);
-@end smallexample
-
-@noindent
-This pragma appears within a task definition (like pragma
-@code{Priority}) and applies to the task in which it appears. The
-argument must be of type String, and provides a name to be used for
-the task instance when the task is created. Note that this expression
-is not required to be static, and in particular, it can contain
-references to task discriminants. This facility can be used to
-provide different names for different tasks as they are created,
-as illustrated in the example below.
-
-The task name is recorded internally in the run-time structures
-and is accessible to tools like the debugger. In addition the
-routine @code{Ada.Task_Identification.Image} will return this
-string, with a unique task address appended.
-
-@smallexample @c ada
--- Example of the use of pragma Task_Name
-
-with Ada.Task_Identification;
-use Ada.Task_Identification;
-with Text_IO; use Text_IO;
-procedure t3 is
-
- type Astring is access String;
-
- task type Task_Typ (Name : access String) is
- pragma Task_Name (Name.all);
- end Task_Typ;
-
- task body Task_Typ is
- Nam : constant String := Image (Current_Task);
- begin
- Put_Line ("-->" & Nam (1 .. 14) & "<--");
- end Task_Typ;
-
- type Ptr_Task is access Task_Typ;
- Task_Var : Ptr_Task;
-
-begin
- Task_Var :=
- new Task_Typ (new String'("This is task 1"));
- Task_Var :=
- new Task_Typ (new String'("This is task 2"));
-end;
-@end smallexample
-
-@node Pragma Task_Storage
-@unnumberedsec Pragma Task_Storage
-@findex Task_Storage
-Syntax:
-
-@smallexample @c ada
-pragma Task_Storage (
- [Task_Type =>] LOCAL_NAME,
- [Top_Guard =>] static_integer_EXPRESSION);
-@end smallexample
-
-@noindent
-This pragma specifies the length of the guard area for tasks. The guard
-area is an additional storage area allocated to a task. A value of zero
-means that either no guard area is created or a minimal guard area is
-created, depending on the target. This pragma can appear anywhere a
-@code{Storage_Size} attribute definition clause is allowed for a task
-type.
-
-@node Pragma Time_Slice
-@unnumberedsec Pragma Time_Slice
-@findex Time_Slice
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Time_Slice (static_duration_EXPRESSION);
-@end smallexample
-
-@noindent
-For implementations of GNAT on operating systems where it is possible
-to supply a time slice value, this pragma may be used for this purpose.
-It is ignored if it is used in a system that does not allow this control,
-or if it appears in other than the main program unit.
-@cindex OpenVMS
-Note that the effect of this pragma is identical to the effect of the
-DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
-
-@node Pragma Title
-@unnumberedsec Pragma Title
-@findex Title
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Title (TITLING_OPTION [, TITLING OPTION]);
-
-TITLING_OPTION ::=
- [Title =>] STRING_LITERAL,
-| [Subtitle =>] STRING_LITERAL
-@end smallexample
-
-@noindent
-Syntax checked but otherwise ignored by GNAT@. This is a listing control
-pragma used in DEC Ada 83 implementations to provide a title and/or
-subtitle for the program listing. The program listing generated by GNAT
-does not have titles or subtitles.
-
-Unlike other pragmas, the full flexibility of named notation is allowed
-for this pragma, i.e.@: the parameters may be given in any order if named
-notation is used, and named and positional notation can be mixed
-following the normal rules for procedure calls in Ada.
-
-@node Pragma Unchecked_Union
-@unnumberedsec Pragma Unchecked_Union
-@cindex Unions in C
-@findex Unchecked_Union
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Unchecked_Union (first_subtype_LOCAL_NAME);
-@end smallexample
-
-@noindent
-This pragma is used to specify a representation of a record type that is
-equivalent to a C union. It was introduced as a GNAT implementation defined
-pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
-pragma, making it language defined, and GNAT fully implements this extended
-version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
-details, consult the Ada 2005 Reference Manual, section B.3.3.
-
-@node Pragma Unimplemented_Unit
-@unnumberedsec Pragma Unimplemented_Unit
-@findex Unimplemented_Unit
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Unimplemented_Unit;
-@end smallexample
-
-@noindent
-If this pragma occurs in a unit that is processed by the compiler, GNAT
-aborts with the message @samp{@var{xxx} not implemented}, where
-@var{xxx} is the name of the current compilation unit. This pragma is
-intended to allow the compiler to handle unimplemented library units in
-a clean manner.
-
-The abort only happens if code is being generated. Thus you can use
-specs of unimplemented packages in syntax or semantic checking mode.
-
-@node Pragma Universal_Aliasing
-@unnumberedsec Pragma Universal_Aliasing
-@findex Universal_Aliasing
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
-@end smallexample
-
-@noindent
-@var{type_LOCAL_NAME} must refer to a type declaration in the current
-declarative part. The effect is to inhibit strict type-based aliasing
-optimization for the given type. In other words, the effect is as though
-access types designating this type were subject to pragma No_Strict_Aliasing.
-For a detailed description of the strict aliasing optimization, and the
-situations in which it must be suppressed, @xref{Optimization and Strict
-Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
-
-@node Pragma Universal_Data
-@unnumberedsec Pragma Universal_Data
-@findex Universal_Data
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Universal_Data [(library_unit_Name)];
-@end smallexample
-
-@noindent
-This pragma is supported only for the AAMP target and is ignored for
-other targets. The pragma specifies that all library-level objects
-(Counter 0 data) associated with the library unit are to be accessed
-and updated using universal addressing (24-bit addresses for AAMP5)
-rather than the default of 16-bit Data Environment (DENV) addressing.
-Use of this pragma will generally result in less efficient code for
-references to global data associated with the library unit, but
-allows such data to be located anywhere in memory. This pragma is
-a library unit pragma, but can also be used as a configuration pragma
-(including use in the @file{gnat.adc} file). The functionality
-of this pragma is also available by applying the -univ switch on the
-compilations of units where universal addressing of the data is desired.
-
-@node Pragma Unmodified
-@unnumberedsec Pragma Unmodified
-@findex Unmodified
-@cindex Warnings, unmodified
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
-@end smallexample
-
-@noindent
-This pragma signals that the assignable entities (variables,
-@code{out} parameters, @code{in out} parameters) whose names are listed are
-deliberately not assigned in the current source unit. This
-suppresses warnings about the
-entities being referenced but not assigned, and in addition a warning will be
-generated if one of these entities is in fact assigned in the
-same unit as the pragma (or in the corresponding body, or one
-of its subunits).
-
-This is particularly useful for clearly signaling that a particular
-parameter is not modified, even though the spec suggests that it might
-be.
-
-@node Pragma Unreferenced
-@unnumberedsec Pragma Unreferenced
-@findex Unreferenced
-@cindex Warnings, unreferenced
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
-pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
-@end smallexample
-
-@noindent
-This pragma signals that the entities whose names are listed are
-deliberately not referenced in the current source unit. This
-suppresses warnings about the
-entities being unreferenced, and in addition a warning will be
-generated if one of these entities is in fact referenced in the
-same unit as the pragma (or in the corresponding body, or one
-of its subunits).
-
-This is particularly useful for clearly signaling that a particular
-parameter is not referenced in some particular subprogram implementation
-and that this is deliberate. It can also be useful in the case of
-objects declared only for their initialization or finalization side
-effects.
-
-If @code{LOCAL_NAME} identifies more than one matching homonym in the
-current scope, then the entity most recently declared is the one to which
-the pragma applies. Note that in the case of accept formals, the pragma
-Unreferenced may appear immediately after the keyword @code{do} which
-allows the indication of whether or not accept formals are referenced
-or not to be given individually for each accept statement.
-
-The left hand side of an assignment does not count as a reference for the
-purpose of this pragma. Thus it is fine to assign to an entity for which
-pragma Unreferenced is given.
-
-Note that if a warning is desired for all calls to a given subprogram,
-regardless of whether they occur in the same unit as the subprogram
-declaration, then this pragma should not be used (calls from another
-unit would not be flagged); pragma Obsolescent can be used instead
-for this purpose, see @xref{Pragma Obsolescent}.
-
-The second form of pragma @code{Unreferenced} is used within a context
-clause. In this case the arguments must be unit names of units previously
-mentioned in @code{with} clauses (similar to the usage of pragma
-@code{Elaborate_All}. The effect is to suppress warnings about unreferenced
-units and unreferenced entities within these units.
-
-@node Pragma Unreferenced_Objects
-@unnumberedsec Pragma Unreferenced_Objects
-@findex Unreferenced_Objects
-@cindex Warnings, unreferenced
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
-@end smallexample
-
-@noindent
-This pragma signals that for the types or subtypes whose names are
-listed, objects which are declared with one of these types or subtypes may
-not be referenced, and if no references appear, no warnings are given.
-
-This is particularly useful for objects which are declared solely for their
-initialization and finalization effect. Such variables are sometimes referred
-to as RAII variables (Resource Acquisition Is Initialization). Using this
-pragma on the relevant type (most typically a limited controlled type), the
-compiler will automatically suppress unwanted warnings about these variables
-not being referenced.
-
-@node Pragma Unreserve_All_Interrupts
-@unnumberedsec Pragma Unreserve_All_Interrupts
-@findex Unreserve_All_Interrupts
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Unreserve_All_Interrupts;
-@end smallexample
-
-@noindent
-Normally certain interrupts are reserved to the implementation. Any attempt
-to attach an interrupt causes Program_Error to be raised, as described in
-RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
-many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is
-reserved to the implementation, so that @kbd{Ctrl-C} can be used to
-interrupt execution.
-
-If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
-a program, then all such interrupts are unreserved. This allows the
-program to handle these interrupts, but disables their standard
-functions. For example, if this pragma is used, then pressing
-@kbd{Ctrl-C} will not automatically interrupt execution. However,
-a program can then handle the @code{SIGINT} interrupt as it chooses.
-
-For a full list of the interrupts handled in a specific implementation,
-see the source code for the spec of @code{Ada.Interrupts.Names} in
-file @file{a-intnam.ads}. This is a target dependent file that contains the
-list of interrupts recognized for a given target. The documentation in
-this file also specifies what interrupts are affected by the use of
-the @code{Unreserve_All_Interrupts} pragma.
-
-For a more general facility for controlling what interrupts can be
-handled, see pragma @code{Interrupt_State}, which subsumes the functionality
-of the @code{Unreserve_All_Interrupts} pragma.
-
-@node Pragma Unsuppress
-@unnumberedsec Pragma Unsuppress
-@findex Unsuppress
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
-@end smallexample
-
-@noindent
-This pragma undoes the effect of a previous pragma @code{Suppress}. If
-there is no corresponding pragma @code{Suppress} in effect, it has no
-effect. The range of the effect is the same as for pragma
-@code{Suppress}. The meaning of the arguments is identical to that used
-in pragma @code{Suppress}.
-
-One important application is to ensure that checks are on in cases where
-code depends on the checks for its correct functioning, so that the code
-will compile correctly even if the compiler switches are set to suppress
-checks.
-
-@node Pragma Use_VADS_Size
-@unnumberedsec Pragma Use_VADS_Size
-@cindex @code{Size}, VADS compatibility
-@findex Use_VADS_Size
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Use_VADS_Size;
-@end smallexample
-
-@noindent
-This is a configuration pragma. In a unit to which it applies, any use
-of the 'Size attribute is automatically interpreted as a use of the
-'VADS_Size attribute. Note that this may result in incorrect semantic
-processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in
-the handling of existing code which depends on the interpretation of Size
-as implemented in the VADS compiler. See description of the VADS_Size
-attribute for further details.
-
-@node Pragma Validity_Checks
-@unnumberedsec Pragma Validity_Checks
-@findex Validity_Checks
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
-@end smallexample
-
-@noindent
-This pragma is used in conjunction with compiler switches to control the
-built-in validity checking provided by GNAT@. The compiler switches, if set
-provide an initial setting for the switches, and this pragma may be used
-to modify these settings, or the settings may be provided entirely by
-the use of the pragma. This pragma can be used anywhere that a pragma
-is legal, including use as a configuration pragma (including use in
-the @file{gnat.adc} file).
-
-The form with a string literal specifies which validity options are to be
-activated. The validity checks are first set to include only the default
-reference manual settings, and then a string of letters in the string
-specifies the exact set of options required. The form of this string
-is exactly as described for the @option{-gnatVx} compiler switch (see the
-GNAT users guide for details). For example the following two methods
-can be used to enable validity checking for mode @code{in} and
-@code{in out} subprogram parameters:
-
-@itemize @bullet
-@item
-@smallexample @c ada
-pragma Validity_Checks ("im");
-@end smallexample
-
-@item
-@smallexample
-gcc -c -gnatVim @dots{}
-@end smallexample
-@end itemize
-
-@noindent
-The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @code{gnatva} switch.
-
-The forms with @code{Off} and @code{On}
-can be used to temporarily disable validity checks
-as shown in the following example:
-
-@smallexample @c ada
-@iftex
-@leftskip=0cm
-@end iftex
-pragma Validity_Checks ("c"); -- validity checks for copies
-pragma Validity_Checks (Off); -- turn off validity checks
-A := B; -- B will not be validity checked
-pragma Validity_Checks (On); -- turn validity checks back on
-A := C; -- C will be validity checked
-@end smallexample
-
-@node Pragma Volatile
-@unnumberedsec Pragma Volatile
-@findex Volatile
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Volatile (LOCAL_NAME);
-@end smallexample
-
-@noindent
-This pragma is defined by the Ada Reference Manual, and the GNAT
-implementation is fully conformant with this definition. The reason it
-is mentioned in this section is that a pragma of the same name was supplied
-in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005
-implementation of pragma Volatile is upwards compatible with the
-implementation in DEC Ada 83.
-
-@node Pragma Warnings
-@unnumberedsec Pragma Warnings
-@findex Warnings
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Warnings (On | Off);
-pragma Warnings (On | Off, LOCAL_NAME);
-pragma Warnings (static_string_EXPRESSION);
-pragma Warnings (On | Off, static_string_EXPRESSION);
-@end smallexample
-
-@noindent
-Normally warnings are enabled, with the output being controlled by
-the command line switch. Warnings (@code{Off}) turns off generation of
-warnings until a Warnings (@code{On}) is encountered or the end of the
-current unit. If generation of warnings is turned off using this
-pragma, then no warning messages are output, regardless of the
-setting of the command line switches.
-
-The form with a single argument may be used as a configuration pragma.
-
-If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for
-the specified entity. This suppression is effective from the point where
-it occurs till the end of the extended scope of the variable (similar to
-the scope of @code{Suppress}).
-
-The form with a single static_string_EXPRESSION argument provides more precise
-control over which warnings are active. The string is a list of letters
-specifying which warnings are to be activated and which deactivated. The
-code for these letters is the same as the string used in the command
-line switch controlling warnings. The following is a brief summary. For
-full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
-User's Guide}.
-
-@smallexample
-a turn on all optional warnings (except d h l .o)
-A turn off all optional warnings
-.a* turn on warnings for failing assertions
-.A turn off warnings for failing assertions
-b turn on warnings for bad fixed value (not multiple of small)
-B* turn off warnings for bad fixed value (not multiple of small)
-c turn on warnings for constant conditional
-C* turn off warnings for constant conditional
-.c turn on warnings for unrepped components
-.C* turn off warnings for unrepped components
-d turn on warnings for implicit dereference
-D* turn off warnings for implicit dereference
-e treat all warnings as errors
-f turn on warnings for unreferenced formal
-F* turn off warnings for unreferenced formal
-g* turn on warnings for unrecognized pragma
-G turn off warnings for unrecognized pragma
-h turn on warnings for hiding variable
-H* turn off warnings for hiding variable
-i* turn on warnings for implementation unit
-I turn off warnings for implementation unit
-j turn on warnings for obsolescent (annex J) feature
-J* turn off warnings for obsolescent (annex J) feature
-k turn on warnings on constant variable
-K* turn off warnings on constant variable
-l turn on warnings for missing elaboration pragma
-L* turn off warnings for missing elaboration pragma
-m turn on warnings for variable assigned but not read
-M* turn off warnings for variable assigned but not read
-n* normal warning mode (cancels -gnatws/-gnatwe)
-o* turn on warnings for address clause overlay
-O turn off warnings for address clause overlay
-.o turn on warnings for out parameters assigned but not read
-.O* turn off warnings for out parameters assigned but not read
-p turn on warnings for ineffective pragma Inline in frontend
-P* turn off warnings for ineffective pragma Inline in frontend
-q* turn on warnings for questionable missing parentheses
-Q turn off warnings for questionable missing parentheses
-r turn on warnings for redundant construct
-R* turn off warnings for redundant construct
-.r turn on warnings for object renaming function
-.R* turn off warnings for object renaming function
-s suppress all warnings
-t turn on warnings for tracking deleted code
-T* turn off warnings for tracking deleted code
-u turn on warnings for unused entity
-U* turn off warnings for unused entity
-v* turn on warnings for unassigned variable
-V turn off warnings for unassigned variable
-w* turn on warnings for wrong low bound assumption
-W turn off warnings for wrong low bound assumption
-x* turn on warnings for export/import
-X turn off warnings for export/import
-.x turn on warnings for non-local exceptions
-.X* turn off warnings for non-local exceptions
-y* turn on warnings for Ada 2005 incompatibility
-Y turn off warnings for Ada 2005 incompatibility
-z* turn on convention/size/align warnings for unchecked conversion
-Z turn off convention/size/align warnings for unchecked conversion
-* indicates default in above list
-@end smallexample
-
-@noindent
-The specified warnings will be in effect until the end of the program
-or another pragma Warnings is encountered. The effect of the pragma is
-cumulative. Initially the set of warnings is the standard default set
-as possibly modified by compiler switches. Then each pragma Warning
-modifies this set of warnings as specified. This form of the pragma may
-also be used as a configuration pragma.
-
-The fourth form, with an On|Off parameter and a string, is used to
-control individual messages, based on their text. The string argument
-is a pattern that is used to match against the text of individual
-warning messages (not including the initial "warnings: " tag).
-
-The pattern may contain asterisks which match zero or more characters in
-the message. For example, you can use
-@code{pragma Warnings (Off, "*bits of*unused")} to suppress the warning
-message @code{warning: 960 bits of "a" unused}. No other regular
-expression notations are permitted. All characters other than asterisk in
-these three specific cases are treated as literal characters in the match.
-
-There are two ways to use this pragma. The OFF form can be used as a
-configuration pragma. The effect is to suppress all warnings (if any)
-that match the pattern string throughout the compilation.
-
-The second usage is to suppress a warning locally, and in this case, two
-pragmas must appear in sequence:
-
-@smallexample @c ada
-pragma Warnings (Off, Pattern);
-@dots{} code where given warning is to be suppressed
-pragma Warnings (On, Pattern);
-@end smallexample
-
-@noindent
-In this usage, the pattern string must match in the Off and On pragmas,
-and at least one matching warning must be suppressed.
-
-@node Pragma Weak_External
-@unnumberedsec Pragma Weak_External
-@findex Weak_External
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Weak_External ([Entity =>] LOCAL_NAME);
-@end smallexample
-
-@noindent
-@var{LOCAL_NAME} must refer to an object that is declared at the library
-level. This pragma specifies that the given entity should be marked as a
-weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
-in GNU C and causes @var{LOCAL_NAME} to be emitted as a weak symbol instead
-of a regular symbol, that is to say a symbol that does not have to be
-resolved by the linker if used in conjunction with a pragma Import.
-
-When a weak symbol is not resolved by the linker, its address is set to
-zero. This is useful in writing interfaces to external modules that may
-or may not be linked in the final executable, for example depending on
-configuration settings.
-
-If a program references at run time an entity to which this pragma has been
-applied, and the corresponding symbol was not resolved at link time, then
-the execution of the program is erroneous. It is not erroneous to take the
-Address of such an entity, for example to guard potential references,
-as shown in the example below.
-
-Some file formats do not support weak symbols so not all target machines
-support this pragma.
-
-@smallexample @c ada
--- Example of the use of pragma Weak_External
-
-package External_Module is
- key : Integer;
- pragma Import (C, key);
- pragma Weak_External (key);
- function Present return boolean;
-end External_Module;
-
-with System; use System;
-package body External_Module is
- function Present return boolean is
- begin
- return key'Address /= System.Null_Address;
- end Present;
-end External_Module;
-@end smallexample
-
-@node Pragma Wide_Character_Encoding
-@unnumberedsec Pragma Wide_Character_Encoding
-@findex Wide_Character_Encoding
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
-@end smallexample
-
-@noindent
-This pragma specifies the wide character encoding to be used in program
-source text appearing subsequently. It is a configuration pragma, but may
-also be used at any point that a pragma is allowed, and it is permissible
-to have more than one such pragma in a file, allowing multiple encodings
-to appear within the same file.
-
-The argument can be an identifier or a character literal. In the identifier
-case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
-@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
-case it is correspondingly one of the characters @samp{h}, @samp{u},
-@samp{s}, @samp{e}, @samp{8}, or @samp{b}.
-
-Note that when the pragma is used within a file, it affects only the
-encoding within that file, and does not affect withed units, specs,
-or subunits.
-
-@node Implementation Defined Attributes
-@chapter Implementation Defined Attributes
-Ada defines (throughout the Ada reference manual,
-summarized in Annex K),
-a set of attributes that provide useful additional functionality in all
-areas of the language. These language defined attributes are implemented
-in GNAT and work as described in the Ada Reference Manual.
-
-In addition, Ada allows implementations to define additional
-attributes whose meaning is defined by the implementation. GNAT provides
-a number of these implementation-dependent attributes which can be used
-to extend and enhance the functionality of the compiler. This section of
-the GNAT reference manual describes these additional attributes.
-
-Note that any program using these attributes may not be portable to
-other compilers (although GNAT implements this set of attributes on all
-platforms). Therefore if portability to other compilers is an important
-consideration, you should minimize the use of these attributes.
-
-@menu
-* Abort_Signal::
-* Address_Size::
-* Asm_Input::
-* Asm_Output::
-* AST_Entry::
-* Bit::
-* Bit_Position::
-* Code_Address::
-* Default_Bit_Order::
-* Elaborated::
-* Elab_Body::
-* Elab_Spec::
-* Emax::
-* Enabled::
-* Enum_Rep::
-* Enum_Val::
-* Epsilon::
-* Fixed_Value::
-* Has_Access_Values::
-* Has_Discriminants::
-* Img::
-* Integer_Value::
-* Invalid_Value::
-* Large::
-* Machine_Size::
-* Mantissa::
-* Max_Interrupt_Priority::
-* Max_Priority::
-* Maximum_Alignment::
-* Mechanism_Code::
-* Null_Parameter::
-* Object_Size::
-* Old::
-* Passed_By_Reference::
-* Pool_Address::
-* Range_Length::
-* Safe_Emax::
-* Safe_Large::
-* Small::
-* Storage_Unit::
-* Stub_Type::
-* Target_Name::
-* Tick::
-* To_Address::
-* Type_Class::
-* UET_Address::
-* Unconstrained_Array::
-* Universal_Literal_String::
-* Unrestricted_Access::
-* VADS_Size::
-* Value_Size::
-* Wchar_T_Size::
-* Word_Size::
-@end menu
-
-@node Abort_Signal
-@unnumberedsec Abort_Signal
-@findex Abort_Signal
-@noindent
-@code{Standard'Abort_Signal} (@code{Standard} is the only allowed
-prefix) provides the entity for the special exception used to signal
-task abort or asynchronous transfer of control. Normally this attribute
-should only be used in the tasking runtime (it is highly peculiar, and
-completely outside the normal semantics of Ada, for a user program to
-intercept the abort exception).
-
-@node Address_Size
-@unnumberedsec Address_Size
-@cindex Size of @code{Address}
-@findex Address_Size
-@noindent
-@code{Standard'Address_Size} (@code{Standard} is the only allowed
-prefix) is a static constant giving the number of bits in an
-@code{Address}. It is the same value as System.Address'Size,
-but has the advantage of being static, while a direct
-reference to System.Address'Size is non-static because Address
-is a private type.
-
-@node Asm_Input
-@unnumberedsec Asm_Input
-@findex Asm_Input
-@noindent
-The @code{Asm_Input} attribute denotes a function that takes two
-parameters. The first is a string, the second is an expression of the
-type designated by the prefix. The first (string) argument is required
-to be a static expression, and is the constraint for the parameter,
-(e.g.@: what kind of register is required). The second argument is the
-value to be used as the input argument. The possible values for the
-constant are the same as those used in the RTL, and are dependent on
-the configuration file used to built the GCC back end.
-@ref{Machine Code Insertions}
-
-@node Asm_Output
-@unnumberedsec Asm_Output
-@findex Asm_Output
-@noindent
-The @code{Asm_Output} attribute denotes a function that takes two
-parameters. The first is a string, the second is the name of a variable
-of the type designated by the attribute prefix. The first (string)
-argument is required to be a static expression and designates the
-constraint for the parameter (e.g.@: what kind of register is
-required). The second argument is the variable to be updated with the
-result. The possible values for constraint are the same as those used in
-the RTL, and are dependent on the configuration file used to build the
-GCC back end. If there are no output operands, then this argument may
-either be omitted, or explicitly given as @code{No_Output_Operands}.
-@ref{Machine Code Insertions}
-
-@node AST_Entry
-@unnumberedsec AST_Entry
-@cindex OpenVMS
-@findex AST_Entry
-@noindent
-This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
-the name of an entry, it yields a value of the predefined type AST_Handler
-(declared in the predefined package System, as extended by the use of
-pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
-be called when an AST occurs. For further details, refer to the @cite{DEC Ada
-Language Reference Manual}, section 9.12a.
-
-@node Bit
-@unnumberedsec Bit
-@findex Bit
-@code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
-offset within the storage unit (byte) that contains the first bit of
-storage allocated for the object. The value of this attribute is of the
-type @code{Universal_Integer}, and is always a non-negative number not
-exceeding the value of @code{System.Storage_Unit}.
-
-For an object that is a variable or a constant allocated in a register,
-the value is zero. (The use of this attribute does not force the
-allocation of a variable to memory).
-
-For an object that is a formal parameter, this attribute applies
-to either the matching actual parameter or to a copy of the
-matching actual parameter.
-
-For an access object the value is zero. Note that
-@code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
-designated object. Similarly for a record component
-@code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
-@code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
-are subject to index checks.
-
-This attribute is designed to be compatible with the DEC Ada 83 definition
-and implementation of the @code{Bit} attribute.
-
-@node Bit_Position
-@unnumberedsec Bit_Position
-@findex Bit_Position
-@noindent
-@code{@var{R.C}'Bit}, where @var{R} is a record object and C is one
-of the fields of the record type, yields the bit
-offset within the record contains the first bit of
-storage allocated for the object. The value of this attribute is of the
-type @code{Universal_Integer}. The value depends only on the field
-@var{C} and is independent of the alignment of
-the containing record @var{R}.
-
-@node Code_Address
-@unnumberedsec Code_Address
-@findex Code_Address
-@cindex Subprogram address
-@cindex Address of subprogram code
-@noindent
-The @code{'Address}
-attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
-intended effect seems to be to provide
-an address value which can be used to call the subprogram by means of
-an address clause as in the following example:
-
-@smallexample @c ada
-procedure K is @dots{}
-
-procedure L;
-for L'Address use K'Address;
-pragma Import (Ada, L);
-@end smallexample
-
-@noindent
-A call to @code{L} is then expected to result in a call to @code{K}@.
-In Ada 83, where there were no access-to-subprogram values, this was
-a common work-around for getting the effect of an indirect call.
-GNAT implements the above use of @code{Address} and the technique
-illustrated by the example code works correctly.
-
-However, for some purposes, it is useful to have the address of the start
-of the generated code for the subprogram. On some architectures, this is
-not necessarily the same as the @code{Address} value described above.
-For example, the @code{Address} value may reference a subprogram
-descriptor rather than the subprogram itself.
-
-The @code{'Code_Address} attribute, which can only be applied to
-subprogram entities, always returns the address of the start of the
-generated code of the specified subprogram, which may or may not be
-the same value as is returned by the corresponding @code{'Address}
-attribute.
-
-@node Default_Bit_Order
-@unnumberedsec Default_Bit_Order
-@cindex Big endian
-@cindex Little endian
-@findex Default_Bit_Order
-@noindent
-@code{Standard'Default_Bit_Order} (@code{Standard} is the only
-permissible prefix), provides the value @code{System.Default_Bit_Order}
-as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
-@code{Low_Order_First}). This is used to construct the definition of
-@code{Default_Bit_Order} in package @code{System}.
-
-@node Elaborated
-@unnumberedsec Elaborated
-@findex Elaborated
-@noindent
-The prefix of the @code{'Elaborated} attribute must be a unit name. The
-value is a Boolean which indicates whether or not the given unit has been
-elaborated. This attribute is primarily intended for internal use by the
-generated code for dynamic elaboration checking, but it can also be used
-in user programs. The value will always be True once elaboration of all
-units has been completed. An exception is for units which need no
-elaboration, the value is always False for such units.
-
-@node Elab_Body
-@unnumberedsec Elab_Body
-@findex Elab_Body
-@noindent
-This attribute can only be applied to a program unit name. It returns
-the entity for the corresponding elaboration procedure for elaborating
-the body of the referenced unit. This is used in the main generated
-elaboration procedure by the binder and is not normally used in any
-other context. However, there may be specialized situations in which it
-is useful to be able to call this elaboration procedure from Ada code,
-e.g.@: if it is necessary to do selective re-elaboration to fix some
-error.
-
-@node Elab_Spec
-@unnumberedsec Elab_Spec
-@findex Elab_Spec
-@noindent
-This attribute can only be applied to a program unit name. It returns
-the entity for the corresponding elaboration procedure for elaborating
-the spec of the referenced unit. This is used in the main
-generated elaboration procedure by the binder and is not normally used
-in any other context. However, there may be specialized situations in
-which it is useful to be able to call this elaboration procedure from
-Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
-some error.
-
-@node Emax
-@unnumberedsec Emax
-@cindex Ada 83 attributes
-@findex Emax
-@noindent
-The @code{Emax} attribute is provided for compatibility with Ada 83. See
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute.
-
-@node Enabled
-@unnumberedsec Enabled
-@findex Enabled
-@noindent
-The @code{Enabled} attribute allows an application program to check at compile
-time to see if the designated check is currently enabled. The prefix is a
-simple identifier, referencing any predefined check name (other than
-@code{All_Checks}) or a check name introduced by pragma Check_Name. If
-no argument is given for the attribute, the check is for the general state
-of the check, if an argument is given, then it is an entity name, and the
-check indicates whether an @code{Suppress} or @code{Unsuppress} has been
-given naming the entity (if not, then the argument is ignored).
-
-Note that instantiations inherit the check status at the point of the
-instantiation, so a useful idiom is to have a library package that
-introduces a check name with @code{pragma Check_Name}, and then contains
-generic packages or subprograms which use the @code{Enabled} attribute
-to see if the check is enabled. A user of this package can then issue
-a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
-the package or subprogram, controlling whether the check will be present.
-
-@node Enum_Rep
-@unnumberedsec Enum_Rep
-@cindex Representation of enums
-@findex Enum_Rep
-@noindent
-For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
-function with the following spec:
-
-@smallexample @c ada
-function @var{S}'Enum_Rep (Arg : @var{S}'Base)
- return @i{Universal_Integer};
-@end smallexample
-
-@noindent
-It is also allowable to apply @code{Enum_Rep} directly to an object of an
-enumeration type or to a non-overloaded enumeration
-literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
-@code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
-enumeration literal or object.
-
-The function returns the representation value for the given enumeration
-value. This will be equal to value of the @code{Pos} attribute in the
-absence of an enumeration representation clause. This is a static
-attribute (i.e.@: the result is static if the argument is static).
-
-@code{@var{S}'Enum_Rep} can also be used with integer types and objects,
-in which case it simply returns the integer value. The reason for this
-is to allow it to be used for @code{(<>)} discrete formal arguments in
-a generic unit that can be instantiated with either enumeration types
-or integer types. Note that if @code{Enum_Rep} is used on a modular
-type whose upper bound exceeds the upper bound of the largest signed
-integer type, and the argument is a variable, so that the universal
-integer calculation is done at run time, then the call to @code{Enum_Rep}
-may raise @code{Constraint_Error}.
-
-@node Enum_Val
-@unnumberedsec Enum_Val
-@cindex Representation of enums
-@findex Enum_Val
-@noindent
-For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
-function with the following spec:
-
-@smallexample @c ada
-function @var{S}'Enum_Rep (Arg : @i{Universal_Integer)
- return @var{S}'Base};
-@end smallexample
-
-@noindent
-The function returns the enumeration value whose representation matches the
-argument, or raises Constraint_Error if no enumeration literal of the type
-has the matching value.
-This will be equal to value of the @code{Val} attribute in the
-absence of an enumeration representation clause. This is a static
-attribute (i.e.@: the result is static if the argument is static).
-
-@node Epsilon
-@unnumberedsec Epsilon
-@cindex Ada 83 attributes
-@findex Epsilon
-@noindent
-The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute.
-
-@node Fixed_Value
-@unnumberedsec Fixed_Value
-@findex Fixed_Value
-@noindent
-For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
-function with the following specification:
-
-@smallexample @c ada
-function @var{S}'Fixed_Value (Arg : @i{Universal_Integer})
- return @var{S};
-@end smallexample
-
-@noindent
-The value returned is the fixed-point value @var{V} such that
-
-@smallexample @c ada
-@var{V} = Arg * @var{S}'Small
-@end smallexample
-
-@noindent
-The effect is thus similar to first converting the argument to the
-integer type used to represent @var{S}, and then doing an unchecked
-conversion to the fixed-point type. The difference is
-that there are full range checks, to ensure that the result is in range.
-This attribute is primarily intended for use in implementation of the
-input-output functions for fixed-point values.
-
-@node Has_Access_Values
-@unnumberedsec Has_Access_Values
-@cindex Access values, testing for
-@findex Has_Access_Values
-@noindent
-The prefix of the @code{Has_Access_Values} attribute is a type. The result
-is a Boolean value which is True if the is an access type, or is a composite
-type with a component (at any nesting depth) that is an access type, and is
-False otherwise.
-The intended use of this attribute is in conjunction with generic
-definitions. If the attribute is applied to a generic private type, it
-indicates whether or not the corresponding actual type has access values.
-
-@node Has_Discriminants
-@unnumberedsec Has_Discriminants
-@cindex Discriminants, testing for
-@findex Has_Discriminants
-@noindent
-The prefix of the @code{Has_Discriminants} attribute is a type. The result
-is a Boolean value which is True if the type has discriminants, and False
-otherwise. The intended use of this attribute is in conjunction with generic
-definitions. If the attribute is applied to a generic private type, it
-indicates whether or not the corresponding actual type has discriminants.
-
-@node Img
-@unnumberedsec Img
-@findex Img
-@noindent
-The @code{Img} attribute differs from @code{Image} in that it may be
-applied to objects as well as types, in which case it gives the
-@code{Image} for the subtype of the object. This is convenient for
-debugging:
-
-@smallexample @c ada
-Put_Line ("X = " & X'Img);
-@end smallexample
-
-@noindent
-has the same meaning as the more verbose:
-
-@smallexample @c ada
-Put_Line ("X = " & @var{T}'Image (X));
-@end smallexample
-
-@noindent
-where @var{T} is the (sub)type of the object @code{X}.
-
-@node Integer_Value
-@unnumberedsec Integer_Value
-@findex Integer_Value
-@noindent
-For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
-function with the following spec:
-
-@smallexample @c ada
-function @var{S}'Integer_Value (Arg : @i{Universal_Fixed})
- return @var{S};
-@end smallexample
-
-@noindent
-The value returned is the integer value @var{V}, such that
-
-@smallexample @c ada
-Arg = @var{V} * @var{T}'Small
-@end smallexample
-
-@noindent
-where @var{T} is the type of @code{Arg}.
-The effect is thus similar to first doing an unchecked conversion from
-the fixed-point type to its corresponding implementation type, and then
-converting the result to the target integer type. The difference is
-that there are full range checks, to ensure that the result is in range.
-This attribute is primarily intended for use in implementation of the
-standard input-output functions for fixed-point values.
-
-@node Invalid_Value
-@unnumberedsec Invalid_Value
-@findex Invalid_Value
-@noindent
-For every scalar type S, S'Invalid_Value returns an undefined value of the
-type. If possible this value is an invalid representation for the type. The
-value returned is identical to the value used to initialize an otherwise
-uninitialized value of the type if pragma Initialize_Scalars is used,
-including the ability to modify the value with the binder -Sxx flag and
-relevant environment variables at run time.
-
-@node Large
-@unnumberedsec Large
-@cindex Ada 83 attributes
-@findex Large
-@noindent
-The @code{Large} attribute is provided for compatibility with Ada 83. See
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute.
-
-@node Machine_Size
-@unnumberedsec Machine_Size
-@findex Machine_Size
-@noindent
-This attribute is identical to the @code{Object_Size} attribute. It is
-provided for compatibility with the DEC Ada 83 attribute of this name.
-
-@node Mantissa
-@unnumberedsec Mantissa
-@cindex Ada 83 attributes
-@findex Mantissa
-@noindent
-The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute.
-
-@node Max_Interrupt_Priority
-@unnumberedsec Max_Interrupt_Priority
-@cindex Interrupt priority, maximum
-@findex Max_Interrupt_Priority
-@noindent
-@code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
-permissible prefix), provides the same value as
-@code{System.Max_Interrupt_Priority}.
-
-@node Max_Priority
-@unnumberedsec Max_Priority
-@cindex Priority, maximum
-@findex Max_Priority
-@noindent
-@code{Standard'Max_Priority} (@code{Standard} is the only permissible
-prefix) provides the same value as @code{System.Max_Priority}.
-
-@node Maximum_Alignment
-@unnumberedsec Maximum_Alignment
-@cindex Alignment, maximum
-@findex Maximum_Alignment
-@noindent
-@code{Standard'Maximum_Alignment} (@code{Standard} is the only
-permissible prefix) provides the maximum useful alignment value for the
-target. This is a static value that can be used to specify the alignment
-for an object, guaranteeing that it is properly aligned in all
-cases.
-
-@node Mechanism_Code
-@unnumberedsec Mechanism_Code
-@cindex Return values, passing mechanism
-@cindex Parameters, passing mechanism
-@findex Mechanism_Code
-@noindent
-@code{@var{function}'Mechanism_Code} yields an integer code for the
-mechanism used for the result of function, and
-@code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
-used for formal parameter number @var{n} (a static integer value with 1
-meaning the first parameter) of @var{subprogram}. The code returned is:
-
-@table @asis
-@item 1
-by copy (value)
-@item 2
-by reference
-@item 3
-by descriptor (default descriptor class)
-@item 4
-by descriptor (UBS: unaligned bit string)
-@item 5
-by descriptor (UBSB: aligned bit string with arbitrary bounds)
-@item 6
-by descriptor (UBA: unaligned bit array)
-@item 7
-by descriptor (S: string, also scalar access type parameter)
-@item 8
-by descriptor (SB: string with arbitrary bounds)
-@item 9
-by descriptor (A: contiguous array)
-@item 10
-by descriptor (NCA: non-contiguous array)
-@end table
-
-@noindent
-Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
-@cindex OpenVMS
-
-@node Null_Parameter
-@unnumberedsec Null_Parameter
-@cindex Zero address, passing
-@findex Null_Parameter
-@noindent
-A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
-type or subtype @var{T} allocated at machine address zero. The attribute
-is allowed only as the default expression of a formal parameter, or as
-an actual expression of a subprogram call. In either case, the
-subprogram must be imported.
-
-The identity of the object is represented by the address zero in the
-argument list, independent of the passing mechanism (explicit or
-default).
-
-This capability is needed to specify that a zero address should be
-passed for a record or other composite object passed by reference.
-There is no way of indicating this without the @code{Null_Parameter}
-attribute.
-
-@node Object_Size
-@unnumberedsec Object_Size
-@cindex Size, used for objects
-@findex Object_Size
-@noindent
-The size of an object is not necessarily the same as the size of the type
-of an object. This is because by default object sizes are increased to be
-a multiple of the alignment of the object. For example,
-@code{Natural'Size} is
-31, but by default objects of type @code{Natural} will have a size of 32 bits.
-Similarly, a record containing an integer and a character:
-
-@smallexample @c ada
-type Rec is record
- I : Integer;
- C : Character;
-end record;
-@end smallexample
-
-@noindent
-will have a size of 40 (that is @code{Rec'Size} will be 40. The
-alignment will be 4, because of the
-integer field, and so the default size of record objects for this type
-will be 64 (8 bytes).
-
-@node Old
-@unnumberedsec Old
-@cindex Capturing Old values
-@cindex Postconditions
-@noindent
-The attribute Prefix'Old can be used within a
-subprogram to refer to the value of the prefix on entry. So for
-example if you have an argument of a record type X called Arg1,
-you can refer to Arg1.Field'Old which yields the value of
-Arg1.Field on entry. The implementation simply involves generating
-an object declaration which captures the value on entry. Any
-prefix is allowed except one of a limited type (since limited
-types cannot be copied to capture their values) or a local variable
-(since it does not exist at subprogram entry time).
-
-The following example shows the use of 'Old to implement
-a test of a postcondition:
-
-@smallexample @c ada
-with Old_Pkg;
-procedure Old is
-begin
- Old_Pkg.Incr;
-end Old;
-
-package Old_Pkg is
- procedure Incr;
-end Old_Pkg;
-
-package body Old_Pkg is
- Count : Natural := 0;
-
- procedure Incr is
- begin
- ... code manipulating the value of Count
-
- pragma Assert (Count = Count'Old + 1);
- end Incr;
-end Old_Pkg;
-@end smallexample
-
-@noindent
-Note that it is allowed to apply 'Old to a constant entity, but this will
-result in a warning, since the old and new values will always be the same.
-
-@node Passed_By_Reference
-@unnumberedsec Passed_By_Reference
-@cindex Parameters, when passed by reference
-@findex Passed_By_Reference
-@noindent
-@code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
-a value of type @code{Boolean} value that is @code{True} if the type is
-normally passed by reference and @code{False} if the type is normally
-passed by copy in calls. For scalar types, the result is always @code{False}
-and is static. For non-scalar types, the result is non-static.
-
-@node Pool_Address
-@unnumberedsec Pool_Address
-@cindex Parameters, when passed by reference
-@findex Pool_Address
-@noindent
-@code{@var{X}'Pool_Address} for any object @var{X} returns the address
-of X within its storage pool. This is the same as
-@code{@var{X}'Address}, except that for an unconstrained array whose
-bounds are allocated just before the first component,
-@code{@var{X}'Pool_Address} returns the address of those bounds,
-whereas @code{@var{X}'Address} returns the address of the first
-component.
-
-Here, we are interpreting ``storage pool'' broadly to mean ``wherever
-the object is allocated'', which could be a user-defined storage pool,
-the global heap, on the stack, or in a static memory area. For an
-object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is
-what is passed to @code{Allocate} and returned from @code{Deallocate}.
-
-@node Range_Length
-@unnumberedsec Range_Length
-@findex Range_Length
-@noindent
-@code{@var{type}'Range_Length} for any discrete type @var{type} yields
-the number of values represented by the subtype (zero for a null
-range). The result is static for static subtypes. @code{Range_Length}
-applied to the index subtype of a one dimensional array always gives the
-same result as @code{Range} applied to the array itself.
-
-@node Safe_Emax
-@unnumberedsec Safe_Emax
-@cindex Ada 83 attributes
-@findex Safe_Emax
-@noindent
-The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute.
-
-@node Safe_Large
-@unnumberedsec Safe_Large
-@cindex Ada 83 attributes
-@findex Safe_Large
-@noindent
-The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute.
-
-@node Small
-@unnumberedsec Small
-@cindex Ada 83 attributes
-@findex Small
-@noindent
-The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
-fixed-point types.
-GNAT also allows this attribute to be applied to floating-point types
-for compatibility with Ada 83. See
-the Ada 83 reference manual for an exact description of the semantics of
-this attribute when applied to floating-point types.
-
-@node Storage_Unit
-@unnumberedsec Storage_Unit
-@findex Storage_Unit
-@noindent
-@code{Standard'Storage_Unit} (@code{Standard} is the only permissible
-prefix) provides the same value as @code{System.Storage_Unit}.
-
-@node Stub_Type
-@unnumberedsec Stub_Type
-@findex Stub_Type
-@noindent
-The GNAT implementation of remote access-to-classwide types is
-organized as described in AARM section E.4 (20.t): a value of an RACW type
-(designating a remote object) is represented as a normal access
-value, pointing to a "stub" object which in turn contains the
-necessary information to contact the designated remote object. A
-call on any dispatching operation of such a stub object does the
-remote call, if necessary, using the information in the stub object
-to locate the target partition, etc.
-
-For a prefix @code{T} that denotes a remote access-to-classwide type,
-@code{T'Stub_Type} denotes the type of the corresponding stub objects.
-
-By construction, the layout of @code{T'Stub_Type} is identical to that of
-type @code{RACW_Stub_Type} declared in the internal implementation-defined
-unit @code{System.Partition_Interface}. Use of this attribute will create
-an implicit dependency on this unit.
-
-@node Target_Name
-@unnumberedsec Target_Name
-@findex Target_Name
-@noindent
-@code{Standard'Target_Name} (@code{Standard} is the only permissible
-prefix) provides a static string value that identifies the target
-for the current compilation. For GCC implementations, this is the
-standard gcc target name without the terminating slash (for
-example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
-
-@node Tick
-@unnumberedsec Tick
-@findex Tick
-@noindent
-@code{Standard'Tick} (@code{Standard} is the only permissible prefix)
-provides the same value as @code{System.Tick},
-
-@node To_Address
-@unnumberedsec To_Address
-@findex To_Address
-@noindent
-The @code{System'To_Address}
-(@code{System} is the only permissible prefix)
-denotes a function identical to
-@code{System.Storage_Elements.To_Address} except that
-it is a static attribute. This means that if its argument is
-a static expression, then the result of the attribute is a
-static expression. The result is that such an expression can be
-used in contexts (e.g.@: preelaborable packages) which require a
-static expression and where the function call could not be used
-(since the function call is always non-static, even if its
-argument is static).
-
-@node Type_Class
-@unnumberedsec Type_Class
-@findex Type_Class
-@noindent
-@code{@var{type}'Type_Class} for any type or subtype @var{type} yields
-the value of the type class for the full type of @var{type}. If
-@var{type} is a generic formal type, the value is the value for the
-corresponding actual subtype. The value of this attribute is of type
-@code{System.Aux_DEC.Type_Class}, which has the following definition:
-
-@smallexample @c ada
- type Type_Class is
- (Type_Class_Enumeration,
- Type_Class_Integer,
- Type_Class_Fixed_Point,
- Type_Class_Floating_Point,
- Type_Class_Array,
- Type_Class_Record,
- Type_Class_Access,
- Type_Class_Task,
- Type_Class_Address);
-@end smallexample
-
-@noindent
-Protected types yield the value @code{Type_Class_Task}, which thus
-applies to all concurrent types. This attribute is designed to
-be compatible with the DEC Ada 83 attribute of the same name.
-
-@node UET_Address
-@unnumberedsec UET_Address
-@findex UET_Address
-@noindent
-The @code{UET_Address} attribute can only be used for a prefix which
-denotes a library package. It yields the address of the unit exception
-table when zero cost exception handling is used. This attribute is
-intended only for use within the GNAT implementation. See the unit
-@code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
-for details on how this attribute is used in the implementation.
-
-@node Unconstrained_Array
-@unnumberedsec Unconstrained_Array
-@findex Unconstrained_Array
-@noindent
-The @code{Unconstrained_Array} attribute can be used with a prefix that
-denotes any type or subtype. It is a static attribute that yields
-@code{True} if the prefix designates an unconstrained array,
-and @code{False} otherwise. In a generic instance, the result is
-still static, and yields the result of applying this test to the
-generic actual.
-
-@node Universal_Literal_String
-@unnumberedsec Universal_Literal_String
-@cindex Named numbers, representation of
-@findex Universal_Literal_String
-@noindent
-The prefix of @code{Universal_Literal_String} must be a named
-number. The static result is the string consisting of the characters of
-the number as defined in the original source. This allows the user
-program to access the actual text of named numbers without intermediate
-conversions and without the need to enclose the strings in quotes (which
-would preclude their use as numbers). This is used internally for the
-construction of values of the floating-point attributes from the file
-@file{ttypef.ads}, but may also be used by user programs.
-
-For example, the following program prints the first 50 digits of pi:
-
-@smallexample @c ada
-with Text_IO; use Text_IO;
-with Ada.Numerics;
-procedure Pi is
-begin
- Put (Ada.Numerics.Pi'Universal_Literal_String);
-end;
-@end smallexample
-
-@node Unrestricted_Access
-@unnumberedsec Unrestricted_Access
-@cindex @code{Access}, unrestricted
-@findex Unrestricted_Access
-@noindent
-The @code{Unrestricted_Access} attribute is similar to @code{Access}
-except that all accessibility and aliased view checks are omitted. This
-is a user-beware attribute. It is similar to
-@code{Address}, for which it is a desirable replacement where the value
-desired is an access type. In other words, its effect is identical to
-first applying the @code{Address} attribute and then doing an unchecked
-conversion to a desired access type. In GNAT, but not necessarily in
-other implementations, the use of static chains for inner level
-subprograms means that @code{Unrestricted_Access} applied to a
-subprogram yields a value that can be called as long as the subprogram
-is in scope (normal Ada accessibility rules restrict this usage).
-
-It is possible to use @code{Unrestricted_Access} for any type, but care
-must be exercised if it is used to create pointers to unconstrained
-objects. In this case, the resulting pointer has the same scope as the
-context of the attribute, and may not be returned to some enclosing
-scope. For instance, a function cannot use @code{Unrestricted_Access}
-to create a unconstrained pointer and then return that value to the
-caller.
-
-@node VADS_Size
-@unnumberedsec VADS_Size
-@cindex @code{Size}, VADS compatibility
-@findex VADS_Size
-@noindent
-The @code{'VADS_Size} attribute is intended to make it easier to port
-legacy code which relies on the semantics of @code{'Size} as implemented
-by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
-same semantic interpretation. In particular, @code{'VADS_Size} applied
-to a predefined or other primitive type with no Size clause yields the
-Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
-typical machines). In addition @code{'VADS_Size} applied to an object
-gives the result that would be obtained by applying the attribute to
-the corresponding type.
-
-@node Value_Size
-@unnumberedsec Value_Size
-@cindex @code{Size}, setting for not-first subtype
-@findex Value_Size
-@code{@var{type}'Value_Size} is the number of bits required to represent
-a value of the given subtype. It is the same as @code{@var{type}'Size},
-but, unlike @code{Size}, may be set for non-first subtypes.
-
-@node Wchar_T_Size
-@unnumberedsec Wchar_T_Size
-@findex Wchar_T_Size
-@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
-prefix) provides the size in bits of the C @code{wchar_t} type
-primarily for constructing the definition of this type in
-package @code{Interfaces.C}.
-
-@node Word_Size
-@unnumberedsec Word_Size
-@findex Word_Size
-@code{Standard'Word_Size} (@code{Standard} is the only permissible
-prefix) provides the value @code{System.Word_Size}.
-
-@c ------------------------
-@node Implementation Advice
-@chapter Implementation Advice
-@noindent
-The main text of the Ada Reference Manual describes the required
-behavior of all Ada compilers, and the GNAT compiler conforms to
-these requirements.
-
-In addition, there are sections throughout the Ada Reference Manual headed
-by the phrase ``Implementation advice''. These sections are not normative,
-i.e., they do not specify requirements that all compilers must
-follow. Rather they provide advice on generally desirable behavior. You
-may wonder why they are not requirements. The most typical answer is
-that they describe behavior that seems generally desirable, but cannot
-be provided on all systems, or which may be undesirable on some systems.
-
-As far as practical, GNAT follows the implementation advice sections in
-the Ada Reference Manual. This chapter contains a table giving the
-reference manual section number, paragraph number and several keywords
-for each advice. Each entry consists of the text of the advice followed
-by the GNAT interpretation of this advice. Most often, this simply says
-``followed'', which means that GNAT follows the advice. However, in a
-number of cases, GNAT deliberately deviates from this advice, in which
-case the text describes what GNAT does and why.
-
-@cindex Error detection
-@unnumberedsec 1.1.3(20): Error Detection
-@sp 1
-@cartouche
-If an implementation detects the use of an unsupported Specialized Needs
-Annex feature at run time, it should raise @code{Program_Error} if
-feasible.
-@end cartouche
-Not relevant. All specialized needs annex features are either supported,
-or diagnosed at compile time.
-
-@cindex Child Units
-@unnumberedsec 1.1.3(31): Child Units
-@sp 1
-@cartouche
-If an implementation wishes to provide implementation-defined
-extensions to the functionality of a language-defined library unit, it
-should normally do so by adding children to the library unit.
-@end cartouche
-Followed.
-
-@cindex Bounded errors
-@unnumberedsec 1.1.5(12): Bounded Errors
-@sp 1
-@cartouche
-If an implementation detects a bounded error or erroneous
-execution, it should raise @code{Program_Error}.
-@end cartouche
-Followed in all cases in which the implementation detects a bounded
-error or erroneous execution. Not all such situations are detected at
-runtime.
-
-@cindex Pragmas
-@unnumberedsec 2.8(16): Pragmas
-@sp 1
-@cartouche
-Normally, implementation-defined pragmas should have no semantic effect
-for error-free programs; that is, if the implementation-defined pragmas
-are removed from a working program, the program should still be legal,
-and should still have the same semantics.
-@end cartouche
-The following implementation defined pragmas are exceptions to this
-rule:
-
-@table @code
-@item Abort_Defer
-Affects semantics
-@item Ada_83
-Affects legality
-@item Assert
-Affects semantics
-@item CPP_Class
-Affects semantics
-@item CPP_Constructor
-Affects semantics
-@item Debug
-Affects semantics
-@item Interface_Name
-Affects semantics
-@item Machine_Attribute
-Affects semantics
-@item Unimplemented_Unit
-Affects legality
-@item Unchecked_Union
-Affects semantics
-@end table
-
-@noindent
-In each of the above cases, it is essential to the purpose of the pragma
-that this advice not be followed. For details see the separate section
-on implementation defined pragmas.
-
-@unnumberedsec 2.8(17-19): Pragmas
-@sp 1
-@cartouche
-Normally, an implementation should not define pragmas that can
-make an illegal program legal, except as follows:
-@end cartouche
-@sp 1
-@cartouche
-A pragma used to complete a declaration, such as a pragma @code{Import};
-@end cartouche
-@sp 1
-@cartouche
-A pragma used to configure the environment by adding, removing, or
-replacing @code{library_items}.
-@end cartouche
-See response to paragraph 16 of this same section.
-
-@cindex Character Sets
-@cindex Alternative Character Sets
-@unnumberedsec 3.5.2(5): Alternative Character Sets
-@sp 1
-@cartouche
-If an implementation supports a mode with alternative interpretations
-for @code{Character} and @code{Wide_Character}, the set of graphic
-characters of @code{Character} should nevertheless remain a proper
-subset of the set of graphic characters of @code{Wide_Character}. Any
-character set ``localizations'' should be reflected in the results of
-the subprograms defined in the language-defined package
-@code{Characters.Handling} (see A.3) available in such a mode. In a mode with
-an alternative interpretation of @code{Character}, the implementation should
-also support a corresponding change in what is a legal
-@code{identifier_letter}.
-@end cartouche
-Not all wide character modes follow this advice, in particular the JIS
-and IEC modes reflect standard usage in Japan, and in these encoding,
-the upper half of the Latin-1 set is not part of the wide-character
-subset, since the most significant bit is used for wide character
-encoding. However, this only applies to the external forms. Internally
-there is no such restriction.
-
-@cindex Integer types
-@unnumberedsec 3.5.4(28): Integer Types
-
-@sp 1
-@cartouche
-An implementation should support @code{Long_Integer} in addition to
-@code{Integer} if the target machine supports 32-bit (or longer)
-arithmetic. No other named integer subtypes are recommended for package
-@code{Standard}. Instead, appropriate named integer subtypes should be
-provided in the library package @code{Interfaces} (see B.2).
-@end cartouche
-@code{Long_Integer} is supported. Other standard integer types are supported
-so this advice is not fully followed. These types
-are supported for convenient interface to C, and so that all hardware
-types of the machine are easily available.
-@unnumberedsec 3.5.4(29): Integer Types
-
-@sp 1
-@cartouche
-An implementation for a two's complement machine should support
-modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
-implementation should support a non-binary modules up to @code{Integer'Last}.
-@end cartouche
-Followed.
-
-@cindex Enumeration values
-@unnumberedsec 3.5.5(8): Enumeration Values
-@sp 1
-@cartouche
-For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
-subtype, if the value of the operand does not correspond to the internal
-code for any enumeration literal of its type (perhaps due to an
-un-initialized variable), then the implementation should raise
-@code{Program_Error}. This is particularly important for enumeration
-types with noncontiguous internal codes specified by an
-enumeration_representation_clause.
-@end cartouche
-Followed.
-
-@cindex Float types
-@unnumberedsec 3.5.7(17): Float Types
-@sp 1
-@cartouche
-An implementation should support @code{Long_Float} in addition to
-@code{Float} if the target machine supports 11 or more digits of
-precision. No other named floating point subtypes are recommended for
-package @code{Standard}. Instead, appropriate named floating point subtypes
-should be provided in the library package @code{Interfaces} (see B.2).
-@end cartouche
-@code{Short_Float} and @code{Long_Long_Float} are also provided. The
-former provides improved compatibility with other implementations
-supporting this type. The latter corresponds to the highest precision
-floating-point type supported by the hardware. On most machines, this
-will be the same as @code{Long_Float}, but on some machines, it will
-correspond to the IEEE extended form. The notable case is all ia32
-(x86) implementations, where @code{Long_Long_Float} corresponds to
-the 80-bit extended precision format supported in hardware on this
-processor. Note that the 128-bit format on SPARC is not supported,
-since this is a software rather than a hardware format.
-
-@cindex Multidimensional arrays
-@cindex Arrays, multidimensional
-@unnumberedsec 3.6.2(11): Multidimensional Arrays
-@sp 1
-@cartouche
-An implementation should normally represent multidimensional arrays in
-row-major order, consistent with the notation used for multidimensional
-array aggregates (see 4.3.3). However, if a pragma @code{Convention}
-(@code{Fortran}, @dots{}) applies to a multidimensional array type, then
-column-major order should be used instead (see B.5, ``Interfacing with
-Fortran'').
-@end cartouche
-Followed.
-
-@findex Duration'Small
-@unnumberedsec 9.6(30-31): Duration'Small
-@sp 1
-@cartouche
-Whenever possible in an implementation, the value of @code{Duration'Small}
-should be no greater than 100 microseconds.
-@end cartouche
-Followed. (@code{Duration'Small} = 10**(@minus{}9)).
-
-@sp 1
-@cartouche
-The time base for @code{delay_relative_statements} should be monotonic;
-it need not be the same time base as used for @code{Calendar.Clock}.
-@end cartouche
-Followed.
-
-@unnumberedsec 10.2.1(12): Consistent Representation
-@sp 1
-@cartouche
-In an implementation, a type declared in a pre-elaborated package should
-have the same representation in every elaboration of a given version of
-the package, whether the elaborations occur in distinct executions of
-the same program, or in executions of distinct programs or partitions
-that include the given version.
-@end cartouche
-Followed, except in the case of tagged types. Tagged types involve
-implicit pointers to a local copy of a dispatch table, and these pointers
-have representations which thus depend on a particular elaboration of the
-package. It is not easy to see how it would be possible to follow this
-advice without severely impacting efficiency of execution.
-
-@cindex Exception information
-@unnumberedsec 11.4.1(19): Exception Information
-@sp 1
-@cartouche
-@code{Exception_Message} by default and @code{Exception_Information}
-should produce information useful for
-debugging. @code{Exception_Message} should be short, about one
-line. @code{Exception_Information} can be long. @code{Exception_Message}
-should not include the
-@code{Exception_Name}. @code{Exception_Information} should include both
-the @code{Exception_Name} and the @code{Exception_Message}.
-@end cartouche
-Followed. For each exception that doesn't have a specified
-@code{Exception_Message}, the compiler generates one containing the location
-of the raise statement. This location has the form ``file:line'', where
-file is the short file name (without path information) and line is the line
-number in the file. Note that in the case of the Zero Cost Exception
-mechanism, these messages become redundant with the Exception_Information that
-contains a full backtrace of the calling sequence, so they are disabled.
-To disable explicitly the generation of the source location message, use the
-Pragma @code{Discard_Names}.
-
-@cindex Suppression of checks
-@cindex Checks, suppression of
-@unnumberedsec 11.5(28): Suppression of Checks
-@sp 1
-@cartouche
-The implementation should minimize the code executed for checks that
-have been suppressed.
-@end cartouche
-Followed.
-
-@cindex Representation clauses
-@unnumberedsec 13.1 (21-24): Representation Clauses
-@sp 1
-@cartouche
-The recommended level of support for all representation items is
-qualified as follows:
-@end cartouche
-@sp 1
-@cartouche
-An implementation need not support representation items containing
-non-static expressions, except that an implementation should support a
-representation item for a given entity if each non-static expression in
-the representation item is a name that statically denotes a constant
-declared before the entity.
-@end cartouche
-Followed. In fact, GNAT goes beyond the recommended level of support
-by allowing nonstatic expressions in some representation clauses even
-without the need to declare constants initialized with the values of
-such expressions.
-For example:
-
-@smallexample @c ada
- X : Integer;
- Y : Float;
- for Y'Address use X'Address;>>
-@end smallexample
-
-
-@sp 1
-@cartouche
-An implementation need not support a specification for the @code{Size}
-for a given composite subtype, nor the size or storage place for an
-object (including a component) of a given composite subtype, unless the
-constraints on the subtype and its composite subcomponents (if any) are
-all static constraints.
-@end cartouche
-Followed. Size Clauses are not permitted on non-static components, as
-described above.
-
-@sp 1
-@cartouche
-An aliased component, or a component whose type is by-reference, should
-always be allocated at an addressable location.
-@end cartouche
-Followed.
-
-@cindex Packed types
-@unnumberedsec 13.2(6-8): Packed Types
-@sp 1
-@cartouche
-If a type is packed, then the implementation should try to minimize
-storage allocated to objects of the type, possibly at the expense of
-speed of accessing components, subject to reasonable complexity in
-addressing calculations.
-@end cartouche
-@sp 1
-@cartouche
-The recommended level of support pragma @code{Pack} is:
-
-For a packed record type, the components should be packed as tightly as
-possible subject to the Sizes of the component subtypes, and subject to
-any @code{record_representation_clause} that applies to the type; the
-implementation may, but need not, reorder components or cross aligned
-word boundaries to improve the packing. A component whose @code{Size} is
-greater than the word size may be allocated an integral number of words.
-@end cartouche
-Followed. Tight packing of arrays is supported for all component sizes
-up to 64-bits. If the array component size is 1 (that is to say, if
-the component is a boolean type or an enumeration type with two values)
-then values of the type are implicitly initialized to zero. This
-happens both for objects of the packed type, and for objects that have a
-subcomponent of the packed type.
-
-@sp 1
-@cartouche
-An implementation should support Address clauses for imported
-subprograms.
-@end cartouche
-Followed.
-@cindex @code{Address} clauses
-@unnumberedsec 13.3(14-19): Address Clauses
-
-@sp 1
-@cartouche
-For an array @var{X}, @code{@var{X}'Address} should point at the first
-component of the array, and not at the array bounds.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-The recommended level of support for the @code{Address} attribute is:
-
-@code{@var{X}'Address} should produce a useful result if @var{X} is an
-object that is aliased or of a by-reference type, or is an entity whose
-@code{Address} has been specified.
-@end cartouche
-Followed. A valid address will be produced even if none of those
-conditions have been met. If necessary, the object is forced into
-memory to ensure the address is valid.
-
-@sp 1
-@cartouche
-An implementation should support @code{Address} clauses for imported
-subprograms.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-Objects (including subcomponents) that are aliased or of a by-reference
-type should be allocated on storage element boundaries.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-If the @code{Address} of an object is specified, or it is imported or exported,
-then the implementation should not perform optimizations based on
-assumptions of no aliases.
-@end cartouche
-Followed.
-
-@cindex @code{Alignment} clauses
-@unnumberedsec 13.3(29-35): Alignment Clauses
-@sp 1
-@cartouche
-The recommended level of support for the @code{Alignment} attribute for
-subtypes is:
-
-An implementation should support specified Alignments that are factors
-and multiples of the number of storage elements per word, subject to the
-following:
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An implementation need not support specified @code{Alignment}s for
-combinations of @code{Size}s and @code{Alignment}s that cannot be easily
-loaded and stored by available machine instructions.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An implementation need not support specified @code{Alignment}s that are
-greater than the maximum @code{Alignment} the implementation ever returns by
-default.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-The recommended level of support for the @code{Alignment} attribute for
-objects is:
-
-Same as above, for subtypes, but in addition:
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-For stand-alone library-level objects of statically constrained
-subtypes, the implementation should support all @code{Alignment}s
-supported by the target linker. For example, page alignment is likely to
-be supported for such objects, but not for subtypes.
-@end cartouche
-Followed.
-
-@cindex @code{Size} clauses
-@unnumberedsec 13.3(42-43): Size Clauses
-@sp 1
-@cartouche
-The recommended level of support for the @code{Size} attribute of
-objects is:
-
-A @code{Size} clause should be supported for an object if the specified
-@code{Size} is at least as large as its subtype's @code{Size}, and
-corresponds to a size in storage elements that is a multiple of the
-object's @code{Alignment} (if the @code{Alignment} is nonzero).
-@end cartouche
-Followed.
-
-@unnumberedsec 13.3(50-56): Size Clauses
-@sp 1
-@cartouche
-If the @code{Size} of a subtype is specified, and allows for efficient
-independent addressability (see 9.10) on the target architecture, then
-the @code{Size} of the following objects of the subtype should equal the
-@code{Size} of the subtype:
-
-Aliased objects (including components).
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-@code{Size} clause on a composite subtype should not affect the
-internal layout of components.
-@end cartouche
-Followed. But note that this can be overridden by use of the implementation
-pragma Implicit_Packing in the case of packed arrays.
-
-@sp 1
-@cartouche
-The recommended level of support for the @code{Size} attribute of subtypes is:
-@end cartouche
-@sp 1
-@cartouche
-The @code{Size} (if not specified) of a static discrete or fixed point
-subtype should be the number of bits needed to represent each value
-belonging to the subtype using an unbiased representation, leaving space
-for a sign bit only if the subtype contains negative values. If such a
-subtype is a first subtype, then an implementation should support a
-specified @code{Size} for it that reflects this representation.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-For a subtype implemented with levels of indirection, the @code{Size}
-should include the size of the pointers, but not the size of what they
-point at.
-@end cartouche
-Followed.
-
-@cindex @code{Component_Size} clauses
-@unnumberedsec 13.3(71-73): Component Size Clauses
-@sp 1
-@cartouche
-The recommended level of support for the @code{Component_Size}
-attribute is:
-@end cartouche
-@sp 1
-@cartouche
-An implementation need not support specified @code{Component_Sizes} that are
-less than the @code{Size} of the component subtype.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An implementation should support specified @code{Component_Size}s that
-are factors and multiples of the word size. For such
-@code{Component_Size}s, the array should contain no gaps between
-components. For other @code{Component_Size}s (if supported), the array
-should contain no gaps between components when packing is also
-specified; the implementation should forbid this combination in cases
-where it cannot support a no-gaps representation.
-@end cartouche
-Followed.
-
-@cindex Enumeration representation clauses
-@cindex Representation clauses, enumeration
-@unnumberedsec 13.4(9-10): Enumeration Representation Clauses
-@sp 1
-@cartouche
-The recommended level of support for enumeration representation clauses
-is:
-
-An implementation need not support enumeration representation clauses
-for boolean types, but should at minimum support the internal codes in
-the range @code{System.Min_Int.System.Max_Int}.
-@end cartouche
-Followed.
-
-@cindex Record representation clauses
-@cindex Representation clauses, records
-@unnumberedsec 13.5.1(17-22): Record Representation Clauses
-@sp 1
-@cartouche
-The recommended level of support for
-@*@code{record_representation_clauses} is:
-
-An implementation should support storage places that can be extracted
-with a load, mask, shift sequence of machine code, and set with a load,
-shift, mask, store sequence, given the available machine instructions
-and run-time model.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-A storage place should be supported if its size is equal to the
-@code{Size} of the component subtype, and it starts and ends on a
-boundary that obeys the @code{Alignment} of the component subtype.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-If the default bit ordering applies to the declaration of a given type,
-then for a component whose subtype's @code{Size} is less than the word
-size, any storage place that does not cross an aligned word boundary
-should be supported.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An implementation may reserve a storage place for the tag field of a
-tagged type, and disallow other components from overlapping that place.
-@end cartouche
-Followed. The storage place for the tag field is the beginning of the tagged
-record, and its size is Address'Size. GNAT will reject an explicit component
-clause for the tag field.
-
-@sp 1
-@cartouche
-An implementation need not support a @code{component_clause} for a
-component of an extension part if the storage place is not after the
-storage places of all components of the parent type, whether or not
-those storage places had been specified.
-@end cartouche
-Followed. The above advice on record representation clauses is followed,
-and all mentioned features are implemented.
-
-@cindex Storage place attributes
-@unnumberedsec 13.5.2(5): Storage Place Attributes
-@sp 1
-@cartouche
-If a component is represented using some form of pointer (such as an
-offset) to the actual data of the component, and this data is contiguous
-with the rest of the object, then the storage place attributes should
-reflect the place of the actual data, not the pointer. If a component is
-allocated discontinuously from the rest of the object, then a warning
-should be generated upon reference to one of its storage place
-attributes.
-@end cartouche
-Followed. There are no such components in GNAT@.
-
-@cindex Bit ordering
-@unnumberedsec 13.5.3(7-8): Bit Ordering
-@sp 1
-@cartouche
-The recommended level of support for the non-default bit ordering is:
-@end cartouche
-@sp 1
-@cartouche
-If @code{Word_Size} = @code{Storage_Unit}, then the implementation
-should support the non-default bit ordering in addition to the default
-bit ordering.
-@end cartouche
-Followed. Word size does not equal storage size in this implementation.
-Thus non-default bit ordering is not supported.
-
-@cindex @code{Address}, as private type
-@unnumberedsec 13.7(37): Address as Private
-@sp 1
-@cartouche
-@code{Address} should be of a private type.
-@end cartouche
-Followed.
-
-@cindex Operations, on @code{Address}
-@cindex @code{Address}, operations of
-@unnumberedsec 13.7.1(16): Address Operations
-@sp 1
-@cartouche
-Operations in @code{System} and its children should reflect the target
-environment semantics as closely as is reasonable. For example, on most
-machines, it makes sense for address arithmetic to ``wrap around''.
-Operations that do not make sense should raise @code{Program_Error}.
-@end cartouche
-Followed. Address arithmetic is modular arithmetic that wraps around. No
-operation raises @code{Program_Error}, since all operations make sense.
-
-@cindex Unchecked conversion
-@unnumberedsec 13.9(14-17): Unchecked Conversion
-@sp 1
-@cartouche
-The @code{Size} of an array object should not include its bounds; hence,
-the bounds should not be part of the converted data.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-The implementation should not generate unnecessary run-time checks to
-ensure that the representation of @var{S} is a representation of the
-target type. It should take advantage of the permission to return by
-reference when possible. Restrictions on unchecked conversions should be
-avoided unless required by the target environment.
-@end cartouche
-Followed. There are no restrictions on unchecked conversion. A warning is
-generated if the source and target types do not have the same size since
-the semantics in this case may be target dependent.
-
-@sp 1
-@cartouche
-The recommended level of support for unchecked conversions is:
-@end cartouche
-@sp 1
-@cartouche
-Unchecked conversions should be supported and should be reversible in
-the cases where this clause defines the result. To enable meaningful use
-of unchecked conversion, a contiguous representation should be used for
-elementary subtypes, for statically constrained array subtypes whose
-component subtype is one of the subtypes described in this paragraph,
-and for record subtypes without discriminants whose component subtypes
-are described in this paragraph.
-@end cartouche
-Followed.
-
-@cindex Heap usage, implicit
-@unnumberedsec 13.11(23-25): Implicit Heap Usage
-@sp 1
-@cartouche
-An implementation should document any cases in which it dynamically
-allocates heap storage for a purpose other than the evaluation of an
-allocator.
-@end cartouche
-Followed, the only other points at which heap storage is dynamically
-allocated are as follows:
-
-@itemize @bullet
-@item
-At initial elaboration time, to allocate dynamically sized global
-objects.
-
-@item
-To allocate space for a task when a task is created.
-
-@item
-To extend the secondary stack dynamically when needed. The secondary
-stack is used for returning variable length results.
-@end itemize
-
-@sp 1
-@cartouche
-A default (implementation-provided) storage pool for an
-access-to-constant type should not have overhead to support deallocation of
-individual objects.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-A storage pool for an anonymous access type should be created at the
-point of an allocator for the type, and be reclaimed when the designated
-object becomes inaccessible.
-@end cartouche
-Followed.
-
-@cindex Unchecked deallocation
-@unnumberedsec 13.11.2(17): Unchecked De-allocation
-@sp 1
-@cartouche
-For a standard storage pool, @code{Free} should actually reclaim the
-storage.
-@end cartouche
-Followed.
-
-@cindex Stream oriented attributes
-@unnumberedsec 13.13.2(17): Stream Oriented Attributes
-@sp 1
-@cartouche
-If a stream element is the same size as a storage element, then the
-normal in-memory representation should be used by @code{Read} and
-@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
-should use the smallest number of stream elements needed to represent
-all values in the base range of the scalar type.
-@end cartouche
-
-Followed. By default, GNAT uses the interpretation suggested by AI-195,
-which specifies using the size of the first subtype.
-However, such an implementation is based on direct binary
-representations and is therefore target- and endianness-dependent.
-To address this issue, GNAT also supplies an alternate implementation
-of the stream attributes @code{Read} and @code{Write},
-which uses the target-independent XDR standard representation
-for scalar types.
-@cindex XDR representation
-@cindex @code{Read} attribute
-@cindex @code{Write} attribute
-@cindex Stream oriented attributes
-The XDR implementation is provided as an alternative body of the
-@code{System.Stream_Attributes} package, in the file
-@file{s-strxdr.adb} in the GNAT library.
-There is no @file{s-strxdr.ads} file.
-In order to install the XDR implementation, do the following:
-@enumerate
-@item Replace the default implementation of the
-@code{System.Stream_Attributes} package with the XDR implementation.
-For example on a Unix platform issue the commands:
-@smallexample
-$ mv s-stratt.adb s-strold.adb
-$ mv s-strxdr.adb s-stratt.adb
-@end smallexample
-
-@item
-Rebuild the GNAT run-time library as documented in
-@ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}.
-@end enumerate
-
-@unnumberedsec A.1(52): Names of Predefined Numeric Types
-@sp 1
-@cartouche
-If an implementation provides additional named predefined integer types,
-then the names should end with @samp{Integer} as in
-@samp{Long_Integer}. If an implementation provides additional named
-predefined floating point types, then the names should end with
-@samp{Float} as in @samp{Long_Float}.
-@end cartouche
-Followed.
-
-@findex Ada.Characters.Handling
-@unnumberedsec A.3.2(49): @code{Ada.Characters.Handling}
-@sp 1
-@cartouche
-If an implementation provides a localized definition of @code{Character}
-or @code{Wide_Character}, then the effects of the subprograms in
-@code{Characters.Handling} should reflect the localizations. See also
-3.5.2.
-@end cartouche
-Followed. GNAT provides no such localized definitions.
-
-@cindex Bounded-length strings
-@unnumberedsec A.4.4(106): Bounded-Length String Handling
-@sp 1
-@cartouche
-Bounded string objects should not be implemented by implicit pointers
-and dynamic allocation.
-@end cartouche
-Followed. No implicit pointers or dynamic allocation are used.
-
-@cindex Random number generation
-@unnumberedsec A.5.2(46-47): Random Number Generation
-@sp 1
-@cartouche
-Any storage associated with an object of type @code{Generator} should be
-reclaimed on exit from the scope of the object.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-If the generator period is sufficiently long in relation to the number
-of distinct initiator values, then each possible value of
-@code{Initiator} passed to @code{Reset} should initiate a sequence of
-random numbers that does not, in a practical sense, overlap the sequence
-initiated by any other value. If this is not possible, then the mapping
-between initiator values and generator states should be a rapidly
-varying function of the initiator value.
-@end cartouche
-Followed. The generator period is sufficiently long for the first
-condition here to hold true.
-
-@findex Get_Immediate
-@unnumberedsec A.10.7(23): @code{Get_Immediate}
-@sp 1
-@cartouche
-The @code{Get_Immediate} procedures should be implemented with
-unbuffered input. For a device such as a keyboard, input should be
-@dfn{available} if a key has already been typed, whereas for a disk
-file, input should always be available except at end of file. For a file
-associated with a keyboard-like device, any line-editing features of the
-underlying operating system should be disabled during the execution of
-@code{Get_Immediate}.
-@end cartouche
-Followed on all targets except VxWorks. For VxWorks, there is no way to
-provide this functionality that does not result in the input buffer being
-flushed before the @code{Get_Immediate} call. A special unit
-@code{Interfaces.Vxworks.IO} is provided that contains routines to enable
-this functionality.
-
-@findex Export
-@unnumberedsec B.1(39-41): Pragma @code{Export}
-@sp 1
-@cartouche
-If an implementation supports pragma @code{Export} to a given language,
-then it should also allow the main subprogram to be written in that
-language. It should support some mechanism for invoking the elaboration
-of the Ada library units included in the system, and for invoking the
-finalization of the environment task. On typical systems, the
-recommended mechanism is to provide two subprograms whose link names are
-@code{adainit} and @code{adafinal}. @code{adainit} should contain the
-elaboration code for library units. @code{adafinal} should contain the
-finalization code. These subprograms should have no effect the second
-and subsequent time they are called.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-Automatic elaboration of pre-elaborated packages should be
-provided when pragma @code{Export} is supported.
-@end cartouche
-Followed when the main program is in Ada. If the main program is in a
-foreign language, then
-@code{adainit} must be called to elaborate pre-elaborated
-packages.
-
-@sp 1
-@cartouche
-For each supported convention @var{L} other than @code{Intrinsic}, an
-implementation should support @code{Import} and @code{Export} pragmas
-for objects of @var{L}-compatible types and for subprograms, and pragma
-@code{Convention} for @var{L}-eligible types and for subprograms,
-presuming the other language has corresponding features. Pragma
-@code{Convention} need not be supported for scalar types.
-@end cartouche
-Followed.
-
-@cindex Package @code{Interfaces}
-@findex Interfaces
-@unnumberedsec B.2(12-13): Package @code{Interfaces}
-@sp 1
-@cartouche
-For each implementation-defined convention identifier, there should be a
-child package of package Interfaces with the corresponding name. This
-package should contain any declarations that would be useful for
-interfacing to the language (implementation) represented by the
-convention. Any declarations useful for interfacing to any language on
-the given hardware architecture should be provided directly in
-@code{Interfaces}.
-@end cartouche
-Followed. An additional package not defined
-in the Ada Reference Manual is @code{Interfaces.CPP}, used
-for interfacing to C++.
-
-@sp 1
-@cartouche
-An implementation supporting an interface to C, COBOL, or Fortran should
-provide the corresponding package or packages described in the following
-clauses.
-@end cartouche
-Followed. GNAT provides all the packages described in this section.
-
-@cindex C, interfacing with
-@unnumberedsec B.3(63-71): Interfacing with C
-@sp 1
-@cartouche
-An implementation should support the following interface correspondences
-between Ada and C@.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada procedure corresponds to a void-returning C function.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada function corresponds to a non-void C function.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada @code{in} scalar parameter is passed as a scalar argument to a C
-function.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada @code{in} parameter of an access-to-object type with designated
-type @var{T} is passed as a @code{@var{t}*} argument to a C function,
-where @var{t} is the C type corresponding to the Ada type @var{T}.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out}
-parameter of an elementary type @var{T}, is passed as a @code{@var{t}*}
-argument to a C function, where @var{t} is the C type corresponding to
-the Ada type @var{T}. In the case of an elementary @code{out} or
-@code{in out} parameter, a pointer to a temporary copy is used to
-preserve by-copy semantics.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada parameter of a record type @var{T}, of any mode, is passed as a
-@code{@var{t}*} argument to a C function, where @var{t} is the C
-structure corresponding to the Ada type @var{T}.
-@end cartouche
-Followed. This convention may be overridden by the use of the C_Pass_By_Copy
-pragma, or Convention, or by explicitly specifying the mechanism for a given
-call using an extended import or export pragma.
-
-@sp 1
-@cartouche
-An Ada parameter of an array type with component type @var{T}, of any
-mode, is passed as a @code{@var{t}*} argument to a C function, where
-@var{t} is the C type corresponding to the Ada type @var{T}.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada parameter of an access-to-subprogram type is passed as a pointer
-to a C function whose prototype corresponds to the designated
-subprogram's specification.
-@end cartouche
-Followed.
-
-@cindex COBOL, interfacing with
-@unnumberedsec B.4(95-98): Interfacing with COBOL
-@sp 1
-@cartouche
-An Ada implementation should support the following interface
-correspondences between Ada and COBOL@.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of
-the COBOL type corresponding to @var{T}.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of
-the corresponding COBOL type.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the
-COBOL type corresponding to the Ada parameter type; for scalars, a local
-copy is used if necessary to ensure by-copy semantics.
-@end cartouche
-Followed.
-
-@cindex Fortran, interfacing with
-@unnumberedsec B.5(22-26): Interfacing with Fortran
-@sp 1
-@cartouche
-An Ada implementation should support the following interface
-correspondences between Ada and Fortran:
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada procedure corresponds to a Fortran subroutine.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada function corresponds to a Fortran function.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada parameter of an elementary, array, or record type @var{T} is
-passed as a @var{T} argument to a Fortran procedure, where @var{T} is
-the Fortran type corresponding to the Ada type @var{T}, and where the
-INTENT attribute of the corresponding dummy argument matches the Ada
-formal parameter mode; the Fortran implementation's parameter passing
-conventions are used. For elementary types, a local copy is used if
-necessary to ensure by-copy semantics.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-An Ada parameter of an access-to-subprogram type is passed as a
-reference to a Fortran procedure whose interface corresponds to the
-designated subprogram's specification.
-@end cartouche
-Followed.
-
-@cindex Machine operations
-@unnumberedsec C.1(3-5): Access to Machine Operations
-@sp 1
-@cartouche
-The machine code or intrinsic support should allow access to all
-operations normally available to assembly language programmers for the
-target environment, including privileged instructions, if any.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-The interfacing pragmas (see Annex B) should support interface to
-assembler; the default assembler should be associated with the
-convention identifier @code{Assembler}.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-If an entity is exported to assembly language, then the implementation
-should allocate it at an addressable location, and should ensure that it
-is retained by the linking process, even if not otherwise referenced
-from the Ada code. The implementation should assume that any call to a
-machine code or assembler subprogram is allowed to read or update every
-object that is specified as exported.
-@end cartouche
-Followed.
-
-@unnumberedsec C.1(10-16): Access to Machine Operations
-@sp 1
-@cartouche
-The implementation should ensure that little or no overhead is
-associated with calling intrinsic and machine-code subprograms.
-@end cartouche
-Followed for both intrinsics and machine-code subprograms.
-
-@sp 1
-@cartouche
-It is recommended that intrinsic subprograms be provided for convenient
-access to any machine operations that provide special capabilities or
-efficiency and that are not otherwise available through the language
-constructs.
-@end cartouche
-Followed. A full set of machine operation intrinsic subprograms is provided.
-
-@sp 1
-@cartouche
-Atomic read-modify-write operations---e.g.@:, test and set, compare and
-swap, decrement and test, enqueue/dequeue.
-@end cartouche
-Followed on any target supporting such operations.
-
-@sp 1
-@cartouche
-Standard numeric functions---e.g.@:, sin, log.
-@end cartouche
-Followed on any target supporting such operations.
-
-@sp 1
-@cartouche
-String manipulation operations---e.g.@:, translate and test.
-@end cartouche
-Followed on any target supporting such operations.
-
-@sp 1
-@cartouche
-Vector operations---e.g.@:, compare vector against thresholds.
-@end cartouche
-Followed on any target supporting such operations.
-
-@sp 1
-@cartouche
-Direct operations on I/O ports.
-@end cartouche
-Followed on any target supporting such operations.
-
-@cindex Interrupt support
-@unnumberedsec C.3(28): Interrupt Support
-@sp 1
-@cartouche
-If the @code{Ceiling_Locking} policy is not in effect, the
-implementation should provide means for the application to specify which
-interrupts are to be blocked during protected actions, if the underlying
-system allows for a finer-grain control of interrupt blocking.
-@end cartouche
-Followed. The underlying system does not allow for finer-grain control
-of interrupt blocking.
-
-@cindex Protected procedure handlers
-@unnumberedsec C.3.1(20-21): Protected Procedure Handlers
-@sp 1
-@cartouche
-Whenever possible, the implementation should allow interrupt handlers to
-be called directly by the hardware.
-@end cartouche
-@c SGI info:
-@ignore
-This is never possible under IRIX, so this is followed by default.
-@end ignore
-Followed on any target where the underlying operating system permits
-such direct calls.
-
-@sp 1
-@cartouche
-Whenever practical, violations of any
-implementation-defined restrictions should be detected before run time.
-@end cartouche
-Followed. Compile time warnings are given when possible.
-
-@cindex Package @code{Interrupts}
-@findex Interrupts
-@unnumberedsec C.3.2(25): Package @code{Interrupts}
-
-@sp 1
-@cartouche
-If implementation-defined forms of interrupt handler procedures are
-supported, such as protected procedures with parameters, then for each
-such form of a handler, a type analogous to @code{Parameterless_Handler}
-should be specified in a child package of @code{Interrupts}, with the
-same operations as in the predefined package Interrupts.
-@end cartouche
-Followed.
-
-@cindex Pre-elaboration requirements
-@unnumberedsec C.4(14): Pre-elaboration Requirements
-@sp 1
-@cartouche
-It is recommended that pre-elaborated packages be implemented in such a
-way that there should be little or no code executed at run time for the
-elaboration of entities not already covered by the Implementation
-Requirements.
-@end cartouche
-Followed. Executable code is generated in some cases, e.g.@: loops
-to initialize large arrays.
-
-@unnumberedsec C.5(8): Pragma @code{Discard_Names}
-
-@sp 1
-@cartouche
-If the pragma applies to an entity, then the implementation should
-reduce the amount of storage used for storing names associated with that
-entity.
-@end cartouche
-Followed.
-
-@cindex Package @code{Task_Attributes}
-@findex Task_Attributes
-@unnumberedsec C.7.2(30): The Package Task_Attributes
-@sp 1
-@cartouche
-Some implementations are targeted to domains in which memory use at run
-time must be completely deterministic. For such implementations, it is
-recommended that the storage for task attributes will be pre-allocated
-statically and not from the heap. This can be accomplished by either
-placing restrictions on the number and the size of the task's
-attributes, or by using the pre-allocated storage for the first @var{N}
-attribute objects, and the heap for the others. In the latter case,
-@var{N} should be documented.
-@end cartouche
-Not followed. This implementation is not targeted to such a domain.
-
-@cindex Locking Policies
-@unnumberedsec D.3(17): Locking Policies
-
-@sp 1
-@cartouche
-The implementation should use names that end with @samp{_Locking} for
-locking policies defined by the implementation.
-@end cartouche
-Followed. A single implementation-defined locking policy is defined,
-whose name (@code{Inheritance_Locking}) follows this suggestion.
-
-@cindex Entry queuing policies
-@unnumberedsec D.4(16): Entry Queuing Policies
-@sp 1
-@cartouche
-Names that end with @samp{_Queuing} should be used
-for all implementation-defined queuing policies.
-@end cartouche
-Followed. No such implementation-defined queuing policies exist.
-
-@cindex Preemptive abort
-@unnumberedsec D.6(9-10): Preemptive Abort
-@sp 1
-@cartouche
-Even though the @code{abort_statement} is included in the list of
-potentially blocking operations (see 9.5.1), it is recommended that this
-statement be implemented in a way that never requires the task executing
-the @code{abort_statement} to block.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-On a multi-processor, the delay associated with aborting a task on
-another processor should be bounded; the implementation should use
-periodic polling, if necessary, to achieve this.
-@end cartouche
-Followed.
-
-@cindex Tasking restrictions
-@unnumberedsec D.7(21): Tasking Restrictions
-@sp 1
-@cartouche
-When feasible, the implementation should take advantage of the specified
-restrictions to produce a more efficient implementation.
-@end cartouche
-GNAT currently takes advantage of these restrictions by providing an optimized
-run time when the Ravenscar profile and the GNAT restricted run time set
-of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
-pragma @code{Profile (Restricted)} for more details.
-
-@cindex Time, monotonic
-@unnumberedsec D.8(47-49): Monotonic Time
-@sp 1
-@cartouche
-When appropriate, implementations should provide configuration
-mechanisms to change the value of @code{Tick}.
-@end cartouche
-Such configuration mechanisms are not appropriate to this implementation
-and are thus not supported.
-
-@sp 1
-@cartouche
-It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
-be implemented as transformations of the same time base.
-@end cartouche
-Followed.
-
-@sp 1
-@cartouche
-It is recommended that the @dfn{best} time base which exists in
-the underlying system be available to the application through
-@code{Clock}. @dfn{Best} may mean highest accuracy or largest range.
-@end cartouche
-Followed.
-
-@cindex Partition communication subsystem
-@cindex PCS
-@unnumberedsec E.5(28-29): Partition Communication Subsystem
-@sp 1
-@cartouche
-Whenever possible, the PCS on the called partition should allow for
-multiple tasks to call the RPC-receiver with different messages and
-should allow them to block until the corresponding subprogram body
-returns.
-@end cartouche
-Followed by GLADE, a separately supplied PCS that can be used with
-GNAT.
-
-@sp 1
-@cartouche
-The @code{Write} operation on a stream of type @code{Params_Stream_Type}
-should raise @code{Storage_Error} if it runs out of space trying to
-write the @code{Item} into the stream.
-@end cartouche
-Followed by GLADE, a separately supplied PCS that can be used with
-GNAT@.
-
-@cindex COBOL support
-@unnumberedsec F(7): COBOL Support
-@sp 1
-@cartouche
-If COBOL (respectively, C) is widely supported in the target
-environment, implementations supporting the Information Systems Annex
-should provide the child package @code{Interfaces.COBOL} (respectively,
-@code{Interfaces.C}) specified in Annex B and should support a
-@code{convention_identifier} of COBOL (respectively, C) in the interfacing
-pragmas (see Annex B), thus allowing Ada programs to interface with
-programs written in that language.
-@end cartouche
-Followed.
-
-@cindex Decimal radix support
-@unnumberedsec F.1(2): Decimal Radix Support
-@sp 1
-@cartouche
-Packed decimal should be used as the internal representation for objects
-of subtype @var{S} when @var{S}'Machine_Radix = 10.
-@end cartouche
-Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary
-representations.
-
-@cindex Numerics
-@unnumberedsec G: Numerics
-@sp 2
-@cartouche
-If Fortran (respectively, C) is widely supported in the target
-environment, implementations supporting the Numerics Annex
-should provide the child package @code{Interfaces.Fortran} (respectively,
-@code{Interfaces.C}) specified in Annex B and should support a
-@code{convention_identifier} of Fortran (respectively, C) in the interfacing
-pragmas (see Annex B), thus allowing Ada programs to interface with
-programs written in that language.
-@end cartouche
-Followed.
-
-@cindex Complex types
-@unnumberedsec G.1.1(56-58): Complex Types
-@sp 2
-@cartouche
-Because the usual mathematical meaning of multiplication of a complex
-operand and a real operand is that of the scaling of both components of
-the former by the latter, an implementation should not perform this
-operation by first promoting the real operand to complex type and then
-performing a full complex multiplication. In systems that, in the
-future, support an Ada binding to IEC 559:1989, the latter technique
-will not generate the required result when one of the components of the
-complex operand is infinite. (Explicit multiplication of the infinite
-component by the zero component obtained during promotion yields a NaN
-that propagates into the final result.) Analogous advice applies in the
-case of multiplication of a complex operand and a pure-imaginary
-operand, and in the case of division of a complex operand by a real or
-pure-imaginary operand.
-@end cartouche
-Not followed.
-
-@sp 1
-@cartouche
-Similarly, because the usual mathematical meaning of addition of a
-complex operand and a real operand is that the imaginary operand remains
-unchanged, an implementation should not perform this operation by first
-promoting the real operand to complex type and then performing a full
-complex addition. In implementations in which the @code{Signed_Zeros}
-attribute of the component type is @code{True} (and which therefore
-conform to IEC 559:1989 in regard to the handling of the sign of zero in
-predefined arithmetic operations), the latter technique will not
-generate the required result when the imaginary component of the complex
-operand is a negatively signed zero. (Explicit addition of the negative
-zero to the zero obtained during promotion yields a positive zero.)
-Analogous advice applies in the case of addition of a complex operand
-and a pure-imaginary operand, and in the case of subtraction of a
-complex operand and a real or pure-imaginary operand.
-@end cartouche
-Not followed.
-
-@sp 1
-@cartouche
-Implementations in which @code{Real'Signed_Zeros} is @code{True} should
-attempt to provide a rational treatment of the signs of zero results and
-result components. As one example, the result of the @code{Argument}
-function should have the sign of the imaginary component of the
-parameter @code{X} when the point represented by that parameter lies on
-the positive real axis; as another, the sign of the imaginary component
-of the @code{Compose_From_Polar} function should be the same as
-(respectively, the opposite of) that of the @code{Argument} parameter when that
-parameter has a value of zero and the @code{Modulus} parameter has a
-nonnegative (respectively, negative) value.
-@end cartouche
-Followed.
-
-@cindex Complex elementary functions
-@unnumberedsec G.1.2(49): Complex Elementary Functions
-@sp 1
-@cartouche
-Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
-@code{True} should attempt to provide a rational treatment of the signs
-of zero results and result components. For example, many of the complex
-elementary functions have components that are odd functions of one of
-the parameter components; in these cases, the result component should
-have the sign of the parameter component at the origin. Other complex
-elementary functions have zero components whose sign is opposite that of
-a parameter component at the origin, or is always positive or always
-negative.
-@end cartouche
-Followed.
-
-@cindex Accuracy requirements
-@unnumberedsec G.2.4(19): Accuracy Requirements
-@sp 1
-@cartouche
-The versions of the forward trigonometric functions without a
-@code{Cycle} parameter should not be implemented by calling the
-corresponding version with a @code{Cycle} parameter of
-@code{2.0*Numerics.Pi}, since this will not provide the required
-accuracy in some portions of the domain. For the same reason, the
-version of @code{Log} without a @code{Base} parameter should not be
-implemented by calling the corresponding version with a @code{Base}
-parameter of @code{Numerics.e}.
-@end cartouche
-Followed.
-
-@cindex Complex arithmetic accuracy
-@cindex Accuracy, complex arithmetic
-@unnumberedsec G.2.6(15): Complex Arithmetic Accuracy
-
-@sp 1
-@cartouche
-The version of the @code{Compose_From_Polar} function without a
-@code{Cycle} parameter should not be implemented by calling the
-corresponding version with a @code{Cycle} parameter of
-@code{2.0*Numerics.Pi}, since this will not provide the required
-accuracy in some portions of the domain.
-@end cartouche
-Followed.
-
-@c -----------------------------------------
-@node Implementation Defined Characteristics
-@chapter Implementation Defined Characteristics
-
-@noindent
-In addition to the implementation dependent pragmas and attributes, and
-the implementation advice, there are a number of other Ada features
-that are potentially implementation dependent. These are mentioned
-throughout the Ada Reference Manual, and are summarized in annex M@.
-
-A requirement for conforming Ada compilers is that they provide
-documentation describing how the implementation deals with each of these
-issues. In this chapter, you will find each point in annex M listed
-followed by a description in italic font of how GNAT
-@c SGI info:
-@ignore
-in the ProDev Ada
-implementation on IRIX 5.3 operating system or greater
-@end ignore
-handles the implementation dependence.
-
-You can use this chapter as a guide to minimizing implementation
-dependent features in your programs if portability to other compilers
-and other operating systems is an important consideration. The numbers
-in each section below correspond to the paragraph number in the Ada
-Reference Manual.
-
-@sp 1
-@cartouche
-@noindent
-@strong{2}. Whether or not each recommendation given in Implementation
-Advice is followed. See 1.1.2(37).
-@end cartouche
-@noindent
-@xref{Implementation Advice}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{3}. Capacity limitations of the implementation. See 1.1.3(3).
-@end cartouche
-@noindent
-The complexity of programs that can be processed is limited only by the
-total amount of available virtual memory, and disk space for the
-generated object files.
-
-@sp 1
-@cartouche
-@noindent
-@strong{4}. Variations from the standard that are impractical to avoid
-given the implementation's execution environment. See 1.1.3(6).
-@end cartouche
-@noindent
-There are no variations from the standard.
-
-@sp 1
-@cartouche
-@noindent
-@strong{5}. Which @code{code_statement}s cause external
-interactions. See 1.1.3(10).
-@end cartouche
-@noindent
-Any @code{code_statement} can potentially cause external interactions.
-
-@sp 1
-@cartouche
-@noindent
-@strong{6}. The coded representation for the text of an Ada
-program. See 2.1(4).
-@end cartouche
-@noindent
-See separate section on source representation.
-
-@sp 1
-@cartouche
-@noindent
-@strong{7}. The control functions allowed in comments. See 2.1(14).
-@end cartouche
-@noindent
-See separate section on source representation.
-
-@sp 1
-@cartouche
-@noindent
-@strong{8}. The representation for an end of line. See 2.2(2).
-@end cartouche
-@noindent
-See separate section on source representation.
-
-@sp 1
-@cartouche
-@noindent
-@strong{9}. Maximum supported line length and lexical element
-length. See 2.2(15).
-@end cartouche
-@noindent
-The maximum line length is 255 characters and the maximum length of a
-lexical element is also 255 characters.
-
-@sp 1
-@cartouche
-@noindent
-@strong{10}. Implementation defined pragmas. See 2.8(14).
-@end cartouche
-@noindent
-
-@xref{Implementation Defined Pragmas}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{11}. Effect of pragma @code{Optimize}. See 2.8(27).
-@end cartouche
-@noindent
-Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
-parameter, checks that the optimization flag is set, and aborts if it is
-not.
-
-@sp 1
-@cartouche
-@noindent
-@strong{12}. The sequence of characters of the value returned by
-@code{@var{S}'Image} when some of the graphic characters of
-@code{@var{S}'Wide_Image} are not defined in @code{Character}. See
-3.5(37).
-@end cartouche
-@noindent
-The sequence of characters is as defined by the wide character encoding
-method used for the source. See section on source representation for
-further details.
-
-@sp 1
-@cartouche
-@noindent
-@strong{13}. The predefined integer types declared in
-@code{Standard}. See 3.5.4(25).
-@end cartouche
-@noindent
-@table @code
-@item Short_Short_Integer
-8 bit signed
-@item Short_Integer
-(Short) 16 bit signed
-@item Integer
-32 bit signed
-@item Long_Integer
-64 bit signed (Alpha OpenVMS only)
-32 bit signed (all other targets)
-@item Long_Long_Integer
-64 bit signed
-@end table
-
-@sp 1
-@cartouche
-@noindent
-@strong{14}. Any nonstandard integer types and the operators defined
-for them. See 3.5.4(26).
-@end cartouche
-@noindent
-There are no nonstandard integer types.
-
-@sp 1
-@cartouche
-@noindent
-@strong{15}. Any nonstandard real types and the operators defined for
-them. See 3.5.6(8).
-@end cartouche
-@noindent
-There are no nonstandard real types.
-
-@sp 1
-@cartouche
-@noindent
-@strong{16}. What combinations of requested decimal precision and range
-are supported for floating point types. See 3.5.7(7).
-@end cartouche
-@noindent
-The precision and range is as defined by the IEEE standard.
-
-@sp 1
-@cartouche
-@noindent
-@strong{17}. The predefined floating point types declared in
-@code{Standard}. See 3.5.7(16).
-@end cartouche
-@noindent
-@table @code
-@item Short_Float
-32 bit IEEE short
-@item Float
-(Short) 32 bit IEEE short
-@item Long_Float
-64 bit IEEE long
-@item Long_Long_Float
-64 bit IEEE long (80 bit IEEE long on x86 processors)
-@end table
-
-@sp 1
-@cartouche
-@noindent
-@strong{18}. The small of an ordinary fixed point type. See 3.5.9(8).
-@end cartouche
-@noindent
-@code{Fine_Delta} is 2**(@minus{}63)
-
-@sp 1
-@cartouche
-@noindent
-@strong{19}. What combinations of small, range, and digits are
-supported for fixed point types. See 3.5.9(10).
-@end cartouche
-@noindent
-Any combinations are permitted that do not result in a small less than
-@code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
-If the mantissa is larger than 53 bits on machines where Long_Long_Float
-is 64 bits (true of all architectures except ia32), then the output from
-Text_IO is accurate to only 53 bits, rather than the full mantissa. This
-is because floating-point conversions are used to convert fixed point.
-
-@sp 1
-@cartouche
-@noindent
-@strong{20}. The result of @code{Tags.Expanded_Name} for types declared
-within an unnamed @code{block_statement}. See 3.9(10).
-@end cartouche
-@noindent
-Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a
-decimal integer are allocated.
-
-@sp 1
-@cartouche
-@noindent
-@strong{21}. Implementation-defined attributes. See 4.1.4(12).
-@end cartouche
-@noindent
-@xref{Implementation Defined Attributes}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{22}. Any implementation-defined time types. See 9.6(6).
-@end cartouche
-@noindent
-There are no implementation-defined time types.
-
-@sp 1
-@cartouche
-@noindent
-@strong{23}. The time base associated with relative delays.
-@end cartouche
-@noindent
-See 9.6(20). The time base used is that provided by the C library
-function @code{gettimeofday}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{24}. The time base of the type @code{Calendar.Time}. See
-9.6(23).
-@end cartouche
-@noindent
-The time base used is that provided by the C library function
-@code{gettimeofday}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{25}. The time zone used for package @code{Calendar}
-operations. See 9.6(24).
-@end cartouche
-@noindent
-The time zone used by package @code{Calendar} is the current system time zone
-setting for local time, as accessed by the C library function
-@code{localtime}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{26}. Any limit on @code{delay_until_statements} of
-@code{select_statements}. See 9.6(29).
-@end cartouche
-@noindent
-There are no such limits.
-
-@sp 1
-@cartouche
-@noindent
-@strong{27}. Whether or not two non-overlapping parts of a composite
-object are independently addressable, in the case where packing, record
-layout, or @code{Component_Size} is specified for the object. See
-9.10(1).
-@end cartouche
-@noindent
-Separate components are independently addressable if they do not share
-overlapping storage units.
-
-@sp 1
-@cartouche
-@noindent
-@strong{28}. The representation for a compilation. See 10.1(2).
-@end cartouche
-@noindent
-A compilation is represented by a sequence of files presented to the
-compiler in a single invocation of the @command{gcc} command.
-
-@sp 1
-@cartouche
-@noindent
-@strong{29}. Any restrictions on compilations that contain multiple
-compilation_units. See 10.1(4).
-@end cartouche
-@noindent
-No single file can contain more than one compilation unit, but any
-sequence of files can be presented to the compiler as a single
-compilation.
-
-@sp 1
-@cartouche
-@noindent
-@strong{30}. The mechanisms for creating an environment and for adding
-and replacing compilation units. See 10.1.4(3).
-@end cartouche
-@noindent
-See separate section on compilation model.
-
-@sp 1
-@cartouche
-@noindent
-@strong{31}. The manner of explicitly assigning library units to a
-partition. See 10.2(2).
-@end cartouche
-@noindent
-If a unit contains an Ada main program, then the Ada units for the partition
-are determined by recursive application of the rules in the Ada Reference
-Manual section 10.2(2-6). In other words, the Ada units will be those that
-are needed by the main program, and then this definition of need is applied
-recursively to those units, and the partition contains the transitive
-closure determined by this relationship. In short, all the necessary units
-are included, with no need to explicitly specify the list. If additional
-units are required, e.g.@: by foreign language units, then all units must be
-mentioned in the context clause of one of the needed Ada units.
-
-If the partition contains no main program, or if the main program is in
-a language other than Ada, then GNAT
-provides the binder options @option{-z} and @option{-n} respectively, and in
-this case a list of units can be explicitly supplied to the binder for
-inclusion in the partition (all units needed by these units will also
-be included automatically). For full details on the use of these
-options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn,
-@value{EDITION} User's Guide}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{32}. The implementation-defined means, if any, of specifying
-which compilation units are needed by a given compilation unit. See
-10.2(2).
-@end cartouche
-@noindent
-The units needed by a given compilation unit are as defined in
-the Ada Reference Manual section 10.2(2-6). There are no
-implementation-defined pragmas or other implementation-defined
-means for specifying needed units.
-
-@sp 1
-@cartouche
-@noindent
-@strong{33}. The manner of designating the main subprogram of a
-partition. See 10.2(7).
-@end cartouche
-@noindent
-The main program is designated by providing the name of the
-corresponding @file{ALI} file as the input parameter to the binder.
-
-@sp 1
-@cartouche
-@noindent
-@strong{34}. The order of elaboration of @code{library_items}. See
-10.2(18).
-@end cartouche
-@noindent
-The first constraint on ordering is that it meets the requirements of
-Chapter 10 of the Ada Reference Manual. This still leaves some
-implementation dependent choices, which are resolved by first
-elaborating bodies as early as possible (i.e., in preference to specs
-where there is a choice), and second by evaluating the immediate with
-clauses of a unit to determine the probably best choice, and
-third by elaborating in alphabetical order of unit names
-where a choice still remains.
-
-@sp 1
-@cartouche
-@noindent
-@strong{35}. Parameter passing and function return for the main
-subprogram. See 10.2(21).
-@end cartouche
-@noindent
-The main program has no parameters. It may be a procedure, or a function
-returning an integer type. In the latter case, the returned integer
-value is the return code of the program (overriding any value that
-may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
-
-@sp 1
-@cartouche
-@noindent
-@strong{36}. The mechanisms for building and running partitions. See
-10.2(24).
-@end cartouche
-@noindent
-GNAT itself supports programs with only a single partition. The GNATDIST
-tool provided with the GLADE package (which also includes an implementation
-of the PCS) provides a completely flexible method for building and running
-programs consisting of multiple partitions. See the separate GLADE manual
-for details.
-
-@sp 1
-@cartouche
-@noindent
-@strong{37}. The details of program execution, including program
-termination. See 10.2(25).
-@end cartouche
-@noindent
-See separate section on compilation model.
-
-@sp 1
-@cartouche
-@noindent
-@strong{38}. The semantics of any non-active partitions supported by the
-implementation. See 10.2(28).
-@end cartouche
-@noindent
-Passive partitions are supported on targets where shared memory is
-provided by the operating system. See the GLADE reference manual for
-further details.
-
-@sp 1
-@cartouche
-@noindent
-@strong{39}. The information returned by @code{Exception_Message}. See
-11.4.1(10).
-@end cartouche
-@noindent
-Exception message returns the null string unless a specific message has
-been passed by the program.
-
-@sp 1
-@cartouche
-@noindent
-@strong{40}. The result of @code{Exceptions.Exception_Name} for types
-declared within an unnamed @code{block_statement}. See 11.4.1(12).
-@end cartouche
-@noindent
-Blocks have implementation defined names of the form @code{B@var{nnn}}
-where @var{nnn} is an integer.
-
-@sp 1
-@cartouche
-@noindent
-@strong{41}. The information returned by
-@code{Exception_Information}. See 11.4.1(13).
-@end cartouche
-@noindent
-@code{Exception_Information} returns a string in the following format:
-
-@smallexample
-@emph{Exception_Name:} nnnnn
-@emph{Message:} mmmmm
-@emph{PID:} ppp
-@emph{Call stack traceback locations:}
-0xhhhh 0xhhhh 0xhhhh ... 0xhhh
-@end smallexample
-
-@noindent
-where
-
-@itemize @bullet
-@item
-@code{nnnn} is the fully qualified name of the exception in all upper
-case letters. This line is always present.
-
-@item
-@code{mmmm} is the message (this line present only if message is non-null)
-
-@item
-@code{ppp} is the Process Id value as a decimal integer (this line is
-present only if the Process Id is nonzero). Currently we are
-not making use of this field.
-
-@item
-The Call stack traceback locations line and the following values
-are present only if at least one traceback location was recorded.
-The values are given in C style format, with lower case letters
-for a-f, and only as many digits present as are necessary.
-@end itemize
-
-@noindent
-The line terminator sequence at the end of each line, including
-the last line is a single @code{LF} character (@code{16#0A#}).
-
-@sp 1
-@cartouche
-@noindent
-@strong{42}. Implementation-defined check names. See 11.5(27).
-@end cartouche
-@noindent
-The implementation defined check name Alignment_Check controls checking of
-address clause values for proper alignment (that is, the address supplied
-must be consistent with the alignment of the type).
-
-In addition, a user program can add implementation-defined check names
-by means of the pragma Check_Name.
-
-@sp 1
-@cartouche
-@noindent
-@strong{43}. The interpretation of each aspect of representation. See
-13.1(20).
-@end cartouche
-@noindent
-See separate section on data representations.
-
-@sp 1
-@cartouche
-@noindent
-@strong{44}. Any restrictions placed upon representation items. See
-13.1(20).
-@end cartouche
-@noindent
-See separate section on data representations.
-
-@sp 1
-@cartouche
-@noindent
-@strong{45}. The meaning of @code{Size} for indefinite subtypes. See
-13.3(48).
-@end cartouche
-@noindent
-Size for an indefinite subtype is the maximum possible size, except that
-for the case of a subprogram parameter, the size of the parameter object
-is the actual size.
-
-@sp 1
-@cartouche
-@noindent
-@strong{46}. The default external representation for a type tag. See
-13.3(75).
-@end cartouche
-@noindent
-The default external representation for a type tag is the fully expanded
-name of the type in upper case letters.
-
-@sp 1
-@cartouche
-@noindent
-@strong{47}. What determines whether a compilation unit is the same in
-two different partitions. See 13.3(76).
-@end cartouche
-@noindent
-A compilation unit is the same in two different partitions if and only
-if it derives from the same source file.
-
-@sp 1
-@cartouche
-@noindent
-@strong{48}. Implementation-defined components. See 13.5.1(15).
-@end cartouche
-@noindent
-The only implementation defined component is the tag for a tagged type,
-which contains a pointer to the dispatching table.
-
-@sp 1
-@cartouche
-@noindent
-@strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit
-ordering. See 13.5.3(5).
-@end cartouche
-@noindent
-@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
-implementation, so no non-default bit ordering is supported. The default
-bit ordering corresponds to the natural endianness of the target architecture.
-
-@sp 1
-@cartouche
-@noindent
-@strong{50}. The contents of the visible part of package @code{System}
-and its language-defined children. See 13.7(2).
-@end cartouche
-@noindent
-See the definition of these packages in files @file{system.ads} and
-@file{s-stoele.ads}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{51}. The contents of the visible part of package
-@code{System.Machine_Code}, and the meaning of
-@code{code_statements}. See 13.8(7).
-@end cartouche
-@noindent
-See the definition and documentation in file @file{s-maccod.ads}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{52}. The effect of unchecked conversion. See 13.9(11).
-@end cartouche
-@noindent
-Unchecked conversion between types of the same size
-results in an uninterpreted transmission of the bits from one type
-to the other. If the types are of unequal sizes, then in the case of
-discrete types, a shorter source is first zero or sign extended as
-necessary, and a shorter target is simply truncated on the left.
-For all non-discrete types, the source is first copied if necessary
-to ensure that the alignment requirements of the target are met, then
-a pointer is constructed to the source value, and the result is obtained
-by dereferencing this pointer after converting it to be a pointer to the
-target type. Unchecked conversions where the target subtype is an
-unconstrained array are not permitted. If the target alignment is
-greater than the source alignment, then a copy of the result is
-made with appropriate alignment
-
-@sp 1
-@cartouche
-@noindent
-@strong{53}. The manner of choosing a storage pool for an access type
-when @code{Storage_Pool} is not specified for the type. See 13.11(17).
-@end cartouche
-@noindent
-There are 3 different standard pools used by the compiler when
-@code{Storage_Pool} is not specified depending whether the type is local
-to a subprogram or defined at the library level and whether
-@code{Storage_Size}is specified or not. See documentation in the runtime
-library units @code{System.Pool_Global}, @code{System.Pool_Size} and
-@code{System.Pool_Local} in files @file{s-poosiz.ads},
-@file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the
-default pools used.
-
-@sp 1
-@cartouche
-@noindent
-@strong{54}. Whether or not the implementation provides user-accessible
-names for the standard pool type(s). See 13.11(17).
-@end cartouche
-@noindent
-
-See documentation in the sources of the run time mentioned in paragraph
-@strong{53} . All these pools are accessible by means of @code{with}'ing
-these units.
-
-@sp 1
-@cartouche
-@noindent
-@strong{55}. The meaning of @code{Storage_Size}. See 13.11(18).
-@end cartouche
-@noindent
-@code{Storage_Size} is measured in storage units, and refers to the
-total space available for an access type collection, or to the primary
-stack space for a task.
-
-@sp 1
-@cartouche
-@noindent
-@strong{56}. Implementation-defined aspects of storage pools. See
-13.11(22).
-@end cartouche
-@noindent
-See documentation in the sources of the run time mentioned in paragraph
-@strong{53} for details on GNAT-defined aspects of storage pools.
-
-@sp 1
-@cartouche
-@noindent
-@strong{57}. The set of restrictions allowed in a pragma
-@code{Restrictions}. See 13.12(7).
-@end cartouche
-@noindent
-All RM defined Restriction identifiers are implemented. The following
-additional restriction identifiers are provided. There are two separate
-lists of implementation dependent restriction identifiers. The first
-set requires consistency throughout a partition (in other words, if the
-restriction identifier is used for any compilation unit in the partition,
-then all compilation units in the partition must obey the restriction.
-
-@table @code
-
-@item Simple_Barriers
-@findex Simple_Barriers
-This restriction ensures at compile time that barriers in entry declarations
-for protected types are restricted to either static boolean expressions or
-references to simple boolean variables defined in the private part of the
-protected type. No other form of entry barriers is permitted. This is one
-of the restrictions of the Ravenscar profile for limited tasking (see also
-pragma @code{Profile (Ravenscar)}).
-
-@item Max_Entry_Queue_Length => Expr
-@findex Max_Entry_Queue_Length
-This restriction is a declaration that any protected entry compiled in
-the scope of the restriction has at most the specified number of
-tasks waiting on the entry
-at any one time, and so no queue is required. This restriction is not
-checked at compile time. A program execution is erroneous if an attempt
-is made to queue more than the specified number of tasks on such an entry.
-
-@item No_Calendar
-@findex No_Calendar
-This restriction ensures at compile time that there is no implicit or
-explicit dependence on the package @code{Ada.Calendar}.
-
-@item No_Default_Initialization
-@findex No_Default_Initialization
-
-This restriction prohibits any instance of default initialization of variables.
-The binder implements a consistency rule which prevents any unit compiled
-without the restriction from with'ing a unit with the restriction (this allows
-the generation of initialization procedures to be skipped, since you can be
-sure that no call is ever generated to an initialization procedure in a unit
-with the restriction active). If used in conjunction with Initialize_Scalars or
-Normalize_Scalars, the effect is to prohibit all cases of variables declared
-without a specific initializer (including the case of OUT scalar parameters).
-
-@item No_Direct_Boolean_Operators
-@findex No_Direct_Boolean_Operators
-This restriction ensures that no logical (and/or/xor) or comparison
-operators are used on operands of type Boolean (or any type derived
-from Boolean). This is intended for use in safety critical programs
-where the certification protocol requires the use of short-circuit
-(and then, or else) forms for all composite boolean operations.
-
-@item No_Dispatching_Calls
-@findex No_Dispatching_Calls
-This restriction ensures at compile time that the code generated by the
-compiler involves no dispatching calls. The use of this restriction allows the
-safe use of record extensions, classwide membership tests and other classwide
-features not involving implicit dispatching. This restriction ensures that
-the code contains no indirect calls through a dispatching mechanism. Note that
-this includes internally-generated calls created by the compiler, for example
-in the implementation of class-wide objects assignments. The
-membership test is allowed in the presence of this restriction, because its
-implementation requires no dispatching.
-This restriction is comparable to the official Ada restriction
-@code{No_Dispatch} except that it is a bit less restrictive in that it allows
-all classwide constructs that do not imply dispatching.
-The following example indicates constructs that violate this restriction.
-
-@smallexample
-package Pkg is
- type T is tagged record
- Data : Natural;
- end record;
- procedure P (X : T);
-
- type DT is new T with record
- More_Data : Natural;
- end record;
- procedure Q (X : DT);
-end Pkg;
-
-with Pkg; use Pkg;
-procedure Example is
- procedure Test (O : T'Class) is
- N : Natural := O'Size;-- Error: Dispatching call
- C : T'Class := O; -- Error: implicit Dispatching Call
- begin
- if O in DT'Class then -- OK : Membership test
- Q (DT (O)); -- OK : Type conversion plus direct call
- else
- P (O); -- Error: Dispatching call
- end if;
- end Test;
-
- Obj : DT;
-begin
- P (Obj); -- OK : Direct call
- P (T (Obj)); -- OK : Type conversion plus direct call
- P (T'Class (Obj)); -- Error: Dispatching call
-
- Test (Obj); -- OK : Type conversion
-
- if Obj in T'Class then -- OK : Membership test
- null;
- end if;
-end Example;
-@end smallexample
-
-@item No_Dynamic_Attachment
-@findex No_Dynamic_Attachment
-This restriction ensures that there is no call to any of the operations
-defined in package Ada.Interrupts.
-
-@item No_Enumeration_Maps
-@findex No_Enumeration_Maps
-This restriction ensures at compile time that no operations requiring
-enumeration maps are used (that is Image and Value attributes applied
-to enumeration types).
-
-@item No_Entry_Calls_In_Elaboration_Code
-@findex No_Entry_Calls_In_Elaboration_Code
-This restriction ensures at compile time that no task or protected entry
-calls are made during elaboration code. As a result of the use of this
-restriction, the compiler can assume that no code past an accept statement
-in a task can be executed at elaboration time.
-
-@item No_Exception_Handlers
-@findex No_Exception_Handlers
-This restriction ensures at compile time that there are no explicit
-exception handlers. It also indicates that no exception propagation will
-be provided. In this mode, exceptions may be raised but will result in
-an immediate call to the last chance handler, a routine that the user
-must define with the following profile:
-
-@smallexample @c ada
-procedure Last_Chance_Handler
- (Source_Location : System.Address; Line : Integer);
-pragma Export (C, Last_Chance_Handler,
- "__gnat_last_chance_handler");
-@end smallexample
-
-The parameter is a C null-terminated string representing a message to be
-associated with the exception (typically the source location of the raise
-statement generated by the compiler). The Line parameter when nonzero
-represents the line number in the source program where the raise occurs.
-
-@item No_Exception_Propagation
-@findex No_Exception_Propagation
-This restriction guarantees that exceptions are never propagated to an outer
-subprogram scope). The only case in which an exception may be raised is when
-the handler is statically in the same subprogram, so that the effect of a raise
-is essentially like a goto statement. Any other raise statement (implicit or
-explicit) will be considered unhandled. Exception handlers are allowed, but may
-not contain an exception occurrence identifier (exception choice). In addition
-use of the package GNAT.Current_Exception is not permitted, and reraise
-statements (raise with no operand) are not permitted.
-
-@item No_Exception_Registration
-@findex No_Exception_Registration
-This restriction ensures at compile time that no stream operations for
-types Exception_Id or Exception_Occurrence are used. This also makes it
-impossible to pass exceptions to or from a partition with this restriction
-in a distributed environment. If this exception is active, then the generated
-code is simplified by omitting the otherwise-required global registration
-of exceptions when they are declared.
-
-@item No_Implicit_Conditionals
-@findex No_Implicit_Conditionals
-This restriction ensures that the generated code does not contain any
-implicit conditionals, either by modifying the generated code where possible,
-or by rejecting any construct that would otherwise generate an implicit
-conditional. Note that this check does not include run time constraint
-checks, which on some targets may generate implicit conditionals as
-well. To control the latter, constraint checks can be suppressed in the
-normal manner. Constructs generating implicit conditionals include comparisons
-of composite objects and the Max/Min attributes.
-
-@item No_Implicit_Dynamic_Code
-@findex No_Implicit_Dynamic_Code
-@cindex trampoline
-This restriction prevents the compiler from building ``trampolines''.
-This is a structure that is built on the stack and contains dynamic
-code to be executed at run time. On some targets, a trampoline is
-built for the following features: @code{Access},
-@code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
-nested task bodies; primitive operations of nested tagged types.
-Trampolines do not work on machines that prevent execution of stack
-data. For example, on windows systems, enabling DEP (data execution
-protection) will cause trampolines to raise an exception.
-Trampolines are also quite slow at run time.
-
-On many targets, trampolines have been largely eliminated. Look at the
-version of system.ads for your target --- if it has
-Always_Compatible_Rep equal to False, then trampolines are largely
-eliminated. In particular, a trampoline is built for the following
-features: @code{Address} of a nested subprogram;
-@code{Access} or @code{Unrestricted_Access} of a nested subprogram,
-but only if pragma Favor_Top_Level applies, or the access type has a
-foreign-language convention; primitive operations of nested tagged
-types.
-
-@item No_Implicit_Loops
-@findex No_Implicit_Loops
-This restriction ensures that the generated code does not contain any
-implicit @code{for} loops, either by modifying
-the generated code where possible,
-or by rejecting any construct that would otherwise generate an implicit
-@code{for} loop. If this restriction is active, it is possible to build
-large array aggregates with all static components without generating an
-intermediate temporary, and without generating a loop to initialize individual
-components. Otherwise, a loop is created for arrays larger than about 5000
-scalar components.
-
-@item No_Initialize_Scalars
-@findex No_Initialize_Scalars
-This restriction ensures that no unit in the partition is compiled with
-pragma Initialize_Scalars. This allows the generation of more efficient
-code, and in particular eliminates dummy null initialization routines that
-are otherwise generated for some record and array types.
-
-@item No_Local_Protected_Objects
-@findex No_Local_Protected_Objects
-This restriction ensures at compile time that protected objects are
-only declared at the library level.
-
-@item No_Protected_Type_Allocators
-@findex No_Protected_Type_Allocators
-This restriction ensures at compile time that there are no allocator
-expressions that attempt to allocate protected objects.
-
-@item No_Secondary_Stack
-@findex No_Secondary_Stack
-This restriction ensures at compile time that the generated code does not
-contain any reference to the secondary stack. The secondary stack is used
-to implement functions returning unconstrained objects (arrays or records)
-on some targets.
-
-@item No_Select_Statements
-@findex No_Select_Statements
-This restriction ensures at compile time no select statements of any kind
-are permitted, that is the keyword @code{select} may not appear.
-This is one of the restrictions of the Ravenscar
-profile for limited tasking (see also pragma @code{Profile (Ravenscar)}).
-
-@item No_Standard_Storage_Pools
-@findex No_Standard_Storage_Pools
-This restriction ensures at compile time that no access types
-use the standard default storage pool. Any access type declared must
-have an explicit Storage_Pool attribute defined specifying a
-user-defined storage pool.
-
-@item No_Streams
-@findex No_Streams
-This restriction ensures at compile/bind time that there are no
-stream objects created (and therefore no actual stream operations).
-This restriction does not forbid dependences on the package
-@code{Ada.Streams}. So it is permissible to with
-@code{Ada.Streams} (or another package that does so itself)
-as long as no actual stream objects are created.
-
-@item No_Task_Attributes_Package
-@findex No_Task_Attributes_Package
-This restriction ensures at compile time that there are no implicit or
-explicit dependencies on the package @code{Ada.Task_Attributes}.
-
-@item No_Task_Termination
-@findex No_Task_Termination
-This restriction ensures at compile time that no terminate alternatives
-appear in any task body.
-
-@item No_Tasking
-@findex No_Tasking
-This restriction prevents the declaration of tasks or task types throughout
-the partition. It is similar in effect to the use of @code{Max_Tasks => 0}
-except that violations are caught at compile time and cause an error message
-to be output either by the compiler or binder.
-
-@item Static_Priorities
-@findex Static_Priorities
-This restriction ensures at compile time that all priority expressions
-are static, and that there are no dependencies on the package
-@code{Ada.Dynamic_Priorities}.
-
-@item Static_Storage_Size
-@findex Static_Storage_Size
-This restriction ensures at compile time that any expression appearing
-in a Storage_Size pragma or attribute definition clause is static.
-
-@end table
-
-@noindent
-The second set of implementation dependent restriction identifiers
-does not require partition-wide consistency.
-The restriction may be enforced for a single
-compilation unit without any effect on any of the
-other compilation units in the partition.
-
-@table @code
-
-@item No_Elaboration_Code
-@findex No_Elaboration_Code
-This restriction ensures at compile time that no elaboration code is
-generated. Note that this is not the same condition as is enforced
-by pragma @code{Preelaborate}. There are cases in which pragma
-@code{Preelaborate} still permits code to be generated (e.g.@: code
-to initialize a large array to all zeroes), and there are cases of units
-which do not meet the requirements for pragma @code{Preelaborate},
-but for which no elaboration code is generated. Generally, it is
-the case that preelaborable units will meet the restrictions, with
-the exception of large aggregates initialized with an others_clause,
-and exception declarations (which generate calls to a run-time
-registry procedure). This restriction is enforced on
-a unit by unit basis, it need not be obeyed consistently
-throughout a partition.
-
-In the case of aggregates with others, if the aggregate has a dynamic
-size, there is no way to eliminate the elaboration code (such dynamic
-bounds would be incompatible with @code{Preelaborate} in any case). If
-the bounds are static, then use of this restriction actually modifies
-the code choice of the compiler to avoid generating a loop, and instead
-generate the aggregate statically if possible, no matter how many times
-the data for the others clause must be repeatedly generated.
-
-It is not possible to precisely document
-the constructs which are compatible with this restriction, since,
-unlike most other restrictions, this is not a restriction on the
-source code, but a restriction on the generated object code. For
-example, if the source contains a declaration:
-
-@smallexample
- Val : constant Integer := X;
-@end smallexample
-
-@noindent
-where X is not a static constant, it may be possible, depending
-on complex optimization circuitry, for the compiler to figure
-out the value of X at compile time, in which case this initialization
-can be done by the loader, and requires no initialization code. It
-is not possible to document the precise conditions under which the
-optimizer can figure this out.
-
-Note that this the implementation of this restriction requires full
-code generation. If it is used in conjunction with "semantics only"
-checking, then some cases of violations may be missed.
-
-@item No_Entry_Queue
-@findex No_Entry_Queue
-This restriction is a declaration that any protected entry compiled in
-the scope of the restriction has at most one task waiting on the entry
-at any one time, and so no queue is required. This restriction is not
-checked at compile time. A program execution is erroneous if an attempt
-is made to queue a second task on such an entry.
-
-@item No_Implementation_Attributes
-@findex No_Implementation_Attributes
-This restriction checks at compile time that no GNAT-defined attributes
-are present. With this restriction, the only attributes that can be used
-are those defined in the Ada Reference Manual.
-
-@item No_Implementation_Pragmas
-@findex No_Implementation_Pragmas
-This restriction checks at compile time that no GNAT-defined pragmas
-are present. With this restriction, the only pragmas that can be used
-are those defined in the Ada Reference Manual.
-
-@item No_Implementation_Restrictions
-@findex No_Implementation_Restrictions
-This restriction checks at compile time that no GNAT-defined restriction
-identifiers (other than @code{No_Implementation_Restrictions} itself)
-are present. With this restriction, the only other restriction identifiers
-that can be used are those defined in the Ada Reference Manual.
-
-@item No_Wide_Characters
-@findex No_Wide_Characters
-This restriction ensures at compile time that no uses of the types
-@code{Wide_Character} or @code{Wide_String} or corresponding wide
-wide types
-appear, and that no wide or wide wide string or character literals
-appear in the program (that is literals representing characters not in
-type @code{Character}.
-
-@end table
-
-@sp 1
-@cartouche
-@noindent
-@strong{58}. The consequences of violating limitations on
-@code{Restrictions} pragmas. See 13.12(9).
-@end cartouche
-@noindent
-Restrictions that can be checked at compile time result in illegalities
-if violated. Currently there are no other consequences of violating
-restrictions.
-
-@sp 1
-@cartouche
-@noindent
-@strong{59}. The representation used by the @code{Read} and
-@code{Write} attributes of elementary types in terms of stream
-elements. See 13.13.2(9).
-@end cartouche
-@noindent
-The representation is the in-memory representation of the base type of
-the type, using the number of bits corresponding to the
-@code{@var{type}'Size} value, and the natural ordering of the machine.
-
-@sp 1
-@cartouche
-@noindent
-@strong{60}. The names and characteristics of the numeric subtypes
-declared in the visible part of package @code{Standard}. See A.1(3).
-@end cartouche
-@noindent
-See items describing the integer and floating-point types supported.
-
-@sp 1
-@cartouche
-@noindent
-@strong{61}. The accuracy actually achieved by the elementary
-functions. See A.5.1(1).
-@end cartouche
-@noindent
-The elementary functions correspond to the functions available in the C
-library. Only fast math mode is implemented.
-
-@sp 1
-@cartouche
-@noindent
-@strong{62}. The sign of a zero result from some of the operators or
-functions in @code{Numerics.Generic_Elementary_Functions}, when
-@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).
-@end cartouche
-@noindent
-The sign of zeroes follows the requirements of the IEEE 754 standard on
-floating-point.
-
-@sp 1
-@cartouche
-@noindent
-@strong{63}. The value of
-@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).
-@end cartouche
-@noindent
-Maximum image width is 649, see library file @file{a-numran.ads}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{64}. The value of
-@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).
-@end cartouche
-@noindent
-Maximum image width is 80, see library file @file{a-nudira.ads}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{65}. The algorithms for random number generation. See
-A.5.2(32).
-@end cartouche
-@noindent
-The algorithm is documented in the source files @file{a-numran.ads} and
-@file{a-numran.adb}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{66}. The string representation of a random number generator's
-state. See A.5.2(38).
-@end cartouche
-@noindent
-See the documentation contained in the file @file{a-numran.adb}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{67}. The minimum time interval between calls to the
-time-dependent Reset procedure that are guaranteed to initiate different
-random number sequences. See A.5.2(45).
-@end cartouche
-@noindent
-The minimum period between reset calls to guarantee distinct series of
-random numbers is one microsecond.
-
-@sp 1
-@cartouche
-@noindent
-@strong{68}. The values of the @code{Model_Mantissa},
-@code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
-@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
-Annex is not supported. See A.5.3(72).
-@end cartouche
-@noindent
-See the source file @file{ttypef.ads} for the values of all numeric
-attributes.
-
-@sp 1
-@cartouche
-@noindent
-@strong{69}. Any implementation-defined characteristics of the
-input-output packages. See A.7(14).
-@end cartouche
-@noindent
-There are no special implementation defined characteristics for these
-packages.
-
-@sp 1
-@cartouche
-@noindent
-@strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See
-A.9(10).
-@end cartouche
-@noindent
-All type representations are contiguous, and the @code{Buffer_Size} is
-the value of @code{@var{type}'Size} rounded up to the next storage unit
-boundary.
-
-@sp 1
-@cartouche
-@noindent
-@strong{71}. External files for standard input, standard output, and
-standard error See A.10(5).
-@end cartouche
-@noindent
-These files are mapped onto the files provided by the C streams
-libraries. See source file @file{i-cstrea.ads} for further details.
-
-@sp 1
-@cartouche
-@noindent
-@strong{72}. The accuracy of the value produced by @code{Put}. See
-A.10.9(36).
-@end cartouche
-@noindent
-If more digits are requested in the output than are represented by the
-precision of the value, zeroes are output in the corresponding least
-significant digit positions.
-
-@sp 1
-@cartouche
-@noindent
-@strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and
-@code{Command_Name}. See A.15(1).
-@end cartouche
-@noindent
-These are mapped onto the @code{argv} and @code{argc} parameters of the
-main program in the natural manner.
-
-@sp 1
-@cartouche
-@noindent
-@strong{74}. Implementation-defined convention names. See B.1(11).
-@end cartouche
-@noindent
-The following convention names are supported
-
-@table @code
-@item Ada
-Ada
-@item Assembler
-Assembly language
-@item Asm
-Synonym for Assembler
-@item Assembly
-Synonym for Assembler
-@item C
-C
-@item C_Pass_By_Copy
-Allowed only for record types, like C, but also notes that record
-is to be passed by copy rather than reference.
-@item COBOL
-COBOL
-@item C_Plus_Plus (or CPP)
-C++
-@item Default
-Treated the same as C
-@item External
-Treated the same as C
-@item Fortran
-Fortran
-@item Intrinsic
-For support of pragma @code{Import} with convention Intrinsic, see
-separate section on Intrinsic Subprograms.
-@item Stdcall
-Stdcall (used for Windows implementations only). This convention correspond
-to the WINAPI (previously called Pascal convention) C/C++ convention under
-Windows. A function with this convention cleans the stack before exit.
-@item DLL
-Synonym for Stdcall
-@item Win32
-Synonym for Stdcall
-@item Stubbed
-Stubbed is a special convention used to indicate that the body of the
-subprogram will be entirely ignored. Any call to the subprogram
-is converted into a raise of the @code{Program_Error} exception. If a
-pragma @code{Import} specifies convention @code{stubbed} then no body need
-be present at all. This convention is useful during development for the
-inclusion of subprograms whose body has not yet been written.
-
-@end table
-@noindent
-In addition, all otherwise unrecognized convention names are also
-treated as being synonymous with convention C@. In all implementations
-except for VMS, use of such other names results in a warning. In VMS
-implementations, these names are accepted silently.
-
-@sp 1
-@cartouche
-@noindent
-@strong{75}. The meaning of link names. See B.1(36).
-@end cartouche
-@noindent
-Link names are the actual names used by the linker.
-
-@sp 1
-@cartouche
-@noindent
-@strong{76}. The manner of choosing link names when neither the link
-name nor the address of an imported or exported entity is specified. See
-B.1(36).
-@end cartouche
-@noindent
-The default linker name is that which would be assigned by the relevant
-external language, interpreting the Ada name as being in all lower case
-letters.
-
-@sp 1
-@cartouche
-@noindent
-@strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37).
-@end cartouche
-@noindent
-The string passed to @code{Linker_Options} is presented uninterpreted as
-an argument to the link command, unless it contains ASCII.NUL characters.
-NUL characters if they appear act as argument separators, so for example
-
-@smallexample @c ada
-pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
-@end smallexample
-
-@noindent
-causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
-linker. The order of linker options is preserved for a given unit. The final
-list of options passed to the linker is in reverse order of the elaboration
-order. For example, linker options for a body always appear before the options
-from the corresponding package spec.
-
-@sp 1
-@cartouche
-@noindent
-@strong{78}. The contents of the visible part of package
-@code{Interfaces} and its language-defined descendants. See B.2(1).
-@end cartouche
-@noindent
-See files with prefix @file{i-} in the distributed library.
-
-@sp 1
-@cartouche
-@noindent
-@strong{79}. Implementation-defined children of package
-@code{Interfaces}. The contents of the visible part of package
-@code{Interfaces}. See B.2(11).
-@end cartouche
-@noindent
-See files with prefix @file{i-} in the distributed library.
-
-@sp 1
-@cartouche
-@noindent
-@strong{80}. The types @code{Floating}, @code{Long_Floating},
-@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
-@code{COBOL_Character}; and the initialization of the variables
-@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
-@code{Interfaces.COBOL}. See B.4(50).
-@end cartouche
-@noindent
-@table @code
-@item Floating
-Float
-@item Long_Floating
-(Floating) Long_Float
-@item Binary
-Integer
-@item Long_Binary
-Long_Long_Integer
-@item Decimal_Element
-Character
-@item COBOL_Character
-Character
-@end table
-
-@noindent
-For initialization, see the file @file{i-cobol.ads} in the distributed library.
-
-@sp 1
-@cartouche
-@noindent
-@strong{81}. Support for access to machine instructions. See C.1(1).
-@end cartouche
-@noindent
-See documentation in file @file{s-maccod.ads} in the distributed library.
-
-@sp 1
-@cartouche
-@noindent
-@strong{82}. Implementation-defined aspects of access to machine
-operations. See C.1(9).
-@end cartouche
-@noindent
-See documentation in file @file{s-maccod.ads} in the distributed library.
-
-@sp 1
-@cartouche
-@noindent
-@strong{83}. Implementation-defined aspects of interrupts. See C.3(2).
-@end cartouche
-@noindent
-Interrupts are mapped to signals or conditions as appropriate. See
-definition of unit
-@code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details
-on the interrupts supported on a particular target.
-
-@sp 1
-@cartouche
-@noindent
-@strong{84}. Implementation-defined aspects of pre-elaboration. See
-C.4(13).
-@end cartouche
-@noindent
-GNAT does not permit a partition to be restarted without reloading,
-except under control of the debugger.
-
-@sp 1
-@cartouche
-@noindent
-@strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7).
-@end cartouche
-@noindent
-Pragma @code{Discard_Names} causes names of enumeration literals to
-be suppressed. In the presence of this pragma, the Image attribute
-provides the image of the Pos of the literal, and Value accepts
-Pos values.
-
-@sp 1
-@cartouche
-@noindent
-@strong{86}. The result of the @code{Task_Identification.Image}
-attribute. See C.7.1(7).
-@end cartouche
-@noindent
-The result of this attribute is a string that identifies
-the object or component that denotes a given task. If a variable @code{Var}
-has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}},
-where the suffix
-is the hexadecimal representation of the virtual address of the corresponding
-task control block. If the variable is an array of tasks, the image of each
-task will have the form of an indexed component indicating the position of a
-given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a
-component of a record, the image of the task will have the form of a selected
-component. These rules are fully recursive, so that the image of a task that
-is a subcomponent of a composite object corresponds to the expression that
-designates this task.
-@noindent
-If a task is created by an allocator, its image depends on the context. If the
-allocator is part of an object declaration, the rules described above are used
-to construct its image, and this image is not affected by subsequent
-assignments. If the allocator appears within an expression, the image
-includes only the name of the task type.
-@noindent
-If the configuration pragma Discard_Names is present, or if the restriction
-No_Implicit_Heap_Allocation is in effect, the image reduces to
-the numeric suffix, that is to say the hexadecimal representation of the
-virtual address of the control block of the task.
-@sp 1
-@cartouche
-@noindent
-@strong{87}. The value of @code{Current_Task} when in a protected entry
-or interrupt handler. See C.7.1(17).
-@end cartouche
-@noindent
-Protected entries or interrupt handlers can be executed by any
-convenient thread, so the value of @code{Current_Task} is undefined.
-
-@sp 1
-@cartouche
-@noindent
-@strong{88}. The effect of calling @code{Current_Task} from an entry
-body or interrupt handler. See C.7.1(19).
-@end cartouche
-@noindent
-The effect of calling @code{Current_Task} from an entry body or
-interrupt handler is to return the identification of the task currently
-executing the code.
-
-@sp 1
-@cartouche
-@noindent
-@strong{89}. Implementation-defined aspects of
-@code{Task_Attributes}. See C.7.2(19).
-@end cartouche
-@noindent
-There are no implementation-defined aspects of @code{Task_Attributes}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{90}. Values of all @code{Metrics}. See D(2).
-@end cartouche
-@noindent
-The metrics information for GNAT depends on the performance of the
-underlying operating system. The sources of the run-time for tasking
-implementation, together with the output from @option{-gnatG} can be
-used to determine the exact sequence of operating systems calls made
-to implement various tasking constructs. Together with appropriate
-information on the performance of the underlying operating system,
-on the exact target in use, this information can be used to determine
-the required metrics.
-
-@sp 1
-@cartouche
-@noindent
-@strong{91}. The declarations of @code{Any_Priority} and
-@code{Priority}. See D.1(11).
-@end cartouche
-@noindent
-See declarations in file @file{system.ads}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{92}. Implementation-defined execution resources. See D.1(15).
-@end cartouche
-@noindent
-There are no implementation-defined execution resources.
-
-@sp 1
-@cartouche
-@noindent
-@strong{93}. Whether, on a multiprocessor, a task that is waiting for
-access to a protected object keeps its processor busy. See D.2.1(3).
-@end cartouche
-@noindent
-On a multi-processor, a task that is waiting for access to a protected
-object does not keep its processor busy.
-
-@sp 1
-@cartouche
-@noindent
-@strong{94}. The affect of implementation defined execution resources
-on task dispatching. See D.2.1(9).
-@end cartouche
-@noindent
-@c SGI info
-@ignore
-Tasks map to IRIX threads, and the dispatching policy is as defined by
-the IRIX implementation of threads.
-@end ignore
-Tasks map to threads in the threads package used by GNAT@. Where possible
-and appropriate, these threads correspond to native threads of the
-underlying operating system.
-
-@sp 1
-@cartouche
-@noindent
-@strong{95}. Implementation-defined @code{policy_identifiers} allowed
-in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3).
-@end cartouche
-@noindent
-There are no implementation-defined policy-identifiers allowed in this
-pragma.
-
-@sp 1
-@cartouche
-@noindent
-@strong{96}. Implementation-defined aspects of priority inversion. See
-D.2.2(16).
-@end cartouche
-@noindent
-Execution of a task cannot be preempted by the implementation processing
-of delay expirations for lower priority tasks.
-
-@sp 1
-@cartouche
-@noindent
-@strong{97}. Implementation defined task dispatching. See D.2.2(18).
-@end cartouche
-@noindent
-@c SGI info:
-@ignore
-Tasks map to IRIX threads, and the dispatching policy is as defined by
-the IRIX implementation of threads.
-@end ignore
-The policy is the same as that of the underlying threads implementation.
-
-@sp 1
-@cartouche
-@noindent
-@strong{98}. Implementation-defined @code{policy_identifiers} allowed
-in a pragma @code{Locking_Policy}. See D.3(4).
-@end cartouche
-@noindent
-The only implementation defined policy permitted in GNAT is
-@code{Inheritance_Locking}. On targets that support this policy, locking
-is implemented by inheritance, i.e.@: the task owning the lock operates
-at a priority equal to the highest priority of any task currently
-requesting the lock.
-
-@sp 1
-@cartouche
-@noindent
-@strong{99}. Default ceiling priorities. See D.3(10).
-@end cartouche
-@noindent
-The ceiling priority of protected objects of the type
-@code{System.Interrupt_Priority'Last} as described in the Ada
-Reference Manual D.3(10),
-
-@sp 1
-@cartouche
-@noindent
-@strong{100}. The ceiling of any protected object used internally by
-the implementation. See D.3(16).
-@end cartouche
-@noindent
-The ceiling priority of internal protected objects is
-@code{System.Priority'Last}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{101}. Implementation-defined queuing policies. See D.4(1).
-@end cartouche
-@noindent
-There are no implementation-defined queuing policies.
-
-@sp 1
-@cartouche
-@noindent
-@strong{102}. On a multiprocessor, any conditions that cause the
-completion of an aborted construct to be delayed later than what is
-specified for a single processor. See D.6(3).
-@end cartouche
-@noindent
-The semantics for abort on a multi-processor is the same as on a single
-processor, there are no further delays.
-
-@sp 1
-@cartouche
-@noindent
-@strong{103}. Any operations that implicitly require heap storage
-allocation. See D.7(8).
-@end cartouche
-@noindent
-The only operation that implicitly requires heap storage allocation is
-task creation.
-
-@sp 1
-@cartouche
-@noindent
-@strong{104}. Implementation-defined aspects of pragma
-@code{Restrictions}. See D.7(20).
-@end cartouche
-@noindent
-There are no such implementation-defined aspects.
-
-@sp 1
-@cartouche
-@noindent
-@strong{105}. Implementation-defined aspects of package
-@code{Real_Time}. See D.8(17).
-@end cartouche
-@noindent
-There are no implementation defined aspects of package @code{Real_Time}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{106}. Implementation-defined aspects of
-@code{delay_statements}. See D.9(8).
-@end cartouche
-@noindent
-Any difference greater than one microsecond will cause the task to be
-delayed (see D.9(7)).
-
-@sp 1
-@cartouche
-@noindent
-@strong{107}. The upper bound on the duration of interrupt blocking
-caused by the implementation. See D.12(5).
-@end cartouche
-@noindent
-The upper bound is determined by the underlying operating system. In
-no cases is it more than 10 milliseconds.
-
-@sp 1
-@cartouche
-@noindent
-@strong{108}. The means for creating and executing distributed
-programs. See E(5).
-@end cartouche
-@noindent
-The GLADE package provides a utility GNATDIST for creating and executing
-distributed programs. See the GLADE reference manual for further details.
-
-@sp 1
-@cartouche
-@noindent
-@strong{109}. Any events that can result in a partition becoming
-inaccessible. See E.1(7).
-@end cartouche
-@noindent
-See the GLADE reference manual for full details on such events.
-
-@sp 1
-@cartouche
-@noindent
-@strong{110}. The scheduling policies, treatment of priorities, and
-management of shared resources between partitions in certain cases. See
-E.1(11).
-@end cartouche
-@noindent
-See the GLADE reference manual for full details on these aspects of
-multi-partition execution.
-
-@sp 1
-@cartouche
-@noindent
-@strong{111}. Events that cause the version of a compilation unit to
-change. See E.3(5).
-@end cartouche
-@noindent
-Editing the source file of a compilation unit, or the source files of
-any units on which it is dependent in a significant way cause the version
-to change. No other actions cause the version number to change. All changes
-are significant except those which affect only layout, capitalization or
-comments.
-
-@sp 1
-@cartouche
-@noindent
-@strong{112}. Whether the execution of the remote subprogram is
-immediately aborted as a result of cancellation. See E.4(13).
-@end cartouche
-@noindent
-See the GLADE reference manual for details on the effect of abort in
-a distributed application.
-
-@sp 1
-@cartouche
-@noindent
-@strong{113}. Implementation-defined aspects of the PCS@. See E.5(25).
-@end cartouche
-@noindent
-See the GLADE reference manual for a full description of all implementation
-defined aspects of the PCS@.
-
-@sp 1
-@cartouche
-@noindent
-@strong{114}. Implementation-defined interfaces in the PCS@. See
-E.5(26).
-@end cartouche
-@noindent
-See the GLADE reference manual for a full description of all
-implementation defined interfaces.
-
-@sp 1
-@cartouche
-@noindent
-@strong{115}. The values of named numbers in the package
-@code{Decimal}. See F.2(7).
-@end cartouche
-@noindent
-@table @code
-@item Max_Scale
-+18
-@item Min_Scale
--18
-@item Min_Delta
-1.0E-18
-@item Max_Delta
-1.0E+18
-@item Max_Decimal_Digits
-18
-@end table
-
-@sp 1
-@cartouche
-@noindent
-@strong{116}. The value of @code{Max_Picture_Length} in the package
-@code{Text_IO.Editing}. See F.3.3(16).
-@end cartouche
-@noindent
-64
-
-@sp 1
-@cartouche
-@noindent
-@strong{117}. The value of @code{Max_Picture_Length} in the package
-@code{Wide_Text_IO.Editing}. See F.3.4(5).
-@end cartouche
-@noindent
-64
-
-@sp 1
-@cartouche
-@noindent
-@strong{118}. The accuracy actually achieved by the complex elementary
-functions and by other complex arithmetic operations. See G.1(1).
-@end cartouche
-@noindent
-Standard library functions are used for the complex arithmetic
-operations. Only fast math mode is currently supported.
-
-@sp 1
-@cartouche
-@noindent
-@strong{119}. The sign of a zero result (or a component thereof) from
-any operator or function in @code{Numerics.Generic_Complex_Types}, when
-@code{Real'Signed_Zeros} is True. See G.1.1(53).
-@end cartouche
-@noindent
-The signs of zero values are as recommended by the relevant
-implementation advice.
-
-@sp 1
-@cartouche
-@noindent
-@strong{120}. The sign of a zero result (or a component thereof) from
-any operator or function in
-@code{Numerics.Generic_Complex_Elementary_Functions}, when
-@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).
-@end cartouche
-@noindent
-The signs of zero values are as recommended by the relevant
-implementation advice.
-
-@sp 1
-@cartouche
-@noindent
-@strong{121}. Whether the strict mode or the relaxed mode is the
-default. See G.2(2).
-@end cartouche
-@noindent
-The strict mode is the default. There is no separate relaxed mode. GNAT
-provides a highly efficient implementation of strict mode.
-
-@sp 1
-@cartouche
-@noindent
-@strong{122}. The result interval in certain cases of fixed-to-float
-conversion. See G.2.1(10).
-@end cartouche
-@noindent
-For cases where the result interval is implementation dependent, the
-accuracy is that provided by performing all operations in 64-bit IEEE
-floating-point format.
-
-@sp 1
-@cartouche
-@noindent
-@strong{123}. The result of a floating point arithmetic operation in
-overflow situations, when the @code{Machine_Overflows} attribute of the
-result type is @code{False}. See G.2.1(13).
-@end cartouche
-@noindent
-Infinite and NaN values are produced as dictated by the IEEE
-floating-point standard.
-
-Note that on machines that are not fully compliant with the IEEE
-floating-point standard, such as Alpha, the @option{-mieee} compiler flag
-must be used for achieving IEEE confirming behavior (although at the cost
-of a significant performance penalty), so infinite and NaN values are
-properly generated.
-
-@sp 1
-@cartouche
-@noindent
-@strong{124}. The result interval for division (or exponentiation by a
-negative exponent), when the floating point hardware implements division
-as multiplication by a reciprocal. See G.2.1(16).
-@end cartouche
-@noindent
-Not relevant, division is IEEE exact.
-
-@sp 1
-@cartouche
-@noindent
-@strong{125}. The definition of close result set, which determines the
-accuracy of certain fixed point multiplications and divisions. See
-G.2.3(5).
-@end cartouche
-@noindent
-Operations in the close result set are performed using IEEE long format
-floating-point arithmetic. The input operands are converted to
-floating-point, the operation is done in floating-point, and the result
-is converted to the target type.
-
-@sp 1
-@cartouche
-@noindent
-@strong{126}. Conditions on a @code{universal_real} operand of a fixed
-point multiplication or division for which the result shall be in the
-perfect result set. See G.2.3(22).
-@end cartouche
-@noindent
-The result is only defined to be in the perfect result set if the result
-can be computed by a single scaling operation involving a scale factor
-representable in 64-bits.
-
-@sp 1
-@cartouche
-@noindent
-@strong{127}. The result of a fixed point arithmetic operation in
-overflow situations, when the @code{Machine_Overflows} attribute of the
-result type is @code{False}. See G.2.3(27).
-@end cartouche
-@noindent
-Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
-types.
-
-@sp 1
-@cartouche
-@noindent
-@strong{128}. The result of an elementary function reference in
-overflow situations, when the @code{Machine_Overflows} attribute of the
-result type is @code{False}. See G.2.4(4).
-@end cartouche
-@noindent
-IEEE infinite and Nan values are produced as appropriate.
-
-@sp 1
-@cartouche
-@noindent
-@strong{129}. The value of the angle threshold, within which certain
-elementary functions, complex arithmetic operations, and complex
-elementary functions yield results conforming to a maximum relative
-error bound. See G.2.4(10).
-@end cartouche
-@noindent
-Information on this subject is not yet available.
-
-@sp 1
-@cartouche
-@noindent
-@strong{130}. The accuracy of certain elementary functions for
-parameters beyond the angle threshold. See G.2.4(10).
-@end cartouche
-@noindent
-Information on this subject is not yet available.
-
-@sp 1
-@cartouche
-@noindent
-@strong{131}. The result of a complex arithmetic operation or complex
-elementary function reference in overflow situations, when the
-@code{Machine_Overflows} attribute of the corresponding real type is
-@code{False}. See G.2.6(5).
-@end cartouche
-@noindent
-IEEE infinite and Nan values are produced as appropriate.
-
-@sp 1
-@cartouche
-@noindent
-@strong{132}. The accuracy of certain complex arithmetic operations and
-certain complex elementary functions for parameters (or components
-thereof) beyond the angle threshold. See G.2.6(8).
-@end cartouche
-@noindent
-Information on those subjects is not yet available.
-
-@sp 1
-@cartouche
-@noindent
-@strong{133}. Information regarding bounded errors and erroneous
-execution. See H.2(1).
-@end cartouche
-@noindent
-Information on this subject is not yet available.
-
-@sp 1
-@cartouche
-@noindent
-@strong{134}. Implementation-defined aspects of pragma
-@code{Inspection_Point}. See H.3.2(8).
-@end cartouche
-@noindent
-Pragma @code{Inspection_Point} ensures that the variable is live and can
-be examined by the debugger at the inspection point.
-
-@sp 1
-@cartouche
-@noindent
-@strong{135}. Implementation-defined aspects of pragma
-@code{Restrictions}. See H.4(25).
-@end cartouche
-@noindent
-There are no implementation-defined aspects of pragma @code{Restrictions}. The
-use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
-generated code. Checks must suppressed by use of pragma @code{Suppress}.
-
-@sp 1
-@cartouche
-@noindent
-@strong{136}. Any restrictions on pragma @code{Restrictions}. See
-H.4(27).
-@end cartouche
-@noindent
-There are no restrictions on pragma @code{Restrictions}.
-
-@node Intrinsic Subprograms
-@chapter Intrinsic Subprograms
-@cindex Intrinsic Subprograms
-
-@menu
-* Intrinsic Operators::
-* Enclosing_Entity::
-* Exception_Information::
-* Exception_Message::
-* Exception_Name::
-* File::
-* Line::
-* Rotate_Left::
-* Rotate_Right::
-* Shift_Left::
-* Shift_Right::
-* Shift_Right_Arithmetic::
-* Source_Location::
-@end menu
-
-@noindent
-GNAT allows a user application program to write the declaration:
-
-@smallexample @c ada
- pragma Import (Intrinsic, name);
-@end smallexample
-
-@noindent
-providing that the name corresponds to one of the implemented intrinsic
-subprograms in GNAT, and that the parameter profile of the referenced
-subprogram meets the requirements. This chapter describes the set of
-implemented intrinsic subprograms, and the requirements on parameter profiles.
-Note that no body is supplied; as with other uses of pragma Import, the
-body is supplied elsewhere (in this case by the compiler itself). Note
-that any use of this feature is potentially non-portable, since the
-Ada standard does not require Ada compilers to implement this feature.
-
-@node Intrinsic Operators
-@section Intrinsic Operators
-@cindex Intrinsic operator
-
-@noindent
-All the predefined numeric operators in package Standard
-in @code{pragma Import (Intrinsic,..)}
-declarations. In the binary operator case, the operands must have the same
-size. The operand or operands must also be appropriate for
-the operator. For example, for addition, the operands must
-both be floating-point or both be fixed-point, and the
-right operand for @code{"**"} must have a root type of
-@code{Standard.Integer'Base}.
-You can use an intrinsic operator declaration as in the following example:
-
-@smallexample @c ada
- type Int1 is new Integer;
- type Int2 is new Integer;
-
- function "+" (X1 : Int1; X2 : Int2) return Int1;
- function "+" (X1 : Int1; X2 : Int2) return Int2;
- pragma Import (Intrinsic, "+");
-@end smallexample
-
-@noindent
-This declaration would permit ``mixed mode'' arithmetic on items
-of the differing types @code{Int1} and @code{Int2}.
-It is also possible to specify such operators for private types, if the
-full views are appropriate arithmetic types.
-
-@node Enclosing_Entity
-@section Enclosing_Entity
-@cindex Enclosing_Entity
-@noindent
-This intrinsic subprogram is used in the implementation of the
-library routine @code{GNAT.Source_Info}. The only useful use of the
-intrinsic import in this case is the one in this unit, so an
-application program should simply call the function
-@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
-the current subprogram, package, task, entry, or protected subprogram.
-
-@node Exception_Information
-@section Exception_Information
-@cindex Exception_Information'
-@noindent
-This intrinsic subprogram is used in the implementation of the
-library routine @code{GNAT.Current_Exception}. The only useful
-use of the intrinsic import in this case is the one in this unit,
-so an application program should simply call the function
-@code{GNAT.Current_Exception.Exception_Information} to obtain
-the exception information associated with the current exception.
-
-@node Exception_Message
-@section Exception_Message
-@cindex Exception_Message
-@noindent
-This intrinsic subprogram is used in the implementation of the
-library routine @code{GNAT.Current_Exception}. The only useful
-use of the intrinsic import in this case is the one in this unit,
-so an application program should simply call the function
-@code{GNAT.Current_Exception.Exception_Message} to obtain
-the message associated with the current exception.
-
-@node Exception_Name
-@section Exception_Name
-@cindex Exception_Name
-@noindent
-This intrinsic subprogram is used in the implementation of the
-library routine @code{GNAT.Current_Exception}. The only useful
-use of the intrinsic import in this case is the one in this unit,
-so an application program should simply call the function
-@code{GNAT.Current_Exception.Exception_Name} to obtain
-the name of the current exception.
-
-@node File
-@section File
-@cindex File
-@noindent
-This intrinsic subprogram is used in the implementation of the
-library routine @code{GNAT.Source_Info}. The only useful use of the
-intrinsic import in this case is the one in this unit, so an
-application program should simply call the function
-@code{GNAT.Source_Info.File} to obtain the name of the current
-file.
-
-@node Line
-@section Line
-@cindex Line
-@noindent
-This intrinsic subprogram is used in the implementation of the
-library routine @code{GNAT.Source_Info}. The only useful use of the
-intrinsic import in this case is the one in this unit, so an
-application program should simply call the function
-@code{GNAT.Source_Info.Line} to obtain the number of the current
-source line.
-
-@node Rotate_Left
-@section Rotate_Left
-@cindex Rotate_Left
-@noindent
-In standard Ada, the @code{Rotate_Left} function is available only
-for the predefined modular types in package @code{Interfaces}. However, in
-GNAT it is possible to define a Rotate_Left function for a user
-defined modular type or any signed integer type as in this example:
-
-@smallexample @c ada
- function Shift_Left
- (Value : My_Modular_Type;
- Amount : Natural)
- return My_Modular_Type;
-@end smallexample
-
-@noindent
-The requirements are that the profile be exactly as in the example
-above. The only modifications allowed are in the formal parameter
-names, and in the type of @code{Value} and the return type, which
-must be the same, and must be either a signed integer type, or
-a modular integer type with a binary modulus, and the size must
-be 8. 16, 32 or 64 bits.
-
-@node Rotate_Right
-@section Rotate_Right
-@cindex Rotate_Right
-@noindent
-A @code{Rotate_Right} function can be defined for any user defined
-binary modular integer type, or signed integer type, as described
-above for @code{Rotate_Left}.
-
-@node Shift_Left
-@section Shift_Left
-@cindex Shift_Left
-@noindent
-A @code{Shift_Left} function can be defined for any user defined
-binary modular integer type, or signed integer type, as described
-above for @code{Rotate_Left}.
-
-@node Shift_Right
-@section Shift_Right
-@cindex Shift_Right
-@noindent
-A @code{Shift_Right} function can be defined for any user defined
-binary modular integer type, or signed integer type, as described
-above for @code{Rotate_Left}.
-
-@node Shift_Right_Arithmetic
-@section Shift_Right_Arithmetic
-@cindex Shift_Right_Arithmetic
-@noindent
-A @code{Shift_Right_Arithmetic} function can be defined for any user
-defined binary modular integer type, or signed integer type, as described
-above for @code{Rotate_Left}.
-
-@node Source_Location
-@section Source_Location
-@cindex Source_Location
-@noindent
-This intrinsic subprogram is used in the implementation of the
-library routine @code{GNAT.Source_Info}. The only useful use of the
-intrinsic import in this case is the one in this unit, so an
-application program should simply call the function
-@code{GNAT.Source_Info.Source_Location} to obtain the current
-source file location.
-
-@node Representation Clauses and Pragmas
-@chapter Representation Clauses and Pragmas
-@cindex Representation Clauses
-
-@menu
-* Alignment Clauses::
-* Size Clauses::
-* Storage_Size Clauses::
-* Size of Variant Record Objects::
-* Biased Representation ::
-* Value_Size and Object_Size Clauses::
-* Component_Size Clauses::
-* Bit_Order Clauses::
-* Effect of Bit_Order on Byte Ordering::
-* Pragma Pack for Arrays::
-* Pragma Pack for Records::
-* Record Representation Clauses::
-* Enumeration Clauses::
-* Address Clauses::
-* Effect of Convention on Representation::
-* Determining the Representations chosen by GNAT::
-@end menu
-
-@noindent
-@cindex Representation Clause
-@cindex Representation Pragma
-@cindex Pragma, representation
-This section describes the representation clauses accepted by GNAT, and
-their effect on the representation of corresponding data objects.
-
-GNAT fully implements Annex C (Systems Programming). This means that all
-the implementation advice sections in chapter 13 are fully implemented.
-However, these sections only require a minimal level of support for
-representation clauses. GNAT provides much more extensive capabilities,
-and this section describes the additional capabilities provided.
-
-@node Alignment Clauses
-@section Alignment Clauses
-@cindex Alignment Clause
-
-@noindent
-GNAT requires that all alignment clauses specify a power of 2, and all
-default alignments are always a power of 2. The default alignment
-values are as follows:
-
-@itemize @bullet
-@item @emph{Primitive Types}.
-For primitive types, the alignment is the minimum of the actual size of
-objects of the type divided by @code{Storage_Unit},
-and the maximum alignment supported by the target.
-(This maximum alignment is given by the GNAT-specific attribute
-@code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.)
-@cindex @code{Maximum_Alignment} attribute
-For example, for type @code{Long_Float}, the object size is 8 bytes, and the
-default alignment will be 8 on any target that supports alignments
-this large, but on some targets, the maximum alignment may be smaller
-than 8, in which case objects of type @code{Long_Float} will be maximally
-aligned.
-
-@item @emph{Arrays}.
-For arrays, the alignment is equal to the alignment of the component type
-for the normal case where no packing or component size is given. If the
-array is packed, and the packing is effective (see separate section on
-packed arrays), then the alignment will be one for long packed arrays,
-or arrays whose length is not known at compile time. For short packed
-arrays, which are handled internally as modular types, the alignment
-will be as described for primitive types, e.g.@: a packed array of length
-31 bits will have an object size of four bytes, and an alignment of 4.
-
-@item @emph{Records}.
-For the normal non-packed case, the alignment of a record is equal to
-the maximum alignment of any of its components. For tagged records, this
-includes the implicit access type used for the tag. If a pragma @code{Pack}
-is used and all components are packable (see separate section on pragma
-@code{Pack}), then the resulting alignment is 1, unless the layout of the
-record makes it profitable to increase it.
-
-A special case is when:
-@itemize @bullet
-@item
-the size of the record is given explicitly, or a
-full record representation clause is given, and
-@item
-the size of the record is 2, 4, or 8 bytes.
-@end itemize
-@noindent
-In this case, an alignment is chosen to match the
-size of the record. For example, if we have:
-
-@smallexample @c ada
- type Small is record
- A, B : Character;
- end record;
- for Small'Size use 16;
-@end smallexample
-
-@noindent
-then the default alignment of the record type @code{Small} is 2, not 1. This
-leads to more efficient code when the record is treated as a unit, and also
-allows the type to specified as @code{Atomic} on architectures requiring
-strict alignment.
-
-@end itemize
-
-@noindent
-An alignment clause may specify a larger alignment than the default value
-up to some maximum value dependent on the target (obtainable by using the
-attribute reference @code{Standard'Maximum_Alignment}). It may also specify
-a smaller alignment than the default value for enumeration, integer and
-fixed point types, as well as for record types, for example
-
-@smallexample @c ada
- type V is record
- A : Integer;
- end record;
-
- for V'alignment use 1;
-@end smallexample
-
-@noindent
-@cindex Alignment, default
-The default alignment for the type @code{V} is 4, as a result of the
-Integer field in the record, but it is permissible, as shown, to
-override the default alignment of the record with a smaller value.
-
-@node Size Clauses
-@section Size Clauses
-@cindex Size Clause
-
-@noindent
-The default size for a type @code{T} is obtainable through the
-language-defined attribute @code{T'Size} and also through the
-equivalent GNAT-defined attribute @code{T'Value_Size}.
-For objects of type @code{T}, GNAT will generally increase the type size
-so that the object size (obtainable through the GNAT-defined attribute
-@code{T'Object_Size})
-is a multiple of @code{T'Alignment * Storage_Unit}.
-For example
-
-@smallexample @c ada
- type Smallint is range 1 .. 6;
-
- type Rec is record
- Y1 : integer;
- Y2 : boolean;
- end record;
-@end smallexample
-
-@noindent
-In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
-as specified by the RM rules,
-but objects of this type will have a size of 8
-(@code{Smallint'Object_Size} = 8),
-since objects by default occupy an integral number
-of storage units. On some targets, notably older
-versions of the Digital Alpha, the size of stand
-alone objects of this type may be 32, reflecting
-the inability of the hardware to do byte load/stores.
-
-Similarly, the size of type @code{Rec} is 40 bits
-(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
-the alignment is 4, so objects of this type will have
-their size increased to 64 bits so that it is a multiple
-of the alignment (in bits). This decision is
-in accordance with the specific Implementation Advice in RM 13.3(43):
-
-@quotation
-A @code{Size} clause should be supported for an object if the specified
-@code{Size} is at least as large as its subtype's @code{Size}, and corresponds
-to a size in storage elements that is a multiple of the object's
-@code{Alignment} (if the @code{Alignment} is nonzero).
-@end quotation
-
-@noindent
-An explicit size clause may be used to override the default size by
-increasing it. For example, if we have:
-
-@smallexample @c ada
- type My_Boolean is new Boolean;
- for My_Boolean'Size use 32;
-@end smallexample
-
-@noindent
-then values of this type will always be 32 bits long. In the case of
-discrete types, the size can be increased up to 64 bits, with the effect
-that the entire specified field is used to hold the value, sign- or
-zero-extended as appropriate. If more than 64 bits is specified, then
-padding space is allocated after the value, and a warning is issued that
-there are unused bits.
-
-Similarly the size of records and arrays may be increased, and the effect
-is to add padding bits after the value. This also causes a warning message
-to be generated.
-
-The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a
-Size in bits, this corresponds to an object of size 256 megabytes (minus
-one). This limitation is true on all targets. The reason for this
-limitation is that it improves the quality of the code in many cases
-if it is known that a Size value can be accommodated in an object of
-type Integer.
-
-@node Storage_Size Clauses
-@section Storage_Size Clauses
-@cindex Storage_Size Clause
-
-@noindent
-For tasks, the @code{Storage_Size} clause specifies the amount of space
-to be allocated for the task stack. This cannot be extended, and if the
-stack is exhausted, then @code{Storage_Error} will be raised (if stack
-checking is enabled). Use a @code{Storage_Size} attribute definition clause,
-or a @code{Storage_Size} pragma in the task definition to set the
-appropriate required size. A useful technique is to include in every
-task definition a pragma of the form:
-
-@smallexample @c ada
- pragma Storage_Size (Default_Stack_Size);
-@end smallexample
-
-@noindent
-Then @code{Default_Stack_Size} can be defined in a global package, and
-modified as required. Any tasks requiring stack sizes different from the
-default can have an appropriate alternative reference in the pragma.
-
-You can also use the @option{-d} binder switch to modify the default stack
-size.
-
-For access types, the @code{Storage_Size} clause specifies the maximum
-space available for allocation of objects of the type. If this space is
-exceeded then @code{Storage_Error} will be raised by an allocation attempt.
-In the case where the access type is declared local to a subprogram, the
-use of a @code{Storage_Size} clause triggers automatic use of a special
-predefined storage pool (@code{System.Pool_Size}) that ensures that all
-space for the pool is automatically reclaimed on exit from the scope in
-which the type is declared.
-
-A special case recognized by the compiler is the specification of a
-@code{Storage_Size} of zero for an access type. This means that no
-items can be allocated from the pool, and this is recognized at compile
-time, and all the overhead normally associated with maintaining a fixed
-size storage pool is eliminated. Consider the following example:
-
-@smallexample @c ada
- procedure p is
- type R is array (Natural) of Character;
- type P is access all R;
- for P'Storage_Size use 0;
- -- Above access type intended only for interfacing purposes
-
- y : P;
-
- procedure g (m : P);
- pragma Import (C, g);
-
- -- @dots{}
-
- begin
- -- @dots{}
- y := new R;
- end;
-@end smallexample
-
-@noindent
-As indicated in this example, these dummy storage pools are often useful in
-connection with interfacing where no object will ever be allocated. If you
-compile the above example, you get the warning:
-
-@smallexample
- p.adb:16:09: warning: allocation from empty storage pool
- p.adb:16:09: warning: Storage_Error will be raised at run time
-@end smallexample
-
-@noindent
-Of course in practice, there will not be any explicit allocators in the
-case of such an access declaration.
-
-@node Size of Variant Record Objects
-@section Size of Variant Record Objects
-@cindex Size, variant record objects
-@cindex Variant record objects, size
-
-@noindent
-In the case of variant record objects, there is a question whether Size gives
-information about a particular variant, or the maximum size required
-for any variant. Consider the following program
-
-@smallexample @c ada
-with Text_IO; use Text_IO;
-procedure q is
- type R1 (A : Boolean := False) is record
- case A is
- when True => X : Character;
- when False => null;
- end case;
- end record;
-
- V1 : R1 (False);
- V2 : R1;
-
-begin
- Put_Line (Integer'Image (V1'Size));
- Put_Line (Integer'Image (V2'Size));
-end q;
-@end smallexample
-
-@noindent
-Here we are dealing with a variant record, where the True variant
-requires 16 bits, and the False variant requires 8 bits.
-In the above example, both V1 and V2 contain the False variant,
-which is only 8 bits long. However, the result of running the
-program is:
-
-@smallexample
-8
-16
-@end smallexample
-
-@noindent
-The reason for the difference here is that the discriminant value of
-V1 is fixed, and will always be False. It is not possible to assign
-a True variant value to V1, therefore 8 bits is sufficient. On the
-other hand, in the case of V2, the initial discriminant value is
-False (from the default), but it is possible to assign a True
-variant value to V2, therefore 16 bits must be allocated for V2
-in the general case, even fewer bits may be needed at any particular
-point during the program execution.
-
-As can be seen from the output of this program, the @code{'Size}
-attribute applied to such an object in GNAT gives the actual allocated
-size of the variable, which is the largest size of any of the variants.
-The Ada Reference Manual is not completely clear on what choice should
-be made here, but the GNAT behavior seems most consistent with the
-language in the RM@.
-
-In some cases, it may be desirable to obtain the size of the current
-variant, rather than the size of the largest variant. This can be
-achieved in GNAT by making use of the fact that in the case of a
-subprogram parameter, GNAT does indeed return the size of the current
-variant (because a subprogram has no way of knowing how much space
-is actually allocated for the actual).
-
-Consider the following modified version of the above program:
-
-@smallexample @c ada
-with Text_IO; use Text_IO;
-procedure q is
- type R1 (A : Boolean := False) is record
- case A is
- when True => X : Character;
- when False => null;
- end case;
- end record;
-
- V2 : R1;
-
- function Size (V : R1) return Integer is
- begin
- return V'Size;
- end Size;
-
-begin
- Put_Line (Integer'Image (V2'Size));
- Put_Line (Integer'IMage (Size (V2)));
- V2 := (True, 'x');
- Put_Line (Integer'Image (V2'Size));
- Put_Line (Integer'IMage (Size (V2)));
-end q;
-@end smallexample
-
-@noindent
-The output from this program is
-
-@smallexample
-16
-8
-16
-16
-@end smallexample
-
-@noindent
-Here we see that while the @code{'Size} attribute always returns
-the maximum size, regardless of the current variant value, the
-@code{Size} function does indeed return the size of the current
-variant value.
-
-@node Biased Representation
-@section Biased Representation
-@cindex Size for biased representation
-@cindex Biased representation
-
-@noindent
-In the case of scalars with a range starting at other than zero, it is
-possible in some cases to specify a size smaller than the default minimum
-value, and in such cases, GNAT uses an unsigned biased representation,
-in which zero is used to represent the lower bound, and successive values
-represent successive values of the type.
-
-For example, suppose we have the declaration:
-
-@smallexample @c ada
- type Small is range -7 .. -4;
- for Small'Size use 2;
-@end smallexample
-
-@noindent
-Although the default size of type @code{Small} is 4, the @code{Size}
-clause is accepted by GNAT and results in the following representation
-scheme:
-
-@smallexample
- -7 is represented as 2#00#
- -6 is represented as 2#01#
- -5 is represented as 2#10#
- -4 is represented as 2#11#
-@end smallexample
-
-@noindent
-Biased representation is only used if the specified @code{Size} clause
-cannot be accepted in any other manner. These reduced sizes that force
-biased representation can be used for all discrete types except for
-enumeration types for which a representation clause is given.
-
-@node Value_Size and Object_Size Clauses
-@section Value_Size and Object_Size Clauses
-@findex Value_Size
-@findex Object_Size
-@cindex Size, of objects
-
-@noindent
-In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
-number of bits required to hold values of type @code{T}.
-Although this interpretation was allowed in Ada 83, it was not required,
-and this requirement in practice can cause some significant difficulties.
-For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
-However, in Ada 95 and Ada 2005,
-@code{Natural'Size} is
-typically 31. This means that code may change in behavior when moving
-from Ada 83 to Ada 95 or Ada 2005. For example, consider:
-
-@smallexample @c ada
- type Rec is record;
- A : Natural;
- B : Natural;
- end record;
-
- for Rec use record
- at 0 range 0 .. Natural'Size - 1;
- at 0 range Natural'Size .. 2 * Natural'Size - 1;
- end record;
-@end smallexample
-
-@noindent
-In the above code, since the typical size of @code{Natural} objects
-is 32 bits and @code{Natural'Size} is 31, the above code can cause
-unexpected inefficient packing in Ada 95 and Ada 2005, and in general
-there are cases where the fact that the object size can exceed the
-size of the type causes surprises.
-
-To help get around this problem GNAT provides two implementation
-defined attributes, @code{Value_Size} and @code{Object_Size}. When
-applied to a type, these attributes yield the size of the type
-(corresponding to the RM defined size attribute), and the size of
-objects of the type respectively.
-
-The @code{Object_Size} is used for determining the default size of
-objects and components. This size value can be referred to using the
-@code{Object_Size} attribute. The phrase ``is used'' here means that it is
-the basis of the determination of the size. The backend is free to
-pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone
-character might be stored in 32 bits on a machine with no efficient
-byte access instructions such as the Alpha.
-
-The default rules for the value of @code{Object_Size} for
-discrete types are as follows:
-
-@itemize @bullet
-@item
-The @code{Object_Size} for base subtypes reflect the natural hardware
-size in bits (run the compiler with @option{-gnatS} to find those values
-for numeric types). Enumeration types and fixed-point base subtypes have
-8, 16, 32 or 64 bits for this size, depending on the range of values
-to be stored.
-
-@item
-The @code{Object_Size} of a subtype is the same as the
-@code{Object_Size} of
-the type from which it is obtained.
-
-@item
-The @code{Object_Size} of a derived base type is copied from the parent
-base type, and the @code{Object_Size} of a derived first subtype is copied
-from the parent first subtype.
-@end itemize
-
-@noindent
-The @code{Value_Size} attribute
-is the (minimum) number of bits required to store a value
-of the type.
-This value is used to determine how tightly to pack
-records or arrays with components of this type, and also affects
-the semantics of unchecked conversion (unchecked conversions where
-the @code{Value_Size} values differ generate a warning, and are potentially
-target dependent).
-
-The default rules for the value of @code{Value_Size} are as follows:
-
-@itemize @bullet
-@item
-The @code{Value_Size} for a base subtype is the minimum number of bits
-required to store all values of the type (including the sign bit
-only if negative values are possible).
-
-@item
-If a subtype statically matches the first subtype of a given type, then it has
-by default the same @code{Value_Size} as the first subtype. This is a
-consequence of RM 13.1(14) (``if two subtypes statically match,
-then their subtype-specific aspects are the same''.)
-
-@item
-All other subtypes have a @code{Value_Size} corresponding to the minimum
-number of bits required to store all values of the subtype. For
-dynamic bounds, it is assumed that the value can range down or up
-to the corresponding bound of the ancestor
-@end itemize
-
-@noindent
-The RM defined attribute @code{Size} corresponds to the
-@code{Value_Size} attribute.
-
-The @code{Size} attribute may be defined for a first-named subtype. This sets
-the @code{Value_Size} of
-the first-named subtype to the given value, and the
-@code{Object_Size} of this first-named subtype to the given value padded up
-to an appropriate boundary. It is a consequence of the default rules
-above that this @code{Object_Size} will apply to all further subtypes. On the
-other hand, @code{Value_Size} is affected only for the first subtype, any
-dynamic subtypes obtained from it directly, and any statically matching
-subtypes. The @code{Value_Size} of any other static subtypes is not affected.
-
-@code{Value_Size} and
-@code{Object_Size} may be explicitly set for any subtype using
-an attribute definition clause. Note that the use of these attributes
-can cause the RM 13.1(14) rule to be violated. If two access types
-reference aliased objects whose subtypes have differing @code{Object_Size}
-values as a result of explicit attribute definition clauses, then it
-is erroneous to convert from one access subtype to the other.
-
-At the implementation level, Esize stores the Object_Size and the
-RM_Size field stores the @code{Value_Size} (and hence the value of the
-@code{Size} attribute,
-which, as noted above, is equivalent to @code{Value_Size}).
-
-To get a feel for the difference, consider the following examples (note
-that in each case the base is @code{Short_Short_Integer} with a size of 8):
-
-@smallexample
- Object_Size Value_Size
-
-type x1 is range 0 .. 5; 8 3
-
-type x2 is range 0 .. 5;
-for x2'size use 12; 16 12
-
-subtype x3 is x2 range 0 .. 3; 16 2
-
-subtype x4 is x2'base range 0 .. 10; 8 4
-
-subtype x5 is x2 range 0 .. dynamic; 16 3*
-
-subtype x6 is x2'base range 0 .. dynamic; 8 3*
-
-@end smallexample
-
-@noindent
-Note: the entries marked ``3*'' are not actually specified by the Ada
-Reference Manual, but it seems in the spirit of the RM rules to allocate
-the minimum number of bits (here 3, given the range for @code{x2})
-known to be large enough to hold the given range of values.
-
-So far, so good, but GNAT has to obey the RM rules, so the question is
-under what conditions must the RM @code{Size} be used.
-The following is a list
-of the occasions on which the RM @code{Size} must be used:
-
-@itemize @bullet
-@item
-Component size for packed arrays or records
-
-@item
-Value of the attribute @code{Size} for a type
-
-@item
-Warning about sizes not matching for unchecked conversion
-@end itemize
-
-@noindent
-For record types, the @code{Object_Size} is always a multiple of the
-alignment of the type (this is true for all types). In some cases the
-@code{Value_Size} can be smaller. Consider:
-
-@smallexample
- type R is record
- X : Integer;
- Y : Character;
- end record;
-@end smallexample
-
-@noindent
-On a typical 32-bit architecture, the X component will be four bytes, and
-require four-byte alignment, and the Y component will be one byte. In this
-case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
-required to store a value of this type, and for example, it is permissible
-to have a component of type R in an outer record whose component size is
-specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
-since it must be rounded up so that this value is a multiple of the
-alignment (4 bytes = 32 bits).
-
-@noindent
-For all other types, the @code{Object_Size}
-and Value_Size are the same (and equivalent to the RM attribute @code{Size}).
-Only @code{Size} may be specified for such types.
-
-@node Component_Size Clauses
-@section Component_Size Clauses
-@cindex Component_Size Clause
-
-@noindent
-Normally, the value specified in a component size clause must be consistent
-with the subtype of the array component with regard to size and alignment.
-In other words, the value specified must be at least equal to the size
-of this subtype, and must be a multiple of the alignment value.
-
-In addition, component size clauses are allowed which cause the array
-to be packed, by specifying a smaller value. A first case is for
-component size values in the range 1 through 63. The value specified
-must not be smaller than the Size of the subtype. GNAT will accurately
-honor all packing requests in this range. For example, if we have:
-
-@smallexample @c ada
-type r is array (1 .. 8) of Natural;
-for r'Component_Size use 31;
-@end smallexample
-
-@noindent
-then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
-Of course access to the components of such an array is considerably
-less efficient than if the natural component size of 32 is used.
-A second case is when the subtype of the component is a record type
-padded because of its default alignment. For example, if we have:
-
-@smallexample @c ada
-type r is record
- i : Integer;
- j : Integer;
- b : Boolean;
-end record;
-
-type a is array (1 .. 8) of r;
-for a'Component_Size use 72;
-@end smallexample
-
-@noindent
-then the resulting array has a length of 72 bytes, instead of 96 bytes
-if the alignment of the record (4) was obeyed.
-
-Note that there is no point in giving both a component size clause
-and a pragma Pack for the same array type. if such duplicate
-clauses are given, the pragma Pack will be ignored.
-
-@node Bit_Order Clauses
-@section Bit_Order Clauses
-@cindex Bit_Order Clause
-@cindex bit ordering
-@cindex ordering, of bits
-
-@noindent
-For record subtypes, GNAT permits the specification of the @code{Bit_Order}
-attribute. The specification may either correspond to the default bit
-order for the target, in which case the specification has no effect and
-places no additional restrictions, or it may be for the non-standard
-setting (that is the opposite of the default).
-
-In the case where the non-standard value is specified, the effect is
-to renumber bits within each byte, but the ordering of bytes is not
-affected. There are certain
-restrictions placed on component clauses as follows:
-
-@itemize @bullet
-
-@item Components fitting within a single storage unit.
-@noindent
-These are unrestricted, and the effect is merely to renumber bits. For
-example if we are on a little-endian machine with @code{Low_Order_First}
-being the default, then the following two declarations have exactly
-the same effect:
-
-@smallexample @c ada
- type R1 is record
- A : Boolean;
- B : Integer range 1 .. 120;
- end record;
-
- for R1 use record
- A at 0 range 0 .. 0;
- B at 0 range 1 .. 7;
- end record;
-
- type R2 is record
- A : Boolean;
- B : Integer range 1 .. 120;
- end record;
-
- for R2'Bit_Order use High_Order_First;
-
- for R2 use record
- A at 0 range 7 .. 7;
- B at 0 range 0 .. 6;
- end record;
-@end smallexample
-
-@noindent
-The useful application here is to write the second declaration with the
-@code{Bit_Order} attribute definition clause, and know that it will be treated
-the same, regardless of whether the target is little-endian or big-endian.
-
-@item Components occupying an integral number of bytes.
-@noindent
-These are components that exactly fit in two or more bytes. Such component
-declarations are allowed, but have no effect, since it is important to realize
-that the @code{Bit_Order} specification does not affect the ordering of bytes.
-In particular, the following attempt at getting an endian-independent integer
-does not work:
-
-@smallexample @c ada
- type R2 is record
- A : Integer;
- end record;
-
- for R2'Bit_Order use High_Order_First;
-
- for R2 use record
- A at 0 range 0 .. 31;
- end record;
-@end smallexample
-
-@noindent
-This declaration will result in a little-endian integer on a
-little-endian machine, and a big-endian integer on a big-endian machine.
-If byte flipping is required for interoperability between big- and
-little-endian machines, this must be explicitly programmed. This capability
-is not provided by @code{Bit_Order}.
-
-@item Components that are positioned across byte boundaries
-@noindent
-but do not occupy an integral number of bytes. Given that bytes are not
-reordered, such fields would occupy a non-contiguous sequence of bits
-in memory, requiring non-trivial code to reassemble. They are for this
-reason not permitted, and any component clause specifying such a layout
-will be flagged as illegal by GNAT@.
-
-@end itemize
-
-@noindent
-Since the misconception that Bit_Order automatically deals with all
-endian-related incompatibilities is a common one, the specification of
-a component field that is an integral number of bytes will always
-generate a warning. This warning may be suppressed using @code{pragma
-Warnings (Off)} if desired. The following section contains additional
-details regarding the issue of byte ordering.
-
-@node Effect of Bit_Order on Byte Ordering
-@section Effect of Bit_Order on Byte Ordering
-@cindex byte ordering
-@cindex ordering, of bytes
-
-@noindent
-In this section we will review the effect of the @code{Bit_Order} attribute
-definition clause on byte ordering. Briefly, it has no effect at all, but
-a detailed example will be helpful. Before giving this
-example, let us review the precise
-definition of the effect of defining @code{Bit_Order}. The effect of a
-non-standard bit order is described in section 15.5.3 of the Ada
-Reference Manual:
-
-@quotation
-2 A bit ordering is a method of interpreting the meaning of
-the storage place attributes.
-@end quotation
-
-@noindent
-To understand the precise definition of storage place attributes in
-this context, we visit section 13.5.1 of the manual:
-
-@quotation
-13 A record_representation_clause (without the mod_clause)
-specifies the layout. The storage place attributes (see 13.5.2)
-are taken from the values of the position, first_bit, and last_bit
-expressions after normalizing those values so that first_bit is
-less than Storage_Unit.
-@end quotation
-
-@noindent
-The critical point here is that storage places are taken from
-the values after normalization, not before. So the @code{Bit_Order}
-interpretation applies to normalized values. The interpretation
-is described in the later part of the 15.5.3 paragraph:
-
-@quotation
-2 A bit ordering is a method of interpreting the meaning of
-the storage place attributes. High_Order_First (known in the
-vernacular as ``big endian'') means that the first bit of a
-storage element (bit 0) is the most significant bit (interpreting
-the sequence of bits that represent a component as an unsigned
-integer value). Low_Order_First (known in the vernacular as
-``little endian'') means the opposite: the first bit is the
-least significant.
-@end quotation
-
-@noindent
-Note that the numbering is with respect to the bits of a storage
-unit. In other words, the specification affects only the numbering
-of bits within a single storage unit.
-
-We can make the effect clearer by giving an example.
-
-Suppose that we have an external device which presents two bytes, the first
-byte presented, which is the first (low addressed byte) of the two byte
-record is called Master, and the second byte is called Slave.
-
-The left most (most significant bit is called Control for each byte, and
-the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost
-(least significant) bit.
-
-On a big-endian machine, we can write the following representation clause
-
-@smallexample @c ada
- type Data is record
- Master_Control : Bit;
- Master_V1 : Bit;
- Master_V2 : Bit;
- Master_V3 : Bit;
- Master_V4 : Bit;
- Master_V5 : Bit;
- Master_V6 : Bit;
- Master_V7 : Bit;
- Slave_Control : Bit;
- Slave_V1 : Bit;
- Slave_V2 : Bit;
- Slave_V3 : Bit;
- Slave_V4 : Bit;
- Slave_V5 : Bit;
- Slave_V6 : Bit;
- Slave_V7 : Bit;
- end record;
-
- for Data use record
- Master_Control at 0 range 0 .. 0;
- Master_V1 at 0 range 1 .. 1;
- Master_V2 at 0 range 2 .. 2;
- Master_V3 at 0 range 3 .. 3;
- Master_V4 at 0 range 4 .. 4;
- Master_V5 at 0 range 5 .. 5;
- Master_V6 at 0 range 6 .. 6;
- Master_V7 at 0 range 7 .. 7;
- Slave_Control at 1 range 0 .. 0;
- Slave_V1 at 1 range 1 .. 1;
- Slave_V2 at 1 range 2 .. 2;
- Slave_V3 at 1 range 3 .. 3;
- Slave_V4 at 1 range 4 .. 4;
- Slave_V5 at 1 range 5 .. 5;
- Slave_V6 at 1 range 6 .. 6;
- Slave_V7 at 1 range 7 .. 7;
- end record;
-@end smallexample
-
-@noindent
-Now if we move this to a little endian machine, then the bit ordering within
-the byte is backwards, so we have to rewrite the record rep clause as:
-
-@smallexample @c ada
- for Data use record
- Master_Control at 0 range 7 .. 7;
- Master_V1 at 0 range 6 .. 6;
- Master_V2 at 0 range 5 .. 5;
- Master_V3 at 0 range 4 .. 4;
- Master_V4 at 0 range 3 .. 3;
- Master_V5 at 0 range 2 .. 2;
- Master_V6 at 0 range 1 .. 1;
- Master_V7 at 0 range 0 .. 0;
- Slave_Control at 1 range 7 .. 7;
- Slave_V1 at 1 range 6 .. 6;
- Slave_V2 at 1 range 5 .. 5;
- Slave_V3 at 1 range 4 .. 4;
- Slave_V4 at 1 range 3 .. 3;
- Slave_V5 at 1 range 2 .. 2;
- Slave_V6 at 1 range 1 .. 1;
- Slave_V7 at 1 range 0 .. 0;
- end record;
-@end smallexample
-
-@noindent
-It is a nuisance to have to rewrite the clause, especially if
-the code has to be maintained on both machines. However,
-this is a case that we can handle with the
-@code{Bit_Order} attribute if it is implemented.
-Note that the implementation is not required on byte addressed
-machines, but it is indeed implemented in GNAT.
-This means that we can simply use the
-first record clause, together with the declaration
-
-@smallexample @c ada
- for Data'Bit_Order use High_Order_First;
-@end smallexample
-
-@noindent
-and the effect is what is desired, namely the layout is exactly the same,
-independent of whether the code is compiled on a big-endian or little-endian
-machine.
-
-The important point to understand is that byte ordering is not affected.
-A @code{Bit_Order} attribute definition never affects which byte a field
-ends up in, only where it ends up in that byte.
-To make this clear, let us rewrite the record rep clause of the previous
-example as:
-
-@smallexample @c ada
- for Data'Bit_Order use High_Order_First;
- for Data use record
- Master_Control at 0 range 0 .. 0;
- Master_V1 at 0 range 1 .. 1;
- Master_V2 at 0 range 2 .. 2;
- Master_V3 at 0 range 3 .. 3;
- Master_V4 at 0 range 4 .. 4;
- Master_V5 at 0 range 5 .. 5;
- Master_V6 at 0 range 6 .. 6;
- Master_V7 at 0 range 7 .. 7;
- Slave_Control at 0 range 8 .. 8;
- Slave_V1 at 0 range 9 .. 9;
- Slave_V2 at 0 range 10 .. 10;
- Slave_V3 at 0 range 11 .. 11;
- Slave_V4 at 0 range 12 .. 12;
- Slave_V5 at 0 range 13 .. 13;
- Slave_V6 at 0 range 14 .. 14;
- Slave_V7 at 0 range 15 .. 15;
- end record;
-@end smallexample
-
-@noindent
-This is exactly equivalent to saying (a repeat of the first example):
-
-@smallexample @c ada
- for Data'Bit_Order use High_Order_First;
- for Data use record
- Master_Control at 0 range 0 .. 0;
- Master_V1 at 0 range 1 .. 1;
- Master_V2 at 0 range 2 .. 2;
- Master_V3 at 0 range 3 .. 3;
- Master_V4 at 0 range 4 .. 4;
- Master_V5 at 0 range 5 .. 5;
- Master_V6 at 0 range 6 .. 6;
- Master_V7 at 0 range 7 .. 7;
- Slave_Control at 1 range 0 .. 0;
- Slave_V1 at 1 range 1 .. 1;
- Slave_V2 at 1 range 2 .. 2;
- Slave_V3 at 1 range 3 .. 3;
- Slave_V4 at 1 range 4 .. 4;
- Slave_V5 at 1 range 5 .. 5;
- Slave_V6 at 1 range 6 .. 6;
- Slave_V7 at 1 range 7 .. 7;
- end record;
-@end smallexample
-
-@noindent
-Why are they equivalent? Well take a specific field, the @code{Slave_V2}
-field. The storage place attributes are obtained by normalizing the
-values given so that the @code{First_Bit} value is less than 8. After
-normalizing the values (0,10,10) we get (1,2,2) which is exactly what
-we specified in the other case.
-
-Now one might expect that the @code{Bit_Order} attribute might affect
-bit numbering within the entire record component (two bytes in this
-case, thus affecting which byte fields end up in), but that is not
-the way this feature is defined, it only affects numbering of bits,
-not which byte they end up in.
-
-Consequently it never makes sense to specify a starting bit number
-greater than 7 (for a byte addressable field) if an attribute
-definition for @code{Bit_Order} has been given, and indeed it
-may be actively confusing to specify such a value, so the compiler
-generates a warning for such usage.
-
-If you do need to control byte ordering then appropriate conditional
-values must be used. If in our example, the slave byte came first on
-some machines we might write:
-
-@smallexample @c ada
- Master_Byte_First constant Boolean := @dots{};
-
- Master_Byte : constant Natural :=
- 1 - Boolean'Pos (Master_Byte_First);
- Slave_Byte : constant Natural :=
- Boolean'Pos (Master_Byte_First);
-
- for Data'Bit_Order use High_Order_First;
- for Data use record
- Master_Control at Master_Byte range 0 .. 0;
- Master_V1 at Master_Byte range 1 .. 1;
- Master_V2 at Master_Byte range 2 .. 2;
- Master_V3 at Master_Byte range 3 .. 3;
- Master_V4 at Master_Byte range 4 .. 4;
- Master_V5 at Master_Byte range 5 .. 5;
- Master_V6 at Master_Byte range 6 .. 6;
- Master_V7 at Master_Byte range 7 .. 7;
- Slave_Control at Slave_Byte range 0 .. 0;
- Slave_V1 at Slave_Byte range 1 .. 1;
- Slave_V2 at Slave_Byte range 2 .. 2;
- Slave_V3 at Slave_Byte range 3 .. 3;
- Slave_V4 at Slave_Byte range 4 .. 4;
- Slave_V5 at Slave_Byte range 5 .. 5;
- Slave_V6 at Slave_Byte range 6 .. 6;
- Slave_V7 at Slave_Byte range 7 .. 7;
- end record;
-@end smallexample
-
-@noindent
-Now to switch between machines, all that is necessary is
-to set the boolean constant @code{Master_Byte_First} in
-an appropriate manner.
-
-@node Pragma Pack for Arrays
-@section Pragma Pack for Arrays
-@cindex Pragma Pack (for arrays)
-
-@noindent
-Pragma @code{Pack} applied to an array has no effect unless the component type
-is packable. For a component type to be packable, it must be one of the
-following cases:
-
-@itemize @bullet
-@item
-Any scalar type
-@item
-Any type whose size is specified with a size clause
-@item
-Any packed array type with a static size
-@item
-Any record type padded because of its default alignment
-@end itemize
-
-@noindent
-For all these cases, if the component subtype size is in the range
-1 through 63, then the effect of the pragma @code{Pack} is exactly as though a
-component size were specified giving the component subtype size.
-For example if we have:
-
-@smallexample @c ada
- type r is range 0 .. 17;
-
- type ar is array (1 .. 8) of r;
- pragma Pack (ar);
-@end smallexample
-
-@noindent
-Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size},
-and the size of the array @code{ar} will be exactly 40 bits.
-
-Note that in some cases this rather fierce approach to packing can produce
-unexpected effects. For example, in Ada 95 and Ada 2005,
-subtype @code{Natural} typically has a size of 31, meaning that if you
-pack an array of @code{Natural}, you get 31-bit
-close packing, which saves a few bits, but results in far less efficient
-access. Since many other Ada compilers will ignore such a packing request,
-GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
-might not be what is intended. You can easily remove this warning by
-using an explicit @code{Component_Size} setting instead, which never generates
-a warning, since the intention of the programmer is clear in this case.
-
-GNAT treats packed arrays in one of two ways. If the size of the array is
-known at compile time and is less than 64 bits, then internally the array
-is represented as a single modular type, of exactly the appropriate number
-of bits. If the length is greater than 63 bits, or is not known at compile
-time, then the packed array is represented as an array of bytes, and the
-length is always a multiple of 8 bits.
-
-Note that to represent a packed array as a modular type, the alignment must
-be suitable for the modular type involved. For example, on typical machines
-a 32-bit packed array will be represented by a 32-bit modular integer with
-an alignment of four bytes. If you explicitly override the default alignment
-with an alignment clause that is too small, the modular representation
-cannot be used. For example, consider the following set of declarations:
-
-@smallexample @c ada
- type R is range 1 .. 3;
- type S is array (1 .. 31) of R;
- for S'Component_Size use 2;
- for S'Size use 62;
- for S'Alignment use 1;
-@end smallexample
-
-@noindent
-If the alignment clause were not present, then a 62-bit modular
-representation would be chosen (typically with an alignment of 4 or 8
-bytes depending on the target). But the default alignment is overridden
-with the explicit alignment clause. This means that the modular
-representation cannot be used, and instead the array of bytes
-representation must be used, meaning that the length must be a multiple
-of 8. Thus the above set of declarations will result in a diagnostic
-rejecting the size clause and noting that the minimum size allowed is 64.
-
-@cindex Pragma Pack (for type Natural)
-@cindex Pragma Pack warning
-
-One special case that is worth noting occurs when the base type of the
-component size is 8/16/32 and the subtype is one bit less. Notably this
-occurs with subtype @code{Natural}. Consider:
-
-@smallexample @c ada
- type Arr is array (1 .. 32) of Natural;
- pragma Pack (Arr);
-@end smallexample
-
-@noindent
-In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
-since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
-Ada 83 compilers did not attempt 31 bit packing.
-
-In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
-GNAT really does pack 31-bit subtype to 31 bits. This may result in a
-substantial unintended performance penalty when porting legacy Ada 83 code.
-To help prevent this, GNAT generates a warning in such cases. If you really
-want 31 bit packing in a case like this, you can set the component size
-explicitly:
-
-@smallexample @c ada
- type Arr is array (1 .. 32) of Natural;
- for Arr'Component_Size use 31;
-@end smallexample
-
-@noindent
-Here 31-bit packing is achieved as required, and no warning is generated,
-since in this case the programmer intention is clear.
-
-@node Pragma Pack for Records
-@section Pragma Pack for Records
-@cindex Pragma Pack (for records)
-
-@noindent
-Pragma @code{Pack} applied to a record will pack the components to reduce
-wasted space from alignment gaps and by reducing the amount of space
-taken by components. We distinguish between @emph{packable} components and
-@emph{non-packable} components.
-Components of the following types are considered packable:
-@itemize @bullet
-@item
-All primitive types are packable.
-
-@item
-Small packed arrays, whose size does not exceed 64 bits, and where the
-size is statically known at compile time, are represented internally
-as modular integers, and so they are also packable.
-
-@end itemize
-
-@noindent
-All packable components occupy the exact number of bits corresponding to
-their @code{Size} value, and are packed with no padding bits, i.e.@: they
-can start on an arbitrary bit boundary.
-
-All other types are non-packable, they occupy an integral number of
-storage units, and
-are placed at a boundary corresponding to their alignment requirements.
-
-For example, consider the record
-
-@smallexample @c ada
- type Rb1 is array (1 .. 13) of Boolean;
- pragma Pack (rb1);
-
- type Rb2 is array (1 .. 65) of Boolean;
- pragma Pack (rb2);
-
- type x2 is record
- l1 : Boolean;
- l2 : Duration;
- l3 : Float;
- l4 : Boolean;
- l5 : Rb1;
- l6 : Rb2;
- end record;
- pragma Pack (x2);
-@end smallexample
-
-@noindent
-The representation for the record x2 is as follows:
-
-@smallexample @c ada
-for x2'Size use 224;
-for x2 use record
- l1 at 0 range 0 .. 0;
- l2 at 0 range 1 .. 64;
- l3 at 12 range 0 .. 31;
- l4 at 16 range 0 .. 0;
- l5 at 16 range 1 .. 13;
- l6 at 18 range 0 .. 71;
-end record;
-@end smallexample
-
-@noindent
-Studying this example, we see that the packable fields @code{l1}
-and @code{l2} are
-of length equal to their sizes, and placed at specific bit boundaries (and
-not byte boundaries) to
-eliminate padding. But @code{l3} is of a non-packable float type, so
-it is on the next appropriate alignment boundary.
-
-The next two fields are fully packable, so @code{l4} and @code{l5} are
-minimally packed with no gaps. However, type @code{Rb2} is a packed
-array that is longer than 64 bits, so it is itself non-packable. Thus
-the @code{l6} field is aligned to the next byte boundary, and takes an
-integral number of bytes, i.e.@: 72 bits.
-
-@node Record Representation Clauses
-@section Record Representation Clauses
-@cindex Record Representation Clause
-
-@noindent
-Record representation clauses may be given for all record types, including
-types obtained by record extension. Component clauses are allowed for any
-static component. The restrictions on component clauses depend on the type
-of the component.
-
-@cindex Component Clause
-For all components of an elementary type, the only restriction on component
-clauses is that the size must be at least the 'Size value of the type
-(actually the Value_Size). There are no restrictions due to alignment,
-and such components may freely cross storage boundaries.
-
-Packed arrays with a size up to and including 64 bits are represented
-internally using a modular type with the appropriate number of bits, and
-thus the same lack of restriction applies. For example, if you declare:
-
-@smallexample @c ada
- type R is array (1 .. 49) of Boolean;
- pragma Pack (R);
- for R'Size use 49;
-@end smallexample
-
-@noindent
-then a component clause for a component of type R may start on any
-specified bit boundary, and may specify a value of 49 bits or greater.
-
-For packed bit arrays that are longer than 64 bits, there are two
-cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
-including the important case of single bits or boolean values, then
-there are no limitations on placement of such components, and they
-may start and end at arbitrary bit boundaries.
-
-If the component size is not a power of 2 (e.g.@: 3 or 5), then
-an array of this type longer than 64 bits must always be placed on
-on a storage unit (byte) boundary and occupy an integral number
-of storage units (bytes). Any component clause that does not
-meet this requirement will be rejected.
-
-Any aliased component, or component of an aliased type, must
-have its normal alignment and size. A component clause that
-does not meet this requirement will be rejected.
-
-The tag field of a tagged type always occupies an address sized field at
-the start of the record. No component clause may attempt to overlay this
-tag. When a tagged type appears as a component, the tag field must have
-proper alignment
-
-In the case of a record extension T1, of a type T, no component clause applied
-to the type T1 can specify a storage location that would overlap the first
-T'Size bytes of the record.
-
-For all other component types, including non-bit-packed arrays,
-the component can be placed at an arbitrary bit boundary,
-so for example, the following is permitted:
-
-@smallexample @c ada
- type R is array (1 .. 10) of Boolean;
- for R'Size use 80;
-
- type Q is record
- G, H : Boolean;
- L, M : R;
- end record;
-
- for Q use record
- G at 0 range 0 .. 0;
- H at 0 range 1 .. 1;
- L at 0 range 2 .. 81;
- R at 0 range 82 .. 161;
- end record;
-@end smallexample
-
-@noindent
-Note: the above rules apply to recent releases of GNAT 5.
-In GNAT 3, there are more severe restrictions on larger components.
-For non-primitive types, including packed arrays with a size greater than
-64 bits, component clauses must respect the alignment requirement of the
-type, in particular, always starting on a byte boundary, and the length
-must be a multiple of the storage unit.
-
-@node Enumeration Clauses
-@section Enumeration Clauses
-
-The only restriction on enumeration clauses is that the range of values
-must be representable. For the signed case, if one or more of the
-representation values are negative, all values must be in the range:
-
-@smallexample @c ada
- System.Min_Int .. System.Max_Int
-@end smallexample
-
-@noindent
-For the unsigned case, where all values are nonnegative, the values must
-be in the range:
-
-@smallexample @c ada
- 0 .. System.Max_Binary_Modulus;
-@end smallexample
-
-@noindent
-A @emph{confirming} representation clause is one in which the values range
-from 0 in sequence, i.e.@: a clause that confirms the default representation
-for an enumeration type.
-Such a confirming representation
-is permitted by these rules, and is specially recognized by the compiler so
-that no extra overhead results from the use of such a clause.
-
-If an array has an index type which is an enumeration type to which an
-enumeration clause has been applied, then the array is stored in a compact
-manner. Consider the declarations:
-
-@smallexample @c ada
- type r is (A, B, C);
- for r use (A => 1, B => 5, C => 10);
- type t is array (r) of Character;
-@end smallexample
-
-@noindent
-The array type t corresponds to a vector with exactly three elements and
-has a default size equal to @code{3*Character'Size}. This ensures efficient
-use of space, but means that accesses to elements of the array will incur
-the overhead of converting representation values to the corresponding
-positional values, (i.e.@: the value delivered by the @code{Pos} attribute).
-
-@node Address Clauses
-@section Address Clauses
-@cindex Address Clause
-
-The reference manual allows a general restriction on representation clauses,
-as found in RM 13.1(22):
-
-@quotation
-An implementation need not support representation
-items containing nonstatic expressions, except that
-an implementation should support a representation item
-for a given entity if each nonstatic expression in the
-representation item is a name that statically denotes
-a constant declared before the entity.
-@end quotation
-
-@noindent
-In practice this is applicable only to address clauses, since this is the
-only case in which a non-static expression is permitted by the syntax. As
-the AARM notes in sections 13.1 (22.a-22.h):
-
-@display
- 22.a Reason: This is to avoid the following sort of thing:
-
- 22.b X : Integer := F(@dots{});
- Y : Address := G(@dots{});
- for X'Address use Y;
-
- 22.c In the above, we have to evaluate the
- initialization expression for X before we
- know where to put the result. This seems
- like an unreasonable implementation burden.
-
- 22.d The above code should instead be written
- like this:
-
- 22.e Y : constant Address := G(@dots{});
- X : Integer := F(@dots{});
- for X'Address use Y;
-
- 22.f This allows the expression ``Y'' to be safely
- evaluated before X is created.
-
- 22.g The constant could be a formal parameter of mode in.
-
- 22.h An implementation can support other nonstatic
- expressions if it wants to. Expressions of type
- Address are hardly ever static, but their value
- might be known at compile time anyway in many
- cases.
-@end display
-
-@noindent
-GNAT does indeed permit many additional cases of non-static expressions. In
-particular, if the type involved is elementary there are no restrictions
-(since in this case, holding a temporary copy of the initialization value,
-if one is present, is inexpensive). In addition, if there is no implicit or
-explicit initialization, then there are no restrictions. GNAT will reject
-only the case where all three of these conditions hold:
-
-@itemize @bullet
-
-@item
-The type of the item is non-elementary (e.g.@: a record or array).
-
-@item
-There is explicit or implicit initialization required for the object.
-Note that access values are always implicitly initialized, and also
-in GNAT, certain bit-packed arrays (those having a dynamic length or
-a length greater than 64) will also be implicitly initialized to zero.
-
-@item
-The address value is non-static. Here GNAT is more permissive than the
-RM, and allows the address value to be the address of a previously declared
-stand-alone variable, as long as it does not itself have an address clause.
-
-@smallexample @c ada
- Anchor : Some_Initialized_Type;
- Overlay : Some_Initialized_Type;
- for Overlay'Address use Anchor'Address;
-@end smallexample
-
-@noindent
-However, the prefix of the address clause cannot be an array component, or
-a component of a discriminated record.
-
-@end itemize
-
-@noindent
-As noted above in section 22.h, address values are typically non-static. In
-particular the To_Address function, even if applied to a literal value, is
-a non-static function call. To avoid this minor annoyance, GNAT provides
-the implementation defined attribute 'To_Address. The following two
-expressions have identical values:
-
-@findex Attribute
-@findex To_Address
-@smallexample @c ada
- To_Address (16#1234_0000#)
- System'To_Address (16#1234_0000#);
-@end smallexample
-
-@noindent
-except that the second form is considered to be a static expression, and
-thus when used as an address clause value is always permitted.
-
-@noindent
-Additionally, GNAT treats as static an address clause that is an
-unchecked_conversion of a static integer value. This simplifies the porting
-of legacy code, and provides a portable equivalent to the GNAT attribute
-@code{To_Address}.
-
-Another issue with address clauses is the interaction with alignment
-requirements. When an address clause is given for an object, the address
-value must be consistent with the alignment of the object (which is usually
-the same as the alignment of the type of the object). If an address clause
-is given that specifies an inappropriately aligned address value, then the
-program execution is erroneous.
-
-Since this source of erroneous behavior can have unfortunate effects, GNAT
-checks (at compile time if possible, generating a warning, or at execution
-time with a run-time check) that the alignment is appropriate. If the
-run-time check fails, then @code{Program_Error} is raised. This run-time
-check is suppressed if range checks are suppressed, or if the special GNAT
-check Alignment_Check is suppressed, or if
-@code{pragma Restrictions (No_Elaboration_Code)} is in effect.
-
-Finally, GNAT does not permit overlaying of objects of controlled types or
-composite types containing a controlled component. In most cases, the compiler
-can detect an attempt at such overlays and will generate a warning at compile
-time and a Program_Error exception at run time.
-
-@findex Export
-An address clause cannot be given for an exported object. More
-understandably the real restriction is that objects with an address
-clause cannot be exported. This is because such variables are not
-defined by the Ada program, so there is no external object to export.
-
-@findex Import
-It is permissible to give an address clause and a pragma Import for the
-same object. In this case, the variable is not really defined by the
-Ada program, so there is no external symbol to be linked. The link name
-and the external name are ignored in this case. The reason that we allow this
-combination is that it provides a useful idiom to avoid unwanted
-initializations on objects with address clauses.
-
-When an address clause is given for an object that has implicit or
-explicit initialization, then by default initialization takes place. This
-means that the effect of the object declaration is to overwrite the
-memory at the specified address. This is almost always not what the
-programmer wants, so GNAT will output a warning:
-
-@smallexample
- with System;
- package G is
- type R is record
- M : Integer := 0;
- end record;
-
- Ext : R;
- for Ext'Address use System'To_Address (16#1234_1234#);
- |
- >>> warning: implicit initialization of "Ext" may
- modify overlaid storage
- >>> warning: use pragma Import for "Ext" to suppress
- initialization (RM B(24))
-
- end G;
-@end smallexample
-
-@noindent
-As indicated by the warning message, the solution is to use a (dummy) pragma
-Import to suppress this initialization. The pragma tell the compiler that the
-object is declared and initialized elsewhere. The following package compiles
-without warnings (and the initialization is suppressed):
-
-@smallexample @c ada
- with System;
- package G is
- type R is record
- M : Integer := 0;
- end record;
-
- Ext : R;
- for Ext'Address use System'To_Address (16#1234_1234#);
- pragma Import (Ada, Ext);
- end G;
-@end smallexample
-
-@noindent
-A final issue with address clauses involves their use for overlaying
-variables, as in the following example:
-@cindex Overlaying of objects
-
-@smallexample @c ada
- A : Integer;
- B : Integer;
- for B'Address use A'Address;
-@end smallexample
-
-@noindent
-or alternatively, using the form recommended by the RM:
-
-@smallexample @c ada
- A : Integer;
- Addr : constant Address := A'Address;
- B : Integer;
- for B'Address use Addr;
-@end smallexample
-
-@noindent
-In both of these cases, @code{A}
-and @code{B} become aliased to one another via the
-address clause. This use of address clauses to overlay
-variables, achieving an effect similar to unchecked
-conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005
-the effect is implementation defined. Furthermore, the
-Ada RM specifically recommends that in a situation
-like this, @code{B} should be subject to the following
-implementation advice (RM 13.3(19)):
-
-@quotation
-19 If the Address of an object is specified, or it is imported
- or exported, then the implementation should not perform
- optimizations based on assumptions of no aliases.
-@end quotation
-
-@noindent
-GNAT follows this recommendation, and goes further by also applying
-this recommendation to the overlaid variable (@code{A}
-in the above example) in this case. This means that the overlay
-works "as expected", in that a modification to one of the variables
-will affect the value of the other.
-
-@node Effect of Convention on Representation
-@section Effect of Convention on Representation
-@cindex Convention, effect on representation
-
-@noindent
-Normally the specification of a foreign language convention for a type or
-an object has no effect on the chosen representation. In particular, the
-representation chosen for data in GNAT generally meets the standard system
-conventions, and for example records are laid out in a manner that is
-consistent with C@. This means that specifying convention C (for example)
-has no effect.
-
-There are four exceptions to this general rule:
-
-@itemize @bullet
-
-@item Convention Fortran and array subtypes
-If pragma Convention Fortran is specified for an array subtype, then in
-accordance with the implementation advice in section 3.6.2(11) of the
-Ada Reference Manual, the array will be stored in a Fortran-compatible
-column-major manner, instead of the normal default row-major order.
-
-@item Convention C and enumeration types
-GNAT normally stores enumeration types in 8, 16, or 32 bits as required
-to accommodate all values of the type. For example, for the enumeration
-type declared by:
-
-@smallexample @c ada
- type Color is (Red, Green, Blue);
-@end smallexample
-
-@noindent
-8 bits is sufficient to store all values of the type, so by default, objects
-of type @code{Color} will be represented using 8 bits. However, normal C
-convention is to use 32 bits for all enum values in C, since enum values
-are essentially of type int. If pragma @code{Convention C} is specified for an
-Ada enumeration type, then the size is modified as necessary (usually to
-32 bits) to be consistent with the C convention for enum values.
-
-Note that this treatment applies only to types. If Convention C is given for
-an enumeration object, where the enumeration type is not Convention C, then
-Object_Size bits are allocated. For example, for a normal enumeration type,
-with less than 256 elements, only 8 bits will be allocated for the object.
-Since this may be a surprise in terms of what C expects, GNAT will issue a
-warning in this situation. The warning can be suppressed by giving an explicit
-size clause specifying the desired size.
-
-@item Convention C/Fortran and Boolean types
-In C, the usual convention for boolean values, that is values used for
-conditions, is that zero represents false, and nonzero values represent
-true. In Ada, the normal convention is that two specific values, typically
-0/1, are used to represent false/true respectively.
-
-Fortran has a similar convention for @code{LOGICAL} values (any nonzero
-value represents true).
-
-To accommodate the Fortran and C conventions, if a pragma Convention specifies
-C or Fortran convention for a derived Boolean, as in the following example:
-
-@smallexample @c ada
- type C_Switch is new Boolean;
- pragma Convention (C, C_Switch);
-@end smallexample
-
-@noindent
-then the GNAT generated code will treat any nonzero value as true. For truth
-values generated by GNAT, the conventional value 1 will be used for True, but
-when one of these values is read, any nonzero value is treated as True.
-
-@item Access types on OpenVMS
-For 64-bit OpenVMS systems, access types (other than those for unconstrained
-arrays) are 64-bits long. An exception to this rule is for the case of
-C-convention access types where there is no explicit size clause present (or
-inherited for derived types). In this case, GNAT chooses to make these
-pointers 32-bits, which provides an easier path for migration of 32-bit legacy
-code. size clause specifying 64-bits must be used to obtain a 64-bit pointer.
-
-@end itemize
-
-@node Determining the Representations chosen by GNAT
-@section Determining the Representations chosen by GNAT
-@cindex Representation, determination of
-@cindex @option{-gnatR} switch
-
-@noindent
-Although the descriptions in this section are intended to be complete, it is
-often easier to simply experiment to see what GNAT accepts and what the
-effect is on the layout of types and objects.
-
-As required by the Ada RM, if a representation clause is not accepted, then
-it must be rejected as illegal by the compiler. However, when a
-representation clause or pragma is accepted, there can still be questions
-of what the compiler actually does. For example, if a partial record
-representation clause specifies the location of some components and not
-others, then where are the non-specified components placed? Or if pragma
-@code{Pack} is used on a record, then exactly where are the resulting
-fields placed? The section on pragma @code{Pack} in this chapter can be
-used to answer the second question, but it is often easier to just see
-what the compiler does.
-
-For this purpose, GNAT provides the option @option{-gnatR}. If you compile
-with this option, then the compiler will output information on the actual
-representations chosen, in a format similar to source representation
-clauses. For example, if we compile the package:
-
-@smallexample @c ada
-package q is
- type r (x : boolean) is tagged record
- case x is
- when True => S : String (1 .. 100);
- when False => null;
- end case;
- end record;
-
- type r2 is new r (false) with record
- y2 : integer;
- end record;
-
- for r2 use record
- y2 at 16 range 0 .. 31;
- end record;
-
- type x is record
- y : character;
- end record;
-
- type x1 is array (1 .. 10) of x;
- for x1'component_size use 11;
-
- type ia is access integer;
-
- type Rb1 is array (1 .. 13) of Boolean;
- pragma Pack (rb1);
-
- type Rb2 is array (1 .. 65) of Boolean;
- pragma Pack (rb2);
-
- type x2 is record
- l1 : Boolean;
- l2 : Duration;
- l3 : Float;
- l4 : Boolean;
- l5 : Rb1;
- l6 : Rb2;
- end record;
- pragma Pack (x2);
-end q;
-@end smallexample
-
-@noindent
-using the switch @option{-gnatR} we obtain the following output:
-
-@smallexample
-Representation information for unit q
--------------------------------------
-
-for r'Size use ??;
-for r'Alignment use 4;
-for r use record
- x at 4 range 0 .. 7;
- _tag at 0 range 0 .. 31;
- s at 5 range 0 .. 799;
-end record;
-
-for r2'Size use 160;
-for r2'Alignment use 4;
-for r2 use record
- x at 4 range 0 .. 7;
- _tag at 0 range 0 .. 31;
- _parent at 0 range 0 .. 63;
- y2 at 16 range 0 .. 31;
-end record;
-
-for x'Size use 8;
-for x'Alignment use 1;
-for x use record
- y at 0 range 0 .. 7;
-end record;
-
-for x1'Size use 112;
-for x1'Alignment use 1;
-for x1'Component_Size use 11;
-
-for rb1'Size use 13;
-for rb1'Alignment use 2;
-for rb1'Component_Size use 1;
-
-for rb2'Size use 72;
-for rb2'Alignment use 1;
-for rb2'Component_Size use 1;
-
-for x2'Size use 224;
-for x2'Alignment use 4;
-for x2 use record
- l1 at 0 range 0 .. 0;
- l2 at 0 range 1 .. 64;
- l3 at 12 range 0 .. 31;
- l4 at 16 range 0 .. 0;
- l5 at 16 range 1 .. 13;
- l6 at 18 range 0 .. 71;
-end record;
-@end smallexample
-
-@noindent
-The Size values are actually the Object_Size, i.e.@: the default size that
-will be allocated for objects of the type.
-The ?? size for type r indicates that we have a variant record, and the
-actual size of objects will depend on the discriminant value.
-
-The Alignment values show the actual alignment chosen by the compiler
-for each record or array type.
-
-The record representation clause for type r shows where all fields
-are placed, including the compiler generated tag field (whose location
-cannot be controlled by the programmer).
-
-The record representation clause for the type extension r2 shows all the
-fields present, including the parent field, which is a copy of the fields
-of the parent type of r2, i.e.@: r1.
-
-The component size and size clauses for types rb1 and rb2 show
-the exact effect of pragma @code{Pack} on these arrays, and the record
-representation clause for type x2 shows how pragma @code{Pack} affects
-this record type.
-
-In some cases, it may be useful to cut and paste the representation clauses
-generated by the compiler into the original source to fix and guarantee
-the actual representation to be used.
-
-@node Standard Library Routines
-@chapter Standard Library Routines
-
-@noindent
-The Ada Reference Manual contains in Annex A a full description of an
-extensive set of standard library routines that can be used in any Ada
-program, and which must be provided by all Ada compilers. They are
-analogous to the standard C library used by C programs.
-
-GNAT implements all of the facilities described in annex A, and for most
-purposes the description in the Ada Reference Manual, or appropriate Ada
-text book, will be sufficient for making use of these facilities.
-
-In the case of the input-output facilities,
-@xref{The Implementation of Standard I/O},
-gives details on exactly how GNAT interfaces to the
-file system. For the remaining packages, the Ada Reference Manual
-should be sufficient. The following is a list of the packages included,
-together with a brief description of the functionality that is provided.
-
-For completeness, references are included to other predefined library
-routines defined in other sections of the Ada Reference Manual (these are
-cross-indexed from Annex A).
-
-@table @code
-@item Ada (A.2)
-This is a parent package for all the standard library packages. It is
-usually included implicitly in your program, and itself contains no
-useful data or routines.
-
-@item Ada.Calendar (9.6)
-@code{Calendar} provides time of day access, and routines for
-manipulating times and durations.
-
-@item Ada.Characters (A.3.1)
-This is a dummy parent package that contains no useful entities
-
-@item Ada.Characters.Handling (A.3.2)
-This package provides some basic character handling capabilities,
-including classification functions for classes of characters (e.g.@: test
-for letters, or digits).
-
-@item Ada.Characters.Latin_1 (A.3.3)
-This package includes a complete set of definitions of the characters
-that appear in type CHARACTER@. It is useful for writing programs that
-will run in international environments. For example, if you want an
-upper case E with an acute accent in a string, it is often better to use
-the definition of @code{UC_E_Acute} in this package. Then your program
-will print in an understandable manner even if your environment does not
-support these extended characters.
-
-@item Ada.Command_Line (A.15)
-This package provides access to the command line parameters and the name
-of the current program (analogous to the use of @code{argc} and @code{argv}
-in C), and also allows the exit status for the program to be set in a
-system-independent manner.
-
-@item Ada.Decimal (F.2)
-This package provides constants describing the range of decimal numbers
-implemented, and also a decimal divide routine (analogous to the COBOL
-verb DIVIDE @dots{} GIVING @dots{} REMAINDER @dots{})
-
-@item Ada.Direct_IO (A.8.4)
-This package provides input-output using a model of a set of records of
-fixed-length, containing an arbitrary definite Ada type, indexed by an
-integer record number.
-
-@item Ada.Dynamic_Priorities (D.5)
-This package allows the priorities of a task to be adjusted dynamically
-as the task is running.
-
-@item Ada.Exceptions (11.4.1)
-This package provides additional information on exceptions, and also
-contains facilities for treating exceptions as data objects, and raising
-exceptions with associated messages.
-
-@item Ada.Finalization (7.6)
-This package contains the declarations and subprograms to support the
-use of controlled types, providing for automatic initialization and
-finalization (analogous to the constructors and destructors of C++)
-
-@item Ada.Interrupts (C.3.2)
-This package provides facilities for interfacing to interrupts, which
-includes the set of signals or conditions that can be raised and
-recognized as interrupts.
-
-@item Ada.Interrupts.Names (C.3.2)
-This package provides the set of interrupt names (actually signal
-or condition names) that can be handled by GNAT@.
-
-@item Ada.IO_Exceptions (A.13)
-This package defines the set of exceptions that can be raised by use of
-the standard IO packages.
-
-@item Ada.Numerics
-This package contains some standard constants and exceptions used
-throughout the numerics packages. Note that the constants pi and e are
-defined here, and it is better to use these definitions than rolling
-your own.
-
-@item Ada.Numerics.Complex_Elementary_Functions
-Provides the implementation of standard elementary functions (such as
-log and trigonometric functions) operating on complex numbers using the
-standard @code{Float} and the @code{Complex} and @code{Imaginary} types
-created by the package @code{Numerics.Complex_Types}.
-
-@item Ada.Numerics.Complex_Types
-This is a predefined instantiation of
-@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
-build the type @code{Complex} and @code{Imaginary}.
-
-@item Ada.Numerics.Discrete_Random
-This package provides a random number generator suitable for generating
-random integer values from a specified range.
-
-@item Ada.Numerics.Float_Random
-This package provides a random number generator suitable for generating
-uniformly distributed floating point values.
-
-@item Ada.Numerics.Generic_Complex_Elementary_Functions
-This is a generic version of the package that provides the
-implementation of standard elementary functions (such as log and
-trigonometric functions) for an arbitrary complex type.
-
-The following predefined instantiations of this package are provided:
-
-@table @code
-@item Short_Float
-@code{Ada.Numerics.Short_Complex_Elementary_Functions}
-@item Float
-@code{Ada.Numerics.Complex_Elementary_Functions}
-@item Long_Float
-@code{Ada.Numerics.Long_Complex_Elementary_Functions}
-@end table
-
-@item Ada.Numerics.Generic_Complex_Types
-This is a generic package that allows the creation of complex types,
-with associated complex arithmetic operations.
-
-The following predefined instantiations of this package exist
-@table @code
-@item Short_Float
-@code{Ada.Numerics.Short_Complex_Complex_Types}
-@item Float
-@code{Ada.Numerics.Complex_Complex_Types}
-@item Long_Float
-@code{Ada.Numerics.Long_Complex_Complex_Types}
-@end table
-
-@item Ada.Numerics.Generic_Elementary_Functions
-This is a generic package that provides the implementation of standard
-elementary functions (such as log an trigonometric functions) for an
-arbitrary float type.
-
-The following predefined instantiations of this package exist
-
-@table @code
-@item Short_Float
-@code{Ada.Numerics.Short_Elementary_Functions}
-@item Float
-@code{Ada.Numerics.Elementary_Functions}
-@item Long_Float
-@code{Ada.Numerics.Long_Elementary_Functions}
-@end table
-
-@item Ada.Real_Time (D.8)
-This package provides facilities similar to those of @code{Calendar}, but
-operating with a finer clock suitable for real time control. Note that
-annex D requires that there be no backward clock jumps, and GNAT generally
-guarantees this behavior, but of course if the external clock on which
-the GNAT runtime depends is deliberately reset by some external event,
-then such a backward jump may occur.
-
-@item Ada.Sequential_IO (A.8.1)
-This package provides input-output facilities for sequential files,
-which can contain a sequence of values of a single type, which can be
-any Ada type, including indefinite (unconstrained) types.
-
-@item Ada.Storage_IO (A.9)
-This package provides a facility for mapping arbitrary Ada types to and
-from a storage buffer. It is primarily intended for the creation of new
-IO packages.
-
-@item Ada.Streams (13.13.1)
-This is a generic package that provides the basic support for the
-concept of streams as used by the stream attributes (@code{Input},
-@code{Output}, @code{Read} and @code{Write}).
-
-@item Ada.Streams.Stream_IO (A.12.1)
-This package is a specialization of the type @code{Streams} defined in
-package @code{Streams} together with a set of operations providing
-Stream_IO capability. The Stream_IO model permits both random and
-sequential access to a file which can contain an arbitrary set of values
-of one or more Ada types.
-
-@item Ada.Strings (A.4.1)
-This package provides some basic constants used by the string handling
-packages.
-
-@item Ada.Strings.Bounded (A.4.4)
-This package provides facilities for handling variable length
-strings. The bounded model requires a maximum length. It is thus
-somewhat more limited than the unbounded model, but avoids the use of
-dynamic allocation or finalization.
-
-@item Ada.Strings.Fixed (A.4.3)
-This package provides facilities for handling fixed length strings.
-
-@item Ada.Strings.Maps (A.4.2)
-This package provides facilities for handling character mappings and
-arbitrarily defined subsets of characters. For instance it is useful in
-defining specialized translation tables.
-
-@item Ada.Strings.Maps.Constants (A.4.6)
-This package provides a standard set of predefined mappings and
-predefined character sets. For example, the standard upper to lower case
-conversion table is found in this package. Note that upper to lower case
-conversion is non-trivial if you want to take the entire set of
-characters, including extended characters like E with an acute accent,
-into account. You should use the mappings in this package (rather than
-adding 32 yourself) to do case mappings.
-
-@item Ada.Strings.Unbounded (A.4.5)
-This package provides facilities for handling variable length
-strings. The unbounded model allows arbitrary length strings, but
-requires the use of dynamic allocation and finalization.
-
-@item Ada.Strings.Wide_Bounded (A.4.7)
-@itemx Ada.Strings.Wide_Fixed (A.4.7)
-@itemx Ada.Strings.Wide_Maps (A.4.7)
-@itemx Ada.Strings.Wide_Maps.Constants (A.4.7)
-@itemx Ada.Strings.Wide_Unbounded (A.4.7)
-These packages provide analogous capabilities to the corresponding
-packages without @samp{Wide_} in the name, but operate with the types
-@code{Wide_String} and @code{Wide_Character} instead of @code{String}
-and @code{Character}.
-
-@item Ada.Strings.Wide_Wide_Bounded (A.4.7)
-@itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
-@itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
-@itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)
-@itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
-These packages provide analogous capabilities to the corresponding
-packages without @samp{Wide_} in the name, but operate with the types
-@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
-of @code{String} and @code{Character}.
-
-@item Ada.Synchronous_Task_Control (D.10)
-This package provides some standard facilities for controlling task
-communication in a synchronous manner.
-
-@item Ada.Tags
-This package contains definitions for manipulation of the tags of tagged
-values.
-
-@item Ada.Task_Attributes
-This package provides the capability of associating arbitrary
-task-specific data with separate tasks.
-
-@item Ada.Text_IO
-This package provides basic text input-output capabilities for
-character, string and numeric data. The subpackages of this
-package are listed next.
-
-@item Ada.Text_IO.Decimal_IO
-Provides input-output facilities for decimal fixed-point types
-
-@item Ada.Text_IO.Enumeration_IO
-Provides input-output facilities for enumeration types.
-
-@item Ada.Text_IO.Fixed_IO
-Provides input-output facilities for ordinary fixed-point types.
-
-@item Ada.Text_IO.Float_IO
-Provides input-output facilities for float types. The following
-predefined instantiations of this generic package are available:
-
-@table @code
-@item Short_Float
-@code{Short_Float_Text_IO}
-@item Float
-@code{Float_Text_IO}
-@item Long_Float
-@code{Long_Float_Text_IO}
-@end table
-
-@item Ada.Text_IO.Integer_IO
-Provides input-output facilities for integer types. The following
-predefined instantiations of this generic package are available:
-
-@table @code
-@item Short_Short_Integer
-@code{Ada.Short_Short_Integer_Text_IO}
-@item Short_Integer
-@code{Ada.Short_Integer_Text_IO}
-@item Integer
-@code{Ada.Integer_Text_IO}
-@item Long_Integer
-@code{Ada.Long_Integer_Text_IO}
-@item Long_Long_Integer
-@code{Ada.Long_Long_Integer_Text_IO}
-@end table
-
-@item Ada.Text_IO.Modular_IO
-Provides input-output facilities for modular (unsigned) types
-
-@item Ada.Text_IO.Complex_IO (G.1.3)
-This package provides basic text input-output capabilities for complex
-data.
-
-@item Ada.Text_IO.Editing (F.3.3)
-This package contains routines for edited output, analogous to the use
-of pictures in COBOL@. The picture formats used by this package are a
-close copy of the facility in COBOL@.
-
-@item Ada.Text_IO.Text_Streams (A.12.2)
-This package provides a facility that allows Text_IO files to be treated
-as streams, so that the stream attributes can be used for writing
-arbitrary data, including binary data, to Text_IO files.
-
-@item Ada.Unchecked_Conversion (13.9)
-This generic package allows arbitrary conversion from one type to
-another of the same size, providing for breaking the type safety in
-special circumstances.
-
-If the types have the same Size (more accurately the same Value_Size),
-then the effect is simply to transfer the bits from the source to the
-target type without any modification. This usage is well defined, and
-for simple types whose representation is typically the same across
-all implementations, gives a portable method of performing such
-conversions.
-
-If the types do not have the same size, then the result is implementation
-defined, and thus may be non-portable. The following describes how GNAT
-handles such unchecked conversion cases.
-
-If the types are of different sizes, and are both discrete types, then
-the effect is of a normal type conversion without any constraint checking.
-In particular if the result type has a larger size, the result will be
-zero or sign extended. If the result type has a smaller size, the result
-will be truncated by ignoring high order bits.
-
-If the types are of different sizes, and are not both discrete types,
-then the conversion works as though pointers were created to the source
-and target, and the pointer value is converted. The effect is that bits
-are copied from successive low order storage units and bits of the source
-up to the length of the target type.
-
-A warning is issued if the lengths differ, since the effect in this
-case is implementation dependent, and the above behavior may not match
-that of some other compiler.
-
-A pointer to one type may be converted to a pointer to another type using
-unchecked conversion. The only case in which the effect is undefined is
-when one or both pointers are pointers to unconstrained array types. In
-this case, the bounds information may get incorrectly transferred, and in
-particular, GNAT uses double size pointers for such types, and it is
-meaningless to convert between such pointer types. GNAT will issue a
-warning if the alignment of the target designated type is more strict
-than the alignment of the source designated type (since the result may
-be unaligned in this case).
-
-A pointer other than a pointer to an unconstrained array type may be
-converted to and from System.Address. Such usage is common in Ada 83
-programs, but note that Ada.Address_To_Access_Conversions is the
-preferred method of performing such conversions in Ada 95 and Ada 2005.
-Neither
-unchecked conversion nor Ada.Address_To_Access_Conversions should be
-used in conjunction with pointers to unconstrained objects, since
-the bounds information cannot be handled correctly in this case.
-
-@item Ada.Unchecked_Deallocation (13.11.2)
-This generic package allows explicit freeing of storage previously
-allocated by use of an allocator.
-
-@item Ada.Wide_Text_IO (A.11)
-This package is similar to @code{Ada.Text_IO}, except that the external
-file supports wide character representations, and the internal types are
-@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
-and @code{String}. It contains generic subpackages listed next.
-
-@item Ada.Wide_Text_IO.Decimal_IO
-Provides input-output facilities for decimal fixed-point types
-
-@item Ada.Wide_Text_IO.Enumeration_IO
-Provides input-output facilities for enumeration types.
-
-@item Ada.Wide_Text_IO.Fixed_IO
-Provides input-output facilities for ordinary fixed-point types.
-
-@item Ada.Wide_Text_IO.Float_IO
-Provides input-output facilities for float types. The following
-predefined instantiations of this generic package are available:
-
-@table @code
-@item Short_Float
-@code{Short_Float_Wide_Text_IO}
-@item Float
-@code{Float_Wide_Text_IO}
-@item Long_Float
-@code{Long_Float_Wide_Text_IO}
-@end table
-
-@item Ada.Wide_Text_IO.Integer_IO
-Provides input-output facilities for integer types. The following
-predefined instantiations of this generic package are available:
-
-@table @code
-@item Short_Short_Integer
-@code{Ada.Short_Short_Integer_Wide_Text_IO}
-@item Short_Integer
-@code{Ada.Short_Integer_Wide_Text_IO}
-@item Integer
-@code{Ada.Integer_Wide_Text_IO}
-@item Long_Integer
-@code{Ada.Long_Integer_Wide_Text_IO}
-@item Long_Long_Integer
-@code{Ada.Long_Long_Integer_Wide_Text_IO}
-@end table
-
-@item Ada.Wide_Text_IO.Modular_IO
-Provides input-output facilities for modular (unsigned) types
-
-@item Ada.Wide_Text_IO.Complex_IO (G.1.3)
-This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
-external file supports wide character representations.
-
-@item Ada.Wide_Text_IO.Editing (F.3.4)
-This package is similar to @code{Ada.Text_IO.Editing}, except that the
-types are @code{Wide_Character} and @code{Wide_String} instead of
-@code{Character} and @code{String}.
-
-@item Ada.Wide_Text_IO.Streams (A.12.3)
-This package is similar to @code{Ada.Text_IO.Streams}, except that the
-types are @code{Wide_Character} and @code{Wide_String} instead of
-@code{Character} and @code{String}.
-
-@item Ada.Wide_Wide_Text_IO (A.11)
-This package is similar to @code{Ada.Text_IO}, except that the external
-file supports wide character representations, and the internal types are
-@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
-and @code{String}. It contains generic subpackages listed next.
-
-@item Ada.Wide_Wide_Text_IO.Decimal_IO
-Provides input-output facilities for decimal fixed-point types
-
-@item Ada.Wide_Wide_Text_IO.Enumeration_IO
-Provides input-output facilities for enumeration types.
-
-@item Ada.Wide_Wide_Text_IO.Fixed_IO
-Provides input-output facilities for ordinary fixed-point types.
-
-@item Ada.Wide_Wide_Text_IO.Float_IO
-Provides input-output facilities for float types. The following
-predefined instantiations of this generic package are available:
-
-@table @code
-@item Short_Float
-@code{Short_Float_Wide_Wide_Text_IO}
-@item Float
-@code{Float_Wide_Wide_Text_IO}
-@item Long_Float
-@code{Long_Float_Wide_Wide_Text_IO}
-@end table
-
-@item Ada.Wide_Wide_Text_IO.Integer_IO
-Provides input-output facilities for integer types. The following
-predefined instantiations of this generic package are available:
-
-@table @code
-@item Short_Short_Integer
-@code{Ada.Short_Short_Integer_Wide_Wide_Text_IO}
-@item Short_Integer
-@code{Ada.Short_Integer_Wide_Wide_Text_IO}
-@item Integer
-@code{Ada.Integer_Wide_Wide_Text_IO}
-@item Long_Integer
-@code{Ada.Long_Integer_Wide_Wide_Text_IO}
-@item Long_Long_Integer
-@code{Ada.Long_Long_Integer_Wide_Wide_Text_IO}
-@end table
-
-@item Ada.Wide_Wide_Text_IO.Modular_IO
-Provides input-output facilities for modular (unsigned) types
-
-@item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)
-This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
-external file supports wide character representations.
-
-@item Ada.Wide_Wide_Text_IO.Editing (F.3.4)
-This package is similar to @code{Ada.Text_IO.Editing}, except that the
-types are @code{Wide_Character} and @code{Wide_String} instead of
-@code{Character} and @code{String}.
-
-@item Ada.Wide_Wide_Text_IO.Streams (A.12.3)
-This package is similar to @code{Ada.Text_IO.Streams}, except that the
-types are @code{Wide_Character} and @code{Wide_String} instead of
-@code{Character} and @code{String}.
-@end table
-
-
-
-@node The Implementation of Standard I/O
-@chapter The Implementation of Standard I/O
-
-@noindent
-GNAT implements all the required input-output facilities described in
-A.6 through A.14. These sections of the Ada Reference Manual describe the
-required behavior of these packages from the Ada point of view, and if
-you are writing a portable Ada program that does not need to know the
-exact manner in which Ada maps to the outside world when it comes to
-reading or writing external files, then you do not need to read this
-chapter. As long as your files are all regular files (not pipes or
-devices), and as long as you write and read the files only from Ada, the
-description in the Ada Reference Manual is sufficient.
-
-However, if you want to do input-output to pipes or other devices, such
-as the keyboard or screen, or if the files you are dealing with are
-either generated by some other language, or to be read by some other
-language, then you need to know more about the details of how the GNAT
-implementation of these input-output facilities behaves.
-
-In this chapter we give a detailed description of exactly how GNAT
-interfaces to the file system. As always, the sources of the system are
-available to you for answering questions at an even more detailed level,
-but for most purposes the information in this chapter will suffice.
-
-Another reason that you may need to know more about how input-output is
-implemented arises when you have a program written in mixed languages
-where, for example, files are shared between the C and Ada sections of
-the same program. GNAT provides some additional facilities, in the form
-of additional child library packages, that facilitate this sharing, and
-these additional facilities are also described in this chapter.
-
-@menu
-* Standard I/O Packages::
-* FORM Strings::
-* Direct_IO::
-* Sequential_IO::
-* Text_IO::
-* Wide_Text_IO::
-* Wide_Wide_Text_IO::
-* Stream_IO::
-* Shared Files::
-* Filenames encoding::
-* Open Modes::
-* Operations on C Streams::
-* Interfacing to C Streams::
-@end menu
-
-@node Standard I/O Packages
-@section Standard I/O Packages
-
-@noindent
-The Standard I/O packages described in Annex A for
-
-@itemize @bullet
-@item
-Ada.Text_IO
-@item
-Ada.Text_IO.Complex_IO
-@item
-Ada.Text_IO.Text_Streams
-@item
-Ada.Wide_Text_IO
-@item
-Ada.Wide_Text_IO.Complex_IO
-@item
-Ada.Wide_Text_IO.Text_Streams
-@item
-Ada.Wide_Wide_Text_IO
-@item
-Ada.Wide_Wide_Text_IO.Complex_IO
-@item
-Ada.Wide_Wide_Text_IO.Text_Streams
-@item
-Ada.Stream_IO
-@item
-Ada.Sequential_IO
-@item
-Ada.Direct_IO
-@end itemize
-
-@noindent
-are implemented using the C
-library streams facility; where
-
-@itemize @bullet
-@item
-All files are opened using @code{fopen}.
-@item
-All input/output operations use @code{fread}/@code{fwrite}.
-@end itemize
-
-@noindent
-There is no internal buffering of any kind at the Ada library level. The only
-buffering is that provided at the system level in the implementation of the
-library routines that support streams. This facilitates shared use of these
-streams by mixed language programs. Note though that system level buffering is
-explicitly enabled at elaboration of the standard I/O packages and that can
-have an impact on mixed language programs, in particular those using I/O before
-calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call
-the Ada elaboration routine before performing any I/O or when impractical,
-flush the common I/O streams and in particular Standard_Output before
-elaborating the Ada code.
-
-@node FORM Strings
-@section FORM Strings
-
-@noindent
-The format of a FORM string in GNAT is:
-
-@smallexample
-"keyword=value,keyword=value,@dots{},keyword=value"
-@end smallexample
-
-@noindent
-where letters may be in upper or lower case, and there are no spaces
-between values. The order of the entries is not important. Currently
-there are two keywords defined.
-
-@smallexample
-SHARED=[YES|NO]
-WCEM=[n|h|u|s|e|8|b]
-@end smallexample
-
-@noindent
-The use of these parameters is described later in this section.
-
-@node Direct_IO
-@section Direct_IO
-
-@noindent
-Direct_IO can only be instantiated for definite types. This is a
-restriction of the Ada language, which means that the records are fixed
-length (the length being determined by @code{@var{type}'Size}, rounded
-up to the next storage unit boundary if necessary).
-
-The records of a Direct_IO file are simply written to the file in index
-sequence, with the first record starting at offset zero, and subsequent
-records following. There is no control information of any kind. For
-example, if 32-bit integers are being written, each record takes
-4-bytes, so the record at index @var{K} starts at offset
-(@var{K}@minus{}1)*4.
-
-There is no limit on the size of Direct_IO files, they are expanded as
-necessary to accommodate whatever records are written to the file.
-
-@node Sequential_IO
-@section Sequential_IO
-
-@noindent
-Sequential_IO may be instantiated with either a definite (constrained)
-or indefinite (unconstrained) type.
-
-For the definite type case, the elements written to the file are simply
-the memory images of the data values with no control information of any
-kind. The resulting file should be read using the same type, no validity
-checking is performed on input.
-
-For the indefinite type case, the elements written consist of two
-parts. First is the size of the data item, written as the memory image
-of a @code{Interfaces.C.size_t} value, followed by the memory image of
-the data value. The resulting file can only be read using the same
-(unconstrained) type. Normal assignment checks are performed on these
-read operations, and if these checks fail, @code{Data_Error} is
-raised. In particular, in the array case, the lengths must match, and in
-the variant record case, if the variable for a particular read operation
-is constrained, the discriminants must match.
-
-Note that it is not possible to use Sequential_IO to write variable
-length array items, and then read the data back into different length
-arrays. For example, the following will raise @code{Data_Error}:
-
-@smallexample @c ada
- package IO is new Sequential_IO (String);
- F : IO.File_Type;
- S : String (1..4);
- @dots{}
- IO.Create (F)
- IO.Write (F, "hello!")
- IO.Reset (F, Mode=>In_File);
- IO.Read (F, S);
- Put_Line (S);
-
-@end smallexample
-
-@noindent
-On some Ada implementations, this will print @code{hell}, but the program is
-clearly incorrect, since there is only one element in the file, and that
-element is the string @code{hello!}.
-
-In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
-using Stream_IO, and this is the preferred mechanism. In particular, the
-above program fragment rewritten to use Stream_IO will work correctly.
-
-@node Text_IO
-@section Text_IO
-
-@noindent
-Text_IO files consist of a stream of characters containing the following
-special control characters:
-
-@smallexample
-LF (line feed, 16#0A#) Line Mark
-FF (form feed, 16#0C#) Page Mark
-@end smallexample
-
-@noindent
-A canonical Text_IO file is defined as one in which the following
-conditions are met:
-
-@itemize @bullet
-@item
-The character @code{LF} is used only as a line mark, i.e.@: to mark the end
-of the line.
-
-@item
-The character @code{FF} is used only as a page mark, i.e.@: to mark the
-end of a page and consequently can appear only immediately following a
-@code{LF} (line mark) character.
-
-@item
-The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF}
-(line mark, page mark). In the former case, the page mark is implicitly
-assumed to be present.
-@end itemize
-
-@noindent
-A file written using Text_IO will be in canonical form provided that no
-explicit @code{LF} or @code{FF} characters are written using @code{Put}
-or @code{Put_Line}. There will be no @code{FF} character at the end of
-the file unless an explicit @code{New_Page} operation was performed
-before closing the file.
-
-A canonical Text_IO file that is a regular file (i.e., not a device or a
-pipe) can be read using any of the routines in Text_IO@. The
-semantics in this case will be exactly as defined in the Ada Reference
-Manual, and all the routines in Text_IO are fully implemented.
-
-A text file that does not meet the requirements for a canonical Text_IO
-file has one of the following:
-
-@itemize @bullet
-@item
-The file contains @code{FF} characters not immediately following a
-@code{LF} character.
-
-@item
-The file contains @code{LF} or @code{FF} characters written by
-@code{Put} or @code{Put_Line}, which are not logically considered to be
-line marks or page marks.
-
-@item
-The file ends in a character other than @code{LF} or @code{FF},
-i.e.@: there is no explicit line mark or page mark at the end of the file.
-@end itemize
-
-@noindent
-Text_IO can be used to read such non-standard text files but subprograms
-to do with line or page numbers do not have defined meanings. In
-particular, a @code{FF} character that does not follow a @code{LF}
-character may or may not be treated as a page mark from the point of
-view of page and line numbering. Every @code{LF} character is considered
-to end a line, and there is an implied @code{LF} character at the end of
-the file.
-
-@menu
-* Text_IO Stream Pointer Positioning::
-* Text_IO Reading and Writing Non-Regular Files::
-* Get_Immediate::
-* Treating Text_IO Files as Streams::
-* Text_IO Extensions::
-* Text_IO Facilities for Unbounded Strings::
-@end menu
-
-@node Text_IO Stream Pointer Positioning
-@subsection Stream Pointer Positioning
-
-@noindent
-@code{Ada.Text_IO} has a definition of current position for a file that
-is being read. No internal buffering occurs in Text_IO, and usually the
-physical position in the stream used to implement the file corresponds
-to this logical position defined by Text_IO@. There are two exceptions:
-
-@itemize @bullet
-@item
-After a call to @code{End_Of_Page} that returns @code{True}, the stream
-is positioned past the @code{LF} (line mark) that precedes the page
-mark. Text_IO maintains an internal flag so that subsequent read
-operations properly handle the logical position which is unchanged by
-the @code{End_Of_Page} call.
-
-@item
-After a call to @code{End_Of_File} that returns @code{True}, if the
-Text_IO file was positioned before the line mark at the end of file
-before the call, then the logical position is unchanged, but the stream
-is physically positioned right at the end of file (past the line mark,
-and past a possible page mark following the line mark. Again Text_IO
-maintains internal flags so that subsequent read operations properly
-handle the logical position.
-@end itemize
-
-@noindent
-These discrepancies have no effect on the observable behavior of
-Text_IO, but if a single Ada stream is shared between a C program and
-Ada program, or shared (using @samp{shared=yes} in the form string)
-between two Ada files, then the difference may be observable in some
-situations.
-
-@node Text_IO Reading and Writing Non-Regular Files
-@subsection Reading and Writing Non-Regular Files
-
-@noindent
-A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
-can be used for reading and writing. Writing is not affected and the
-sequence of characters output is identical to the normal file case, but
-for reading, the behavior of Text_IO is modified to avoid undesirable
-look-ahead as follows:
-
-An input file that is not a regular file is considered to have no page
-marks. Any @code{Ascii.FF} characters (the character normally used for a
-page mark) appearing in the file are considered to be data
-characters. In particular:
-
-@itemize @bullet
-@item
-@code{Get_Line} and @code{Skip_Line} do not test for a page mark
-following a line mark. If a page mark appears, it will be treated as a
-data character.
-
-@item
-This avoids the need to wait for an extra character to be typed or
-entered from the pipe to complete one of these operations.
-
-@item
-@code{End_Of_Page} always returns @code{False}
-
-@item
-@code{End_Of_File} will return @code{False} if there is a page mark at
-the end of the file.
-@end itemize
-
-@noindent
-Output to non-regular files is the same as for regular files. Page marks
-may be written to non-regular files using @code{New_Page}, but as noted
-above they will not be treated as page marks on input if the output is
-piped to another Ada program.
-
-Another important discrepancy when reading non-regular files is that the end
-of file indication is not ``sticky''. If an end of file is entered, e.g.@: by
-pressing the @key{EOT} key,
-then end of file
-is signaled once (i.e.@: the test @code{End_Of_File}
-will yield @code{True}, or a read will
-raise @code{End_Error}), but then reading can resume
-to read data past that end of
-file indication, until another end of file indication is entered.
-
-@node Get_Immediate
-@subsection Get_Immediate
-@cindex Get_Immediate
-
-@noindent
-Get_Immediate returns the next character (including control characters)
-from the input file. In particular, Get_Immediate will return LF or FF
-characters used as line marks or page marks. Such operations leave the
-file positioned past the control character, and it is thus not treated
-as having its normal function. This means that page, line and column
-counts after this kind of Get_Immediate call are set as though the mark
-did not occur. In the case where a Get_Immediate leaves the file
-positioned between the line mark and page mark (which is not normally
-possible), it is undefined whether the FF character will be treated as a
-page mark.
-
-@node Treating Text_IO Files as Streams
-@subsection Treating Text_IO Files as Streams
-@cindex Stream files
-
-@noindent
-The package @code{Text_IO.Streams} allows a Text_IO file to be treated
-as a stream. Data written to a Text_IO file in this stream mode is
-binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
-16#0C# (@code{FF}), the resulting file may have non-standard
-format. Similarly if read operations are used to read from a Text_IO
-file treated as a stream, then @code{LF} and @code{FF} characters may be
-skipped and the effect is similar to that described above for
-@code{Get_Immediate}.
-
-@node Text_IO Extensions
-@subsection Text_IO Extensions
-@cindex Text_IO extensions
-
-@noindent
-A package GNAT.IO_Aux in the GNAT library provides some useful extensions
-to the standard @code{Text_IO} package:
-
-@itemize @bullet
-@item function File_Exists (Name : String) return Boolean;
-Determines if a file of the given name exists.
-
-@item function Get_Line return String;
-Reads a string from the standard input file. The value returned is exactly
-the length of the line that was read.
-
-@item function Get_Line (File : Ada.Text_IO.File_Type) return String;
-Similar, except that the parameter File specifies the file from which
-the string is to be read.
-
-@end itemize
-
-@node Text_IO Facilities for Unbounded Strings
-@subsection Text_IO Facilities for Unbounded Strings
-@cindex Text_IO for unbounded strings
-@cindex Unbounded_String, Text_IO operations
-
-@noindent
-The package @code{Ada.Strings.Unbounded.Text_IO}
-in library files @code{a-suteio.ads/adb} contains some GNAT-specific
-subprograms useful for Text_IO operations on unbounded strings:
-
-@itemize @bullet
-
-@item function Get_Line (File : File_Type) return Unbounded_String;
-Reads a line from the specified file
-and returns the result as an unbounded string.
-
-@item procedure Put (File : File_Type; U : Unbounded_String);
-Writes the value of the given unbounded string to the specified file
-Similar to the effect of
-@code{Put (To_String (U))} except that an extra copy is avoided.
-
-@item procedure Put_Line (File : File_Type; U : Unbounded_String);
-Writes the value of the given unbounded string to the specified file,
-followed by a @code{New_Line}.
-Similar to the effect of @code{Put_Line (To_String (U))} except
-that an extra copy is avoided.
-@end itemize
-
-@noindent
-In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
-and is optional. If the parameter is omitted, then the standard input or
-output file is referenced as appropriate.
-
-The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
-files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
-@code{Wide_Text_IO} functionality for unbounded wide strings.
-
-The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
-files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
-@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
-
-@node Wide_Text_IO
-@section Wide_Text_IO
-
-@noindent
-@code{Wide_Text_IO} is similar in most respects to Text_IO, except that
-both input and output files may contain special sequences that represent
-wide character values. The encoding scheme for a given file may be
-specified using a FORM parameter:
-
-@smallexample
-WCEM=@var{x}
-@end smallexample
-
-@noindent
-as part of the FORM string (WCEM = wide character encoding method),
-where @var{x} is one of the following characters
-
-@table @samp
-@item h
-Hex ESC encoding
-@item u
-Upper half encoding
-@item s
-Shift-JIS encoding
-@item e
-EUC Encoding
-@item 8
-UTF-8 encoding
-@item b
-Brackets encoding
-@end table
-
-@noindent
-The encoding methods match those that
-can be used in a source
-program, but there is no requirement that the encoding method used for
-the source program be the same as the encoding method used for files,
-and different files may use different encoding methods.
-
-The default encoding method for the standard files, and for opened files
-for which no WCEM parameter is given in the FORM string matches the
-wide character encoding specified for the main program (the default
-being brackets encoding if no coding method was specified with -gnatW).
-
-@table @asis
-@item Hex Coding
-In this encoding, a wide character is represented by a five character
-sequence:
-
-@smallexample
-ESC a b c d
-@end smallexample
-
-@noindent
-where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal
-characters (using upper case letters) of the wide character code. For
-example, ESC A345 is used to represent the wide character with code
-16#A345#. This scheme is compatible with use of the full
-@code{Wide_Character} set.
-
-@item Upper Half Coding
-The wide character with encoding 16#abcd#, where the upper bit is on
-(i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and
-16#cd#. The second byte may never be a format control character, but is
-not required to be in the upper half. This method can be also used for
-shift-JIS or EUC where the internal coding matches the external coding.
-
-@item Shift JIS Coding
-A wide character is represented by a two character sequence 16#ab# and
-16#cd#, with the restrictions described for upper half encoding as
-described above. The internal character code is the corresponding JIS
-character according to the standard algorithm for Shift-JIS
-conversion. Only characters defined in the JIS code set table can be
-used with this encoding method.
-
-@item EUC Coding
-A wide character is represented by a two character sequence 16#ab# and
-16#cd#, with both characters being in the upper half. The internal
-character code is the corresponding JIS character according to the EUC
-encoding algorithm. Only characters defined in the JIS code set table
-can be used with this encoding method.
-
-@item UTF-8 Coding
-A wide character is represented using
-UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
-10646-1/Am.2. Depending on the character value, the representation
-is a one, two, or three byte sequence:
-
-@smallexample
-16#0000#-16#007f#: 2#0xxxxxxx#
-16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
-16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
-@end smallexample
-
-@noindent
-where the @var{xxx} bits correspond to the left-padded bits of the
-16-bit character value. Note that all lower half ASCII characters
-are represented as ASCII bytes and all upper half characters and
-other wide characters are represented as sequences of upper-half
-(The full UTF-8 scheme allows for encoding 31-bit characters as
-6-byte sequences, but in this implementation, all UTF-8 sequences
-of four or more bytes length will raise a Constraint_Error, as
-will all invalid UTF-8 sequences.)
-
-@item Brackets Coding
-In this encoding, a wide character is represented by the following eight
-character sequence:
-
-@smallexample
-[ " a b c d " ]
-@end smallexample
-
-@noindent
-where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
-characters (using uppercase letters) of the wide character code. For
-example, @code{["A345"]} is used to represent the wide character with code
-@code{16#A345#}.
-This scheme is compatible with use of the full Wide_Character set.
-On input, brackets coding can also be used for upper half characters,
-e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
-is only used for wide characters with a code greater than @code{16#FF#}.
-
-Note that brackets coding is not normally used in the context of
-Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
-a portable way of encoding source files. In the context of Wide_Text_IO
-or Wide_Wide_Text_IO, it can only be used if the file does not contain
-any instance of the left bracket character other than to encode wide
-character values using the brackets encoding method. In practice it is
-expected that some standard wide character encoding method such
-as UTF-8 will be used for text input output.
-
-If brackets notation is used, then any occurrence of a left bracket
-in the input file which is not the start of a valid wide character
-sequence will cause Constraint_Error to be raised. It is possible to
-encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO
-input will interpret this as a left bracket.
-
-However, when a left bracket is output, it will be output as a left bracket
-and not as ["5B"]. We make this decision because for normal use of
-Wide_Text_IO for outputting messages, it is unpleasant to clobber left
-brackets. For example, if we write:
-
-@smallexample
- Put_Line ("Start of output [first run]");
-@end smallexample
-
-@noindent
-we really do not want to have the left bracket in this message clobbered so
-that the output reads:
-
-@smallexample
- Start of output ["5B"]first run]
-@end smallexample
-
-@noindent
-In practice brackets encoding is reasonably useful for normal Put_Line use
-since we won't get confused between left brackets and wide character
-sequences in the output. But for input, or when files are written out
-and read back in, it really makes better sense to use one of the standard
-encoding methods such as UTF-8.
-
-@end table
-
-@noindent
-For the coding schemes other than UTF-8, Hex, or Brackets encoding,
-not all wide character
-values can be represented. An attempt to output a character that cannot
-be represented using the encoding scheme for the file causes
-Constraint_Error to be raised. An invalid wide character sequence on
-input also causes Constraint_Error to be raised.
-
-@menu
-* Wide_Text_IO Stream Pointer Positioning::
-* Wide_Text_IO Reading and Writing Non-Regular Files::
-@end menu
-
-@node Wide_Text_IO Stream Pointer Positioning
-@subsection Stream Pointer Positioning
-
-@noindent
-@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
-of stream pointer positioning (@pxref{Text_IO}). There is one additional
-case:
-
-If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
-normal lower ASCII set (i.e.@: a character in the range:
-
-@smallexample @c ada
-Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
-@end smallexample
-
-@noindent
-then although the logical position of the file pointer is unchanged by
-the @code{Look_Ahead} call, the stream is physically positioned past the
-wide character sequence. Again this is to avoid the need for buffering
-or backup, and all @code{Wide_Text_IO} routines check the internal
-indication that this situation has occurred so that this is not visible
-to a normal program using @code{Wide_Text_IO}. However, this discrepancy
-can be observed if the wide text file shares a stream with another file.
-
-@node Wide_Text_IO Reading and Writing Non-Regular Files
-@subsection Reading and Writing Non-Regular Files
-
-@noindent
-As in the case of Text_IO, when a non-regular file is read, it is
-assumed that the file contains no page marks (any form characters are
-treated as data characters), and @code{End_Of_Page} always returns
-@code{False}. Similarly, the end of file indication is not sticky, so
-it is possible to read beyond an end of file.
-
-@node Wide_Wide_Text_IO
-@section Wide_Wide_Text_IO
-
-@noindent
-@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
-both input and output files may contain special sequences that represent
-wide wide character values. The encoding scheme for a given file may be
-specified using a FORM parameter:
-
-@smallexample
-WCEM=@var{x}
-@end smallexample
-
-@noindent
-as part of the FORM string (WCEM = wide character encoding method),
-where @var{x} is one of the following characters
-
-@table @samp
-@item h
-Hex ESC encoding
-@item u
-Upper half encoding
-@item s
-Shift-JIS encoding
-@item e
-EUC Encoding
-@item 8
-UTF-8 encoding
-@item b
-Brackets encoding
-@end table
-
-@noindent
-The encoding methods match those that
-can be used in a source
-program, but there is no requirement that the encoding method used for
-the source program be the same as the encoding method used for files,
-and different files may use different encoding methods.
-
-The default encoding method for the standard files, and for opened files
-for which no WCEM parameter is given in the FORM string matches the
-wide character encoding specified for the main program (the default
-being brackets encoding if no coding method was specified with -gnatW).
-
-@table @asis
-
-@item UTF-8 Coding
-A wide character is represented using
-UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
-10646-1/Am.2. Depending on the character value, the representation
-is a one, two, three, or four byte sequence:
-
-@smallexample
-16#000000#-16#00007f#: 2#0xxxxxxx#
-16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
-16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
-16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
-@end smallexample
-
-@noindent
-where the @var{xxx} bits correspond to the left-padded bits of the
-21-bit character value. Note that all lower half ASCII characters
-are represented as ASCII bytes and all upper half characters and
-other wide characters are represented as sequences of upper-half
-characters.
-
-@item Brackets Coding
-In this encoding, a wide wide character is represented by the following eight
-character sequence if is in wide character range
-
-@smallexample
-[ " a b c d " ]
-@end smallexample
-
-and by the following ten character sequence if not
-
-@smallexample
-[ " a b c d e f " ]
-@end smallexample
-
-@noindent
-where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
-are the four or six hexadecimal
-characters (using uppercase letters) of the wide wide character code. For
-example, @code{["01A345"]} is used to represent the wide wide character
-with code @code{16#01A345#}.
-
-This scheme is compatible with use of the full Wide_Wide_Character set.
-On input, brackets coding can also be used for upper half characters,
-e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
-is only used for wide characters with a code greater than @code{16#FF#}.
-
-@end table
-
-@noindent
-If is also possible to use the other Wide_Character encoding methods,
-such as Shift-JIS, but the other schemes cannot support the full range
-of wide wide characters.
-An attempt to output a character that cannot
-be represented using the encoding scheme for the file causes
-Constraint_Error to be raised. An invalid wide character sequence on
-input also causes Constraint_Error to be raised.
-
-@menu
-* Wide_Wide_Text_IO Stream Pointer Positioning::
-* Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
-@end menu
-
-@node Wide_Wide_Text_IO Stream Pointer Positioning
-@subsection Stream Pointer Positioning
-
-@noindent
-@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
-of stream pointer positioning (@pxref{Text_IO}). There is one additional
-case:
-
-If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
-normal lower ASCII set (i.e.@: a character in the range:
-
-@smallexample @c ada
-Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
-@end smallexample
-
-@noindent
-then although the logical position of the file pointer is unchanged by
-the @code{Look_Ahead} call, the stream is physically positioned past the
-wide character sequence. Again this is to avoid the need for buffering
-or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
-indication that this situation has occurred so that this is not visible
-to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
-can be observed if the wide text file shares a stream with another file.
-
-@node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
-@subsection Reading and Writing Non-Regular Files
-
-@noindent
-As in the case of Text_IO, when a non-regular file is read, it is
-assumed that the file contains no page marks (any form characters are
-treated as data characters), and @code{End_Of_Page} always returns
-@code{False}. Similarly, the end of file indication is not sticky, so
-it is possible to read beyond an end of file.
-
-@node Stream_IO
-@section Stream_IO
-
-@noindent
-A stream file is a sequence of bytes, where individual elements are
-written to the file as described in the Ada Reference Manual. The type
-@code{Stream_Element} is simply a byte. There are two ways to read or
-write a stream file.
-
-@itemize @bullet
-@item
-The operations @code{Read} and @code{Write} directly read or write a
-sequence of stream elements with no control information.
-
-@item
-The stream attributes applied to a stream file transfer data in the
-manner described for stream attributes.
-@end itemize
-
-@node Shared Files
-@section Shared Files
-
-@noindent
-Section A.14 of the Ada Reference Manual allows implementations to
-provide a wide variety of behavior if an attempt is made to access the
-same external file with two or more internal files.
-
-To provide a full range of functionality, while at the same time
-minimizing the problems of portability caused by this implementation
-dependence, GNAT handles file sharing as follows:
-
-@itemize @bullet
-@item
-In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt
-to open two or more files with the same full name is considered an error
-and is not supported. The exception @code{Use_Error} will be
-raised. Note that a file that is not explicitly closed by the program
-remains open until the program terminates.
-
-@item
-If the form parameter @samp{shared=no} appears in the form string, the
-file can be opened or created with its own separate stream identifier,
-regardless of whether other files sharing the same external file are
-opened. The exact effect depends on how the C stream routines handle
-multiple accesses to the same external files using separate streams.
-
-@item
-If the form parameter @samp{shared=yes} appears in the form string for
-each of two or more files opened using the same full name, the same
-stream is shared between these files, and the semantics are as described
-in Ada Reference Manual, Section A.14.
-@end itemize
-
-@noindent
-When a program that opens multiple files with the same name is ported
-from another Ada compiler to GNAT, the effect will be that
-@code{Use_Error} is raised.
-
-The documentation of the original compiler and the documentation of the
-program should then be examined to determine if file sharing was
-expected, and @samp{shared=@var{xxx}} parameters added to @code{Open}
-and @code{Create} calls as required.
-
-When a program is ported from GNAT to some other Ada compiler, no
-special attention is required unless the @samp{shared=@var{xxx}} form
-parameter is used in the program. In this case, you must examine the
-documentation of the new compiler to see if it supports the required
-file sharing semantics, and form strings modified appropriately. Of
-course it may be the case that the program cannot be ported if the
-target compiler does not support the required functionality. The best
-approach in writing portable code is to avoid file sharing (and hence
-the use of the @samp{shared=@var{xxx}} parameter in the form string)
-completely.
-
-One common use of file sharing in Ada 83 is the use of instantiations of
-Sequential_IO on the same file with different types, to achieve
-heterogeneous input-output. Although this approach will work in GNAT if
-@samp{shared=yes} is specified, it is preferable in Ada to use Stream_IO
-for this purpose (using the stream attributes)
-
-@node Filenames encoding
-@section Filenames encoding
-
-@noindent
-An encoding form parameter can be used to specify the filename
-encoding @samp{encoding=@var{xxx}}.
-
-@itemize @bullet
-@item
-If the form parameter @samp{encoding=utf8} appears in the form string, the
-filename must be encoded in UTF-8.
-
-@item
-If the form parameter @samp{encoding=8bits} appears in the form
-string, the filename must be a standard 8bits string.
-@end itemize
-
-In the absence of a @samp{encoding=@var{xxx}} form parameter, the
-value UTF-8 is used. This encoding form parameter is only supported on
-the Windows platform. On the other Operating Systems the runtime is
-supporting UTF-8 natively.
-
-@node Open Modes
-@section Open Modes
-
-@noindent
-@code{Open} and @code{Create} calls result in a call to @code{fopen}
-using the mode shown in the following table:
-
-@sp 2
-@center @code{Open} and @code{Create} Call Modes
-@smallexample
- @b{OPEN } @b{CREATE}
-Append_File "r+" "w+"
-In_File "r" "w+"
-Out_File (Direct_IO) "r+" "w"
-Out_File (all other cases) "w" "w"
-Inout_File "r+" "w+"
-@end smallexample
-
-@noindent
-If text file translation is required, then either @samp{b} or @samp{t}
-is added to the mode, depending on the setting of Text. Text file
-translation refers to the mapping of CR/LF sequences in an external file
-to LF characters internally. This mapping only occurs in DOS and
-DOS-like systems, and is not relevant to other systems.
-
-A special case occurs with Stream_IO@. As shown in the above table, the
-file is initially opened in @samp{r} or @samp{w} mode for the
-@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
-subsequently requires switching from reading to writing or vice-versa,
-then the file is reopened in @samp{r+} mode to permit the required operation.
-
-@node Operations on C Streams
-@section Operations on C Streams
-The package @code{Interfaces.C_Streams} provides an Ada program with direct
-access to the C library functions for operations on C streams:
-
-@smallexample @c adanocomment
-package Interfaces.C_Streams is
- -- Note: the reason we do not use the types that are in
- -- Interfaces.C is that we want to avoid dragging in the
- -- code in this unit if possible.
- subtype chars is System.Address;
- -- Pointer to null-terminated array of characters
- subtype FILEs is System.Address;
- -- Corresponds to the C type FILE*
- subtype voids is System.Address;
- -- Corresponds to the C type void*
- subtype int is Integer;
- subtype long is Long_Integer;
- -- Note: the above types are subtypes deliberately, and it
- -- is part of this spec that the above correspondences are
- -- guaranteed. This means that it is legitimate to, for
- -- example, use Integer instead of int. We provide these
- -- synonyms for clarity, but in some cases it may be
- -- convenient to use the underlying types (for example to
- -- avoid an unnecessary dependency of a spec on the spec
- -- of this unit).
- type size_t is mod 2 ** Standard'Address_Size;
- NULL_Stream : constant FILEs;
- -- Value returned (NULL in C) to indicate an
- -- fdopen/fopen/tmpfile error
- ----------------------------------
- -- Constants Defined in stdio.h --
- ----------------------------------
- EOF : constant int;
- -- Used by a number of routines to indicate error or
- -- end of file
- IOFBF : constant int;
- IOLBF : constant int;
- IONBF : constant int;
- -- Used to indicate buffering mode for setvbuf call
- SEEK_CUR : constant int;
- SEEK_END : constant int;
- SEEK_SET : constant int;
- -- Used to indicate origin for fseek call
- function stdin return FILEs;
- function stdout return FILEs;
- function stderr return FILEs;
- -- Streams associated with standard files
- --------------------------
- -- Standard C functions --
- --------------------------
- -- The functions selected below are ones that are
- -- available in DOS, OS/2, UNIX and Xenix (but not
- -- necessarily in ANSI C). These are very thin interfaces
- -- which copy exactly the C headers. For more
- -- documentation on these functions, see the Microsoft C
- -- "Run-Time Library Reference" (Microsoft Press, 1990,
- -- ISBN 1-55615-225-6), which includes useful information
- -- on system compatibility.
- procedure clearerr (stream : FILEs);
- function fclose (stream : FILEs) return int;
- function fdopen (handle : int; mode : chars) return FILEs;
- function feof (stream : FILEs) return int;
- function ferror (stream : FILEs) return int;
- function fflush (stream : FILEs) return int;
- function fgetc (stream : FILEs) return int;
- function fgets (strng : chars; n : int; stream : FILEs)
- return chars;
- function fileno (stream : FILEs) return int;
- function fopen (filename : chars; Mode : chars)
- return FILEs;
- -- Note: to maintain target independence, use
- -- text_translation_required, a boolean variable defined in
- -- a-sysdep.c to deal with the target dependent text
- -- translation requirement. If this variable is set,
- -- then b/t should be appended to the standard mode
- -- argument to set the text translation mode off or on
- -- as required.
- function fputc (C : int; stream : FILEs) return int;
- function fputs (Strng : chars; Stream : FILEs) return int;
- function fread
- (buffer : voids;
- size : size_t;
- count : size_t;
- stream : FILEs)
- return size_t;
- function freopen
- (filename : chars;
- mode : chars;
- stream : FILEs)
- return FILEs;
- function fseek
- (stream : FILEs;
- offset : long;
- origin : int)
- return int;
- function ftell (stream : FILEs) return long;
- function fwrite
- (buffer : voids;
- size : size_t;
- count : size_t;
- stream : FILEs)
- return size_t;
- function isatty (handle : int) return int;
- procedure mktemp (template : chars);
- -- The return value (which is just a pointer to template)
- -- is discarded
- procedure rewind (stream : FILEs);
- function rmtmp return int;
- function setvbuf
- (stream : FILEs;
- buffer : chars;
- mode : int;
- size : size_t)
- return int;
-
- function tmpfile return FILEs;
- function ungetc (c : int; stream : FILEs) return int;
- function unlink (filename : chars) return int;
- ---------------------
- -- Extra functions --
- ---------------------
- -- These functions supply slightly thicker bindings than
- -- those above. They are derived from functions in the
- -- C Run-Time Library, but may do a bit more work than
- -- just directly calling one of the Library functions.
- function is_regular_file (handle : int) return int;
- -- Tests if given handle is for a regular file (result 1)
- -- or for a non-regular file (pipe or device, result 0).
- ---------------------------------
- -- Control of Text/Binary Mode --
- ---------------------------------
- -- If text_translation_required is true, then the following
- -- functions may be used to dynamically switch a file from
- -- binary to text mode or vice versa. These functions have
- -- no effect if text_translation_required is false (i.e.@: in
- -- normal UNIX mode). Use fileno to get a stream handle.
- procedure set_binary_mode (handle : int);
- procedure set_text_mode (handle : int);
- ----------------------------
- -- Full Path Name support --
- ----------------------------
- procedure full_name (nam : chars; buffer : chars);
- -- Given a NUL terminated string representing a file
- -- name, returns in buffer a NUL terminated string
- -- representing the full path name for the file name.
- -- On systems where it is relevant the drive is also
- -- part of the full path name. It is the responsibility
- -- of the caller to pass an actual parameter for buffer
- -- that is big enough for any full path name. Use
- -- max_path_len given below as the size of buffer.
- max_path_len : integer;
- -- Maximum length of an allowable full path name on the
- -- system, including a terminating NUL character.
-end Interfaces.C_Streams;
-@end smallexample
-
-@node Interfacing to C Streams
-@section Interfacing to C Streams
-
-@noindent
-The packages in this section permit interfacing Ada files to C Stream
-operations.
-
-@smallexample @c ada
- with Interfaces.C_Streams;
- package Ada.Sequential_IO.C_Streams is
- function C_Stream (F : File_Type)
- return Interfaces.C_Streams.FILEs;
- procedure Open
- (File : in out File_Type;
- Mode : in File_Mode;
- C_Stream : in Interfaces.C_Streams.FILEs;
- Form : in String := "");
- end Ada.Sequential_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Direct_IO.C_Streams is
- function C_Stream (F : File_Type)
- return Interfaces.C_Streams.FILEs;
- procedure Open
- (File : in out File_Type;
- Mode : in File_Mode;
- C_Stream : in Interfaces.C_Streams.FILEs;
- Form : in String := "");
- end Ada.Direct_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Text_IO.C_Streams is
- function C_Stream (F : File_Type)
- return Interfaces.C_Streams.FILEs;
- procedure Open
- (File : in out File_Type;
- Mode : in File_Mode;
- C_Stream : in Interfaces.C_Streams.FILEs;
- Form : in String := "");
- end Ada.Text_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Wide_Text_IO.C_Streams is
- function C_Stream (F : File_Type)
- return Interfaces.C_Streams.FILEs;
- procedure Open
- (File : in out File_Type;
- Mode : in File_Mode;
- C_Stream : in Interfaces.C_Streams.FILEs;
- Form : in String := "");
- end Ada.Wide_Text_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Wide_Wide_Text_IO.C_Streams is
- function C_Stream (F : File_Type)
- return Interfaces.C_Streams.FILEs;
- procedure Open
- (File : in out File_Type;
- Mode : in File_Mode;
- C_Stream : in Interfaces.C_Streams.FILEs;
- Form : in String := "");
- end Ada.Wide_Wide_Text_IO.C_Streams;
-
- with Interfaces.C_Streams;
- package Ada.Stream_IO.C_Streams is
- function C_Stream (F : File_Type)
- return Interfaces.C_Streams.FILEs;
- procedure Open
- (File : in out File_Type;
- Mode : in File_Mode;
- C_Stream : in Interfaces.C_Streams.FILEs;
- Form : in String := "");
- end Ada.Stream_IO.C_Streams;
-@end smallexample
-
-@noindent
-In each of these six packages, the @code{C_Stream} function obtains the
-@code{FILE} pointer from a currently opened Ada file. It is then
-possible to use the @code{Interfaces.C_Streams} package to operate on
-this stream, or the stream can be passed to a C program which can
-operate on it directly. Of course the program is responsible for
-ensuring that only appropriate sequences of operations are executed.
-
-One particular use of relevance to an Ada program is that the
-@code{setvbuf} function can be used to control the buffering of the
-stream used by an Ada file. In the absence of such a call the standard
-default buffering is used.
-
-The @code{Open} procedures in these packages open a file giving an
-existing C Stream instead of a file name. Typically this stream is
-imported from a C program, allowing an Ada file to operate on an
-existing C file.
-
-@node The GNAT Library
-@chapter The GNAT Library
-
-@noindent
-The GNAT library contains a number of general and special purpose packages.
-It represents functionality that the GNAT developers have found useful, and
-which is made available to GNAT users. The packages described here are fully
-supported, and upwards compatibility will be maintained in future releases,
-so you can use these facilities with the confidence that the same functionality
-will be available in future releases.
-
-The chapter here simply gives a brief summary of the facilities available.
-The full documentation is found in the spec file for the package. The full
-sources of these library packages, including both spec and body, are provided
-with all GNAT releases. For example, to find out the full specifications of
-the SPITBOL pattern matching capability, including a full tutorial and
-extensive examples, look in the @file{g-spipat.ads} file in the library.
-
-For each entry here, the package name (as it would appear in a @code{with}
-clause) is given, followed by the name of the corresponding spec file in
-parentheses. The packages are children in four hierarchies, @code{Ada},
-@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
-GNAT-specific hierarchy.
-
-Note that an application program should only use packages in one of these
-four hierarchies if the package is defined in the Ada Reference Manual,
-or is listed in this section of the GNAT Programmers Reference Manual.
-All other units should be considered internal implementation units and
-should not be directly @code{with}'ed by application code. The use of
-a @code{with} statement that references one of these internal implementation
-units makes an application potentially dependent on changes in versions
-of GNAT, and will generate a warning message.
-
-@menu
-* Ada.Characters.Latin_9 (a-chlat9.ads)::
-* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
-* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
-* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
-* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
-* Ada.Command_Line.Environment (a-colien.ads)::
-* Ada.Command_Line.Remove (a-colire.ads)::
-* Ada.Command_Line.Response_File (a-clrefi.ads)::
-* Ada.Direct_IO.C_Streams (a-diocst.ads)::
-* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
-* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
-* Ada.Exceptions.Traceback (a-exctra.ads)::
-* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
-* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
-* Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
-* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
-* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
-* Ada.Text_IO.C_Streams (a-tiocst.ads)::
-* Ada.Wide_Characters.Unicode (a-wichun.ads)::
-* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
-* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
-* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
-* GNAT.Altivec (g-altive.ads)::
-* GNAT.Altivec.Conversions (g-altcon.ads)::
-* GNAT.Altivec.Vector_Operations (g-alveop.ads)::
-* GNAT.Altivec.Vector_Types (g-alvety.ads)::
-* GNAT.Altivec.Vector_Views (g-alvevi.ads)::
-* GNAT.Array_Split (g-arrspl.ads)::
-* GNAT.AWK (g-awk.ads)::
-* GNAT.Bounded_Buffers (g-boubuf.ads)::
-* GNAT.Bounded_Mailboxes (g-boumai.ads)::
-* GNAT.Bubble_Sort (g-bubsor.ads)::
-* GNAT.Bubble_Sort_A (g-busora.ads)::
-* GNAT.Bubble_Sort_G (g-busorg.ads)::
-* GNAT.Byte_Order_Mark (g-byorma.ads)::
-* GNAT.Byte_Swapping (g-bytswa.ads)::
-* GNAT.Calendar (g-calend.ads)::
-* GNAT.Calendar.Time_IO (g-catiio.ads)::
-* GNAT.Case_Util (g-casuti.ads)::
-* GNAT.CGI (g-cgi.ads)::
-* GNAT.CGI.Cookie (g-cgicoo.ads)::
-* GNAT.CGI.Debug (g-cgideb.ads)::
-* GNAT.Command_Line (g-comlin.ads)::
-* GNAT.Compiler_Version (g-comver.ads)::
-* GNAT.Ctrl_C (g-ctrl_c.ads)::
-* GNAT.CRC32 (g-crc32.ads)::
-* GNAT.Current_Exception (g-curexc.ads)::
-* GNAT.Debug_Pools (g-debpoo.ads)::
-* GNAT.Debug_Utilities (g-debuti.ads)::
-* GNAT.Decode_String (g-decstr.ads)::
-* GNAT.Decode_UTF8_String (g-deutst.ads)::
-* GNAT.Directory_Operations (g-dirope.ads)::
-* GNAT.Directory_Operations.Iteration (g-diopit.ads)::
-* GNAT.Dynamic_HTables (g-dynhta.ads)::
-* GNAT.Dynamic_Tables (g-dyntab.ads)::
-* GNAT.Encode_String (g-encstr.ads)::
-* GNAT.Encode_UTF8_String (g-enutst.ads)::
-* GNAT.Exception_Actions (g-excact.ads)::
-* GNAT.Exception_Traces (g-exctra.ads)::
-* GNAT.Exceptions (g-except.ads)::
-* GNAT.Expect (g-expect.ads)::
-* GNAT.Float_Control (g-flocon.ads)::
-* GNAT.Heap_Sort (g-heasor.ads)::
-* GNAT.Heap_Sort_A (g-hesora.ads)::
-* GNAT.Heap_Sort_G (g-hesorg.ads)::
-* GNAT.HTable (g-htable.ads)::
-* GNAT.IO (g-io.ads)::
-* GNAT.IO_Aux (g-io_aux.ads)::
-* GNAT.Lock_Files (g-locfil.ads)::
-* GNAT.MD5 (g-md5.ads)::
-* GNAT.Memory_Dump (g-memdum.ads)::
-* GNAT.Most_Recent_Exception (g-moreex.ads)::
-* GNAT.OS_Lib (g-os_lib.ads)::
-* GNAT.Perfect_Hash_Generators (g-pehage.ads)::
-* GNAT.Random_Numbers (g-rannum.ads)::
-* GNAT.Regexp (g-regexp.ads)::
-* GNAT.Registry (g-regist.ads)::
-* GNAT.Regpat (g-regpat.ads)::
-* GNAT.Secondary_Stack_Info (g-sestin.ads)::
-* GNAT.Semaphores (g-semaph.ads)::
-* GNAT.Serial_Communications (g-sercom.ads)::
-* GNAT.SHA1 (g-sha1.ads)::
-* GNAT.Signals (g-signal.ads)::
-* GNAT.Sockets (g-socket.ads)::
-* GNAT.Source_Info (g-souinf.ads)::
-* GNAT.Spelling_Checker (g-speche.ads)::
-* GNAT.Spelling_Checker_Generic (g-spchge.ads)::
-* GNAT.Spitbol.Patterns (g-spipat.ads)::
-* GNAT.Spitbol (g-spitbo.ads)::
-* GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
-* GNAT.Spitbol.Table_Integer (g-sptain.ads)::
-* GNAT.Spitbol.Table_VString (g-sptavs.ads)::
-* GNAT.Strings (g-string.ads)::
-* GNAT.String_Split (g-strspl.ads)::
-* GNAT.Table (g-table.ads)::
-* GNAT.Task_Lock (g-tasloc.ads)::
-* GNAT.Threads (g-thread.ads)::
-* GNAT.Time_Stamp (g-timsta.ads)::
-* GNAT.Traceback (g-traceb.ads)::
-* GNAT.Traceback.Symbolic (g-trasym.ads)::
-* GNAT.UTF_32 (g-utf_32.ads)::
-* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
-* GNAT.Wide_Spelling_Checker (g-wispch.ads)::
-* GNAT.Wide_String_Split (g-wistsp.ads)::
-* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
-* GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
-* Interfaces.C.Extensions (i-cexten.ads)::
-* Interfaces.C.Streams (i-cstrea.ads)::
-* Interfaces.CPP (i-cpp.ads)::
-* Interfaces.Packed_Decimal (i-pacdec.ads)::
-* Interfaces.VxWorks (i-vxwork.ads)::
-* Interfaces.VxWorks.IO (i-vxwoio.ads)::
-* System.Address_Image (s-addima.ads)::
-* System.Assertions (s-assert.ads)::
-* System.Memory (s-memory.ads)::
-* System.Partition_Interface (s-parint.ads)::
-* System.Pool_Global (s-pooglo.ads)::
-* System.Pool_Local (s-pooloc.ads)::
-* System.Restrictions (s-restri.ads)::
-* System.Rident (s-rident.ads)::
-* System.Task_Info (s-tasinf.ads)::
-* System.Wch_Cnv (s-wchcnv.ads)::
-* System.Wch_Con (s-wchcon.ads)::
-@end menu
-
-@node Ada.Characters.Latin_9 (a-chlat9.ads)
-@section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
-@cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
-@cindex Latin_9 constants for Character
-
-@noindent
-This child of @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-RM-defined package @code{Ada.Characters.Latin_1} but with the
-few modifications required for @code{Latin-9}
-The provision of such a package
-is specifically authorized by the Ada Reference Manual
-(RM A.3.3(27)).
-
-@node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
-@section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
-@cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
-@cindex Latin_1 constants for Wide_Character
-
-@noindent
-This child of @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-RM-defined package @code{Ada.Characters.Latin_1} but with the
-types of the constants being @code{Wide_Character}
-instead of @code{Character}. The provision of such a package
-is specifically authorized by the Ada Reference Manual
-(RM A.3.3(27)).
-
-@node Ada.Characters.Wide_Latin_9 (a-cwila9.ads)
-@section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
-@cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
-@cindex Latin_9 constants for Wide_Character
-
-@noindent
-This child of @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-GNAT defined package @code{Ada.Characters.Latin_9} but with the
-types of the constants being @code{Wide_Character}
-instead of @code{Character}. The provision of such a package
-is specifically authorized by the Ada Reference Manual
-(RM A.3.3(27)).
-
-@node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
-@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
-@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
-@cindex Latin_1 constants for Wide_Wide_Character
-
-@noindent
-This child of @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-RM-defined package @code{Ada.Characters.Latin_1} but with the
-types of the constants being @code{Wide_Wide_Character}
-instead of @code{Character}. The provision of such a package
-is specifically authorized by the Ada Reference Manual
-(RM A.3.3(27)).
-
-@node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
-@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
-@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
-@cindex Latin_9 constants for Wide_Wide_Character
-
-@noindent
-This child of @code{Ada.Characters}
-provides a set of definitions corresponding to those in the
-GNAT defined package @code{Ada.Characters.Latin_9} but with the
-types of the constants being @code{Wide_Wide_Character}
-instead of @code{Character}. The provision of such a package
-is specifically authorized by the Ada Reference Manual
-(RM A.3.3(27)).
-
-@node Ada.Command_Line.Environment (a-colien.ads)
-@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
-@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
-@cindex Environment entries
-
-@noindent
-This child of @code{Ada.Command_Line}
-provides a mechanism for obtaining environment values on systems
-where this concept makes sense.
-
-@node Ada.Command_Line.Remove (a-colire.ads)
-@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
-@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
-@cindex Removing command line arguments
-@cindex Command line, argument removal
-
-@noindent
-This child of @code{Ada.Command_Line}
-provides a mechanism for logically removing
-arguments from the argument list. Once removed, an argument is not visible
-to further calls on the subprograms in @code{Ada.Command_Line} will not
-see the removed argument.
-
-@node Ada.Command_Line.Response_File (a-clrefi.ads)
-@section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
-@cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
-@cindex Response file for command line
-@cindex Command line, response file
-@cindex Command line, handling long command lines
-
-@noindent
-This child of @code{Ada.Command_Line} provides a mechanism facilities for
-getting command line arguments from a text file, called a "response file".
-Using a response file allow passing a set of arguments to an executable longer
-than the maximum allowed by the system on the command line.
-
-@node Ada.Direct_IO.C_Streams (a-diocst.ads)
-@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
-@cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
-@cindex C Streams, Interfacing with Direct_IO
-
-@noindent
-This package provides subprograms that allow interfacing between
-C streams and @code{Direct_IO}. The stream identifier can be
-extracted from a file opened on the Ada side, and an Ada file
-can be constructed from a stream opened on the C side.
-
-@node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
-@section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
-@cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
-@cindex Null_Occurrence, testing for
-
-@noindent
-This child subprogram provides a way of testing for the null
-exception occurrence (@code{Null_Occurrence}) without raising
-an exception.
-
-@node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
-@section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
-@cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
-@cindex Null_Occurrence, testing for
-
-@noindent
-This child subprogram is used for handling otherwise unhandled
-exceptions (hence the name last chance), and perform clean ups before
-terminating the program. Note that this subprogram never returns.
-
-@node Ada.Exceptions.Traceback (a-exctra.ads)
-@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
-@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
-@cindex Traceback for Exception Occurrence
-
-@noindent
-This child package provides the subprogram (@code{Tracebacks}) to
-give a traceback array of addresses based on an exception
-occurrence.
-
-@node Ada.Sequential_IO.C_Streams (a-siocst.ads)
-@section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
-@cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
-@cindex C Streams, Interfacing with Sequential_IO
-
-@noindent
-This package provides subprograms that allow interfacing between
-C streams and @code{Sequential_IO}. The stream identifier can be
-extracted from a file opened on the Ada side, and an Ada file
-can be constructed from a stream opened on the C side.
-
-@node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
-@section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
-@cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
-@cindex C Streams, Interfacing with Stream_IO
-
-@noindent
-This package provides subprograms that allow interfacing between
-C streams and @code{Stream_IO}. The stream identifier can be
-extracted from a file opened on the Ada side, and an Ada file
-can be constructed from a stream opened on the C side.
-
-@node Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
-@section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
-@cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
-@cindex @code{Unbounded_String}, IO support
-@cindex @code{Text_IO}, extensions for unbounded strings
-
-@noindent
-This package provides subprograms for Text_IO for unbounded
-strings, avoiding the necessity for an intermediate operation
-with ordinary strings.
-
-@node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
-@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
-@cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
-@cindex @code{Unbounded_Wide_String}, IO support
-@cindex @code{Text_IO}, extensions for unbounded wide strings
-
-@noindent
-This package provides subprograms for Text_IO for unbounded
-wide strings, avoiding the necessity for an intermediate operation
-with ordinary wide strings.
-
-@node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
-@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
-@cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
-@cindex @code{Unbounded_Wide_Wide_String}, IO support
-@cindex @code{Text_IO}, extensions for unbounded wide wide strings
-
-@noindent
-This package provides subprograms for Text_IO for unbounded
-wide wide strings, avoiding the necessity for an intermediate operation
-with ordinary wide wide strings.
-
-@node Ada.Text_IO.C_Streams (a-tiocst.ads)
-@section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
-@cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
-@cindex C Streams, Interfacing with @code{Text_IO}
-
-@noindent
-This package provides subprograms that allow interfacing between
-C streams and @code{Text_IO}. The stream identifier can be
-extracted from a file opened on the Ada side, and an Ada file
-can be constructed from a stream opened on the C side.
-
-@node Ada.Wide_Characters.Unicode (a-wichun.ads)
-@section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
-@cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
-@cindex Unicode categorization, Wide_Character
-
-@noindent
-This package provides subprograms that allow categorization of
-Wide_Character values according to Unicode categories.
-
-@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
-@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
-@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
-@cindex C Streams, Interfacing with @code{Wide_Text_IO}
-
-@noindent
-This package provides subprograms that allow interfacing between
-C streams and @code{Wide_Text_IO}. The stream identifier can be
-extracted from a file opened on the Ada side, and an Ada file
-can be constructed from a stream opened on the C side.
-
-@node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
-@section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
-@cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
-@cindex Unicode categorization, Wide_Wide_Character
-
-@noindent
-This package provides subprograms that allow categorization of
-Wide_Wide_Character values according to Unicode categories.
-
-@node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
-@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
-@cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
-@cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
-
-@noindent
-This package provides subprograms that allow interfacing between
-C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
-extracted from a file opened on the Ada side, and an Ada file
-can be constructed from a stream opened on the C side.
-
-@node GNAT.Altivec (g-altive.ads)
-@section @code{GNAT.Altivec} (@file{g-altive.ads})
-@cindex @code{GNAT.Altivec} (@file{g-altive.ads})
-@cindex AltiVec
-
-@noindent
-This is the root package of the GNAT AltiVec binding. It provides
-definitions of constants and types common to all the versions of the
-binding.
-
-@node GNAT.Altivec.Conversions (g-altcon.ads)
-@section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
-@cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
-@cindex AltiVec
-
-@noindent
-This package provides the Vector/View conversion routines.
-
-@node GNAT.Altivec.Vector_Operations (g-alveop.ads)
-@section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
-@cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
-@cindex AltiVec
-
-@noindent
-This package exposes the Ada interface to the AltiVec operations on
-vector objects. A soft emulation is included by default in the GNAT
-library. The hard binding is provided as a separate package. This unit
-is common to both bindings.
-
-@node GNAT.Altivec.Vector_Types (g-alvety.ads)
-@section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
-@cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
-@cindex AltiVec
-
-@noindent
-This package exposes the various vector types part of the Ada binding
-to AltiVec facilities.
-
-@node GNAT.Altivec.Vector_Views (g-alvevi.ads)
-@section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
-@cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
-@cindex AltiVec
-
-@noindent
-This package provides public 'View' data types from/to which private
-vector representations can be converted via
-GNAT.Altivec.Conversions. This allows convenient access to individual
-vector elements and provides a simple way to initialize vector
-objects.
-
-@node GNAT.Array_Split (g-arrspl.ads)
-@section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
-@cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
-@cindex Array splitter
-
-@noindent
-Useful array-manipulation routines: given a set of separators, split
-an array wherever the separators appear, and provide direct access
-to the resulting slices.
-
-@node GNAT.AWK (g-awk.ads)
-@section @code{GNAT.AWK} (@file{g-awk.ads})
-@cindex @code{GNAT.AWK} (@file{g-awk.ads})
-@cindex Parsing
-@cindex AWK
-
-@noindent
-Provides AWK-like parsing functions, with an easy interface for parsing one
-or more files containing formatted data. The file is viewed as a database
-where each record is a line and a field is a data element in this line.
-
-@node GNAT.Bounded_Buffers (g-boubuf.ads)
-@section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
-@cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
-@cindex Parsing
-@cindex Bounded Buffers
-
-@noindent
-Provides a concurrent generic bounded buffer abstraction. Instances are
-useful directly or as parts of the implementations of other abstractions,
-such as mailboxes.
-
-@node GNAT.Bounded_Mailboxes (g-boumai.ads)
-@section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
-@cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
-@cindex Parsing
-@cindex Mailboxes
-
-@noindent
-Provides a thread-safe asynchronous intertask mailbox communication facility.
-
-@node GNAT.Bubble_Sort (g-bubsor.ads)
-@section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
-@cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
-@cindex Sorting
-@cindex Bubble sort
-
-@noindent
-Provides a general implementation of bubble sort usable for sorting arbitrary
-data items. Exchange and comparison procedures are provided by passing
-access-to-procedure values.
-
-@node GNAT.Bubble_Sort_A (g-busora.ads)
-@section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
-@cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
-@cindex Sorting
-@cindex Bubble sort
-
-@noindent
-Provides a general implementation of bubble sort usable for sorting arbitrary
-data items. Move and comparison procedures are provided by passing
-access-to-procedure values. This is an older version, retained for
-compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
-
-@node GNAT.Bubble_Sort_G (g-busorg.ads)
-@section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
-@cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
-@cindex Sorting
-@cindex Bubble sort
-
-@noindent
-Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
-are provided as generic parameters, this improves efficiency, especially
-if the procedures can be inlined, at the expense of duplicating code for
-multiple instantiations.
-
-@node GNAT.Byte_Order_Mark (g-byorma.ads)
-@section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
-@cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
-@cindex UTF-8 representation
-@cindex Wide characte representations
-
-@noindent
-Provides a routine which given a string, reads the start of the string to
-see whether it is one of the standard byte order marks (BOM's) which signal
-the encoding of the string. The routine includes detection of special XML
-sequences for various UCS input formats.
-
-@node GNAT.Byte_Swapping (g-bytswa.ads)
-@section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
-@cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
-@cindex Byte swapping
-@cindex Endian
-
-@noindent
-General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
-Machine-specific implementations are available in some cases.
-
-@node GNAT.Calendar (g-calend.ads)
-@section @code{GNAT.Calendar} (@file{g-calend.ads})
-@cindex @code{GNAT.Calendar} (@file{g-calend.ads})
-@cindex @code{Calendar}
-
-@noindent
-Extends the facilities provided by @code{Ada.Calendar} to include handling
-of days of the week, an extended @code{Split} and @code{Time_Of} capability.
-Also provides conversion of @code{Ada.Calendar.Time} values to and from the
-C @code{timeval} format.
-
-@node GNAT.Calendar.Time_IO (g-catiio.ads)
-@section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
-@cindex @code{Calendar}
-@cindex Time
-@cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
-
-@node GNAT.CRC32 (g-crc32.ads)
-@section @code{GNAT.CRC32} (@file{g-crc32.ads})
-@cindex @code{GNAT.CRC32} (@file{g-crc32.ads})
-@cindex CRC32
-@cindex Cyclic Redundancy Check
-
-@noindent
-This package implements the CRC-32 algorithm. For a full description
-of this algorithm see
-``Computation of Cyclic Redundancy Checks via Table Look-Up'',
-@cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013,
-Aug.@: 1988. Sarwate, D.V@.
-
-@node GNAT.Case_Util (g-casuti.ads)
-@section @code{GNAT.Case_Util} (@file{g-casuti.ads})
-@cindex @code{GNAT.Case_Util} (@file{g-casuti.ads})
-@cindex Casing utilities
-@cindex Character handling (@code{GNAT.Case_Util})
-
-@noindent
-A set of simple routines for handling upper and lower casing of strings
-without the overhead of the full casing tables
-in @code{Ada.Characters.Handling}.
-
-@node GNAT.CGI (g-cgi.ads)
-@section @code{GNAT.CGI} (@file{g-cgi.ads})
-@cindex @code{GNAT.CGI} (@file{g-cgi.ads})
-@cindex CGI (Common Gateway Interface)
-
-@noindent
-This is a package for interfacing a GNAT program with a Web server via the
-Common Gateway Interface (CGI)@. Basically this package parses the CGI
-parameters, which are a set of key/value pairs sent by the Web server. It
-builds a table whose index is the key and provides some services to deal
-with this table.
-
-@node GNAT.CGI.Cookie (g-cgicoo.ads)
-@section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
-@cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
-@cindex CGI (Common Gateway Interface) cookie support
-@cindex Cookie support in CGI
-
-@noindent
-This is a package to interface a GNAT program with a Web server via the
-Common Gateway Interface (CGI). It exports services to deal with Web
-cookies (piece of information kept in the Web client software).
-
-@node GNAT.CGI.Debug (g-cgideb.ads)
-@section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
-@cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
-@cindex CGI (Common Gateway Interface) debugging
-
-@noindent
-This is a package to help debugging CGI (Common Gateway Interface)
-programs written in Ada.
-
-@node GNAT.Command_Line (g-comlin.ads)
-@section @code{GNAT.Command_Line} (@file{g-comlin.ads})
-@cindex @code{GNAT.Command_Line} (@file{g-comlin.ads})
-@cindex Command line
-
-@noindent
-Provides a high level interface to @code{Ada.Command_Line} facilities,
-including the ability to scan for named switches with optional parameters
-and expand file names using wild card notations.
-
-@node GNAT.Compiler_Version (g-comver.ads)
-@section @code{GNAT.Compiler_Version} (@file{g-comver.ads})
-@cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads})
-@cindex Compiler Version
-@cindex Version, of compiler
-
-@noindent
-Provides a routine for obtaining the version of the compiler used to
-compile the program. More accurately this is the version of the binder
-used to bind the program (this will normally be the same as the version
-of the compiler if a consistent tool set is used to compile all units
-of a partition).
-
-@node GNAT.Ctrl_C (g-ctrl_c.ads)
-@section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
-@cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
-@cindex Interrupt
-
-@noindent
-Provides a simple interface to handle Ctrl-C keyboard events.
-
-@node GNAT.Current_Exception (g-curexc.ads)
-@section @code{GNAT.Current_Exception} (@file{g-curexc.ads})
-@cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads})
-@cindex Current exception
-@cindex Exception retrieval
-
-@noindent
-Provides access to information on the current exception that has been raised
-without the need for using the Ada 95 / Ada 2005 exception choice parameter
-specification syntax.
-This is particularly useful in simulating typical facilities for
-obtaining information about exceptions provided by Ada 83 compilers.
-
-@node GNAT.Debug_Pools (g-debpoo.ads)
-@section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
-@cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
-@cindex Debugging
-@cindex Debug pools
-@cindex Memory corruption debugging
-
-@noindent
-Provide a debugging storage pools that helps tracking memory corruption
-problems. @xref{The GNAT Debug Pool Facility,,, gnat_ugn,
-@value{EDITION} User's Guide}.
-
-@node GNAT.Debug_Utilities (g-debuti.ads)
-@section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
-@cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
-@cindex Debugging
-
-@noindent
-Provides a few useful utilities for debugging purposes, including conversion
-to and from string images of address values. Supports both C and Ada formats
-for hexadecimal literals.
-
-@node GNAT.Decode_String (g-decstr.ads)
-@section @code{GNAT.Decode_String} (@file{g-decstr.ads})
-@cindex @code{GNAT.Decode_String} (@file{g-decstr.ads})
-@cindex Decoding strings
-@cindex String decoding
-@cindex Wide character encoding
-@cindex UTF-8
-@cindex Unicode
-
-@noindent
-A generic package providing routines for decoding wide character and wide wide
-character strings encoded as sequences of 8-bit characters using a specified
-encoding method. Includes validation routines, and also routines for stepping
-to next or previous encoded character in an encoded string.
-Useful in conjunction with Unicode character coding. Note there is a
-preinstantiation for UTF-8. See next entry.
-
-@node GNAT.Decode_UTF8_String (g-deutst.ads)
-@section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
-@cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
-@cindex Decoding strings
-@cindex Decoding UTF-8 strings
-@cindex UTF-8 string decoding
-@cindex Wide character decoding
-@cindex UTF-8
-@cindex Unicode
-
-@noindent
-A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
-
-@node GNAT.Directory_Operations (g-dirope.ads)
-@section @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
-@cindex @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
-@cindex Directory operations
-
-@noindent
-Provides a set of routines for manipulating directories, including changing
-the current directory, making new directories, and scanning the files in a
-directory.
-
-@node GNAT.Directory_Operations.Iteration (g-diopit.ads)
-@section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
-@cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
-@cindex Directory operations iteration
-
-@noindent
-A child unit of GNAT.Directory_Operations providing additional operations
-for iterating through directories.
-
-@node GNAT.Dynamic_HTables (g-dynhta.ads)
-@section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
-@cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
-@cindex Hash tables
-
-@noindent
-A generic implementation of hash tables that can be used to hash arbitrary
-data. Provided in two forms, a simple form with built in hash functions,
-and a more complex form in which the hash function is supplied.
-
-@noindent
-This package provides a facility similar to that of @code{GNAT.HTable},
-except that this package declares a type that can be used to define
-dynamic instances of the hash table, while an instantiation of
-@code{GNAT.HTable} creates a single instance of the hash table.
-
-@node GNAT.Dynamic_Tables (g-dyntab.ads)
-@section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
-@cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
-@cindex Table implementation
-@cindex Arrays, extendable
-
-@noindent
-A generic package providing a single dimension array abstraction where the
-length of the array can be dynamically modified.
-
-@noindent
-This package provides a facility similar to that of @code{GNAT.Table},
-except that this package declares a type that can be used to define
-dynamic instances of the table, while an instantiation of
-@code{GNAT.Table} creates a single instance of the table type.
-
-@node GNAT.Encode_String (g-encstr.ads)
-@section @code{GNAT.Encode_String} (@file{g-encstr.ads})
-@cindex @code{GNAT.Encode_String} (@file{g-encstr.ads})
-@cindex Encoding strings
-@cindex String encoding
-@cindex Wide character encoding
-@cindex UTF-8
-@cindex Unicode
-
-@noindent
-A generic package providing routines for encoding wide character and wide
-wide character strings as sequences of 8-bit characters using a specified
-encoding method. Useful in conjunction with Unicode character coding.
-Note there is a preinstantiation for UTF-8. See next entry.
-
-@node GNAT.Encode_UTF8_String (g-enutst.ads)
-@section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
-@cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
-@cindex Encoding strings
-@cindex Encoding UTF-8 strings
-@cindex UTF-8 string encoding
-@cindex Wide character encoding
-@cindex UTF-8
-@cindex Unicode
-
-@noindent
-A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
-
-@node GNAT.Exception_Actions (g-excact.ads)
-@section @code{GNAT.Exception_Actions} (@file{g-excact.ads})
-@cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads})
-@cindex Exception actions
-
-@noindent
-Provides callbacks when an exception is raised. Callbacks can be registered
-for specific exceptions, or when any exception is raised. This
-can be used for instance to force a core dump to ease debugging.
-
-@node GNAT.Exception_Traces (g-exctra.ads)
-@section @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
-@cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
-@cindex Exception traces
-@cindex Debugging
-
-@noindent
-Provides an interface allowing to control automatic output upon exception
-occurrences.
-
-@node GNAT.Exceptions (g-except.ads)
-@section @code{GNAT.Exceptions} (@file{g-expect.ads})
-@cindex @code{GNAT.Exceptions} (@file{g-expect.ads})
-@cindex Exceptions, Pure
-@cindex Pure packages, exceptions
-
-@noindent
-Normally it is not possible to raise an exception with
-a message from a subprogram in a pure package, since the
-necessary types and subprograms are in @code{Ada.Exceptions}
-which is not a pure unit. @code{GNAT.Exceptions} provides a
-facility for getting around this limitation for a few
-predefined exceptions, and for example allow raising
-@code{Constraint_Error} with a message from a pure subprogram.
-
-@node GNAT.Expect (g-expect.ads)
-@section @code{GNAT.Expect} (@file{g-expect.ads})
-@cindex @code{GNAT.Expect} (@file{g-expect.ads})
-
-@noindent
-Provides a set of subprograms similar to what is available
-with the standard Tcl Expect tool.
-It allows you to easily spawn and communicate with an external process.
-You can send commands or inputs to the process, and compare the output
-with some expected regular expression. Currently @code{GNAT.Expect}
-is implemented on all native GNAT ports except for OpenVMS@.
-It is not implemented for cross ports, and in particular is not
-implemented for VxWorks or LynxOS@.
-
-@node GNAT.Float_Control (g-flocon.ads)
-@section @code{GNAT.Float_Control} (@file{g-flocon.ads})
-@cindex @code{GNAT.Float_Control} (@file{g-flocon.ads})
-@cindex Floating-Point Processor
-
-@noindent
-Provides an interface for resetting the floating-point processor into the
-mode required for correct semantic operation in Ada. Some third party
-library calls may cause this mode to be modified, and the Reset procedure
-in this package can be used to reestablish the required mode.
-
-@node GNAT.Heap_Sort (g-heasor.ads)
-@section @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
-@cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
-@cindex Sorting
-
-@noindent
-Provides a general implementation of heap sort usable for sorting arbitrary
-data items. Exchange and comparison procedures are provided by passing
-access-to-procedure values. The algorithm used is a modified heap sort
-that performs approximately N*log(N) comparisons in the worst case.
-
-@node GNAT.Heap_Sort_A (g-hesora.ads)
-@section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
-@cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
-@cindex Sorting
-
-@noindent
-Provides a general implementation of heap sort usable for sorting arbitrary
-data items. Move and comparison procedures are provided by passing
-access-to-procedure values. The algorithm used is a modified heap sort
-that performs approximately N*log(N) comparisons in the worst case.
-This differs from @code{GNAT.Heap_Sort} in having a less convenient
-interface, but may be slightly more efficient.
-
-@node GNAT.Heap_Sort_G (g-hesorg.ads)
-@section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
-@cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
-@cindex Sorting
-
-@noindent
-Similar to @code{Heap_Sort_A} except that the move and sorting procedures
-are provided as generic parameters, this improves efficiency, especially
-if the procedures can be inlined, at the expense of duplicating code for
-multiple instantiations.
-
-@node GNAT.HTable (g-htable.ads)
-@section @code{GNAT.HTable} (@file{g-htable.ads})
-@cindex @code{GNAT.HTable} (@file{g-htable.ads})
-@cindex Hash tables
-
-@noindent
-A generic implementation of hash tables that can be used to hash arbitrary
-data. Provides two approaches, one a simple static approach, and the other
-allowing arbitrary dynamic hash tables.
-
-@node GNAT.IO (g-io.ads)
-@section @code{GNAT.IO} (@file{g-io.ads})
-@cindex @code{GNAT.IO} (@file{g-io.ads})
-@cindex Simple I/O
-@cindex Input/Output facilities
-
-@noindent
-A simple preelaborable input-output package that provides a subset of
-simple Text_IO functions for reading characters and strings from
-Standard_Input, and writing characters, strings and integers to either
-Standard_Output or Standard_Error.
-
-@node GNAT.IO_Aux (g-io_aux.ads)
-@section @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
-@cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
-@cindex Text_IO
-@cindex Input/Output facilities
-
-Provides some auxiliary functions for use with Text_IO, including a test
-for whether a file exists, and functions for reading a line of text.
-
-@node GNAT.Lock_Files (g-locfil.ads)
-@section @code{GNAT.Lock_Files} (@file{g-locfil.ads})
-@cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads})
-@cindex File locking
-@cindex Locking using files
-
-@noindent
-Provides a general interface for using files as locks. Can be used for
-providing program level synchronization.
-
-@node GNAT.MD5 (g-md5.ads)
-@section @code{GNAT.MD5} (@file{g-md5.ads})
-@cindex @code{GNAT.MD5} (@file{g-md5.ads})
-@cindex Message Digest MD5
-
-@noindent
-Implements the MD5 Message-Digest Algorithm as described in RFC 1321.
-
-@node GNAT.Memory_Dump (g-memdum.ads)
-@section @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
-@cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
-@cindex Dump Memory
-
-@noindent
-Provides a convenient routine for dumping raw memory to either the
-standard output or standard error files. Uses GNAT.IO for actual
-output.
-
-@node GNAT.Most_Recent_Exception (g-moreex.ads)
-@section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
-@cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
-@cindex Exception, obtaining most recent
-
-@noindent
-Provides access to the most recently raised exception. Can be used for
-various logging purposes, including duplicating functionality of some
-Ada 83 implementation dependent extensions.
-
-@node GNAT.OS_Lib (g-os_lib.ads)
-@section @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
-@cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
-@cindex Operating System interface
-@cindex Spawn capability
-
-@noindent
-Provides a range of target independent operating system interface functions,
-including time/date management, file operations, subprocess management,
-including a portable spawn procedure, and access to environment variables
-and error return codes.
-
-@node GNAT.Perfect_Hash_Generators (g-pehage.ads)
-@section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
-@cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
-@cindex Hash functions
-
-@noindent
-Provides a generator of static minimal perfect hash functions. No
-collisions occur and each item can be retrieved from the table in one
-probe (perfect property). The hash table size corresponds to the exact
-size of the key set and no larger (minimal property). The key set has to
-be know in advance (static property). The hash functions are also order
-preserving. If w2 is inserted after w1 in the generator, their
-hashcode are in the same order. These hashing functions are very
-convenient for use with realtime applications.
-
-@node GNAT.Random_Numbers (g-rannum.ads)
-@section @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
-@cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
-@cindex Random number generation
-
-@noindent
-Provides random number capabilities which extend those available in the
-standard Ada library and are more convenient to use.
-
-@node GNAT.Regexp (g-regexp.ads)
-@section @code{GNAT.Regexp} (@file{g-regexp.ads})
-@cindex @code{GNAT.Regexp} (@file{g-regexp.ads})
-@cindex Regular expressions
-@cindex Pattern matching
-
-@noindent
-A simple implementation of regular expressions, using a subset of regular
-expression syntax copied from familiar Unix style utilities. This is the
-simples of the three pattern matching packages provided, and is particularly
-suitable for ``file globbing'' applications.
-
-@node GNAT.Registry (g-regist.ads)
-@section @code{GNAT.Registry} (@file{g-regist.ads})
-@cindex @code{GNAT.Registry} (@file{g-regist.ads})
-@cindex Windows Registry
-
-@noindent
-This is a high level binding to the Windows registry. It is possible to
-do simple things like reading a key value, creating a new key. For full
-registry API, but at a lower level of abstraction, refer to the Win32.Winreg
-package provided with the Win32Ada binding
-
-@node GNAT.Regpat (g-regpat.ads)
-@section @code{GNAT.Regpat} (@file{g-regpat.ads})
-@cindex @code{GNAT.Regpat} (@file{g-regpat.ads})
-@cindex Regular expressions
-@cindex Pattern matching
-
-@noindent
-A complete implementation of Unix-style regular expression matching, copied
-from the original V7 style regular expression library written in C by
-Henry Spencer (and binary compatible with this C library).
-
-@node GNAT.Secondary_Stack_Info (g-sestin.ads)
-@section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
-@cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
-@cindex Secondary Stack Info
-
-@noindent
-Provide the capability to query the high water mark of the current task's
-secondary stack.
-
-@node GNAT.Semaphores (g-semaph.ads)
-@section @code{GNAT.Semaphores} (@file{g-semaph.ads})
-@cindex @code{GNAT.Semaphores} (@file{g-semaph.ads})
-@cindex Semaphores
-
-@noindent
-Provides classic counting and binary semaphores using protected types.
-
-@node GNAT.Serial_Communications (g-sercom.ads)
-@section @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
-@cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
-@cindex Serial_Communications
-
-@noindent
-Provides a simple interface to send and receive data over a serial
-port. This is only supported on GNU/Linux and Windows.
-
-@node GNAT.SHA1 (g-sha1.ads)
-@section @code{GNAT.SHA1} (@file{g-sha1.ads})
-@cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
-@cindex Secure Hash Algorithm SHA-1
-
-@noindent
-Implements the SHA-1 Secure Hash Algorithm as described in RFC 3174.
-
-@node GNAT.Signals (g-signal.ads)
-@section @code{GNAT.Signals} (@file{g-signal.ads})
-@cindex @code{GNAT.Signals} (@file{g-signal.ads})
-@cindex Signals
-
-@noindent
-Provides the ability to manipulate the blocked status of signals on supported
-targets.
-
-@node GNAT.Sockets (g-socket.ads)
-@section @code{GNAT.Sockets} (@file{g-socket.ads})
-@cindex @code{GNAT.Sockets} (@file{g-socket.ads})
-@cindex Sockets
-
-@noindent
-A high level and portable interface to develop sockets based applications.
-This package is based on the sockets thin binding found in
-@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
-on all native GNAT ports except for OpenVMS@. It is not implemented
-for the LynxOS@ cross port.
-
-@node GNAT.Source_Info (g-souinf.ads)
-@section @code{GNAT.Source_Info} (@file{g-souinf.ads})
-@cindex @code{GNAT.Source_Info} (@file{g-souinf.ads})
-@cindex Source Information
-
-@noindent
-Provides subprograms that give access to source code information known at
-compile time, such as the current file name and line number.
-
-@node GNAT.Spelling_Checker (g-speche.ads)
-@section @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
-@cindex @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
-@cindex Spell checking
-
-@noindent
-Provides a function for determining whether one string is a plausible
-near misspelling of another string.
-
-@node GNAT.Spelling_Checker_Generic (g-spchge.ads)
-@section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
-@cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
-@cindex Spell checking
-
-@noindent
-Provides a generic function that can be instantiated with a string type for
-determining whether one string is a plausible near misspelling of another
-string.
-
-@node GNAT.Spitbol.Patterns (g-spipat.ads)
-@section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
-@cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
-@cindex SPITBOL pattern matching
-@cindex Pattern matching
-
-@noindent
-A complete implementation of SNOBOL4 style pattern matching. This is the
-most elaborate of the pattern matching packages provided. It fully duplicates
-the SNOBOL4 dynamic pattern construction and matching capabilities, using the
-efficient algorithm developed by Robert Dewar for the SPITBOL system.
-
-@node GNAT.Spitbol (g-spitbo.ads)
-@section @code{GNAT.Spitbol} (@file{g-spitbo.ads})
-@cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads})
-@cindex SPITBOL interface
-
-@noindent
-The top level package of the collection of SPITBOL-style functionality, this
-package provides basic SNOBOL4 string manipulation functions, such as
-Pad, Reverse, Trim, Substr capability, as well as a generic table function
-useful for constructing arbitrary mappings from strings in the style of
-the SNOBOL4 TABLE function.
-
-@node GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
-@section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
-@cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
-@cindex Sets of strings
-@cindex SPITBOL Tables
-
-@noindent
-A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
-for type @code{Standard.Boolean}, giving an implementation of sets of
-string values.
-
-@node GNAT.Spitbol.Table_Integer (g-sptain.ads)
-@section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
-@cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
-@cindex Integer maps
-@cindex Maps
-@cindex SPITBOL Tables
-
-@noindent
-A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
-for type @code{Standard.Integer}, giving an implementation of maps
-from string to integer values.
-
-@node GNAT.Spitbol.Table_VString (g-sptavs.ads)
-@section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
-@cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
-@cindex String maps
-@cindex Maps
-@cindex SPITBOL Tables
-
-@noindent
-A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
-a variable length string type, giving an implementation of general
-maps from strings to strings.
-
-@node GNAT.Strings (g-string.ads)
-@section @code{GNAT.Strings} (@file{g-string.ads})
-@cindex @code{GNAT.Strings} (@file{g-string.ads})
-
-@noindent
-Common String access types and related subprograms. Basically it
-defines a string access and an array of string access types.
-
-@node GNAT.String_Split (g-strspl.ads)
-@section @code{GNAT.String_Split} (@file{g-strspl.ads})
-@cindex @code{GNAT.String_Split} (@file{g-strspl.ads})
-@cindex String splitter
-
-@noindent
-Useful string manipulation routines: given a set of separators, split
-a string wherever the separators appear, and provide direct access
-to the resulting slices. This package is instantiated from
-@code{GNAT.Array_Split}.
-
-@node GNAT.Table (g-table.ads)
-@section @code{GNAT.Table} (@file{g-table.ads})
-@cindex @code{GNAT.Table} (@file{g-table.ads})
-@cindex Table implementation
-@cindex Arrays, extendable
-
-@noindent
-A generic package providing a single dimension array abstraction where the
-length of the array can be dynamically modified.
-
-@noindent
-This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
-except that this package declares a single instance of the table type,
-while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
-used to define dynamic instances of the table.
-
-@node GNAT.Task_Lock (g-tasloc.ads)
-@section @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
-@cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
-@cindex Task synchronization
-@cindex Task locking
-@cindex Locking
-
-@noindent
-A very simple facility for locking and unlocking sections of code using a
-single global task lock. Appropriate for use in situations where contention
-between tasks is very rarely expected.
-
-@node GNAT.Time_Stamp (g-timsta.ads)
-@section @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
-@cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
-@cindex Time stamp
-@cindex Current time
-
-@noindent
-Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
-represents the current date and time in ISO 8601 format. This is a very simple
-routine with minimal code and there are no dependencies on any other unit.
-
-@node GNAT.Threads (g-thread.ads)
-@section @code{GNAT.Threads} (@file{g-thread.ads})
-@cindex @code{GNAT.Threads} (@file{g-thread.ads})
-@cindex Foreign threads
-@cindex Threads, foreign
-
-@noindent
-Provides facilities for dealing with foreign threads which need to be known
-by the GNAT run-time system. Consult the documentation of this package for
-further details if your program has threads that are created by a non-Ada
-environment which then accesses Ada code.
-
-@node GNAT.Traceback (g-traceb.ads)
-@section @code{GNAT.Traceback} (@file{g-traceb.ads})
-@cindex @code{GNAT.Traceback} (@file{g-traceb.ads})
-@cindex Trace back facilities
-
-@noindent
-Provides a facility for obtaining non-symbolic traceback information, useful
-in various debugging situations.
-
-@node GNAT.Traceback.Symbolic (g-trasym.ads)
-@section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
-@cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
-@cindex Trace back facilities
-
-@node GNAT.UTF_32 (g-utf_32.ads)
-@section @code{GNAT.UTF_32} (@file{g-table.ads})
-@cindex @code{GNAT.UTF_32} (@file{g-table.ads})
-@cindex Wide character codes
-
-@noindent
-This is a package intended to be used in conjunction with the
-@code{Wide_Character} type in Ada 95 and the
-@code{Wide_Wide_Character} type in Ada 2005 (available
-in @code{GNAT} in Ada 2005 mode). This package contains
-Unicode categorization routines, as well as lexical
-categorization routines corresponding to the Ada 2005
-lexical rules for identifiers and strings, and also a
-lower case to upper case fold routine corresponding to
-the Ada 2005 rules for identifier equivalence.
-
-@node GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)
-@section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
-@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
-@cindex Spell checking
-
-@noindent
-Provides a function for determining whether one wide wide string is a plausible
-near misspelling of another wide wide string, where the strings are represented
-using the UTF_32_String type defined in System.Wch_Cnv.
-
-@node GNAT.Wide_Spelling_Checker (g-wispch.ads)
-@section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
-@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
-@cindex Spell checking
-
-@noindent
-Provides a function for determining whether one wide string is a plausible
-near misspelling of another wide string.
-
-@node GNAT.Wide_String_Split (g-wistsp.ads)
-@section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
-@cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
-@cindex Wide_String splitter
-
-@noindent
-Useful wide string manipulation routines: given a set of separators, split
-a wide string wherever the separators appear, and provide direct access
-to the resulting slices. This package is instantiated from
-@code{GNAT.Array_Split}.
-
-@node GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
-@section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
-@cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
-@cindex Spell checking
-
-@noindent
-Provides a function for determining whether one wide wide string is a plausible
-near misspelling of another wide wide string.
-
-@node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
-@section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
-@cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
-@cindex Wide_Wide_String splitter
-
-@noindent
-Useful wide wide string manipulation routines: given a set of separators, split
-a wide wide string wherever the separators appear, and provide direct access
-to the resulting slices. This package is instantiated from
-@code{GNAT.Array_Split}.
-
-@node Interfaces.C.Extensions (i-cexten.ads)
-@section @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
-@cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
-
-@noindent
-This package contains additional C-related definitions, intended
-for use with either manually or automatically generated bindings
-to C libraries.
-
-@node Interfaces.C.Streams (i-cstrea.ads)
-@section @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
-@cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
-@cindex C streams, interfacing
-
-@noindent
-This package is a binding for the most commonly used operations
-on C streams.
-
-@node Interfaces.CPP (i-cpp.ads)
-@section @code{Interfaces.CPP} (@file{i-cpp.ads})
-@cindex @code{Interfaces.CPP} (@file{i-cpp.ads})
-@cindex C++ interfacing
-@cindex Interfacing, to C++
-
-@noindent
-This package provides facilities for use in interfacing to C++. It
-is primarily intended to be used in connection with automated tools
-for the generation of C++ interfaces.
-
-@node Interfaces.Packed_Decimal (i-pacdec.ads)
-@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
-@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
-@cindex IBM Packed Format
-@cindex Packed Decimal
-
-@noindent
-This package provides a set of routines for conversions to and
-from a packed decimal format compatible with that used on IBM
-mainframes.
-
-@node Interfaces.VxWorks (i-vxwork.ads)
-@section @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
-@cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
-@cindex Interfacing to VxWorks
-@cindex VxWorks, interfacing
-
-@noindent
-This package provides a limited binding to the VxWorks API.
-In particular, it interfaces with the
-VxWorks hardware interrupt facilities.
-
-@node Interfaces.VxWorks.IO (i-vxwoio.ads)
-@section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
-@cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
-@cindex Interfacing to VxWorks' I/O
-@cindex VxWorks, I/O interfacing
-@cindex VxWorks, Get_Immediate
-@cindex Get_Immediate, VxWorks
-
-@noindent
-This package provides a binding to the ioctl (IO/Control)
-function of VxWorks, defining a set of option values and
-function codes. A particular use of this package is
-to enable the use of Get_Immediate under VxWorks.
-
-@node System.Address_Image (s-addima.ads)
-@section @code{System.Address_Image} (@file{s-addima.ads})
-@cindex @code{System.Address_Image} (@file{s-addima.ads})
-@cindex Address image
-@cindex Image, of an address
-
-@noindent
-This function provides a useful debugging
-function that gives an (implementation dependent)
-string which identifies an address.
-
-@node System.Assertions (s-assert.ads)
-@section @code{System.Assertions} (@file{s-assert.ads})
-@cindex @code{System.Assertions} (@file{s-assert.ads})
-@cindex Assertions
-@cindex Assert_Failure, exception
-
-@noindent
-This package provides the declaration of the exception raised
-by an run-time assertion failure, as well as the routine that
-is used internally to raise this assertion.
-
-@node System.Memory (s-memory.ads)
-@section @code{System.Memory} (@file{s-memory.ads})
-@cindex @code{System.Memory} (@file{s-memory.ads})
-@cindex Memory allocation
-
-@noindent
-This package provides the interface to the low level routines used
-by the generated code for allocation and freeing storage for the
-default storage pool (analogous to the C routines malloc and free.
-It also provides a reallocation interface analogous to the C routine
-realloc. The body of this unit may be modified to provide alternative
-allocation mechanisms for the default pool, and in addition, direct
-calls to this unit may be made for low level allocation uses (for
-example see the body of @code{GNAT.Tables}).
-
-@node System.Partition_Interface (s-parint.ads)
-@section @code{System.Partition_Interface} (@file{s-parint.ads})
-@cindex @code{System.Partition_Interface} (@file{s-parint.ads})
-@cindex Partition interfacing functions
-
-@noindent
-This package provides facilities for partition interfacing. It
-is used primarily in a distribution context when using Annex E
-with @code{GLADE}.
-
-@node System.Pool_Global (s-pooglo.ads)
-@section @code{System.Pool_Global} (@file{s-pooglo.ads})
-@cindex @code{System.Pool_Global} (@file{s-pooglo.ads})
-@cindex Storage pool, global
-@cindex Global storage pool
-
-@noindent
-This package provides a storage pool that is equivalent to the default
-storage pool used for access types for which no pool is specifically
-declared. It uses malloc/free to allocate/free and does not attempt to
-do any automatic reclamation.
-
-@node System.Pool_Local (s-pooloc.ads)
-@section @code{System.Pool_Local} (@file{s-pooloc.ads})
-@cindex @code{System.Pool_Local} (@file{s-pooloc.ads})
-@cindex Storage pool, local
-@cindex Local storage pool
-
-@noindent
-This package provides a storage pool that is intended for use with locally
-defined access types. It uses malloc/free for allocate/free, and maintains
-a list of allocated blocks, so that all storage allocated for the pool can
-be freed automatically when the pool is finalized.
-
-@node System.Restrictions (s-restri.ads)
-@section @code{System.Restrictions} (@file{s-restri.ads})
-@cindex @code{System.Restrictions} (@file{s-restri.ads})
-@cindex Run-time restrictions access
-
-@noindent
-This package provides facilities for accessing at run time
-the status of restrictions specified at compile time for
-the partition. Information is available both with regard
-to actual restrictions specified, and with regard to
-compiler determined information on which restrictions
-are violated by one or more packages in the partition.
-
-@node System.Rident (s-rident.ads)
-@section @code{System.Rident} (@file{s-rident.ads})
-@cindex @code{System.Rident} (@file{s-rident.ads})
-@cindex Restrictions definitions
-
-@noindent
-This package provides definitions of the restrictions
-identifiers supported by GNAT, and also the format of
-the restrictions provided in package System.Restrictions.
-It is not normally necessary to @code{with} this generic package
-since the necessary instantiation is included in
-package System.Restrictions.
-
-@node System.Task_Info (s-tasinf.ads)
-@section @code{System.Task_Info} (@file{s-tasinf.ads})
-@cindex @code{System.Task_Info} (@file{s-tasinf.ads})
-@cindex Task_Info pragma
-
-@noindent
-This package provides target dependent functionality that is used
-to support the @code{Task_Info} pragma
-
-@node System.Wch_Cnv (s-wchcnv.ads)
-@section @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
-@cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
-@cindex Wide Character, Representation
-@cindex Wide String, Conversion
-@cindex Representation of wide characters
-
-@noindent
-This package provides routines for converting between
-wide and wide wide characters and a representation as a value of type
-@code{Standard.String}, using a specified wide character
-encoding method. It uses definitions in
-package @code{System.Wch_Con}.
-
-@node System.Wch_Con (s-wchcon.ads)
-@section @code{System.Wch_Con} (@file{s-wchcon.ads})
-@cindex @code{System.Wch_Con} (@file{s-wchcon.ads})
-
-@noindent
-This package provides definitions and descriptions of
-the various methods used for encoding wide characters
-in ordinary strings. These definitions are used by
-the package @code{System.Wch_Cnv}.
-
-@node Interfacing to Other Languages
-@chapter Interfacing to Other Languages
-@noindent
-The facilities in annex B of the Ada Reference Manual are fully
-implemented in GNAT, and in addition, a full interface to C++ is
-provided.
-
-@menu
-* Interfacing to C::
-* Interfacing to C++::
-* Interfacing to COBOL::
-* Interfacing to Fortran::
-* Interfacing to non-GNAT Ada code::
-@end menu
-
-@node Interfacing to C
-@section Interfacing to C
-
-@noindent
-Interfacing to C with GNAT can use one of two approaches:
-
-@itemize @bullet
-@item
-The types in the package @code{Interfaces.C} may be used.
-@item
-Standard Ada types may be used directly. This may be less portable to
-other compilers, but will work on all GNAT compilers, which guarantee
-correspondence between the C and Ada types.
-@end itemize
-
-@noindent
-Pragma @code{Convention C} may be applied to Ada types, but mostly has no
-effect, since this is the default. The following table shows the
-correspondence between Ada scalar types and the corresponding C types.
-
-@table @code
-@item Integer
-@code{int}
-@item Short_Integer
-@code{short}
-@item Short_Short_Integer
-@code{signed char}
-@item Long_Integer
-@code{long}
-@item Long_Long_Integer
-@code{long long}
-@item Short_Float
-@code{float}
-@item Float
-@code{float}
-@item Long_Float
-@code{double}
-@item Long_Long_Float
-This is the longest floating-point type supported by the hardware.
-@end table
-
-@noindent
-Additionally, there are the following general correspondences between Ada
-and C types:
-@itemize @bullet
-@item
-Ada enumeration types map to C enumeration types directly if pragma
-@code{Convention C} is specified, which causes them to have int
-length. Without pragma @code{Convention C}, Ada enumeration types map to
-8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short},
-@code{int}, respectively) depending on the number of values passed.
-This is the only case in which pragma @code{Convention C} affects the
-representation of an Ada type.
-
-@item
-Ada access types map to C pointers, except for the case of pointers to
-unconstrained types in Ada, which have no direct C equivalent.
-
-@item
-Ada arrays map directly to C arrays.
-
-@item
-Ada records map directly to C structures.
-
-@item
-Packed Ada records map to C structures where all members are bit fields
-of the length corresponding to the @code{@var{type}'Size} value in Ada.
-@end itemize
-
-@node Interfacing to C++
-@section Interfacing to C++
-
-@noindent
-The interface to C++ makes use of the following pragmas, which are
-primarily intended to be constructed automatically using a binding generator
-tool, although it is possible to construct them by hand. No suitable binding
-generator tool is supplied with GNAT though.
-
-Using these pragmas it is possible to achieve complete
-inter-operability between Ada tagged types and C++ class definitions.
-See @ref{Implementation Defined Pragmas}, for more details.
-
-@table @code
-@item pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})
-The argument denotes an entity in the current declarative region that is
-declared as a tagged or untagged record type. It indicates that the type
-corresponds to an externally declared C++ class type, and is to be laid
-out the same way that C++ would lay out the type.
-
-Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
-for backward compatibility but its functionality is available
-using pragma @code{Import} with @code{Convention} = @code{CPP}.
-
-@item pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})
-This pragma identifies an imported function (imported in the usual way
-with pragma @code{Import}) as corresponding to a C++ constructor.
-@end table
-
-@node Interfacing to COBOL
-@section Interfacing to COBOL
-
-@noindent
-Interfacing to COBOL is achieved as described in section B.4 of
-the Ada Reference Manual.
-
-@node Interfacing to Fortran
-@section Interfacing to Fortran
-
-@noindent
-Interfacing to Fortran is achieved as described in section B.5 of the
-Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a
-multi-dimensional array causes the array to be stored in column-major
-order as required for convenient interface to Fortran.
-
-@node Interfacing to non-GNAT Ada code
-@section Interfacing to non-GNAT Ada code
-
-It is possible to specify the convention @code{Ada} in a pragma
-@code{Import} or pragma @code{Export}. However this refers to
-the calling conventions used by GNAT, which may or may not be
-similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
-compiler to allow interoperation.
-
-If arguments types are kept simple, and if the foreign compiler generally
-follows system calling conventions, then it may be possible to integrate
-files compiled by other Ada compilers, provided that the elaboration
-issues are adequately addressed (for example by eliminating the
-need for any load time elaboration).
-
-In particular, GNAT running on VMS is designed to
-be highly compatible with the DEC Ada 83 compiler, so this is one
-case in which it is possible to import foreign units of this type,
-provided that the data items passed are restricted to simple scalar
-values or simple record types without variants, or simple array
-types with fixed bounds.
-
-@node Specialized Needs Annexes
-@chapter Specialized Needs Annexes
-
-@noindent
-Ada 95 and Ada 2005 define a number of Specialized Needs Annexes, which are not
-required in all implementations. However, as described in this chapter,
-GNAT implements all of these annexes:
-
-@table @asis
-@item Systems Programming (Annex C)
-The Systems Programming Annex is fully implemented.
-
-@item Real-Time Systems (Annex D)
-The Real-Time Systems Annex is fully implemented.
-
-@item Distributed Systems (Annex E)
-Stub generation is fully implemented in the GNAT compiler. In addition,
-a complete compatible PCS is available as part of the GLADE system,
-a separate product. When the two
-products are used in conjunction, this annex is fully implemented.
-
-@item Information Systems (Annex F)
-The Information Systems annex is fully implemented.
-
-@item Numerics (Annex G)
-The Numerics Annex is fully implemented.
-
-@item Safety and Security / High-Integrity Systems (Annex H)
-The Safety and Security Annex (termed the High-Integrity Systems Annex
-in Ada 2005) is fully implemented.
-@end table
-
-@node Implementation of Specific Ada Features
-@chapter Implementation of Specific Ada Features
-
-@noindent
-This chapter describes the GNAT implementation of several Ada language
-facilities.
-
-@menu
-* Machine Code Insertions::
-* GNAT Implementation of Tasking::
-* GNAT Implementation of Shared Passive Packages::
-* Code Generation for Array Aggregates::
-* The Size of Discriminated Records with Default Discriminants::
-* Strict Conformance to the Ada Reference Manual::
-@end menu
-
-@node Machine Code Insertions
-@section Machine Code Insertions
-@cindex Machine Code insertions
-
-@noindent
-Package @code{Machine_Code} provides machine code support as described
-in the Ada Reference Manual in two separate forms:
-@itemize @bullet
-@item
-Machine code statements, consisting of qualified expressions that
-fit the requirements of RM section 13.8.
-@item
-An intrinsic callable procedure, providing an alternative mechanism of
-including machine instructions in a subprogram.
-@end itemize
-
-@noindent
-The two features are similar, and both are closely related to the mechanism
-provided by the asm instruction in the GNU C compiler. Full understanding
-and use of the facilities in this package requires understanding the asm
-instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression
-Operands, gcc, Using the GNU Compiler Collection (GCC)}.
-
-Calls to the function @code{Asm} and the procedure @code{Asm} have identical
-semantic restrictions and effects as described below. Both are provided so
-that the procedure call can be used as a statement, and the function call
-can be used to form a code_statement.
-
-The first example given in the GCC documentation is the C @code{asm}
-instruction:
-@smallexample
- asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
-@end smallexample
-
-@noindent
-The equivalent can be written for GNAT as:
-
-@smallexample @c ada
-Asm ("fsinx %1 %0",
- My_Float'Asm_Output ("=f", result),
- My_Float'Asm_Input ("f", angle));
-@end smallexample
-
-@noindent
-The first argument to @code{Asm} is the assembler template, and is
-identical to what is used in GNU C@. This string must be a static
-expression. The second argument is the output operand list. It is
-either a single @code{Asm_Output} attribute reference, or a list of such
-references enclosed in parentheses (technically an array aggregate of
-such references).
-
-The @code{Asm_Output} attribute denotes a function that takes two
-parameters. The first is a string, the second is the name of a variable
-of the type designated by the attribute prefix. The first (string)
-argument is required to be a static expression and designates the
-constraint for the parameter (e.g.@: what kind of register is
-required). The second argument is the variable to be updated with the
-result. The possible values for constraint are the same as those used in
-the RTL, and are dependent on the configuration file used to build the
-GCC back end. If there are no output operands, then this argument may
-either be omitted, or explicitly given as @code{No_Output_Operands}.
-
-The second argument of @code{@var{my_float}'Asm_Output} functions as
-though it were an @code{out} parameter, which is a little curious, but
-all names have the form of expressions, so there is no syntactic
-irregularity, even though normally functions would not be permitted
-@code{out} parameters. The third argument is the list of input
-operands. It is either a single @code{Asm_Input} attribute reference, or
-a list of such references enclosed in parentheses (technically an array
-aggregate of such references).
-
-The @code{Asm_Input} attribute denotes a function that takes two
-parameters. The first is a string, the second is an expression of the
-type designated by the prefix. The first (string) argument is required
-to be a static expression, and is the constraint for the parameter,
-(e.g.@: what kind of register is required). The second argument is the
-value to be used as the input argument. The possible values for the
-constant are the same as those used in the RTL, and are dependent on
-the configuration file used to built the GCC back end.
-
-If there are no input operands, this argument may either be omitted, or
-explicitly given as @code{No_Input_Operands}. The fourth argument, not
-present in the above example, is a list of register names, called the
-@dfn{clobber} argument. This argument, if given, must be a static string
-expression, and is a space or comma separated list of names of registers
-that must be considered destroyed as a result of the @code{Asm} call. If
-this argument is the null string (the default value), then the code
-generator assumes that no additional registers are destroyed.
-
-The fifth argument, not present in the above example, called the
-@dfn{volatile} argument, is by default @code{False}. It can be set to
-the literal value @code{True} to indicate to the code generator that all
-optimizations with respect to the instruction specified should be
-suppressed, and that in particular, for an instruction that has outputs,
-the instruction will still be generated, even if none of the outputs are
-used. @xref{Extended Asm,, Assembler Instructions with C Expression Operands,
-gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
-Generally it is strongly advisable to use Volatile for any ASM statement
-that is missing either input or output operands, or when two or more ASM
-statements appear in sequence, to avoid unwanted optimizations. A warning
-is generated if this advice is not followed.
-
-The @code{Asm} subprograms may be used in two ways. First the procedure
-forms can be used anywhere a procedure call would be valid, and
-correspond to what the RM calls ``intrinsic'' routines. Such calls can
-be used to intersperse machine instructions with other Ada statements.
-Second, the function forms, which return a dummy value of the limited
-private type @code{Asm_Insn}, can be used in code statements, and indeed
-this is the only context where such calls are allowed. Code statements
-appear as aggregates of the form:
-
-@smallexample @c ada
-Asm_Insn'(Asm (@dots{}));
-Asm_Insn'(Asm_Volatile (@dots{}));
-@end smallexample
-
-@noindent
-In accordance with RM rules, such code statements are allowed only
-within subprograms whose entire body consists of such statements. It is
-not permissible to intermix such statements with other Ada statements.
-
-Typically the form using intrinsic procedure calls is more convenient
-and more flexible. The code statement form is provided to meet the RM
-suggestion that such a facility should be made available. The following
-is the exact syntax of the call to @code{Asm}. As usual, if named notation
-is used, the arguments may be given in arbitrary order, following the
-normal rules for use of positional and named arguments)
-
-@smallexample
-ASM_CALL ::= Asm (
- [Template =>] static_string_EXPRESSION
- [,[Outputs =>] OUTPUT_OPERAND_LIST ]
- [,[Inputs =>] INPUT_OPERAND_LIST ]
- [,[Clobber =>] static_string_EXPRESSION ]
- [,[Volatile =>] static_boolean_EXPRESSION] )
-
-OUTPUT_OPERAND_LIST ::=
- [PREFIX.]No_Output_Operands
-| OUTPUT_OPERAND_ATTRIBUTE
-| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
-
-OUTPUT_OPERAND_ATTRIBUTE ::=
- SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
-
-INPUT_OPERAND_LIST ::=
- [PREFIX.]No_Input_Operands
-| INPUT_OPERAND_ATTRIBUTE
-| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
-
-INPUT_OPERAND_ATTRIBUTE ::=
- SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
-@end smallexample
-
-@noindent
-The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
-are declared in the package @code{Machine_Code} and must be referenced
-according to normal visibility rules. In particular if there is no
-@code{use} clause for this package, then appropriate package name
-qualification is required.
-
-@node GNAT Implementation of Tasking
-@section GNAT Implementation of Tasking
-
-@noindent
-This chapter outlines the basic GNAT approach to tasking (in particular,
-a multi-layered library for portability) and discusses issues related
-to compliance with the Real-Time Systems Annex.
-
-@menu
-* Mapping Ada Tasks onto the Underlying Kernel Threads::
-* Ensuring Compliance with the Real-Time Annex::
-@end menu
-
-@node Mapping Ada Tasks onto the Underlying Kernel Threads
-@subsection Mapping Ada Tasks onto the Underlying Kernel Threads
-
-@noindent
-GNAT's run-time support comprises two layers:
-
-@itemize @bullet
-@item GNARL (GNAT Run-time Layer)
-@item GNULL (GNAT Low-level Library)
-@end itemize
-
-@noindent
-In GNAT, Ada's tasking services rely on a platform and OS independent
-layer known as GNARL@. This code is responsible for implementing the
-correct semantics of Ada's task creation, rendezvous, protected
-operations etc.
-
-GNARL decomposes Ada's tasking semantics into simpler lower level
-operations such as create a thread, set the priority of a thread,
-yield, create a lock, lock/unlock, etc. The spec for these low-level
-operations constitutes GNULLI, the GNULL Interface. This interface is
-directly inspired from the POSIX real-time API@.
-
-If the underlying executive or OS implements the POSIX standard
-faithfully, the GNULL Interface maps as is to the services offered by
-the underlying kernel. Otherwise, some target dependent glue code maps
-the services offered by the underlying kernel to the semantics expected
-by GNARL@.
-
-Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the
-key point is that each Ada task is mapped on a thread in the underlying
-kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
-
-In addition Ada task priorities map onto the underlying thread priorities.
-Mapping Ada tasks onto the underlying kernel threads has several advantages:
-
-@itemize @bullet
-@item
-The underlying scheduler is used to schedule the Ada tasks. This
-makes Ada tasks as efficient as kernel threads from a scheduling
-standpoint.
-
-@item
-Interaction with code written in C containing threads is eased
-since at the lowest level Ada tasks and C threads map onto the same
-underlying kernel concept.
-
-@item
-When an Ada task is blocked during I/O the remaining Ada tasks are
-able to proceed.
-
-@item
-On multiprocessor systems Ada tasks can execute in parallel.
-@end itemize
-
-@noindent
-Some threads libraries offer a mechanism to fork a new process, with the
-child process duplicating the threads from the parent.
-GNAT does not
-support this functionality when the parent contains more than one task.
-@cindex Forking a new process
-
-@node Ensuring Compliance with the Real-Time Annex
-@subsection Ensuring Compliance with the Real-Time Annex
-@cindex Real-Time Systems Annex compliance
-
-@noindent
-Although mapping Ada tasks onto
-the underlying threads has significant advantages, it does create some
-complications when it comes to respecting the scheduling semantics
-specified in the real-time annex (Annex D).
-
-For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
-scheduling policy states:
-
-@quotation
-@emph{When the active priority of a ready task that is not running
-changes, or the setting of its base priority takes effect, the
-task is removed from the ready queue for its old active priority
-and is added at the tail of the ready queue for its new active
-priority, except in the case where the active priority is lowered
-due to the loss of inherited priority, in which case the task is
-added at the head of the ready queue for its new active priority.}
-@end quotation
-
-@noindent
-While most kernels do put tasks at the end of the priority queue when
-a task changes its priority, (which respects the main
-FIFO_Within_Priorities requirement), almost none keep a thread at the
-beginning of its priority queue when its priority drops from the loss
-of inherited priority.
-
-As a result most vendors have provided incomplete Annex D implementations.
-
-The GNAT run-time, has a nice cooperative solution to this problem
-which ensures that accurate FIFO_Within_Priorities semantics are
-respected.
-
-The principle is as follows. When an Ada task T is about to start
-running, it checks whether some other Ada task R with the same
-priority as T has been suspended due to the loss of priority
-inheritance. If this is the case, T yields and is placed at the end of
-its priority queue. When R arrives at the front of the queue it
-executes.
-
-Note that this simple scheme preserves the relative order of the tasks
-that were ready to execute in the priority queue where R has been
-placed at the end.
-
-@node GNAT Implementation of Shared Passive Packages
-@section GNAT Implementation of Shared Passive Packages
-@cindex Shared passive packages
-
-@noindent
-GNAT fully implements the pragma @code{Shared_Passive} for
-@cindex pragma @code{Shared_Passive}
-the purpose of designating shared passive packages.
-This allows the use of passive partitions in the
-context described in the Ada Reference Manual; i.e., for communication
-between separate partitions of a distributed application using the
-features in Annex E.
-@cindex Annex E
-@cindex Distribution Systems Annex
-
-However, the implementation approach used by GNAT provides for more
-extensive usage as follows:
-
-@table @emph
-@item Communication between separate programs
-
-This allows separate programs to access the data in passive
-partitions, using protected objects for synchronization where
-needed. The only requirement is that the two programs have a
-common shared file system. It is even possible for programs
-running on different machines with different architectures
-(e.g.@: different endianness) to communicate via the data in
-a passive partition.
-
-@item Persistence between program runs
-
-The data in a passive package can persist from one run of a
-program to another, so that a later program sees the final
-values stored by a previous run of the same program.
-
-@end table
-
-@noindent
-The implementation approach used is to store the data in files. A
-separate stream file is created for each object in the package, and
-an access to an object causes the corresponding file to be read or
-written.
-
-The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
-@cindex @code{SHARED_MEMORY_DIRECTORY} environment variable
-set to the directory to be used for these files.
-The files in this directory
-have names that correspond to their fully qualified names. For
-example, if we have the package
-
-@smallexample @c ada
-package X is
- pragma Shared_Passive (X);
- Y : Integer;
- Z : Float;
-end X;
-@end smallexample
-
-@noindent
-and the environment variable is set to @code{/stemp/}, then the files created
-will have the names:
-
-@smallexample
-/stemp/x.y
-/stemp/x.z
-@end smallexample
-
-@noindent
-These files are created when a value is initially written to the object, and
-the files are retained until manually deleted. This provides the persistence
-semantics. If no file exists, it means that no partition has assigned a value
-to the variable; in this case the initial value declared in the package
-will be used. This model ensures that there are no issues in synchronizing
-the elaboration process, since elaboration of passive packages elaborates the
-initial values, but does not create the files.
-
-The files are written using normal @code{Stream_IO} access.
-If you want to be able
-to communicate between programs or partitions running on different
-architectures, then you should use the XDR versions of the stream attribute
-routines, since these are architecture independent.
-
-If active synchronization is required for access to the variables in the
-shared passive package, then as described in the Ada Reference Manual, the
-package may contain protected objects used for this purpose. In this case
-a lock file (whose name is @file{___lock} (three underscores)
-is created in the shared memory directory.
-@cindex @file{___lock} file (for shared passive packages)
-This is used to provide the required locking
-semantics for proper protected object synchronization.
-
-As of January 2003, GNAT supports shared passive packages on all platforms
-except for OpenVMS.
-
-@node Code Generation for Array Aggregates
-@section Code Generation for Array Aggregates
-
-@menu
-* Static constant aggregates with static bounds::
-* Constant aggregates with unconstrained nominal types::
-* Aggregates with static bounds::
-* Aggregates with non-static bounds::
-* Aggregates in assignment statements::
-@end menu
-
-@noindent
-Aggregates have a rich syntax and allow the user to specify the values of
-complex data structures by means of a single construct. As a result, the
-code generated for aggregates can be quite complex and involve loops, case
-statements and multiple assignments. In the simplest cases, however, the
-compiler will recognize aggregates whose components and constraints are
-fully static, and in those cases the compiler will generate little or no
-executable code. The following is an outline of the code that GNAT generates
-for various aggregate constructs. For further details, you will find it
-useful to examine the output produced by the -gnatG flag to see the expanded
-source that is input to the code generator. You may also want to examine
-the assembly code generated at various levels of optimization.
-
-The code generated for aggregates depends on the context, the component values,
-and the type. In the context of an object declaration the code generated is
-generally simpler than in the case of an assignment. As a general rule, static
-component values and static subtypes also lead to simpler code.
-
-@node Static constant aggregates with static bounds
-@subsection Static constant aggregates with static bounds
-
-@noindent
-For the declarations:
-@smallexample @c ada
- type One_Dim is array (1..10) of integer;
- ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
-@end smallexample
-
-@noindent
-GNAT generates no executable code: the constant ar0 is placed in static memory.
-The same is true for constant aggregates with named associations:
-
-@smallexample @c ada
- Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
- Cr3 : constant One_Dim := (others => 7777);
-@end smallexample
-
-@noindent
-The same is true for multidimensional constant arrays such as:
-
-@smallexample @c ada
- type two_dim is array (1..3, 1..3) of integer;
- Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
-@end smallexample
-
-@noindent
-The same is true for arrays of one-dimensional arrays: the following are
-static:
-
-@smallexample @c ada
-type ar1b is array (1..3) of boolean;
-type ar_ar is array (1..3) of ar1b;
-None : constant ar1b := (others => false); -- fully static
-None2 : constant ar_ar := (1..3 => None); -- fully static
-@end smallexample
-
-@noindent
-However, for multidimensional aggregates with named associations, GNAT will
-generate assignments and loops, even if all associations are static. The
-following two declarations generate a loop for the first dimension, and
-individual component assignments for the second dimension:
-
-@smallexample @c ada
-Zero1: constant two_dim := (1..3 => (1..3 => 0));
-Zero2: constant two_dim := (others => (others => 0));
-@end smallexample
-
-@node Constant aggregates with unconstrained nominal types
-@subsection Constant aggregates with unconstrained nominal types
-
-@noindent
-In such cases the aggregate itself establishes the subtype, so that
-associations with @code{others} cannot be used. GNAT determines the
-bounds for the actual subtype of the aggregate, and allocates the
-aggregate statically as well. No code is generated for the following:
-
-@smallexample @c ada
- type One_Unc is array (natural range <>) of integer;
- Cr_Unc : constant One_Unc := (12,24,36);
-@end smallexample
-
-@node Aggregates with static bounds
-@subsection Aggregates with static bounds
-
-@noindent
-In all previous examples the aggregate was the initial (and immutable) value
-of a constant. If the aggregate initializes a variable, then code is generated
-for it as a combination of individual assignments and loops over the target
-object. The declarations
-
-@smallexample @c ada
- Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
- Cr_Var2 : One_Dim := (others > -1);
-@end smallexample
-
-@noindent
-generate the equivalent of
-
-@smallexample @c ada
- Cr_Var1 (1) := 2;
- Cr_Var1 (2) := 3;
- Cr_Var1 (3) := 5;
- Cr_Var1 (4) := 11;
-
- for I in Cr_Var2'range loop
- Cr_Var2 (I) := -1;
- end loop;
-@end smallexample
-
-@node Aggregates with non-static bounds
-@subsection Aggregates with non-static bounds
-
-@noindent
-If the bounds of the aggregate are not statically compatible with the bounds
-of the nominal subtype of the target, then constraint checks have to be
-generated on the bounds. For a multidimensional array, constraint checks may
-have to be applied to sub-arrays individually, if they do not have statically
-compatible subtypes.
-
-@node Aggregates in assignment statements
-@subsection Aggregates in assignment statements
-
-@noindent
-In general, aggregate assignment requires the construction of a temporary,
-and a copy from the temporary to the target of the assignment. This is because
-it is not always possible to convert the assignment into a series of individual
-component assignments. For example, consider the simple case:
-
-@smallexample @c ada
- A := (A(2), A(1));
-@end smallexample
-
-@noindent
-This cannot be converted into:
-
-@smallexample @c ada
- A(1) := A(2);
- A(2) := A(1);
-@end smallexample
-
-@noindent
-So the aggregate has to be built first in a separate location, and then
-copied into the target. GNAT recognizes simple cases where this intermediate
-step is not required, and the assignments can be performed in place, directly
-into the target. The following sufficient criteria are applied:
-
-@itemize @bullet
-@item
-The bounds of the aggregate are static, and the associations are static.
-@item
-The components of the aggregate are static constants, names of
-simple variables that are not renamings, or expressions not involving
-indexed components whose operands obey these rules.
-@end itemize
-
-@noindent
-If any of these conditions are violated, the aggregate will be built in
-a temporary (created either by the front-end or the code generator) and then
-that temporary will be copied onto the target.
-
-
-@node The Size of Discriminated Records with Default Discriminants
-@section The Size of Discriminated Records with Default Discriminants
-
-@noindent
-If a discriminated type @code{T} has discriminants with default values, it is
-possible to declare an object of this type without providing an explicit
-constraint:
-
-@smallexample @c ada
-@group
-type Size is range 1..100;
-
-type Rec (D : Size := 15) is record
- Name : String (1..D);
-end T;
-
-Word : Rec;
-@end group
-@end smallexample
-
-@noindent
-Such an object is said to be @emph{unconstrained}.
-The discriminant of the object
-can be modified by a full assignment to the object, as long as it preserves the
-relation between the value of the discriminant, and the value of the components
-that depend on it:
-
-@smallexample @c ada
-@group
-Word := (3, "yes");
-
-Word := (5, "maybe");
-
-Word := (5, "no"); -- raises Constraint_Error
-@end group
-@end smallexample
-
-@noindent
-In order to support this behavior efficiently, an unconstrained object is
-given the maximum size that any value of the type requires. In the case
-above, @code{Word} has storage for the discriminant and for
-a @code{String} of length 100.
-It is important to note that unconstrained objects do not require dynamic
-allocation. It would be an improper implementation to place on the heap those
-components whose size depends on discriminants. (This improper implementation
-was used by some Ada83 compilers, where the @code{Name} component above
-would have
-been stored as a pointer to a dynamic string). Following the principle that
-dynamic storage management should never be introduced implicitly,
-an Ada compiler should reserve the full size for an unconstrained declared
-object, and place it on the stack.
-
-This maximum size approach
-has been a source of surprise to some users, who expect the default
-values of the discriminants to determine the size reserved for an
-unconstrained object: ``If the default is 15, why should the object occupy
-a larger size?''
-The answer, of course, is that the discriminant may be later modified,
-and its full range of values must be taken into account. This is why the
-declaration:
-
-@smallexample
-@group
-type Rec (D : Positive := 15) is record
- Name : String (1..D);
-end record;
-
-Too_Large : Rec;
-@end group
-@end smallexample
-
-@noindent
-is flagged by the compiler with a warning:
-an attempt to create @code{Too_Large} will raise @code{Storage_Error},
-because the required size includes @code{Positive'Last}
-bytes. As the first example indicates, the proper approach is to declare an
-index type of ``reasonable'' range so that unconstrained objects are not too
-large.
-
-One final wrinkle: if the object is declared to be @code{aliased}, or if it is
-created in the heap by means of an allocator, then it is @emph{not}
-unconstrained:
-it is constrained by the default values of the discriminants, and those values
-cannot be modified by full assignment. This is because in the presence of
-aliasing all views of the object (which may be manipulated by different tasks,
-say) must be consistent, so it is imperative that the object, once created,
-remain invariant.
-
-@node Strict Conformance to the Ada Reference Manual
-@section Strict Conformance to the Ada Reference Manual
-
-@noindent
-The dynamic semantics defined by the Ada Reference Manual impose a set of
-run-time checks to be generated. By default, the GNAT compiler will insert many
-run-time checks into the compiled code, including most of those required by the
-Ada Reference Manual. However, there are three checks that are not enabled
-in the default mode for efficiency reasons: arithmetic overflow checking for
-integer operations (including division by zero), checks for access before
-elaboration on subprogram calls, and stack overflow checking (most operating
-systems do not perform this check by default).
-
-Strict conformance to the Ada Reference Manual can be achieved by adding
-three compiler options for overflow checking for integer operations
-(@option{-gnato}), dynamic checks for access-before-elaboration on subprogram
-calls and generic instantiations (@option{-gnatE}), and stack overflow
-checking (@option{-fstack-check}).
-
-Note that the result of a floating point arithmetic operation in overflow and
-invalid situations, when the @code{Machine_Overflows} attribute of the result
-type is @code{False}, is to generate IEEE NaN and infinite values. This is the
-case for machines compliant with the IEEE floating-point standard, but on
-machines that are not fully compliant with this standard, such as Alpha, the
-@option{-mieee} compiler flag must be used for achieving IEEE confirming
-behavior (although at the cost of a significant performance penalty), so
-infinite and and NaN values are properly generated.
-
-
-@node Project File Reference
-@chapter Project File Reference
-
-@noindent
-This chapter describes the syntax and semantics of project files.
-Project files specify the options to be used when building a system.
-Project files can specify global settings for all tools,
-as well as tool-specific settings.
-@xref{Examples of Project Files,,, gnat_ugn, @value{EDITION} User's Guide},
-for examples of use.
-
-@menu
-* Reserved Words::
-* Lexical Elements::
-* Declarations::
-* Empty declarations::
-* Typed string declarations::
-* Variables::
-* Expressions::
-* Attributes::
-* Project Attributes::
-* Attribute References::
-* External Values::
-* Case Construction::
-* Packages::
-* Package Renamings::
-* Projects::
-* Project Extensions::
-* Project File Elaboration::
-@end menu
-
-@node Reserved Words
-@section Reserved Words
-
-@noindent
-All Ada reserved words are reserved in project files, and cannot be used
-as variable names or project names. In addition, the following are
-also reserved in project files:
-
-@itemize
-@item @code{extends}
-
-@item @code{external}
-
-@item @code{project}
-
-@end itemize
-
-@node Lexical Elements
-@section Lexical Elements
-
-@noindent
-Rules for identifiers are the same as in Ada. Identifiers
-are case-insensitive. Strings are case sensitive, except where noted.
-Comments have the same form as in Ada.
-
-@noindent
-Syntax:
-
-@smallexample
-simple_name ::=
- identifier
-
-name ::=
- simple_name @{. simple_name@}
-@end smallexample
-
-@node Declarations
-@section Declarations
-
-@noindent
-Declarations introduce new entities that denote types, variables, attributes,
-and packages. Some declarations can only appear immediately within a project
-declaration. Others can appear within a project or within a package.
-
-Syntax:
-@smallexample
-declarative_item ::=
- simple_declarative_item |
- typed_string_declaration |
- package_declaration
-
-simple_declarative_item ::=
- variable_declaration |
- typed_variable_declaration |
- attribute_declaration |
- case_construction |
- empty_declaration
-@end smallexample
-
-@node Empty declarations
-@section Empty declarations
-
-@smallexample
-empty_declaration ::=
- @b{null} ;
-@end smallexample
-
-An empty declaration is allowed anywhere a declaration is allowed.
-It has no effect.
-
-@node Typed string declarations
-@section Typed string declarations
-
-@noindent
-Typed strings are sequences of string literals. Typed strings are the only
-named types in project files. They are used in case constructions, where they
-provide support for conditional attribute definitions.
-
-Syntax:
-@smallexample
-typed_string_declaration ::=
- @b{type} <typed_string_>_simple_name @b{is}
- ( string_literal @{, string_literal@} );
-@end smallexample
-
-@noindent
-A typed string declaration can only appear immediately within a project
-declaration.
-
-All the string literals in a typed string declaration must be distinct.
-
-@node Variables
-@section Variables
-
-@noindent
-Variables denote values, and appear as constituents of expressions.
-
-@smallexample
-typed_variable_declaration ::=
- <typed_variable_>simple_name : <typed_string_>name := string_expression ;
-
-variable_declaration ::=
- <variable_>simple_name := expression;
-@end smallexample
-
-@noindent
-The elaboration of a variable declaration introduces the variable and
-assigns to it the value of the expression. The name of the variable is
-available after the assignment symbol.
-
-@noindent
-A typed_variable can only be declare once.
-
-@noindent
-a non-typed variable can be declared multiple times.
-
-@noindent
-Before the completion of its first declaration, the value of variable
-is the null string.
-
-@node Expressions
-@section Expressions
-
-@noindent
-An expression is a formula that defines a computation or retrieval of a value.
-In a project file the value of an expression is either a string or a list
-of strings. A string value in an expression is either a literal, the current
-value of a variable, an external value, an attribute reference, or a
-concatenation operation.
-
-Syntax:
-
-@smallexample
-expression ::=
- term @{& term@}
-
-term ::=
- string_literal |
- string_list |
- <variable_>name |
- external_value |
- attribute_reference
-
-string_literal ::=
- (same as Ada)
-
-string_list ::=
- ( <string_>expression @{ , <string_>expression @} )
-@end smallexample
-
-@subsection Concatenation
-@noindent
-The following concatenation functions are defined:
-
-@smallexample @c ada
- function "&" (X : String; Y : String) return String;
- function "&" (X : String_List; Y : String) return String_List;
- function "&" (X : String_List; Y : String_List) return String_List;
-@end smallexample
-
-@node Attributes
-@section Attributes
-
-@noindent
-An attribute declaration defines a property of a project or package. This
-property can later be queried by means of an attribute reference.
-Attribute values are strings or string lists.
-
-Some attributes are associative arrays. These attributes are mappings whose
-domain is a set of strings. These attributes are declared one association
-at a time, by specifying a point in the domain and the corresponding image
-of the attribute. They may also be declared as a full associative array,
-getting the same associations as the corresponding attribute in an imported
-or extended project.
-
-Attributes that are not associative arrays are called simple attributes.
-
-Syntax:
-@smallexample
-attribute_declaration ::=
- full_associative_array_declaration |
- @b{for} attribute_designator @b{use} expression ;
-
-full_associative_array_declaration ::=
- @b{for} <associative_array_attribute_>simple_name @b{use}
- <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
-
-attribute_designator ::=
- <simple_attribute_>simple_name |
- <associative_array_attribute_>simple_name ( string_literal )
-@end smallexample
-
-@noindent
-Some attributes are project-specific, and can only appear immediately within
-a project declaration. Others are package-specific, and can only appear within
-the proper package.
-
-The expression in an attribute definition must be a string or a string_list.
-The string literal appearing in the attribute_designator of an associative
-array attribute is case-insensitive.
-
-@node Project Attributes
-@section Project Attributes
-
-@noindent
-The following attributes apply to a project. All of them are simple
-attributes.
-
-@table @code
-@item Object_Dir
-Expression must be a path name. The attribute defines the
-directory in which the object files created by the build are to be placed. If
-not specified, object files are placed in the project directory.
-
-@item Exec_Dir
-Expression must be a path name. The attribute defines the
-directory in which the executables created by the build are to be placed.
-If not specified, executables are placed in the object directory.
-
-@item Source_Dirs
-Expression must be a list of path names. The attribute
-defines the directories in which the source files for the project are to be
-found. If not specified, source files are found in the project directory.
-If a string in the list ends with "/**", then the directory that precedes
-"/**" and all of its subdirectories (recursively) are included in the list
-of source directories.
-
-@item Excluded_Source_Dirs
-Expression must be a list of strings. Each entry designates a directory that
-is not to be included in the list of source directories of the project.
-This is normally used when there are strings ending with "/**" in the value
-of attribute Source_Dirs.
-
-@item Source_Files
-Expression must be a list of file names. The attribute
-defines the individual files, in the project directory, which are to be used
-as sources for the project. File names are path_names that contain no directory
-information. If the project has no sources the attribute must be declared
-explicitly with an empty list.
-
-@item Excluded_Source_Files (Locally_Removed_Files)
-Expression must be a list of strings that are legal file names.
-Each file name must designate a source that would normally be a source file
-in the source directories of the project or, if the project file is an
-extending project file, inherited by the current project file. It cannot
-designate an immediate source that is not inherited. Each of the source files
-in the list are not considered to be sources of the project file: they are not
-inherited. Attribute Locally_Removed_Files is obsolescent, attribute
-Excluded_Source_Files is preferred.
-
-@item Source_List_File
-Expression must a single path name. The attribute
-defines a text file that contains a list of source file names to be used
-as sources for the project
-
-@item Library_Dir
-Expression must be a path name. The attribute defines the
-directory in which a library is to be built. The directory must exist, must
-be distinct from the project's object directory, and must be writable.
-
-@item Library_Name
-Expression must be a string that is a legal file name,
-without extension. The attribute defines a string that is used to generate
-the name of the library to be built by the project.
-
-@item Library_Kind
-Argument must be a string value that must be one of the
-following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This
-string is case-insensitive. If this attribute is not specified, the library is
-a static library. Otherwise, the library may be dynamic or relocatable. This
-distinction is operating-system dependent.
-
-@item Library_Version
-Expression must be a string value whose interpretation
-is platform dependent. On UNIX, it is used only for dynamic/relocatable
-libraries as the internal name of the library (the @code{"soname"}). If the
-library file name (built from the @code{Library_Name}) is different from the
-@code{Library_Version}, then the library file will be a symbolic link to the
-actual file whose name will be @code{Library_Version}.
-
-@item Library_Interface
-Expression must be a string list. Each element of the string list
-must designate a unit of the project.
-If this attribute is present in a Library Project File, then the project
-file is a Stand-alone Library_Project_File.
-
-@item Library_Auto_Init
-Expression must be a single string "true" or "false", case-insensitive.
-If this attribute is present in a Stand-alone Library Project File,
-it indicates if initialization is automatic when the dynamic library
-is loaded.
-
-@item Library_Options
-Expression must be a string list. Indicates additional switches that
-are to be used when building a shared library.
-
-@item Library_GCC
-Expression must be a single string. Designates an alternative to "gcc"
-for building shared libraries.
-
-@item Library_Src_Dir
-Expression must be a path name. The attribute defines the
-directory in which the sources of the interfaces of a Stand-alone Library will
-be copied. The directory must exist, must be distinct from the project's
-object directory and source directories of all projects in the project tree,
-and must be writable.
-
-@item Library_Src_Dir
-Expression must be a path name. The attribute defines the
-directory in which the ALI files of a Library will
-be copied. The directory must exist, must be distinct from the project's
-object directory and source directories of all projects in the project tree,
-and must be writable.
-
-@item Library_Symbol_File
-Expression must be a single string. Its value is the single file name of a
-symbol file to be created when building a stand-alone library when the
-symbol policy is either "compliant", "controlled" or "restricted",
-on platforms that support symbol control, such as VMS. When symbol policy
-is "direct", then a file with this name must exist in the object directory.
-
-@item Library_Reference_Symbol_File
-Expression must be a single string. Its value is the path name of a
-reference symbol file that is read when the symbol policy is either
-"compliant" or "controlled", on platforms that support symbol control,
-such as VMS, when building a stand-alone library. The path may be an absolute
-path or a path relative to the project directory.
-
-@item Library_Symbol_Policy
-Expression must be a single string. Its case-insensitive value can only be
-"autonomous", "default", "compliant", "controlled", "restricted" or "direct".
-
-This attribute is not taken into account on all platforms. It controls the
-policy for exported symbols and, on some platforms (like VMS) that have the
-notions of major and minor IDs built in the library files, it controls
-the setting of these IDs.
-
-"autonomous" or "default": exported symbols are not controlled.
-
-"compliant": if attribute Library_Reference_Symbol_File is not defined, then
-it is equivalent to policy "autonomous". If there are exported symbols in
-the reference symbol file that are not in the object files of the interfaces,
-the major ID of the library is increased. If there are symbols in the
-object files of the interfaces that are not in the reference symbol file,
-these symbols are put at the end of the list in the newly created symbol file
-and the minor ID is increased.
-
-"controlled": the attribute Library_Reference_Symbol_File must be defined.
-The library will fail to build if the exported symbols in the object files of
-the interfaces do not match exactly the symbol in the symbol file.
-
-"restricted": The attribute Library_Symbol_File must be defined. The library
-will fail to build if there are symbols in the symbol file that are not in
-the exported symbols of the object files of the interfaces. Additional symbols
-in the object files are not added to the symbol file.
-
-"direct": The attribute Library_Symbol_File must be defined and must designate
-an existing file in the object directory. This symbol file is passed directly
-to the underlying linker without any symbol processing.
-
-@item Main
-Expression must be a list of strings that are legal file names.
-These file names designate existing compilation units in the source directory
-that are legal main subprograms.
-
-When a project file is elaborated, as part of the execution of a gnatmake
-command, one or several executables are built and placed in the Exec_Dir.
-If the gnatmake command does not include explicit file names, the executables
-that are built correspond to the files specified by this attribute.
-
-@item Externally_Built
-Expression must be a single string. Its value must be either "true" of "false",
-case-insensitive. The default is "false". When the value of this attribute is
-"true", no attempt is made to compile the sources or to build the library,
-when the project is a library project.
-
-@item Main_Language
-This is a simple attribute. Its value is a string that specifies the
-language of the main program.
-
-@item Languages
-Expression must be a string list. Each string designates
-a programming language that is known to GNAT. The strings are case-insensitive.
-
-@end table
-
-@node Attribute References
-@section Attribute References
-
-@noindent
-Attribute references are used to retrieve the value of previously defined
-attribute for a package or project.
-Syntax:
-@smallexample
-attribute_reference ::=
- attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ]
-
-attribute_prefix ::=
- @b{project} |
- <project_simple_name | package_identifier |
- <project_>simple_name . package_identifier
-@end smallexample
-
-@noindent
-If an attribute has not been specified for a given package or project, its
-value is the null string or the empty list.
-
-@node External Values
-@section External Values
-
-@noindent
-An external value is an expression whose value is obtained from the command
-that invoked the processing of the current project file (typically a
-gnatmake command).
-
-Syntax:
-@smallexample
-external_value ::=
- @b{external} ( string_literal [, string_literal] )
-@end smallexample
-
-@noindent
-The first string_literal is the string to be used on the command line or
-in the environment to specify the external value. The second string_literal,
-if present, is the default to use if there is no specification for this
-external value either on the command line or in the environment.
-
-@node Case Construction
-@section Case Construction
-
-@noindent
-A case construction supports attribute and variable declarations that depend
-on the value of a previously declared variable.
-
-Syntax:
-@smallexample
-case_construction ::=
- @b{case} <typed_variable_>name @b{is}
- @{case_item@}
- @b{end case} ;
-
-case_item ::=
- @b{when} discrete_choice_list =>
- @{case_construction |
- attribute_declaration |
- variable_declaration |
- empty_declaration@}
-
-discrete_choice_list ::=
- string_literal @{| string_literal@} |
- @b{others}
-@end smallexample
-
-@noindent
-Inside a case construction, variable declarations must be for variables that
-have already been declared before the case construction.
-
-All choices in a choice list must be distinct. The choice lists of two
-distinct alternatives must be disjoint. Unlike Ada, the choice lists of all
-alternatives do not need to include all values of the type. An @code{others}
-choice must appear last in the list of alternatives.
-
-@node Packages
-@section Packages
-
-@noindent
-A package provides a grouping of variable declarations and attribute
-declarations to be used when invoking various GNAT tools. The name of
-the package indicates the tool(s) to which it applies.
-Syntax:
-
-@smallexample
-package_declaration ::=
- package_spec | package_renaming
-
-package_spec ::=
- @b{package} package_identifier @b{is}
- @{simple_declarative_item@}
- @b{end} package_identifier ;
-
-package_identifier ::=
- @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
- @code{Linker} | @code{Finder} | @code{Cross_Reference} |
- @code{gnatls} | @code{IDE} | @code{Pretty_Printer}
-@end smallexample
-
-@subsection Package Naming
-
-@noindent
-The attributes of a @code{Naming} package specifies the naming conventions
-that apply to the source files in a project. When invoking other GNAT tools,
-they will use the sources in the source directories that satisfy these
-naming conventions.
-
-The following attributes apply to a @code{Naming} package:
-
-@table @code
-@item Casing
-This is a simple attribute whose value is a string. Legal values of this
-string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}.
-These strings are themselves case insensitive.
-
-@noindent
-If @code{Casing} is not specified, then the default is @code{"lowercase"}.
-
-@item Dot_Replacement
-This is a simple attribute whose string value satisfies the following
-requirements:
-
-@itemize @bullet
-@item It must not be empty
-@item It cannot start or end with an alphanumeric character
-@item It cannot be a single underscore
-@item It cannot start with an underscore followed by an alphanumeric
-@item It cannot contain a dot @code{'.'} if longer than one character
-@end itemize
-
-@noindent
-If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
-
-@item Spec_Suffix
-This is an associative array attribute, defined on language names,
-whose image is a string that must satisfy the following
-conditions:
-
-@itemize @bullet
-@item It must not be empty
-@item It cannot start with an alphanumeric character
-@item It cannot start with an underscore followed by an alphanumeric character
-@end itemize
-
-@noindent
-For Ada, the attribute denotes the suffix used in file names that contain
-library unit declarations, that is to say units that are package and
-subprogram declarations. If @code{Spec_Suffix ("Ada")} is not
-specified, then the default is @code{".ads"}.
-
-For C and C++, the attribute denotes the suffix used in file names that
-contain prototypes.
-
-@item Body_Suffix
-This is an associative array attribute defined on language names,
-whose image is a string that must satisfy the following
-conditions:
-
-@itemize @bullet
-@item It must not be empty
-@item It cannot start with an alphanumeric character
-@item It cannot start with an underscore followed by an alphanumeric character
-@item It cannot be a suffix of @code{Spec_Suffix}
-@end itemize
-
-@noindent
-For Ada, the attribute denotes the suffix used in file names that contain
-library bodies, that is to say units that are package and subprogram bodies.
-If @code{Body_Suffix ("Ada")} is not specified, then the default is
-@code{".adb"}.
-
-For C and C++, the attribute denotes the suffix used in file names that contain
-source code.
-
-@item Separate_Suffix
-This is a simple attribute whose value satisfies the same conditions as
-@code{Body_Suffix}.
-
-This attribute is specific to Ada. It denotes the suffix used in file names
-that contain separate bodies. If it is not specified, then it defaults to same
-value as @code{Body_Suffix ("Ada")}.
-
-@item Spec
-This is an associative array attribute, specific to Ada, defined over
-compilation unit names. The image is a string that is the name of the file
-that contains that library unit. The file name is case sensitive if the
-conventions of the host operating system require it.
-
-@item Body
-This is an associative array attribute, specific to Ada, defined over
-compilation unit names. The image is a string that is the name of the file
-that contains the library unit body for the named unit. The file name is case
-sensitive if the conventions of the host operating system require it.
-
-@item Specification_Exceptions
-This is an associative array attribute defined on language names,
-whose value is a list of strings.
-
-This attribute is not significant for Ada.
-
-For C and C++, each string in the list denotes the name of a file that
-contains prototypes, but whose suffix is not necessarily the
-@code{Spec_Suffix} for the language.
-
-@item Implementation_Exceptions
-This is an associative array attribute defined on language names,
-whose value is a list of strings.
-
-This attribute is not significant for Ada.
-
-For C and C++, each string in the list denotes the name of a file that
-contains source code, but whose suffix is not necessarily the
-@code{Body_Suffix} for the language.
-@end table
-
-The following attributes of package @code{Naming} are obsolescent. They are
-kept as synonyms of other attributes for compatibility with previous versions
-of the Project Manager.
-
-@table @code
-@item Specification_Suffix
-This is a synonym of @code{Spec_Suffix}.
-
-@item Implementation_Suffix
-This is a synonym of @code{Body_Suffix}.
-
-@item Specification
-This is a synonym of @code{Spec}.
-
-@item Implementation
-This is a synonym of @code{Body}.
-@end table
-
-@subsection package Compiler
-
-@noindent
-The attributes of the @code{Compiler} package specify the compilation options
-to be used by the underlying compiler.
-
-@table @code
-@item Default_Switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies the compilation options to be used when compiling a component
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies the
-compilation options to be used when compiling the named file. If a file
-is not specified in the Switches attribute, it is compiled with the
-options specified by Default_Switches of its language, if defined.
-
-@item Local_Configuration_Pragmas.
-This is a simple attribute, whose
-value is a path name that designates a file containing configuration pragmas
-to be used for all invocations of the compiler for immediate sources of the
-project.
-@end table
-
-@subsection package Builder
-
-@noindent
-The attributes of package @code{Builder} specify the compilation, binding, and
-linking options to be used when building an executable for a project. The
-following attributes apply to package @code{Builder}:
-
-@table @code
-@item Default_Switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when building a main
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when building the named main file. If a main file
-is not specified in the Switches attribute, it is built with the
-options specified by Default_Switches of its language, if defined.
-
-@item Global_Configuration_Pragmas
-This is a simple attribute, whose
-value is a path name that designates a file that contains configuration pragmas
-to be used in every build of an executable. If both local and global
-configuration pragmas are specified, a compilation makes use of both sets.
-
-
-@item Executable
-This is an associative array attribute. Its domain is
-a set of main source file names. Its range is a simple string that specifies
-the executable file name to be used when linking the specified main source.
-If a main source is not specified in the Executable attribute, the executable
-file name is deducted from the main source file name.
-This attribute has no effect if its value is the empty string.
-
-@item Executable_Suffix
-This is a simple attribute whose value is the suffix to be added to
-the executables that don't have an attribute Executable specified.
-@end table
-
-@subsection package Gnatls
-
-@noindent
-The attributes of package @code{Gnatls} specify the tool options to be used
-when invoking the library browser @command{gnatls}.
-The following attributes apply to package @code{Gnatls}:
-
-@table @code
-@item Switches
-This is a single attribute with a string list value. Each nonempty string
-in the list is an option when invoking @code{gnatls}.
-@end table
-
-@subsection package Binder
-
-@noindent
-The attributes of package @code{Binder} specify the options to be used
-when invoking the binder in the construction of an executable.
-The following attributes apply to package @code{Binder}:
-
-@table @code
-@item Default_Switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when binding a main
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when binding the named main file. If a main file
-is not specified in the Switches attribute, it is bound with the
-options specified by Default_Switches of its language, if defined.
-@end table
-
-@subsection package Linker
-
-@noindent
-The attributes of package @code{Linker} specify the options to be used when
-invoking the linker in the construction of an executable.
-The following attributes apply to package @code{Linker}:
-
-@table @code
-@item Default_Switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when linking a main
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when linking the named main file. If a main file
-is not specified in the Switches attribute, it is linked with the
-options specified by Default_Switches of its language, if defined.
-
-@item Linker_Options
-This is a string list attribute. Its value specifies additional options that
-be given to the linker when linking an executable. This attribute is not
-used in the main project, only in projects imported directly or indirectly.
-
-@end table
-
-@subsection package Cross_Reference
-
-@noindent
-The attributes of package @code{Cross_Reference} specify the tool options
-to be used
-when invoking the library tool @command{gnatxref}.
-The following attributes apply to package @code{Cross_Reference}:
-
-@table @code
-@item Default_Switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when calling @command{gnatxref} on a source
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when calling @command{gnatxref} on the named main source.
-If a source is not specified in the Switches attribute, @command{gnatxref} will
-be called with the options specified by Default_Switches of its language,
-if defined.
-@end table
-
-@subsection package Finder
-
-@noindent
-The attributes of package @code{Finder} specify the tool options to be used
-when invoking the search tool @command{gnatfind}.
-The following attributes apply to package @code{Finder}:
-
-@table @code
-@item Default_Switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when calling @command{gnatfind} on a source
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when calling @command{gnatfind} on the named main source.
-If a source is not specified in the Switches attribute, @command{gnatfind} will
-be called with the options specified by Default_Switches of its language,
-if defined.
-@end table
-
-@subsection package Pretty_Printer
-
-@noindent
-The attributes of package @code{Pretty_Printer}
-specify the tool options to be used
-when invoking the formatting tool @command{gnatpp}.
-The following attributes apply to package @code{Pretty_Printer}:
-
-@table @code
-@item Default_switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when calling @command{gnatpp} on a source
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when calling @command{gnatpp} on the named main source.
-If a source is not specified in the Switches attribute, @command{gnatpp} will
-be called with the options specified by Default_Switches of its language,
-if defined.
-@end table
-
-@subsection package gnatstub
-
-@noindent
-The attributes of package @code{gnatstub}
-specify the tool options to be used
-when invoking the tool @command{gnatstub}.
-The following attributes apply to package @code{gnatstub}:
-
-@table @code
-@item Default_switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when calling @command{gnatstub} on a source
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when calling @command{gnatstub} on the named main source.
-If a source is not specified in the Switches attribute, @command{gnatpp} will
-be called with the options specified by Default_Switches of its language,
-if defined.
-@end table
-
-@subsection package Eliminate
-
-@noindent
-The attributes of package @code{Eliminate}
-specify the tool options to be used
-when invoking the tool @command{gnatelim}.
-The following attributes apply to package @code{Eliminate}:
-
-@table @code
-@item Default_switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when calling @command{gnatelim} on a source
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when calling @command{gnatelim} on the named main source.
-If a source is not specified in the Switches attribute, @command{gnatelim} will
-be called with the options specified by Default_Switches of its language,
-if defined.
-@end table
-
-@subsection package Metrics
-
-@noindent
-The attributes of package @code{Metrics}
-specify the tool options to be used
-when invoking the tool @command{gnatmetric}.
-The following attributes apply to package @code{Metrics}:
-
-@table @code
-@item Default_switches
-This is an associative array attribute. Its
-domain is a set of language names. Its range is a string list that
-specifies options to be used when calling @command{gnatmetric} on a source
-written in that language, for which no file-specific switches have been
-specified.
-
-@item Switches
-This is an associative array attribute. Its domain is
-a set of file names. Its range is a string list that specifies
-options to be used when calling @command{gnatmetric} on the named main source.
-If a source is not specified in the Switches attribute, @command{gnatmetric}
-will be called with the options specified by Default_Switches of its language,
-if defined.
-@end table
-
-@subsection package IDE
-
-@noindent
-The attributes of package @code{IDE} specify the options to be used when using
-an Integrated Development Environment such as @command{GPS}.
-
-@table @code
-@item Remote_Host
-This is a simple attribute. Its value is a string that designates the remote
-host in a cross-compilation environment, to be used for remote compilation and
-debugging. This field should not be specified when running on the local
-machine.
-
-@item Program_Host
-This is a simple attribute. Its value is a string that specifies the
-name of IP address of the embedded target in a cross-compilation environment,
-on which the program should execute.
-
-@item Communication_Protocol
-This is a simple string attribute. Its value is the name of the protocol
-to use to communicate with the target in a cross-compilation environment,
-e.g.@: @code{"wtx"} or @code{"vxworks"}.
-
-@item Compiler_Command
-This is an associative array attribute, whose domain is a language name. Its
-value is string that denotes the command to be used to invoke the compiler.
-The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
-gnatmake, in particular in the handling of switches.
-
-@item Debugger_Command
-This is simple attribute, Its value is a string that specifies the name of
-the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
-
-@item Default_Switches
-This is an associative array attribute. Its indexes are the name of the
-external tools that the GNAT Programming System (GPS) is supporting. Its
-value is a list of switches to use when invoking that tool.
-
-@item Gnatlist
-This is a simple attribute. Its value is a string that specifies the name
-of the @command{gnatls} utility to be used to retrieve information about the
-predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
-
-@item VCS_Kind
-This is a simple attribute. Its value is a string used to specify the
-Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
-ClearCase or Perforce.
-
-@item VCS_File_Check
-This is a simple attribute. Its value is a string that specifies the
-command used by the VCS to check the validity of a file, either
-when the user explicitly asks for a check, or as a sanity check before
-doing the check-in.
-
-@item VCS_Log_Check
-This is a simple attribute. Its value is a string that specifies
-the command used by the VCS to check the validity of a log file.
-
-@item VCS_Repository_Root
-The VCS repository root path. This is used to create tags or branches
-of the repository. For subversion the value should be the @code{URL}
-as specified to check-out the working copy of the repository.
-
-@item VCS_Patch_Root
-The local root directory to use for building patch file. All patch chunks
-will be relative to this path. The root project directory is used if
-this value is not defined.
-
-@end table
-
-@node Package Renamings
-@section Package Renamings
-
-@noindent
-A package can be defined by a renaming declaration. The new package renames
-a package declared in a different project file, and has the same attributes
-as the package it renames.
-Syntax:
-@smallexample
-package_renaming ::==
- @b{package} package_identifier @b{renames}
- <project_>simple_name.package_identifier ;
-@end smallexample
-
-@noindent
-The package_identifier of the renamed package must be the same as the
-package_identifier. The project whose name is the prefix of the renamed
-package must contain a package declaration with this name. This project
-must appear in the context_clause of the enclosing project declaration,
-or be the parent project of the enclosing child project.
-
-@node Projects
-@section Projects
-
-@noindent
-A project file specifies a set of rules for constructing a software system.
-A project file can be self-contained, or depend on other project files.
-Dependencies are expressed through a context clause that names other projects.
-
-Syntax:
-
-@smallexample
-project ::=
- context_clause project_declaration
-
-project_declaration ::=
- simple_project_declaration | project_extension
-
-simple_project_declaration ::=
- @b{project} <project_>simple_name @b{is}
- @{declarative_item@}
- @b{end} <project_>simple_name;
-
-context_clause ::=
- @{with_clause@}
-
-with_clause ::=
- [@b{limited}] @b{with} path_name @{ , path_name @} ;
-
-path_name ::=
- string_literal
-@end smallexample
-
-@noindent
-A path name denotes a project file. A path name can be absolute or relative.
-An absolute path name includes a sequence of directories, in the syntax of
-the host operating system, that identifies uniquely the project file in the
-file system. A relative path name identifies the project file, relative
-to the directory that contains the current project, or relative to a
-directory listed in the environment variable ADA_PROJECT_PATH.
-Path names are case sensitive if file names in the host operating system
-are case sensitive.
-
-The syntax of the environment variable ADA_PROJECT_PATH is a list of
-directory names separated by colons (semicolons on Windows).
-
-A given project name can appear only once in a context_clause.
-
-It is illegal for a project imported by a context clause to refer, directly
-or indirectly, to the project in which this context clause appears (the
-dependency graph cannot contain cycles), except when one of the with_clause
-in the cycle is a @code{limited with}.
-
-@node Project Extensions
-@section Project Extensions
-
-@noindent
-A project extension introduces a new project, which inherits the declarations
-of another project.
-Syntax:
-@smallexample
-
-project_extension ::=
- @b{project} <project_>simple_name @b{extends} path_name @b{is}
- @{declarative_item@}
- @b{end} <project_>simple_name;
-@end smallexample
-
-@noindent
-The project extension declares a child project. The child project inherits
-all the declarations and all the files of the parent project, These inherited
-declaration can be overridden in the child project, by means of suitable
-declarations.
-
-@node Project File Elaboration
-@section Project File Elaboration
-
-@noindent
-A project file is processed as part of the invocation of a gnat tool that
-uses the project option. Elaboration of the process file consists in the
-sequential elaboration of all its declarations. The computed values of
-attributes and variables in the project are then used to establish the
-environment in which the gnat tool will execute.
-
-@node Obsolescent Features
-@chapter Obsolescent Features
-
-@noindent
-This chapter describes features that are provided by GNAT, but are
-considered obsolescent since there are preferred ways of achieving
-the same effect. These features are provided solely for historical
-compatibility purposes.
-
-@menu
-* pragma No_Run_Time::
-* pragma Ravenscar::
-* pragma Restricted_Run_Time::
-@end menu
-
-@node pragma No_Run_Time
-@section pragma No_Run_Time
-
-The pragma @code{No_Run_Time} is used to achieve an affect similar
-to the use of the "Zero Foot Print" configurable run time, but without
-requiring a specially configured run time. The result of using this
-pragma, which must be used for all units in a partition, is to restrict
-the use of any language features requiring run-time support code. The
-preferred usage is to use an appropriately configured run-time that
-includes just those features that are to be made accessible.
-
-@node pragma Ravenscar
-@section pragma Ravenscar
-
-The pragma @code{Ravenscar} has exactly the same effect as pragma
-@code{Profile (Ravenscar)}. The latter usage is preferred since it
-is part of the new Ada 2005 standard.
-
-@node pragma Restricted_Run_Time
-@section pragma Restricted_Run_Time
-
-The pragma @code{Restricted_Run_Time} has exactly the same effect as
-pragma @code{Profile (Restricted)}. The latter usage is
-preferred since the Ada 2005 pragma @code{Profile} is intended for
-this kind of implementation dependent addition.
-
-@include fdl.texi
-@c GNU Free Documentation License
-
-@node Index,,GNU Free Documentation License, Top
-@unnumbered Index
-
-@printindex cp
-
-@contents
-
-@bye