--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename gnat_rm.info
+@documentencoding UTF-8
+@ifinfo
+@*Generated by Sphinx 5.2.3.@*
+@end ifinfo
+@settitle GNAT Reference Manual
+@defindex ge
+@paragraphindent 0
+@exampleindent 4
+@finalout
+@dircategory GNU Ada Tools
+@direntry
+* gnat_rm: (gnat_rm.info). gnat_rm
+@end direntry
+
+@c %**end of header
+
+@copying
+@quotation
+GNAT Reference Manual , Oct 27, 2022
+
+AdaCore
+
+Copyright @copyright{} 2008-2022, Free Software Foundation
+@end quotation
+
+@end copying
+
+@titlepage
+@title GNAT Reference Manual
+@insertcopying
+@end titlepage
+@contents
+
+@c %** start of user preamble
+
+@c %** end of user preamble
+
+@ifnottex
+@node Top
+@top GNAT Reference Manual
+@insertcopying
+@end ifnottex
+
+@c %**start of body
+@anchor{gnat_rm doc}@anchor{0}
+`GNAT, The GNU Ada Development Environment'
+
+
+@include gcc-common.texi
+GCC version @value{version-GCC}@*
+AdaCore
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 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 @ref{1,,GNU Free Documentation License}.
+
+@menu
+* About This Guide::
+* Implementation Defined Pragmas::
+* Implementation Defined Aspects::
+* Implementation Defined Attributes::
+* Standard and Implementation Defined Restrictions::
+* 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::
+* Implementation of Ada 2012 Features::
+* Security Hardening Features::
+* Obsolescent Features::
+* Compatibility and Porting Guide::
+* GNU Free Documentation License::
+* Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+About This Guide
+
+* What This Reference Manual Contains::
+* Conventions::
+* Related Information::
+
+Implementation Defined Pragmas
+
+* Pragma Abort_Defer::
+* Pragma Abstract_State::
+* Pragma Ada_83::
+* Pragma Ada_95::
+* Pragma Ada_05::
+* Pragma Ada_2005::
+* Pragma Ada_12::
+* Pragma Ada_2012::
+* Pragma Ada_2022::
+* Pragma Aggregate_Individually_Assign::
+* Pragma Allow_Integer_Address::
+* Pragma Annotate::
+* Pragma Assert::
+* Pragma Assert_And_Cut::
+* Pragma Assertion_Policy::
+* Pragma Assume::
+* Pragma Assume_No_Invalid_Values::
+* Pragma Async_Readers::
+* Pragma Async_Writers::
+* Pragma Attribute_Definition::
+* Pragma C_Pass_By_Copy::
+* Pragma Check::
+* Pragma Check_Float_Overflow::
+* 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 Constant_After_Elaboration::
+* Pragma Contract_Cases::
+* Pragma Convention_Identifier::
+* Pragma CPP_Class::
+* Pragma CPP_Constructor::
+* Pragma CPP_Virtual::
+* Pragma CPP_Vtable::
+* Pragma CPU::
+* Pragma Deadline_Floor::
+* Pragma Default_Initial_Condition::
+* Pragma Debug::
+* Pragma Debug_Policy::
+* Pragma Default_Scalar_Storage_Order::
+* Pragma Default_Storage_Pool::
+* Pragma Depends::
+* Pragma Detect_Blocking::
+* Pragma Disable_Atomic_Synchronization::
+* Pragma Dispatching_Domain::
+* Pragma Effective_Reads::
+* Pragma Effective_Writes::
+* Pragma Elaboration_Checks::
+* Pragma Eliminate::
+* Pragma Enable_Atomic_Synchronization::
+* Pragma Export_Function::
+* Pragma Export_Object::
+* Pragma Export_Procedure::
+* Pragma Export_Valued_Procedure::
+* Pragma Extend_System::
+* Pragma Extensions_Allowed::
+* Pragma Extensions_Visible::
+* Pragma External::
+* Pragma External_Name_Casing::
+* Pragma Fast_Math::
+* Pragma Favor_Top_Level::
+* Pragma Finalize_Storage_Only::
+* Pragma Float_Representation::
+* Pragma Ghost::
+* Pragma Global::
+* Pragma Ident::
+* Pragma Ignore_Pragma::
+* Pragma Implementation_Defined::
+* Pragma Implemented::
+* Pragma Implicit_Packing::
+* Pragma Import_Function::
+* Pragma Import_Object::
+* Pragma Import_Procedure::
+* Pragma Import_Valued_Procedure::
+* Pragma Independent::
+* Pragma Independent_Components::
+* Pragma Initial_Condition::
+* Pragma Initialize_Scalars::
+* Pragma Initializes::
+* Pragma Inline_Always::
+* Pragma Inline_Generic::
+* Pragma Interface::
+* Pragma Interface_Name::
+* Pragma Interrupt_Handler::
+* Pragma Interrupt_State::
+* Pragma Invariant::
+* Pragma Keep_Names::
+* Pragma License::
+* Pragma Link_With::
+* Pragma Linker_Alias::
+* Pragma Linker_Constructor::
+* Pragma Linker_Destructor::
+* Pragma Linker_Section::
+* Pragma Lock_Free::
+* Pragma Loop_Invariant::
+* Pragma Loop_Optimize::
+* Pragma Loop_Variant::
+* Pragma Machine_Attribute::
+* Pragma Main::
+* Pragma Main_Storage::
+* Pragma Max_Queue_Length::
+* Pragma No_Body::
+* Pragma No_Caching::
+* Pragma No_Component_Reordering::
+* Pragma No_Elaboration_Code_All::
+* Pragma No_Heap_Finalization::
+* Pragma No_Inline::
+* Pragma No_Return::
+* Pragma No_Strict_Aliasing::
+* Pragma No_Tagged_Streams::
+* Pragma Normalize_Scalars::
+* Pragma Obsolescent::
+* Pragma Optimize_Alignment::
+* Pragma Ordered::
+* Pragma Overflow_Mode::
+* Pragma Overriding_Renamings::
+* Pragma Partition_Elaboration_Policy::
+* Pragma Part_Of::
+* Pragma Passive::
+* Pragma Persistent_BSS::
+* Pragma Post::
+* Pragma Postcondition::
+* Pragma Post_Class::
+* Pragma Pre::
+* Pragma Precondition::
+* Pragma Predicate::
+* Pragma Predicate_Failure::
+* Pragma Preelaborable_Initialization::
+* Pragma Prefix_Exception_Messages::
+* Pragma Pre_Class::
+* Pragma Priority_Specific_Dispatching::
+* Pragma Profile::
+* Pragma Profile_Warnings::
+* Pragma Propagate_Exceptions::
+* Pragma Provide_Shift_Operators::
+* Pragma Psect_Object::
+* Pragma Pure_Function::
+* Pragma Rational::
+* Pragma Ravenscar::
+* Pragma Refined_Depends::
+* Pragma Refined_Global::
+* Pragma Refined_Post::
+* Pragma Refined_State::
+* Pragma Relative_Deadline::
+* Pragma Remote_Access_Type::
+* Pragma Rename_Pragma::
+* Pragma Restricted_Run_Time::
+* Pragma Restriction_Warnings::
+* Pragma Reviewable::
+* Pragma Secondary_Stack_Size::
+* Pragma Share_Generic::
+* Pragma Shared::
+* Pragma Short_Circuit_And_Or::
+* Pragma Short_Descriptors::
+* Pragma Simple_Storage_Pool_Type::
+* Pragma Source_File_Name::
+* Pragma Source_File_Name_Project::
+* Pragma Source_Reference::
+* Pragma SPARK_Mode::
+* Pragma Static_Elaboration_Desired::
+* Pragma Stream_Convert::
+* Pragma Style_Checks::
+* Pragma Subtitle::
+* Pragma Suppress::
+* Pragma Suppress_All::
+* Pragma Suppress_Debug_Info::
+* Pragma Suppress_Exception_Locations::
+* Pragma Suppress_Initialization::
+* Pragma Task_Name::
+* Pragma Task_Storage::
+* Pragma Test_Case::
+* Pragma Thread_Local_Storage::
+* Pragma Time_Slice::
+* Pragma Title::
+* Pragma Type_Invariant::
+* Pragma Type_Invariant_Class::
+* Pragma Unchecked_Union::
+* Pragma Unevaluated_Use_Of_Old::
+* Pragma Unimplemented_Unit::
+* Pragma Universal_Aliasing::
+* Pragma Unmodified::
+* Pragma Unreferenced::
+* Pragma Unreferenced_Objects::
+* Pragma Unreserve_All_Interrupts::
+* Pragma Unsuppress::
+* Pragma Use_VADS_Size::
+* Pragma Unused::
+* Pragma Validity_Checks::
+* Pragma Volatile::
+* Pragma Volatile_Full_Access::
+* Pragma Volatile_Function::
+* Pragma Warning_As_Error::
+* Pragma Warnings::
+* Pragma Weak_External::
+* Pragma Wide_Character_Encoding::
+
+Implementation Defined Aspects
+
+* Aspect Abstract_State::
+* Aspect Annotate::
+* Aspect Async_Readers::
+* Aspect Async_Writers::
+* Aspect Constant_After_Elaboration::
+* Aspect Contract_Cases::
+* Aspect Depends::
+* Aspect Default_Initial_Condition::
+* Aspect Dimension::
+* Aspect Dimension_System::
+* Aspect Disable_Controlled::
+* Aspect Effective_Reads::
+* Aspect Effective_Writes::
+* Aspect Extensions_Visible::
+* Aspect Favor_Top_Level::
+* Aspect Ghost::
+* Aspect Global::
+* Aspect Initial_Condition::
+* Aspect Initializes::
+* Aspect Inline_Always::
+* Aspect Invariant::
+* Aspect Invariant’Class::
+* Aspect Iterable::
+* Aspect Linker_Section::
+* Aspect Lock_Free::
+* Aspect Max_Queue_Length::
+* Aspect No_Caching::
+* Aspect No_Elaboration_Code_All::
+* Aspect No_Inline::
+* Aspect No_Tagged_Streams::
+* Aspect No_Task_Parts::
+* Aspect Object_Size::
+* Aspect Obsolescent::
+* Aspect Part_Of::
+* Aspect Persistent_BSS::
+* Aspect Predicate::
+* Aspect Pure_Function::
+* Aspect Refined_Depends::
+* Aspect Refined_Global::
+* Aspect Refined_Post::
+* Aspect Refined_State::
+* Aspect Relaxed_Initialization::
+* Aspect Remote_Access_Type::
+* Aspect Secondary_Stack_Size::
+* Aspect Scalar_Storage_Order::
+* Aspect Shared::
+* Aspect Simple_Storage_Pool::
+* Aspect Simple_Storage_Pool_Type::
+* Aspect SPARK_Mode::
+* Aspect Suppress_Debug_Info::
+* Aspect Suppress_Initialization::
+* Aspect Test_Case::
+* Aspect Thread_Local_Storage::
+* Aspect Universal_Aliasing::
+* Aspect Unmodified::
+* Aspect Unreferenced::
+* Aspect Unreferenced_Objects::
+* Aspect Value_Size::
+* Aspect Volatile_Full_Access::
+* Aspect Volatile_Function::
+* Aspect Warnings::
+
+Implementation Defined Attributes
+
+* Attribute Abort_Signal::
+* Attribute Address_Size::
+* Attribute Asm_Input::
+* Attribute Asm_Output::
+* Attribute Atomic_Always_Lock_Free::
+* Attribute Bit::
+* Attribute Bit_Position::
+* Attribute Code_Address::
+* Attribute Compiler_Version::
+* Attribute Constrained::
+* Attribute Default_Bit_Order::
+* Attribute Default_Scalar_Storage_Order::
+* Attribute Deref::
+* Attribute Descriptor_Size::
+* Attribute Elaborated::
+* Attribute Elab_Body::
+* Attribute Elab_Spec::
+* Attribute Elab_Subp_Body::
+* Attribute Emax::
+* Attribute Enabled::
+* Attribute Enum_Rep::
+* Attribute Enum_Val::
+* Attribute Epsilon::
+* Attribute Fast_Math::
+* Attribute Finalization_Size::
+* Attribute Fixed_Value::
+* Attribute From_Any::
+* Attribute Has_Access_Values::
+* Attribute Has_Discriminants::
+* Attribute Has_Tagged_Values::
+* Attribute Img::
+* Attribute Initialized::
+* Attribute Integer_Value::
+* Attribute Invalid_Value::
+* Attribute Iterable::
+* Attribute Large::
+* Attribute Library_Level::
+* Attribute Loop_Entry::
+* Attribute Machine_Size::
+* Attribute Mantissa::
+* Attribute Maximum_Alignment::
+* Attribute Max_Integer_Size::
+* Attribute Mechanism_Code::
+* Attribute Null_Parameter::
+* Attribute Object_Size::
+* Attribute Old::
+* Attribute Passed_By_Reference::
+* Attribute Pool_Address::
+* Attribute Range_Length::
+* Attribute Restriction_Set::
+* Attribute Result::
+* Attribute Safe_Emax::
+* Attribute Safe_Large::
+* Attribute Safe_Small::
+* Attribute Scalar_Storage_Order::
+* Attribute Simple_Storage_Pool::
+* Attribute Small::
+* Attribute Small_Denominator::
+* Attribute Small_Numerator::
+* Attribute Storage_Unit::
+* Attribute Stub_Type::
+* Attribute System_Allocator_Alignment::
+* Attribute Target_Name::
+* Attribute To_Address::
+* Attribute To_Any::
+* Attribute Type_Class::
+* Attribute Type_Key::
+* Attribute TypeCode::
+* Attribute Unconstrained_Array::
+* Attribute Universal_Literal_String::
+* Attribute Unrestricted_Access::
+* Attribute Update::
+* Attribute Valid_Value::
+* Attribute Valid_Scalars::
+* Attribute VADS_Size::
+* Attribute Value_Size::
+* Attribute Wchar_T_Size::
+* Attribute Word_Size::
+
+Standard and Implementation Defined Restrictions
+
+* Partition-Wide Restrictions::
+* Program Unit Level Restrictions::
+
+Partition-Wide Restrictions
+
+* Immediate_Reclamation::
+* Max_Asynchronous_Select_Nesting::
+* Max_Entry_Queue_Length::
+* Max_Protected_Entries::
+* Max_Select_Alternatives::
+* Max_Storage_At_Blocking::
+* Max_Task_Entries::
+* Max_Tasks::
+* No_Abort_Statements::
+* No_Access_Parameter_Allocators::
+* No_Access_Subprograms::
+* No_Allocators::
+* No_Anonymous_Allocators::
+* No_Asynchronous_Control::
+* No_Calendar::
+* No_Coextensions::
+* No_Default_Initialization::
+* No_Delay::
+* No_Dependence::
+* No_Direct_Boolean_Operators::
+* No_Dispatch::
+* No_Dispatching_Calls::
+* No_Dynamic_Attachment::
+* No_Dynamic_Priorities::
+* No_Entry_Calls_In_Elaboration_Code::
+* No_Enumeration_Maps::
+* No_Exception_Handlers::
+* No_Exception_Propagation::
+* No_Exception_Registration::
+* No_Exceptions::
+* No_Finalization::
+* No_Fixed_Point::
+* No_Floating_Point::
+* No_Implicit_Conditionals::
+* No_Implicit_Dynamic_Code::
+* No_Implicit_Heap_Allocations::
+* No_Implicit_Protected_Object_Allocations::
+* No_Implicit_Task_Allocations::
+* No_Initialize_Scalars::
+* No_IO::
+* No_Local_Allocators::
+* No_Local_Protected_Objects::
+* No_Local_Tagged_Types::
+* No_Local_Timing_Events::
+* No_Long_Long_Integers::
+* No_Multiple_Elaboration::
+* No_Nested_Finalization::
+* No_Protected_Type_Allocators::
+* No_Protected_Types::
+* No_Recursion::
+* No_Reentrancy::
+* No_Relative_Delay::
+* No_Requeue_Statements::
+* No_Secondary_Stack::
+* No_Select_Statements::
+* No_Specific_Termination_Handlers::
+* No_Specification_of_Aspect::
+* No_Standard_Allocators_After_Elaboration::
+* No_Standard_Storage_Pools::
+* No_Stream_Optimizations::
+* No_Streams::
+* No_Tagged_Type_Registration::
+* No_Task_Allocators::
+* No_Task_At_Interrupt_Priority::
+* No_Task_Attributes_Package::
+* No_Task_Hierarchy::
+* No_Task_Termination::
+* No_Tasking::
+* No_Terminate_Alternatives::
+* No_Unchecked_Access::
+* No_Unchecked_Conversion::
+* No_Unchecked_Deallocation::
+* No_Use_Of_Entity::
+* Pure_Barriers::
+* Simple_Barriers::
+* Static_Priorities::
+* Static_Storage_Size::
+
+Program Unit Level Restrictions
+
+* No_Elaboration_Code::
+* No_Dynamic_Accessibility_Checks::
+* No_Dynamic_Sized_Objects::
+* No_Entry_Queue::
+* No_Implementation_Aspect_Specifications::
+* No_Implementation_Attributes::
+* No_Implementation_Identifiers::
+* No_Implementation_Pragmas::
+* No_Implementation_Restrictions::
+* No_Implementation_Units::
+* No_Implicit_Aliasing::
+* No_Implicit_Loops::
+* No_Obsolescent_Features::
+* No_Wide_Characters::
+* Static_Dispatch_Tables::
+* SPARK_05::
+
+Implementation Advice
+
+* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection.
+* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units.
+* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors.
+* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas.
+* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas.
+* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets.
+* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types.
+* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types.
+* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values.
+* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types.
+* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays.
+* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small.
+* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation.
+* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information.
+* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks.
+* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses.
+* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types.
+* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses.
+* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses.
+* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses.
+* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses.
+* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses.
+* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses.
+* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses.
+* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes.
+* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering.
+* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private.
+* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations.
+* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion.
+* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage.
+* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation.
+* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes.
+* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types.
+* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling.
+* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling.
+* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation.
+* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate.
+* RM A.18; Containers: RM A 18 Containers.
+* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export.
+* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces.
+* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C.
+* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL.
+* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran.
+* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations.
+* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations.
+* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support.
+* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers.
+* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts.
+* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements.
+* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names.
+* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes.
+* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies.
+* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies.
+* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort.
+* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions.
+* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time.
+* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem.
+* RM F(7); COBOL Support: RM F 7 COBOL Support.
+* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support.
+* RM G; Numerics: RM G Numerics.
+* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types.
+* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions.
+* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements.
+* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy.
+* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy.
+
+Intrinsic Subprograms
+
+* Intrinsic Operators::
+* Compilation_ISO_Date::
+* Compilation_Date::
+* Compilation_Time::
+* Enclosing_Entity::
+* Exception_Information::
+* Exception_Message::
+* Exception_Name::
+* File::
+* Line::
+* Shifts and Rotates::
+* Source_Location::
+
+Representation Clauses and Pragmas
+
+* 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::
+* Handling of Records with Holes::
+* Enumeration Clauses::
+* Address Clauses::
+* Use of Address Clauses for Memory-Mapped I/O::
+* Effect of Convention on Representation::
+* Conventions and Anonymous Access Types::
+* Determining the Representations chosen by GNAT::
+
+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::
+* Text Translation::
+* Shared Files::
+* Filenames encoding::
+* File content encoding::
+* Open Modes::
+* Operations on C Streams::
+* Interfacing to C Streams::
+
+Text_IO
+
+* Stream Pointer Positioning::
+* 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
+
+* Stream Pointer Positioning: Stream Pointer Positioning<2>.
+* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>.
+
+Wide_Wide_Text_IO
+
+* Stream Pointer Positioning: Stream Pointer Positioning<3>.
+* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>.
+
+The GNAT Library
+
+* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads.
+* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads.
+* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads.
+* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads.
+* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads.
+* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
+* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
+* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
+* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads.
+* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads.
+* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads.
+* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads.
+* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads.
+* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads.
+* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads.
+* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads.
+* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads.
+* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads.
+* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads.
+* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads.
+* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads.
+* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads.
+* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads.
+* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads.
+* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads.
+* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads.
+* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads.
+* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads.
+* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads.
+* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads.
+* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads.
+* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads.
+* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads.
+* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads.
+* GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads.
+* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads.
+* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads.
+* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads.
+* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads.
+* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads.
+* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads.
+* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads.
+* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads.
+* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads.
+* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads.
+* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads.
+* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads.
+* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads.
+* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads.
+* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads.
+* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads.
+* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads.
+* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads.
+* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads.
+* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads.
+* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads.
+* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads.
+* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads.
+* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads.
+* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads.
+* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads.
+* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads.
+* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads.
+* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads.
+* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads.
+* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads.
+* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads.
+* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads.
+* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads.
+* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads.
+* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads.
+* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads.
+* GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads.
+* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads.
+* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads.
+* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads.
+* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads.
+* GNAT.IO (g-io.ads): GNAT IO g-io ads.
+* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads.
+* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads.
+* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads.
+* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads.
+* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads.
+* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads.
+* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads.
+* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads.
+* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads.
+* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads.
+* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads.
+* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads.
+* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads.
+* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads.
+* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads.
+* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads.
+* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads.
+* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads.
+* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads.
+* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads.
+* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads.
+* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads.
+* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads.
+* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads.
+* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads.
+* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads.
+* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads.
+* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads.
+* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads.
+* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads.
+* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads.
+* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads.
+* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads.
+* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads.
+* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads.
+* GNAT.Strings (g-string.ads): GNAT Strings g-string ads.
+* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads.
+* GNAT.Table (g-table.ads): GNAT Table g-table ads.
+* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads.
+* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads.
+* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads.
+* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads.
+* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads.
+* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads.
+* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads.
+* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads.
+* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads.
+* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads.
+* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads.
+* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads.
+* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads.
+* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads.
+* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads.
+* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads.
+* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads.
+* System.Address_Image (s-addima.ads): System Address_Image s-addima ads.
+* System.Assertions (s-assert.ads): System Assertions s-assert ads.
+* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads.
+* System.Memory (s-memory.ads): System Memory s-memory ads.
+* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads.
+* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads.
+* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads.
+* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads.
+* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads.
+* System.Restrictions (s-restri.ads): System Restrictions s-restri ads.
+* System.Rident (s-rident.ads): System Rident s-rident ads.
+* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads.
+* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads.
+* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads.
+* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads.
+
+Interfacing to Other Languages
+
+* Interfacing to C::
+* Interfacing to C++::
+* Interfacing to COBOL::
+* Interfacing to Fortran::
+* Interfacing to non-GNAT Ada code::
+
+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::
+* Image Values For Nonscalar Types::
+* Strict Conformance to the Ada Reference Manual::
+
+GNAT Implementation of Tasking
+
+* Mapping Ada Tasks onto the Underlying Kernel Threads::
+* Ensuring Compliance with the Real-Time Annex::
+* Support for Locking Policies::
+
+Code Generation for Array Aggregates
+
+* Static constant aggregates with static bounds::
+* Constant aggregates with unconstrained nominal types::
+* Aggregates with static bounds::
+* Aggregates with nonstatic bounds::
+* Aggregates in assignment statements::
+
+Security Hardening Features
+
+* Register Scrubbing::
+* Stack Scrubbing::
+* Hardened Conditionals::
+* Hardened Booleans::
+* Control Flow Redundancy::
+
+Obsolescent Features
+
+* pragma No_Run_Time::
+* pragma Ravenscar::
+* pragma Restricted_Run_Time::
+* pragma Task_Info::
+* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads.
+
+Compatibility and Porting Guide
+
+* Writing Portable Fixed-Point Declarations::
+* Compatibility with Ada 83::
+* Compatibility between Ada 95 and Ada 2005::
+* Implementation-dependent characteristics::
+* Compatibility with Other Ada Systems::
+* Representation Clauses::
+* Compatibility with HP Ada 83::
+
+Compatibility with Ada 83
+
+* Legal Ada 83 programs that are illegal in Ada 95::
+* More deterministic semantics::
+* Changed semantics::
+* Other language compatibility issues::
+
+Implementation-dependent characteristics
+
+* Implementation-defined pragmas::
+* Implementation-defined attributes::
+* Libraries::
+* Elaboration order::
+* Target-specific aspects::
+
+@end detailmenu
+@end menu
+
+@node About This Guide,Implementation Defined Pragmas,Top,Top
+@anchor{gnat_rm/about_this_guide doc}@anchor{2}@anchor{gnat_rm/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_rm/about_this_guide gnat-reference-manual}@anchor{4}@anchor{gnat_rm/about_this_guide id1}@anchor{5}
+@chapter About This Guide
+
+
+
+This manual contains useful information in writing programs using the
+GNAT compiler. It includes information on implementation dependent
+characteristics of GNAT, including all the information required by
+Annex M of the Ada language standard.
+
+GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
+invoked in Ada 83 compatibility mode.
+By default, GNAT assumes Ada 2012,
+but you can override with a compiler switch
+to explicitly specify the language version.
+(Please refer to the `GNAT User’s Guide' for details on these switches.)
+Throughout this manual, references to ‘Ada’ without a year suffix
+apply to all the Ada 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.
+
+@geindex Implementation-dependent features
+
+@geindex 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.
+
+@menu
+* What This Reference Manual Contains::
+* Conventions::
+* Related Information::
+
+@end menu
+
+@node What This Reference Manual Contains,Conventions,,About This Guide
+@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6}
+@section What This Reference Manual Contains
+
+
+This reference manual contains the following chapters:
+
+
+@itemize *
+
+@item
+@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent
+pragmas, which can be used to extend and enhance the functionality of the
+compiler.
+
+@item
+@ref{8,,Implementation Defined Attributes}, lists GNAT
+implementation-dependent attributes, which can be used to extend and
+enhance the functionality of the compiler.
+
+@item
+@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT
+implementation-dependent restrictions, which can be used to extend and
+enhance the functionality of the compiler.
+
+@item
+@ref{a,,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{b,,Implementation Defined Characteristics}, provides a guide to
+minimizing implementation dependent features.
+
+@item
+@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms
+implemented by GNAT, and how they can be imported into user
+application programs.
+
+@item
+@ref{d,,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{e,,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{f,,The Implementation of Standard I/O}, details how the GNAT
+implementation of the input-output facilities.
+
+@item
+@ref{10,,The GNAT Library}, is a catalog of packages that complement
+the Ada predefined library.
+
+@item
+@ref{11,,Interfacing to Other Languages}, describes how programs
+written in Ada using GNAT can be interfaced to other programming
+languages.
+
+@item
+@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all
+of the specialized needs annexes.
+
+@item
+@ref{13,,Implementation of Specific Ada Features}, discusses issues related
+to GNAT’s implementation of machine code insertions, tasking, and several
+other features.
+
+@item
+@ref{14,,Implementation of Ada 2012 Features}, describes the status of the
+GNAT implementation of the Ada 2012 language standard.
+
+@item
+@ref{15,,Security Hardening Features} documents GNAT extensions aimed
+at security hardening.
+
+@item
+@ref{16,,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.
+
+@item
+@ref{17,,Compatibility and Porting Guide} presents some guidelines for
+developing portable Ada code, describes the compatibility issues that
+may arise between GNAT and other Ada compilation systems (including those
+for Ada 83), and shows how GNAT can expedite porting applications
+developed in other Ada environments.
+
+@item
+@ref{1,,GNU Free Documentation License} contains the license for this document.
+@end itemize
+
+@geindex Ada 95 Language Reference Manual
+
+@geindex Ada 2005 Language Reference Manual
+
+This reference manual assumes a basic familiarity with the Ada 95 language, as
+described in the
+@cite{International Standard ANSI/ISO/IEC-8652:1995}.
+It does not require knowledge of the new features introduced by Ada 2005 or
+Ada 2012.
+All three reference manuals are included in the GNAT documentation
+package.
+
+@node Conventions,Related Information,What This Reference Manual Contains,About This Guide
+@anchor{gnat_rm/about_this_guide conventions}@anchor{18}
+@section Conventions
+
+
+@geindex Conventions
+@geindex typographical
+
+@geindex Typographical conventions
+
+Following are examples of the typographical and graphic conventions used
+in this guide:
+
+
+@itemize *
+
+@item
+@code{Functions}, @code{utility program names}, @code{standard names},
+and @code{classes}.
+
+@item
+@code{Option flags}
+
+@item
+@code{File names}
+
+@item
+@code{Variables}
+
+@item
+`Emphasis'
+
+@item
+[optional information or parameters]
+
+@item
+Examples are described by text
+
+@example
+and then shown this way.
+@end example
+
+@item
+Commands that are entered by the user are shown as preceded by a prompt string
+comprising the @code{$} character followed by a space.
+@end itemize
+
+@node Related Information,,Conventions,About This Guide
+@anchor{gnat_rm/about_this_guide related-information}@anchor{19}
+@section Related Information
+
+
+See the following documents for further information on GNAT:
+
+
+@itemize *
+
+@item
+@cite{GNAT User’s Guide for Native Platforms},
+which provides information on how to use the
+GNAT development environment.
+
+@item
+@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard.
+
+@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}, the Ada 2005 programming language standard.
+
+@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.
+
+@item
+@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard.
+
+@item
+@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms},
+which contains specific information on compatibility between GNAT and
+DEC Ada 83 systems.
+
+@item
+@cite{DEC Ada@comma{} 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,Implementation Defined Aspects,About This Guide,Top
+@anchor{gnat_rm/implementation_defined_pragmas doc}@anchor{1a}@anchor{gnat_rm/implementation_defined_pragmas id1}@anchor{1b}@anchor{gnat_rm/implementation_defined_pragmas implementation-defined-pragmas}@anchor{7}
+@chapter Implementation Defined Pragmas
+
+
+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 Abstract_State::
+* Pragma Ada_83::
+* Pragma Ada_95::
+* Pragma Ada_05::
+* Pragma Ada_2005::
+* Pragma Ada_12::
+* Pragma Ada_2012::
+* Pragma Ada_2022::
+* Pragma Aggregate_Individually_Assign::
+* Pragma Allow_Integer_Address::
+* Pragma Annotate::
+* Pragma Assert::
+* Pragma Assert_And_Cut::
+* Pragma Assertion_Policy::
+* Pragma Assume::
+* Pragma Assume_No_Invalid_Values::
+* Pragma Async_Readers::
+* Pragma Async_Writers::
+* Pragma Attribute_Definition::
+* Pragma C_Pass_By_Copy::
+* Pragma Check::
+* Pragma Check_Float_Overflow::
+* 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 Constant_After_Elaboration::
+* Pragma Contract_Cases::
+* Pragma Convention_Identifier::
+* Pragma CPP_Class::
+* Pragma CPP_Constructor::
+* Pragma CPP_Virtual::
+* Pragma CPP_Vtable::
+* Pragma CPU::
+* Pragma Deadline_Floor::
+* Pragma Default_Initial_Condition::
+* Pragma Debug::
+* Pragma Debug_Policy::
+* Pragma Default_Scalar_Storage_Order::
+* Pragma Default_Storage_Pool::
+* Pragma Depends::
+* Pragma Detect_Blocking::
+* Pragma Disable_Atomic_Synchronization::
+* Pragma Dispatching_Domain::
+* Pragma Effective_Reads::
+* Pragma Effective_Writes::
+* Pragma Elaboration_Checks::
+* Pragma Eliminate::
+* Pragma Enable_Atomic_Synchronization::
+* Pragma Export_Function::
+* Pragma Export_Object::
+* Pragma Export_Procedure::
+* Pragma Export_Valued_Procedure::
+* Pragma Extend_System::
+* Pragma Extensions_Allowed::
+* Pragma Extensions_Visible::
+* Pragma External::
+* Pragma External_Name_Casing::
+* Pragma Fast_Math::
+* Pragma Favor_Top_Level::
+* Pragma Finalize_Storage_Only::
+* Pragma Float_Representation::
+* Pragma Ghost::
+* Pragma Global::
+* Pragma Ident::
+* Pragma Ignore_Pragma::
+* Pragma Implementation_Defined::
+* Pragma Implemented::
+* Pragma Implicit_Packing::
+* Pragma Import_Function::
+* Pragma Import_Object::
+* Pragma Import_Procedure::
+* Pragma Import_Valued_Procedure::
+* Pragma Independent::
+* Pragma Independent_Components::
+* Pragma Initial_Condition::
+* Pragma Initialize_Scalars::
+* Pragma Initializes::
+* Pragma Inline_Always::
+* Pragma Inline_Generic::
+* Pragma Interface::
+* Pragma Interface_Name::
+* Pragma Interrupt_Handler::
+* Pragma Interrupt_State::
+* Pragma Invariant::
+* Pragma Keep_Names::
+* Pragma License::
+* Pragma Link_With::
+* Pragma Linker_Alias::
+* Pragma Linker_Constructor::
+* Pragma Linker_Destructor::
+* Pragma Linker_Section::
+* Pragma Lock_Free::
+* Pragma Loop_Invariant::
+* Pragma Loop_Optimize::
+* Pragma Loop_Variant::
+* Pragma Machine_Attribute::
+* Pragma Main::
+* Pragma Main_Storage::
+* Pragma Max_Queue_Length::
+* Pragma No_Body::
+* Pragma No_Caching::
+* Pragma No_Component_Reordering::
+* Pragma No_Elaboration_Code_All::
+* Pragma No_Heap_Finalization::
+* Pragma No_Inline::
+* Pragma No_Return::
+* Pragma No_Strict_Aliasing::
+* Pragma No_Tagged_Streams::
+* Pragma Normalize_Scalars::
+* Pragma Obsolescent::
+* Pragma Optimize_Alignment::
+* Pragma Ordered::
+* Pragma Overflow_Mode::
+* Pragma Overriding_Renamings::
+* Pragma Partition_Elaboration_Policy::
+* Pragma Part_Of::
+* Pragma Passive::
+* Pragma Persistent_BSS::
+* Pragma Post::
+* Pragma Postcondition::
+* Pragma Post_Class::
+* Pragma Pre::
+* Pragma Precondition::
+* Pragma Predicate::
+* Pragma Predicate_Failure::
+* Pragma Preelaborable_Initialization::
+* Pragma Prefix_Exception_Messages::
+* Pragma Pre_Class::
+* Pragma Priority_Specific_Dispatching::
+* Pragma Profile::
+* Pragma Profile_Warnings::
+* Pragma Propagate_Exceptions::
+* Pragma Provide_Shift_Operators::
+* Pragma Psect_Object::
+* Pragma Pure_Function::
+* Pragma Rational::
+* Pragma Ravenscar::
+* Pragma Refined_Depends::
+* Pragma Refined_Global::
+* Pragma Refined_Post::
+* Pragma Refined_State::
+* Pragma Relative_Deadline::
+* Pragma Remote_Access_Type::
+* Pragma Rename_Pragma::
+* Pragma Restricted_Run_Time::
+* Pragma Restriction_Warnings::
+* Pragma Reviewable::
+* Pragma Secondary_Stack_Size::
+* Pragma Share_Generic::
+* Pragma Shared::
+* Pragma Short_Circuit_And_Or::
+* Pragma Short_Descriptors::
+* Pragma Simple_Storage_Pool_Type::
+* Pragma Source_File_Name::
+* Pragma Source_File_Name_Project::
+* Pragma Source_Reference::
+* Pragma SPARK_Mode::
+* Pragma Static_Elaboration_Desired::
+* Pragma Stream_Convert::
+* Pragma Style_Checks::
+* Pragma Subtitle::
+* Pragma Suppress::
+* Pragma Suppress_All::
+* Pragma Suppress_Debug_Info::
+* Pragma Suppress_Exception_Locations::
+* Pragma Suppress_Initialization::
+* Pragma Task_Name::
+* Pragma Task_Storage::
+* Pragma Test_Case::
+* Pragma Thread_Local_Storage::
+* Pragma Time_Slice::
+* Pragma Title::
+* Pragma Type_Invariant::
+* Pragma Type_Invariant_Class::
+* Pragma Unchecked_Union::
+* Pragma Unevaluated_Use_Of_Old::
+* Pragma Unimplemented_Unit::
+* Pragma Universal_Aliasing::
+* Pragma Unmodified::
+* Pragma Unreferenced::
+* Pragma Unreferenced_Objects::
+* Pragma Unreserve_All_Interrupts::
+* Pragma Unsuppress::
+* Pragma Use_VADS_Size::
+* Pragma Unused::
+* Pragma Validity_Checks::
+* Pragma Volatile::
+* Pragma Volatile_Full_Access::
+* Pragma Volatile_Function::
+* Pragma Warning_As_Error::
+* Pragma Warnings::
+* Pragma Weak_External::
+* Pragma Wide_Character_Encoding::
+
+@end menu
+
+@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c}
+@section Pragma Abort_Defer
+
+
+@geindex Deferring aborts
+
+Syntax:
+
+@example
+pragma Abort_Defer;
+@end example
+
+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). This can also be useful for adding a polling point in Ada code,
+where asynchronous abort of tasks is checked when leaving the statement
+sequence, and is lighter than, for example, using @code{delay 0.0;}, since with
+zero-cost exception handling, propagating exceptions (implicitly used to
+implement task abort) cannot be done reliably in an asynchronous way.
+
+An example of usage would be:
+
+@example
+-- Add a polling point to check for task aborts
+
+begin
+ pragma Abort_Defer;
+end;
+@end example
+
+@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e}
+@section Pragma Abstract_State
+
+
+Syntax:
+
+@example
+pragma Abstract_State (ABSTRACT_STATE_LIST);
+
+ABSTRACT_STATE_LIST ::=
+ null
+ | STATE_NAME_WITH_OPTIONS
+ | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} )
+
+STATE_NAME_WITH_OPTIONS ::=
+ STATE_NAME
+ | (STATE_NAME with OPTION_LIST)
+
+OPTION_LIST ::= OPTION @{, OPTION@}
+
+OPTION ::=
+ SIMPLE_OPTION
+ | NAME_VALUE_OPTION
+
+SIMPLE_OPTION ::= Ghost | Synchronous
+
+NAME_VALUE_OPTION ::=
+ Part_Of => ABSTRACT_STATE
+ | External [=> EXTERNAL_PROPERTY_LIST]
+
+EXTERNAL_PROPERTY_LIST ::=
+ EXTERNAL_PROPERTY
+ | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} )
+
+EXTERNAL_PROPERTY ::=
+ Async_Readers [=> static_boolean_EXPRESSION]
+ | Async_Writers [=> static_boolean_EXPRESSION]
+ | Effective_Reads [=> static_boolean_EXPRESSION]
+ | Effective_Writes [=> static_boolean_EXPRESSION]
+ others => static_boolean_EXPRESSION
+
+STATE_NAME ::= defining_identifier
+
+ABSTRACT_STATE ::= name
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in
+the SPARK 2014 Reference Manual, section 7.1.4.
+
+@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f}
+@section Pragma Ada_83
+
+
+Syntax:
+
+@example
+pragma Ada_83;
+@end example
+
+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,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20}
+@section Pragma Ada_95
+
+
+Syntax:
+
+@example
+pragma Ada_95;
+@end example
+
+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,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21}
+@section Pragma Ada_05
+
+
+Syntax:
+
+@example
+pragma Ada_05;
+pragma Ada_05 (local_NAME);
+@end example
+
+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 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.
+
+The one argument form (which is not a configuration pragma)
+is used for managing the transition from
+Ada 95 to Ada 2005 in the run-time library. If an entity is marked
+as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95
+mode will generate a warning. In addition, in Ada_83 or Ada_95
+mode, a preference rule is established which does not choose
+such an entity unless it is unambiguously specified. This avoids
+extra subprograms marked this way from generating ambiguities in
+otherwise legal pre-Ada_2005 programs. The one argument form is
+intended for exclusive use in the GNAT run-time library.
+
+@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22}
+@section Pragma Ada_2005
+
+
+Syntax:
+
+@example
+pragma Ada_2005;
+@end example
+
+This configuration pragma is a synonym for pragma Ada_05 and has the
+same syntax and effect.
+
+@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23}
+@section Pragma Ada_12
+
+
+Syntax:
+
+@example
+pragma Ada_12;
+pragma Ada_12 (local_NAME);
+@end example
+
+A configuration pragma that establishes Ada 2012 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 2012 features, but which is intended to be usable from
+Ada 83, Ada 95, or Ada 2005 programs.
+
+The one argument form, which is not a configuration pragma,
+is used for managing the transition from Ada
+2005 to Ada 2012 in the run-time library. If an entity is marked
+as Ada_2012 only, then referencing the entity in any pre-Ada_2012
+mode will generate a warning. In addition, in any pre-Ada_2012
+mode, a preference rule is established which does not choose
+such an entity unless it is unambiguously specified. This avoids
+extra subprograms marked this way from generating ambiguities in
+otherwise legal pre-Ada_2012 programs. The one argument form is
+intended for exclusive use in the GNAT run-time library.
+
+@node Pragma Ada_2012,Pragma Ada_2022,Pragma Ada_12,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24}
+@section Pragma Ada_2012
+
+
+Syntax:
+
+@example
+pragma Ada_2012;
+@end example
+
+This configuration pragma is a synonym for pragma Ada_12 and has the
+same syntax and effect.
+
+@node Pragma Ada_2022,Pragma Aggregate_Individually_Assign,Pragma Ada_2012,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2022}@anchor{25}
+@section Pragma Ada_2022
+
+
+Syntax:
+
+@example
+pragma Ada_2022;
+pragma Ada_2022 (local_NAME);
+@end example
+
+A configuration pragma that establishes Ada 2022 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 2022 features, but which is intended to be usable from
+Ada 83, Ada 95, Ada 2005 or Ada 2012 programs.
+
+The one argument form, which is not a configuration pragma,
+is used for managing the transition from Ada
+2012 to Ada 2022 in the run-time library. If an entity is marked
+as Ada_2022 only, then referencing the entity in any pre-Ada_2022
+mode will generate a warning. In addition, in any pre-Ada_2012
+mode, a preference rule is established which does not choose
+such an entity unless it is unambiguously specified. This avoids
+extra subprograms marked this way from generating ambiguities in
+otherwise legal pre-Ada_2022 programs. The one argument form is
+intended for exclusive use in the GNAT run-time library.
+
+@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2022,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{26}
+@section Pragma Aggregate_Individually_Assign
+
+
+Syntax:
+
+@example
+pragma Aggregate_Individually_Assign;
+@end example
+
+Where possible, GNAT will store the binary representation of a record aggregate
+in memory for space and performance reasons. This configuration pragma changes
+this behavior so that record aggregates are instead always converted into
+individual assignment statements.
+
+@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{27}
+@section Pragma Allow_Integer_Address
+
+
+Syntax:
+
+@example
+pragma Allow_Integer_Address;
+@end example
+
+In almost all versions of GNAT, @code{System.Address} is a private
+type in accordance with the implementation advice in the RM. This
+means that integer values,
+in particular integer literals, are not allowed as address values.
+If the configuration pragma
+@code{Allow_Integer_Address} is given, then integer expressions may
+be used anywhere a value of type @code{System.Address} is required.
+The effect is to introduce an implicit unchecked conversion from the
+integer value to type @code{System.Address}. The reverse case of using
+an address where an integer type is required is handled analogously.
+The following example compiles without errors:
+
+@example
+pragma Allow_Integer_Address;
+with System; use System;
+package AddrAsInt is
+ X : Integer;
+ Y : Integer;
+ for X'Address use 16#1240#;
+ for Y use at 16#3230#;
+ m : Address := 16#4000#;
+ n : constant Address := 4000;
+ p : constant Address := Address (X + Y);
+ v : Integer := y'Address;
+ w : constant Integer := Integer (Y'Address);
+ type R is new integer;
+ RR : R := 1000;
+ Z : Integer;
+ for Z'Address use RR;
+end AddrAsInt;
+@end example
+
+Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address}
+is not a private type. In implementations of @code{GNAT} where
+System.Address is a visible integer type,
+this pragma serves no purpose but is ignored
+rather than rejected to allow common sets of sources to be used
+in the two situations.
+
+@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{28}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29}
+@section Pragma Annotate
+
+
+Syntax:
+
+@example
+pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]);
+
+ARG ::= NAME | EXPRESSION
+@end example
+
+This pragma is used to annotate programs. IDENTIFIER identifies
+the type of annotation. GNAT verifies that it is an identifier, but does
+not otherwise analyze it. The second optional identifier is also left
+unanalyzed, and by convention is used to control the action of the tool to
+which the annotation is addressed. The remaining ARG arguments
+can be either string literals or more generally expressions.
+String literals (and concatenations of string literals) are assumed to be
+either of type
+@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String}
+depending on the character literals they contain.
+All other kinds of arguments are analyzed as expressions, and must be
+unambiguous. The last argument if present must have the identifier
+@code{Entity} and GNAT verifies that a local name is given.
+
+The analyzed pragma is retained in the tree, but not otherwise processed
+by any part of the GNAT compiler, except to generate corresponding note
+lines in the generated ALI file. For the format of these note lines, see
+the compiler source file lib-writ.ads. This pragma is intended for use by
+external tools, including ASIS. The use of pragma Annotate does not
+affect the compilation process in any way. This pragma may be used as
+a configuration pragma.
+
+@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2a}
+@section Pragma Assert
+
+
+Syntax:
+
+@example
+pragma Assert (
+ boolean_EXPRESSION
+ [, string_EXPRESSION]);
+@end example
+
+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:
+
+@example
+if assertions-enabled then
+ if not boolean_EXPRESSION then
+ System.Assertions.Raise_Assert_Failure
+ (string_EXPRESSION);
+ end if;
+end if;
+@end example
+
+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 @code{file}:@code{nnn},
+where @code{file} is the name of the source file containing the assert,
+and @code{nnn} is the line number of the assert.
+
+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.
+
+Assert checks can be either checked or ignored. By default they are ignored.
+They will be checked if either the command line switch `-gnata' is
+used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used
+to enable @code{Assert_Checks}.
+
+If assertions are ignored, 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 checked, 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.
+
+Note that the implementation defined policy @code{DISABLE}, given in a
+pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis.
+
+Note: this is a standard language-defined pragma in versions
+of Ada from 2005 on. In GNAT, it is implemented in all versions
+of Ada, and the DISABLE policy is an implementation-defined
+addition.
+
+@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2b}
+@section Pragma Assert_And_Cut
+
+
+Syntax:
+
+@example
+pragma Assert_And_Cut (
+ boolean_EXPRESSION
+ [, string_EXPRESSION]);
+@end example
+
+The effect of this pragma is identical to that of pragma @code{Assert},
+except that in an @code{Assertion_Policy} pragma, the identifier
+@code{Assert_And_Cut} is used to control whether it is ignored or checked
+(or disabled).
+
+The intention is that this be used within a subprogram when the
+given test expresion sums up all the work done so far in the
+subprogram, so that the rest of the subprogram can be verified
+(informally or formally) using only the entry preconditions,
+and the expression in this pragma. This allows dividing up
+a subprogram into sections for the purposes of testing or
+formal verification. The pragma also serves as useful
+documentation.
+
+@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2c}
+@section Pragma Assertion_Policy
+
+
+Syntax:
+
+@example
+pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE);
+
+pragma Assertion_Policy (
+ ASSERTION_KIND => POLICY_IDENTIFIER
+ @{, ASSERTION_KIND => POLICY_IDENTIFIER@});
+
+ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
+
+RM_ASSERTION_KIND ::= Assert |
+ Static_Predicate |
+ Dynamic_Predicate |
+ Pre |
+ Pre'Class |
+ Post |
+ Post'Class |
+ Type_Invariant |
+ Type_Invariant'Class |
+ Default_Initial_Condition
+
+ID_ASSERTION_KIND ::= Assertions |
+ Assert_And_Cut |
+ Assume |
+ Contract_Cases |
+ Debug |
+ Ghost |
+ Initial_Condition |
+ Invariant |
+ Invariant'Class |
+ Loop_Invariant |
+ Loop_Variant |
+ Postcondition |
+ Precondition |
+ Predicate |
+ Refined_Post |
+ Statement_Assertions |
+ Subprogram_Variant
+
+POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible
+@end example
+
+This is a standard Ada 2012 pragma that is available as an
+implementation-defined pragma in earlier versions of Ada.
+The assertion kinds @code{RM_ASSERTION_KIND} are those defined in
+the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND}
+are implementation defined additions recognized by the GNAT compiler.
+
+The pragma applies in both cases to pragmas and aspects with matching
+names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition}
+applies to both the @code{Precondition} pragma
+and the aspect @code{Precondition}. Note that the identifiers for
+pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not
+Pre_Class and Post_Class), since these pragmas are intended to be
+identical to the corresponding aspects.
+
+If the policy is @code{CHECK}, then assertions are enabled, i.e.
+the corresponding pragma or aspect is activated.
+If the policy is @code{IGNORE}, then assertions are ignored, i.e.
+the corresponding pragma or aspect is deactivated.
+This pragma overrides the effect of the `-gnata' switch on the
+command line.
+If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default,
+however, if the `-gnatp' switch is specified all assertions are ignored.
+
+The implementation defined policy @code{DISABLE} is like
+@code{IGNORE} except that it completely disables semantic
+checking of the corresponding pragma or aspect. This is
+useful when the pragma or aspect argument references subprograms
+in a with’ed package which is replaced by a dummy package
+for the final build.
+
+The implementation defined assertion kind @code{Assertions} applies to all
+assertion kinds. The form with no assertion kind given implies this
+choice, so it applies to all assertion kinds (RM defined, and
+implementation defined).
+
+The implementation defined assertion kind @code{Statement_Assertions}
+applies to @code{Assert}, @code{Assert_And_Cut},
+@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}.
+
+@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2d}
+@section Pragma Assume
+
+
+Syntax:
+
+@example
+pragma Assume (
+ boolean_EXPRESSION
+ [, string_EXPRESSION]);
+@end example
+
+The effect of this pragma is identical to that of pragma @code{Assert},
+except that in an @code{Assertion_Policy} pragma, the identifier
+@code{Assume} is used to control whether it is ignored or checked
+(or disabled).
+
+The intention is that this be used for assumptions about the
+external environment. So you cannot expect to verify formally
+or informally that the condition is met, this must be
+established by examining things outside the program itself.
+For example, we may have code that depends on the size of
+@code{Long_Long_Integer} being at least 64. So we could write:
+
+@example
+pragma Assume (Long_Long_Integer'Size >= 64);
+@end example
+
+This assumption cannot be proved from the program itself,
+but it acts as a useful run-time check that the assumption
+is met, and documents the need to ensure that it is met by
+reference to information outside the program.
+
+@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2e}
+@section Pragma Assume_No_Invalid_Values
+
+
+@geindex Invalid representations
+
+@geindex Invalid values
+
+Syntax:
+
+@example
+pragma Assume_No_Invalid_Values (On | Off);
+@end example
+
+This is a configuration pragma that controls the assumptions made by the
+compiler about the occurrence of invalid representations (invalid values)
+in the code.
+
+The default behavior (corresponding to an Off argument for this pragma), is
+to assume that values may in general be invalid unless the compiler can
+prove they are valid. Consider the following example:
+
+@example
+V1 : Integer range 1 .. 10;
+V2 : Integer range 11 .. 20;
+...
+for J in V2 .. V1 loop
+ ...
+end loop;
+@end example
+
+if V1 and V2 have valid values, then the loop is known at compile
+time not to execute since the lower bound must be greater than the
+upper bound. However in default mode, no such assumption is made,
+and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
+is given, the compiler will assume that any occurrence of a variable
+other than in an explicit @code{'Valid} test always has a valid
+value, and the loop above will be optimized away.
+
+The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
+you know your code is free of uninitialized variables and other
+possible sources of invalid representations, and may result in
+more efficient code. A program that accesses an invalid representation
+with this pragma in effect is erroneous, so no guarantees can be made
+about its behavior.
+
+It is peculiar though permissible to use this pragma in conjunction
+with validity checking (-gnatVa). In such cases, accessing invalid
+values will generally give an exception, though formally the program
+is erroneous so there are no guarantees that this will always be the
+case, and it is recommended that these two options not be used together.
+
+@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30}
+@section Pragma Async_Readers
+
+
+Syntax:
+
+@example
+pragma Async_Readers [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in
+the SPARK 2014 Reference Manual, section 7.1.2.
+
+@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{32}
+@section Pragma Async_Writers
+
+
+Syntax:
+
+@example
+pragma Async_Writers [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in
+the SPARK 2014 Reference Manual, section 7.1.2.
+
+@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{33}
+@section Pragma Attribute_Definition
+
+
+Syntax:
+
+@example
+pragma Attribute_Definition
+ ([Attribute =>] ATTRIBUTE_DESIGNATOR,
+ [Entity =>] LOCAL_NAME,
+ [Expression =>] EXPRESSION | NAME);
+@end example
+
+If @code{Attribute} is a known attribute name, this pragma is equivalent to
+the attribute definition clause:
+
+@example
+for Entity'Attribute use Expression;
+@end example
+
+If @code{Attribute} is not a recognized attribute name, the pragma is
+ignored, and a warning is emitted. This allows source
+code to be written that takes advantage of some new attribute, while remaining
+compilable with earlier compilers.
+
+@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{34}
+@section Pragma C_Pass_By_Copy
+
+
+@geindex Passing by copy
+
+Syntax:
+
+@example
+pragma C_Pass_By_Copy
+ ([Max_Size =>] static_integer_EXPRESSION);
+@end example
+
+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 *
+
+@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
+
+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,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{35}
+@section Pragma Check
+
+
+@geindex Assertions
+
+@geindex Named assertions
+
+Syntax:
+
+@example
+pragma Check (
+ [Name =>] CHECK_KIND,
+ [Check =>] Boolean_EXPRESSION
+ [, [Message =>] string_EXPRESSION] );
+
+CHECK_KIND ::= IDENTIFIER |
+ Pre'Class |
+ Post'Class |
+ Type_Invariant'Class |
+ Invariant'Class
+@end example
+
+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.
+
+Checks introduced by this pragma are normally deactivated by default. They can
+be activated either by the command line option `-gnata', which turns on
+all checks, or individually controlled using pragma @code{Check_Policy}.
+
+The identifiers @code{Assertions} and @code{Statement_Assertions} are not
+permitted as check kinds, since this would cause confusion with the use
+of these identifiers in @code{Assertion_Policy} and @code{Check_Policy}
+pragmas, where they are used to refer to sets of assertions.
+
+@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{36}
+@section Pragma Check_Float_Overflow
+
+
+@geindex Floating-point overflow
+
+Syntax:
+
+@example
+pragma Check_Float_Overflow;
+@end example
+
+In Ada, the predefined floating-point types (@code{Short_Float},
+@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are
+defined to be `unconstrained'. This means that even though each
+has a well-defined base range, an operation that delivers a result
+outside this base range is not required to raise an exception.
+This implementation permission accommodates the notion
+of infinities in IEEE floating-point, and corresponds to the
+efficient execution mode on most machines. GNAT will not raise
+overflow exceptions on these machines; instead it will generate
+infinities and NaN’s as defined in the IEEE standard.
+
+Generating infinities, although efficient, is not always desirable.
+Often the preferable approach is to check for overflow, even at the
+(perhaps considerable) expense of run-time performance.
+This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit
+range constraints – and indeed such a subtype
+can have the same base range as its base type. For example:
+
+@example
+subtype My_Float is Float range Float'Range;
+@end example
+
+Here @code{My_Float} has the same range as
+@code{Float} but is constrained, so operations on
+@code{My_Float} values will be checked for overflow
+against this range.
+
+This style will achieve the desired goal, but
+it is often more convenient to be able to simply use
+the standard predefined floating-point types as long
+as overflow checking could be guaranteed.
+The @code{Check_Float_Overflow}
+configuration pragma achieves this effect. If a unit is compiled
+subject to this configuration pragma, then all operations
+on predefined floating-point types including operations on
+base types of these floating-point types will be treated as
+though those types were constrained, and overflow checks
+will be generated. The @code{Constraint_Error}
+exception is raised if the result is out of range.
+
+This mode can also be set by use of the compiler
+switch `-gnateF'.
+
+@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{37}
+@section Pragma Check_Name
+
+
+@geindex Defining check names
+
+@geindex Check names
+@geindex defining
+
+Syntax:
+
+@example
+pragma Check_Name (check_name_IDENTIFIER);
+@end example
+
+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).
+
+Check names introduced by this pragma are subject to control by compiler
+switches (in particular -gnatp) in the usual manner.
+
+@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{38}
+@section Pragma Check_Policy
+
+
+@geindex Controlling assertions
+
+@geindex Assertions
+@geindex control
+
+@geindex Check pragma control
+
+@geindex Named assertions
+
+Syntax:
+
+@example
+pragma Check_Policy
+ ([Name =>] CHECK_KIND,
+ [Policy =>] POLICY_IDENTIFIER);
+
+pragma Check_Policy (
+ CHECK_KIND => POLICY_IDENTIFIER
+ @{, CHECK_KIND => POLICY_IDENTIFIER@});
+
+ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
+
+CHECK_KIND ::= IDENTIFIER |
+ Pre'Class |
+ Post'Class |
+ Type_Invariant'Class |
+ Invariant'Class
+
+The identifiers Name and Policy are not allowed as CHECK_KIND values. This
+avoids confusion between the two possible syntax forms for this pragma.
+
+POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE
+@end example
+
+This pragma is used to set the checking policy for assertions (specified
+by aspects or pragmas), the @code{Debug} pragma, or additional checks
+to be checked using the @code{Check} pragma. It may appear either as
+a configuration pragma, or within a declarative part of package. In the
+latter case, it applies from the point where it appears to the end of
+the declarative region (like pragma @code{Suppress}).
+
+The @code{Check_Policy} pragma is similar to the
+predefined @code{Assertion_Policy} pragma,
+and if the check kind corresponds to one of the assertion kinds that
+are allowed by @code{Assertion_Policy}, then the effect is identical.
+
+If the first argument is Debug, then the policy applies to Debug pragmas,
+disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or
+@code{IGNORE}, and allowing them to execute with normal semantics if
+the policy is @code{ON} or @code{CHECK}. In addition if the policy is
+@code{DISABLE}, then the procedure call in @code{Debug} pragmas will
+be totally ignored and not analyzed semantically.
+
+Finally the first argument may be some other identifier than the above
+possibilities, in which case it controls a set of named assertions
+that can be checked using pragma @code{Check}. For example, if the pragma:
+
+@example
+pragma Check_Policy (Critical_Error, OFF);
+@end example
+
+is given, then subsequent @code{Check} pragmas whose first argument is also
+@code{Critical_Error} will be disabled.
+
+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
+`-gnata' is given, which turns on all checks by default.
+
+The check policy settings @code{CHECK} and @code{IGNORE} are recognized
+as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for
+compatibility with the standard @code{Assertion_Policy} pragma. The check
+policy setting @code{DISABLE} causes the second argument of a corresponding
+@code{Check} pragma to be completely ignored and not analyzed.
+
+@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{39}
+@section Pragma Comment
+
+
+Syntax:
+
+@example
+pragma Comment (static_string_EXPRESSION);
+@end example
+
+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,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3a}
+@section Pragma Common_Object
+
+
+Syntax:
+
+@example
+pragma Common_Object (
+ [Internal =>] LOCAL_NAME
+ [, [External =>] EXTERNAL_SYMBOL]
+ [, [Size =>] EXTERNAL_SYMBOL] );
+
+EXTERNAL_SYMBOL ::=
+ IDENTIFIER
+| static_string_EXPRESSION
+@end example
+
+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 @code{LOCAL_NAME} is assigned to the area designated by
+the @code{External} argument.
+You may define a record to correspond to a series
+of fields. The @code{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,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3b}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c}
+@section Pragma Compile_Time_Error
+
+
+Syntax:
+
+@example
+pragma Compile_Time_Error
+ (boolean_EXPRESSION, static_string_EXPRESSION);
+@end example
+
+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 ensures that the value of an expression
+is known at compile time, and has the value False. 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 not 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,Pragma Complete_Representation,Pragma Compile_Time_Error,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d}
+@section Pragma Compile_Time_Warning
+
+
+Syntax:
+
+@example
+pragma Compile_Time_Warning
+ (boolean_EXPRESSION, static_string_EXPRESSION);
+@end example
+
+Same as pragma Compile_Time_Error, except a warning is issued instead
+of an error message. If switch `-gnatw_C' is used, a warning is only issued
+if the value of the expression is known to be True at compile time, not when
+the value of the expression is not known at compile time.
+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.
+
+In previous versions of the compiler, combining `-gnatwe' with
+Compile_Time_Warning resulted in a fatal error. Now the compiler always emits
+a warning. You can use @ref{3b,,Pragma Compile_Time_Error} to force the generation of
+an error.
+
+@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compile_Time_Warning,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e}
+@section Pragma Complete_Representation
+
+
+Syntax:
+
+@example
+pragma Complete_Representation;
+@end example
+
+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,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f}
+@section Pragma Complex_Representation
+
+
+Syntax:
+
+@example
+pragma Complex_Representation
+ ([Entity =>] LOCAL_NAME);
+@end example
+
+The @code{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,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40}
+@section Pragma Component_Alignment
+
+
+@geindex Alignments of components
+
+@geindex Pragma Component_Alignment
+
+Syntax:
+
+@example
+pragma Component_Alignment (
+ [Form =>] ALIGNMENT_CHOICE
+ [, [Name =>] type_LOCAL_NAME]);
+
+ALIGNMENT_CHOICE ::=
+ Component_Size
+| Component_Size_4
+| Storage_Unit
+| Default
+@end example
+
+Specifies the alignment of components in array or record types.
+The meaning of the @code{Form} argument is as follows:
+
+@quotation
+
+@geindex Component_Size (in pragma Component_Alignment)
+@end quotation
+
+
+@table @asis
+
+@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.
+
+@geindex Component_Size_4 (in pragma Component_Alignment)
+
+@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.
+
+@geindex Storage_Unit (in pragma Component_Alignment)
+
+@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}.
+
+@geindex Default (in pragma Component_Alignment)
+
+@item `Default'
+
+Specifies that array or record components are aligned on default
+boundaries, appropriate to the underlying hardware or operating system or
+both. The @code{Default} choice is the same as @code{Component_Size} (natural
+alignment).
+@end table
+
+If the @code{Name} parameter is present, @code{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 Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42}
+@section Pragma Constant_After_Elaboration
+
+
+Syntax:
+
+@example
+pragma Constant_After_Elaboration [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect
+@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1.
+
+@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44}
+@section Pragma Contract_Cases
+
+
+@geindex Contract cases
+
+Syntax:
+
+@example
+pragma Contract_Cases (CONTRACT_CASE @{, CONTRACT_CASE@});
+
+CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE
+
+CASE_GUARD ::= boolean_EXPRESSION | others
+
+CONSEQUENCE ::= boolean_EXPRESSION
+@end example
+
+The @code{Contract_Cases} pragma allows defining fine-grain specifications
+that can complement or replace the contract given by a precondition and a
+postcondition. Additionally, the @code{Contract_Cases} pragma can be used
+by testing and formal verification tools. The compiler checks its validity and,
+depending on the assertion policy at the point of declaration of the pragma,
+it may insert a check in the executable. For code generation, the contract
+cases
+
+@example
+pragma Contract_Cases (
+ Cond1 => Pred1,
+ Cond2 => Pred2);
+@end example
+
+are equivalent to
+
+@example
+C1 : constant Boolean := Cond1; -- evaluated at subprogram entry
+C2 : constant Boolean := Cond2; -- evaluated at subprogram entry
+pragma Precondition ((C1 and not C2) or (C2 and not C1));
+pragma Postcondition (if C1 then Pred1);
+pragma Postcondition (if C2 then Pred2);
+@end example
+
+The precondition ensures that one and only one of the case guards is
+satisfied on entry to the subprogram.
+The postcondition ensures that for the case guard that was True on entry,
+the corresponding consequence is True on exit. Other consequence expressions
+are not evaluated.
+
+A precondition @code{P} and postcondition @code{Q} can also be
+expressed as contract cases:
+
+@example
+pragma Contract_Cases (P => Q);
+@end example
+
+The placement and visibility rules for @code{Contract_Cases} pragmas are
+identical to those described for preconditions and postconditions.
+
+The compiler checks that boolean expressions given in case guards and
+consequences are valid, where the rules for case guards are the same as
+the rule for an expression in @code{Precondition} and the rules for
+consequences are the same as the rule for an expression in
+@code{Postcondition}. In particular, attributes @code{'Old} and
+@code{'Result} can only be used within consequence expressions.
+The case guard for the last contract case may be @code{others}, to denote
+any case not captured by the previous cases. The
+following is an example of use within a package spec:
+
+@example
+package Math_Functions is
+ ...
+ function Sqrt (Arg : Float) return Float;
+ pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0,
+ Arg >= 100.0 => Sqrt'Result >= 10.0,
+ others => Sqrt'Result = 0.0));
+ ...
+end Math_Functions;
+@end example
+
+The meaning of contract cases is that only one case should apply at each
+call, as determined by the corresponding case guard evaluating to True,
+and that the consequence for this case should hold when the subprogram
+returns.
+
+@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45}
+@section Pragma Convention_Identifier
+
+
+@geindex Conventions
+@geindex synonyms
+
+Syntax:
+
+@example
+pragma Convention_Identifier (
+ [Name =>] IDENTIFIER,
+ [Convention =>] convention_IDENTIFIER);
+@end example
+
+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:
+
+@example
+pragma Convention_Identifier (Fortran77, Fortran);
+@end example
+
+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 parameterize 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,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46}
+@section Pragma CPP_Class
+
+
+@geindex Interfacing with C++
+
+Syntax:
+
+@example
+pragma CPP_Class ([Entity =>] LOCAL_NAME);
+@end example
+
+The argument denotes an entity in the current declarative region that is
+declared as a 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. If the C++ class has virtual primitives
+then the record must be declared as a tagged record 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 an error is issued in that case.
+
+See @ref{47,,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,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{48}
+@section Pragma CPP_Constructor
+
+
+@geindex Interfacing with C++
+
+Syntax:
+
+@example
+pragma CPP_Constructor ([Entity =>] LOCAL_NAME
+ [, [External_Name =>] static_string_EXPRESSION ]
+ [, [Link_Name =>] static_string_EXPRESSION ]);
+@end example
+
+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 *
+
+@item
+`function' @code{Fname} `return' T`
+
+@item
+`function' @code{Fname} `return' T’Class
+
+@item
+`function' @code{Fname} (…) `return' T`
+
+@item
+`function' @code{Fname} (…) `return' T’Class
+@end itemize
+
+where @code{T} is a limited record type imported from C++ with pragma
+@code{Import} and @code{Convention} = @code{CPP}.
+
+The first two forms import the default constructor, used when an object
+of type @code{T} is created on the Ada side with no explicit constructor.
+The latter two forms cover all the non-default constructors of the type.
+See the GNAT User’s Guide for details.
+
+If no constructors are imported, it is impossible to create any objects
+on the Ada side and the type is implicitly declared abstract.
+
+Pragma @code{CPP_Constructor} is intended primarily for automatic generation
+using an automatic binding generator tool (such as the @code{-fdump-ada-spec}
+GCC switch).
+See @ref{47,,Interfacing to C++} for more related information.
+
+Note: The use of functions returning class-wide types for constructors is
+currently obsolete. They are supported for backward compatibility. The
+use of functions returning the type T leave the Ada sources more clear
+because the imported C++ constructors always return an object of type T;
+that is, they never return an object whose type is a descendant of type T.
+
+@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49}
+@section Pragma CPP_Virtual
+
+
+@geindex Interfacing to C++
+
+This pragma is now obsolete and, other than generating a warning if warnings
+on obsolescent features are enabled, is completely ignored.
+It is retained for compatibility
+purposes. It used to be required to ensure compatibility with C++, but
+is no longer required for that purpose because GNAT generates
+the same object layout as the G++ compiler by default.
+
+See @ref{47,,Interfacing to C++} for related information.
+
+@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a}
+@section Pragma CPP_Vtable
+
+
+@geindex Interfacing with C++
+
+This pragma is now obsolete and, other than generating a warning if warnings
+on obsolescent features are enabled, is completely ignored.
+It used to be required to ensure compatibility with C++, but
+is no longer required for that purpose because GNAT generates
+the same object layout as the G++ compiler by default.
+
+See @ref{47,,Interfacing to C++} for related information.
+
+@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b}
+@section Pragma CPU
+
+
+Syntax:
+
+@example
+pragma CPU (EXPRESSION);
+@end example
+
+This pragma is standard in Ada 2012, but is available in all earlier
+versions of Ada as an implementation-defined pragma.
+See Ada 2012 Reference Manual for details.
+
+@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c}
+@section Pragma Deadline_Floor
+
+
+Syntax:
+
+@example
+pragma Deadline_Floor (time_span_EXPRESSION);
+@end example
+
+This pragma applies only to protected types and specifies the floor
+deadline inherited by a task when the task enters a protected object.
+It is effective only when the EDF scheduling policy is used.
+
+@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4d}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4e}
+@section Pragma Default_Initial_Condition
+
+
+Syntax:
+
+@example
+pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect
+@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3.
+
+@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4f}
+@section Pragma Debug
+
+
+Syntax:
+
+@example
+pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
+
+PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
+ PROCEDURE_NAME
+| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
+@end example
+
+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 `-gnata'
+or by use of the pragma @code{Check_Policy} with a first argument of
+@code{Debug}.
+
+@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{50}
+@section Pragma Debug_Policy
+
+
+Syntax:
+
+@example
+pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF);
+@end example
+
+This pragma is equivalent to a corresponding @code{Check_Policy} pragma
+with a first argument of @code{Debug}. It is retained for historical
+compatibility reasons.
+
+@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51}
+@section Pragma Default_Scalar_Storage_Order
+
+
+@geindex Default_Scalar_Storage_Order
+
+@geindex Scalar_Storage_Order
+
+Syntax:
+
+@example
+pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First);
+@end example
+
+Normally if no explicit @code{Scalar_Storage_Order} is given for a record
+type or array type, then the scalar storage order defaults to the ordinary
+default for the target. But this default may be overridden using this pragma.
+The pragma may appear as a configuration pragma, or locally within a package
+spec or declarative part. In the latter case, it applies to all subsequent
+types declared within that package spec or declarative part.
+
+The following example shows the use of this pragma:
+
+@example
+pragma Default_Scalar_Storage_Order (High_Order_First);
+with System; use System;
+package DSSO1 is
+ type H1 is record
+ a : Integer;
+ end record;
+
+ type L2 is record
+ a : Integer;
+ end record;
+ for L2'Scalar_Storage_Order use Low_Order_First;
+
+ type L2a is new L2;
+
+ package Inner is
+ type H3 is record
+ a : Integer;
+ end record;
+
+ pragma Default_Scalar_Storage_Order (Low_Order_First);
+
+ type L4 is record
+ a : Integer;
+ end record;
+ end Inner;
+
+ type H4a is new Inner.L4;
+
+ type H5 is record
+ a : Integer;
+ end record;
+end DSSO1;
+@end example
+
+In this example record types with names starting with `L' have @cite{Low_Order_First} scalar
+storage order, and record types with names starting with `H' have @code{High_Order_First}.
+Note that in the case of @code{H4a}, the order is not inherited
+from the parent type. Only an explicitly set @code{Scalar_Storage_Order}
+gets inherited on type derivation.
+
+If this pragma is used as a configuration pragma which appears within a
+configuration pragma file (as opposed to appearing explicitly at the start
+of a single unit), then the binder will require that all units in a partition
+be compiled in a similar manner, other than run-time units, which are not
+affected by this pragma. Note that the use of this form is discouraged because
+it may significantly degrade the run-time performance of the software, instead
+the default scalar storage order ought to be changed only on a local basis.
+
+@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52}
+@section Pragma Default_Storage_Pool
+
+
+@geindex Default_Storage_Pool
+
+Syntax:
+
+@example
+pragma Default_Storage_Pool (storage_pool_NAME | null);
+@end example
+
+This pragma is standard in Ada 2012, but is available in all earlier
+versions of Ada as an implementation-defined pragma.
+See Ada 2012 Reference Manual for details.
+
+@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{54}
+@section Pragma Depends
+
+
+Syntax:
+
+@example
+pragma Depends (DEPENDENCY_RELATION);
+
+DEPENDENCY_RELATION ::=
+ null
+ | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
+
+DEPENDENCY_CLAUSE ::=
+ OUTPUT_LIST =>[+] INPUT_LIST
+ | NULL_DEPENDENCY_CLAUSE
+
+NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
+
+OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
+
+INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
+
+OUTPUT ::= NAME | FUNCTION_RESULT
+INPUT ::= NAME
+
+where FUNCTION_RESULT is a function Result attribute_reference
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Depends} in the
+SPARK 2014 Reference Manual, section 6.1.5.
+
+@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55}
+@section Pragma Detect_Blocking
+
+
+Syntax:
+
+@example
+pragma Detect_Blocking;
+@end example
+
+This is a standard pragma in Ada 2005, that is available in all earlier
+versions of Ada as an implementation-defined pragma.
+
+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 Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56}
+@section Pragma Disable_Atomic_Synchronization
+
+
+@geindex Atomic Synchronization
+
+Syntax:
+
+@example
+pragma Disable_Atomic_Synchronization [(Entity)];
+@end example
+
+Ada requires that accesses (reads or writes) of an atomic variable be
+regarded as synchronization points in the case of multiple tasks.
+Particularly in the case of multi-processors this may require special
+handling, e.g. the generation of memory barriers. This capability may
+be turned off using this pragma in cases where it is known not to be
+required.
+
+The placement and scope rules for this pragma are the same as those
+for @code{pragma Suppress}. In particular it can be used as a
+configuration pragma, or in a declaration sequence where it applies
+till the end of the scope. If an @code{Entity} argument is present,
+the action applies only to that entity.
+
+@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57}
+@section Pragma Dispatching_Domain
+
+
+Syntax:
+
+@example
+pragma Dispatching_Domain (EXPRESSION);
+@end example
+
+This pragma is standard in Ada 2012, but is available in all earlier
+versions of Ada as an implementation-defined pragma.
+See Ada 2012 Reference Manual for details.
+
+@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59}
+@section Pragma Effective_Reads
+
+
+Syntax:
+
+@example
+pragma Effective_Reads [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in
+the SPARK 2014 Reference Manual, section 7.1.2.
+
+@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b}
+@section Pragma Effective_Writes
+
+
+Syntax:
+
+@example
+pragma Effective_Writes [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Effective_Writes}
+in the SPARK 2014 Reference Manual, section 7.1.2.
+
+@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c}
+@section Pragma Elaboration_Checks
+
+
+@geindex Elaboration control
+
+Syntax:
+
+@example
+pragma Elaboration_Checks (Dynamic | Static);
+@end example
+
+This is a configuration pragma which specifies the elaboration model to be
+used during compilation. For more information on the elaboration models of
+GNAT, consult the chapter on elaboration order handling in the `GNAT User’s
+Guide'.
+
+The pragma may appear in the following contexts:
+
+
+@itemize *
+
+@item
+Configuration pragmas file
+
+@item
+Prior to the context clauses of a compilation unit’s initial declaration
+@end itemize
+
+Any other placement of the pragma will result in a warning and the effects of
+the offending pragma will be ignored.
+
+If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in
+effect. If the pragma argument is @code{Static}, then the static elaboration model
+is in effect.
+
+@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d}
+@section Pragma Eliminate
+
+
+@geindex Elimination of unused subprograms
+
+Syntax:
+
+@example
+pragma Eliminate (
+ [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT ,
+ [ Entity => ] IDENTIFIER |
+ SELECTED_COMPONENT |
+ STRING_LITERAL
+ [, Source_Location => SOURCE_TRACE ] );
+
+ SOURCE_TRACE ::= STRING_LITERAL
+@end example
+
+This pragma indicates that the given entity is not used in the program to be
+compiled and built, thus allowing the compiler to
+eliminate the code or data associated with the named entity. Any reference to
+an eliminated entity causes a compile-time or link-time error.
+
+The pragma has the following semantics, where @code{U} is the unit specified by
+the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity}
+argument:
+
+
+@itemize *
+
+@item
+@code{E} must be a subprogram that is explicitly declared either:
+
+
+@itemize *
+
+@item
+Within @code{U}, or
+
+@item
+Within a generic package that is instantiated in @code{U}, or
+
+@item
+As an instance of generic subprogram instantiated in @code{U}.
+@end itemize
+
+Otherwise the pragma is ignored.
+
+@item
+If @code{E} is overloaded within @code{U} then, in the absence of a
+@code{Source_Location} argument, all overloadings are eliminated.
+
+@item
+If @code{E} is overloaded within @code{U} and only some overloadings
+are to be eliminated, then each overloading to be eliminated
+must be specified in a corresponding pragma @code{Eliminate}
+with a @code{Source_Location} argument identifying the line where the
+declaration appears, as described below.
+
+@item
+If @code{E} is declared as the result of a generic instantiation, then
+a @code{Source_Location} argument is needed, as described below.
+@end itemize
+
+Pragma @code{Eliminate} allows a program to be compiled in a system-independent
+manner, so that unused entities are eliminated but without
+needing to modify the source text. Normally the required set of
+@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool.
+
+Any source file change that removes, splits, or
+adds lines may make the set of @code{Eliminate} pragmas invalid because their
+@code{Source_Location} argument values may get out of date.
+
+Pragma @code{Eliminate} may be used where the referenced entity is a dispatching
+operation. In this case all the subprograms to which the given operation can
+dispatch are considered to be unused (are never called as a result of a direct
+or a dispatching call).
+
+The string literal given for the source location specifies the line number
+of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}:
+
+@example
+SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ]
+
+LBRACKET ::= '['
+RBRACKET ::= ']'
+
+SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
+
+LINE_NUMBER ::= DIGIT @{DIGIT@}
+@end example
+
+Spaces around the colon in a @code{SOURCE_REFERENCE} are optional.
+
+The source trace that is given as the @code{Source_Location} must obey the
+following rules (or else the pragma is ignored), where @code{U} is
+the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the
+subprogram specified by the @code{Entity} argument:
+
+
+@itemize *
+
+@item
+@code{FILE_NAME} is the short name (with no directory
+information) of the Ada source file for @code{U}, using the required syntax
+for the underlying file system (e.g. case is significant if the underlying
+operating system is case sensitive).
+If @code{U} is a package and @code{E} is a subprogram declared in the package
+specification and its full declaration appears in the package body,
+then the relevant source file is the one for the package specification;
+analogously if @code{U} is a generic package.
+
+@item
+If @code{E} is not declared in a generic instantiation (this includes
+generic subprogram instances), the source trace includes only one source
+line reference. @code{LINE_NUMBER} gives the line number of the occurrence
+of the declaration of @code{E} within the source file (as a decimal literal
+without an exponent or point).
+
+@item
+If @code{E} is declared by a generic instantiation, its source trace
+(from left to right) starts with the source location of the
+declaration of @code{E} in the generic unit and ends with the source
+location of the instantiation, given in square brackets. This approach is
+applied recursively with nested instantiations: the rightmost (nested
+most deeply in square brackets) element of the source trace is the location
+of the outermost instantiation, and the leftmost element (that is, outside
+of any square brackets) is the location of the declaration of @code{E} in
+the generic unit.
+@end itemize
+
+Examples:
+
+@quotation
+
+@example
+pragma Eliminate (Pkg0, Proc);
+-- Eliminate (all overloadings of) Proc in Pkg0
+
+pragma Eliminate (Pkg1, Proc,
+ Source_Location => "pkg1.ads:8");
+-- Eliminate overloading of Proc at line 8 in pkg1.ads
+
+-- Assume the following file contents:
+-- gen_pkg.ads
+-- 1: generic
+-- 2: type T is private;
+-- 3: package Gen_Pkg is
+-- 4: procedure Proc(N : T);
+-- ... ...
+-- ... end Gen_Pkg;
+--
+-- q.adb
+-- 1: with Gen_Pkg;
+-- 2: procedure Q is
+-- 3: package Inst_Pkg is new Gen_Pkg(Integer);
+-- ... -- No calls on Inst_Pkg.Proc
+-- ... end Q;
+
+-- The following pragma eliminates Inst_Pkg.Proc from Q
+pragma Eliminate (Q, Proc,
+ Source_Location => "gen_pkg.ads:4[q.adb:3]");
+@end example
+@end quotation
+
+@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5e}
+@section Pragma Enable_Atomic_Synchronization
+
+
+@geindex Atomic Synchronization
+
+Syntax:
+
+@example
+pragma Enable_Atomic_Synchronization [(Entity)];
+@end example
+
+Ada requires that accesses (reads or writes) of an atomic variable be
+regarded as synchronization points in the case of multiple tasks.
+Particularly in the case of multi-processors this may require special
+handling, e.g. the generation of memory barriers. This synchronization
+is performed by default, but can be turned off using
+@code{pragma Disable_Atomic_Synchronization}. The
+@code{Enable_Atomic_Synchronization} pragma can be used to turn
+it back on.
+
+The placement and scope rules for this pragma are the same as those
+for @code{pragma Unsuppress}. In particular it can be used as a
+configuration pragma, or in a declaration sequence where it applies
+till the end of the scope. If an @code{Entity} argument is present,
+the action applies only to that entity.
+
+@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f}
+@section Pragma Export_Function
+
+
+@geindex Argument passing mechanisms
+
+Syntax:
+
+@example
+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
+@end example
+
+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.
+
+The @code{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 to achieve the required
+unique designation. The @cite{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.
+
+@geindex 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,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60}
+@section Pragma Export_Object
+
+
+Syntax:
+
+@example
+pragma Export_Object (
+ [Internal =>] LOCAL_NAME
+ [, [External =>] EXTERNAL_SYMBOL]
+ [, [Size =>] EXTERNAL_SYMBOL]);
+
+EXTERNAL_SYMBOL ::=
+ IDENTIFIER
+| static_string_EXPRESSION
+@end example
+
+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. @code{Size} is syntax checked,
+but otherwise ignored by GNAT.
+
+@node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61}
+@section Pragma Export_Procedure
+
+
+Syntax:
+
+@example
+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
+@end example
+
+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.
+
+@geindex 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_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{62}
+@section Pragma Export_Valued_Procedure
+
+
+Syntax:
+
+@example
+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
+@end example
+
+This pragma is identical to @code{Export_Procedure} except that the
+first parameter of @code{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.
+
+@geindex 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,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{63}
+@section Pragma Extend_System
+
+
+@geindex System
+@geindex extending
+
+@geindex DEC Ada 83
+
+Syntax:
+
+@example
+pragma Extend_System ([Name =>] IDENTIFIER);
+@end example
+
+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 `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 `-gnatg' switch
+for compiling System units, as explained in the
+GNAT User’s Guide.
+
+@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{64}
+@section Pragma Extensions_Allowed
+
+
+@geindex Ada Extensions
+
+@geindex GNAT Extensions
+
+Syntax:
+
+@example
+pragma Extensions_Allowed (On | Off | All);
+@end example
+
+This configuration pragma enables (via the “On” or “All” argument) or disables
+(via the “Off” argument) the implementation extension mode; the pragma takes
+precedence over the `-gnatX' and `-gnatX0' command switches.
+
+If an argument of “All” is specified, the latest version of the Ada language
+is implemented (currently Ada 2022) and, in addition, a number
+of GNAT specific extensions are recognized. These extensions are listed
+below. An argument of “On” has the same effect except that only
+some, not all, of the listed extensions are enabled; those extensions
+are identified below.
+
+
+@itemize *
+
+@item
+Constrained attribute for generic objects
+
+The @code{Constrained} attribute is permitted for objects of
+generic types. The result indicates if the corresponding actual
+is constrained.
+
+@item
+@code{Static} aspect on intrinsic functions
+
+The Ada 202x @code{Static} aspect can be specified on Intrinsic imported
+functions and the compiler will evaluate some of these intrinsic statically,
+in particular the @code{Shift_Left} and @code{Shift_Right} intrinsics.
+
+An Extensions_Allowed pragma argument of “On” enables this extension.
+
+@item
+@code{[]} aggregates
+
+This new aggregate syntax for arrays and containers is provided under -gnatX
+to experiment and confirm this new language syntax.
+
+@item
+Additional @code{when} constructs
+
+In addition to the @code{exit when CONDITION} control structure, several
+additional constructs are allowed following this format. Including
+@code{return when CONDITION}, @code{goto when CONDITION}, and
+@code{raise [with EXCEPTION_MESSAGE] when CONDITION.}
+
+Some examples:
+
+@example
+return Result when Variable > 10;
+
+raise Program_Error with "Element is null" when Element = null;
+
+goto End_Of_Subprogram when Variable = -1;
+@end example
+
+@item
+Casing on composite values (aka pattern matching)
+
+The selector for a case statement may be of a composite type, subject to
+some restrictions (described below). Aggregate syntax is used for choices
+of such a case statement; however, in cases where a “normal” aggregate would
+require a discrete value, a discrete subtype may be used instead; box
+notation can also be used to match all values.
+
+Consider this example:
+
+@example
+type Rec is record
+ F1, F2 : Integer;
+end record;
+
+procedure Caser_1 (X : Rec) is
+begin
+ case X is
+ when (F1 => Positive, F2 => Positive) =>
+ Do_This;
+ when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) =>
+ Do_That;
+ when others =>
+ Do_The_Other_Thing;
+ end case;
+end Caser_1;
+@end example
+
+If Caser_1 is called and both components of X are positive, then
+Do_This will be called; otherwise, if either component is nonnegative
+then Do_That will be called; otherwise, Do_The_Other_Thing will be called.
+
+If the set of values that match the choice(s) of an earlier alternative
+overlaps the corresponding set of a later alternative, then the first
+set shall be a proper subset of the second (and the later alternative
+will not be executed if the earlier alternative “matches”). All possible
+values of the composite type shall be covered. The composite type of the
+selector shall be an array or record type that is neither limited
+class-wide. Currently, a “when others =>” case choice is required; it is
+intended that this requirement will be relaxed at some point.
+
+If a subcomponent’s subtype does not meet certain restrictions, then
+the only value that can be specified for that subcomponent in a case
+choice expression is a “box” component association (which matches all
+possible values for the subcomponent). This restriction applies if
+
+
+@itemize -
+
+@item
+the component subtype is not a record, array, or discrete type; or
+
+@item
+the component subtype is subject to a non-static constraint or
+has a predicate; or
+
+@item
+the component type is an enumeration type that is subject to an
+enumeration representation clause; or
+
+@item
+the component type is a multidimensional array type or an
+array type with a nonstatic index subtype.
+@end itemize
+
+Support for casing on arrays (and on records that contain arrays) is
+currently subject to some restrictions. Non-positional
+array aggregates are not supported as (or within) case choices. Likewise
+for array type and subtype names. The current implementation exceeds
+compile-time capacity limits in some annoyingly common scenarios; the
+message generated in such cases is usually “Capacity exceeded in compiling
+case statement with composite selector type”.
+
+In addition, pattern bindings are supported. This is a mechanism
+for binding a name to a component of a matching value for use within
+an alternative of a case statement. For a component association
+that occurs within a case choice, the expression may be followed by
+“is <identifier>”. In the special case of a “box” component association,
+the identifier may instead be provided within the box. Either of these
+indicates that the given identifer denotes (a constant view of) the matching
+subcomponent of the case selector. Binding is not yet supported for arrays
+or subcomponents thereof.
+
+Consider this example (which uses type Rec from the previous example):
+
+@example
+procedure Caser_2 (X : Rec) is
+begin
+ case X is
+ when (F1 => Positive is Abc, F2 => Positive) =>
+ Do_This (Abc)
+ when (F1 => Natural is N1, F2 => <N2>) |
+ (F1 => <N2>, F2 => Natural is N1) =>
+ Do_That (Param_1 => N1, Param_2 => N2);
+ when others =>
+ Do_The_Other_Thing;
+ end case;
+end Caser_2;
+@end example
+
+This example is the same as the previous one with respect to
+determining whether Do_This, Do_That, or Do_The_Other_Thing will
+be called. But for this version, Do_This takes a parameter and Do_That
+takes two parameters. If Do_This is called, the actual parameter in the
+call will be X.F1.
+
+If Do_That is called, the situation is more complex because there are two
+choices for that alternative. If Do_That is called because the first choice
+matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero
+or negative), then the actual parameters of the call will be (in order)
+X.F1 and X.F2. If Do_That is called because the second choice matched (and
+the first one did not), then the actual parameters will be reversed.
+
+Within the choice list for single alternative, each choice must
+define the same set of bindings and the component subtypes for
+for a given identifer must all statically match. Currently, the case
+of a binding for a nondiscrete component is not implemented.
+
+An Extensions_Allowed pragma argument of “On” enables this extension.
+
+@item
+Fixed lower bounds for array types and subtypes
+
+Unconstrained array types and subtypes can be specified with a lower bound
+that is fixed to a certain value, by writing an index range that uses the
+syntax “<lower-bound-expression> .. <>”. This guarantees that all objects
+of the type or subtype will have the specified lower bound.
+
+For example, a matrix type with fixed lower bounds of zero for each
+dimension can be declared by the following:
+
+@example
+type Matrix is
+ array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer;
+@end example
+
+Objects of type Matrix declared with an index constraint must have index
+ranges starting at zero:
+
+@example
+M1 : Matrix (0 .. 9, 0 .. 19);
+M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE
+@end example
+
+Similarly, a subtype of String can be declared that specifies the lower
+bound of objects of that subtype to be 1:
+
+@quotation
+
+@example
+subtype String_1 is String (1 .. <>);
+@end example
+@end quotation
+
+If a string slice is passed to a formal of subtype String_1 in a call to
+a subprogram S, the slice’s bounds will “slide” so that the lower bound
+is 1. Within S, the lower bound of the formal is known to be 1, so, unlike
+a normal unconstrained String formal, there is no need to worry about
+accounting for other possible lower-bound values. Sliding of bounds also
+occurs in other contexts, such as for object declarations with an
+unconstrained subtype with fixed lower bound, as well as in subtype
+conversions.
+
+Use of this feature increases safety by simplifying code, and can also
+improve the efficiency of indexing operations, since the compiler statically
+knows the lower bound of unconstrained array formals when the formal’s
+subtype has index ranges with static fixed lower bounds.
+
+An Extensions_Allowed pragma argument of “On” enables this extension.
+
+@item
+Prefixed-view notation for calls to primitive subprograms of untagged types
+
+Since Ada 2005, calls to primitive subprograms of a tagged type that
+have a “prefixed view” (see RM 4.1.3(9.2)) have been allowed to be
+written using the form of a selected_component, with the first actual
+parameter given as the prefix and the name of the subprogram as a
+selector. This prefixed-view notation for calls is extended so as to
+also allow such syntax for calls to primitive subprograms of untagged
+types. The primitives of an untagged type T that have a prefixed view
+are those where the first formal parameter of the subprogram either
+is of type T or is an anonymous access parameter whose designated type
+is T. For a type that has a component that happens to have the same
+simple name as one of the type’s primitive subprograms, where the
+component is visible at the point of a selected_component using that
+name, preference is given to the component in a selected_component
+(as is currently the case for tagged types with such component names).
+
+An Extensions_Allowed pragma argument of “On” enables this extension.
+
+@item
+Expression defaults for generic formal functions
+
+The declaration of a generic formal function is allowed to specify
+an expression as a default, using the syntax of an expression function.
+
+Here is an example of this feature:
+
+@example
+generic
+ type T is private;
+ with function Copy (Item : T) return T is (Item); -- Defaults to Item
+package Stacks is
+
+ type Stack is limited private;
+
+ procedure Push (S : in out Stack; X : T); -- Calls Copy on X
+
+ function Pop (S : in out Stack) return T; -- Calls Copy to return item
+
+private
+ -- ...
+end Stacks;
+@end example
+@end itemize
+
+@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{65}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{66}
+@section Pragma Extensions_Visible
+
+
+Syntax:
+
+@example
+pragma Extensions_Visible [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible}
+in the SPARK 2014 Reference Manual, section 6.1.7.
+
+@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{67}
+@section Pragma External
+
+
+Syntax:
+
+@example
+pragma External (
+ [ Convention =>] convention_IDENTIFIER,
+ [ Entity =>] LOCAL_NAME
+ [, [External_Name =>] static_string_EXPRESSION ]
+ [, [Link_Name =>] static_string_EXPRESSION ]);
+@end example
+
+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,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{68}
+@section Pragma External_Name_Casing
+
+
+@geindex Dec Ada 83 casing compatibility
+
+@geindex External Names
+@geindex casing
+
+@geindex Casing of External names
+
+Syntax:
+
+@example
+pragma External_Name_Casing (
+ Uppercase | Lowercase
+ [, Uppercase | Lowercase | As_Is]);
+@end example
+
+This pragma provides control over the casing of external names associated
+with Import and Export pragmas. There are two cases to consider:
+
+
+@itemize *
+
+@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:
+
+@example
+pragma Import (C, C_Routine);
+@end example
+
+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:
+
+@example
+pragma Import (C, C_Routine, "C_routine");
+@end example
+
+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 itemize
+
+This pragma may appear anywhere that a pragma is valid. In particular, it
+can be used as a configuration pragma in the @code{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 was 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:
+
+@example
+pragma External_Name_Casing (Uppercase, Uppercase);
+@end example
+
+to enforce the upper casing of all external symbols.
+
+@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{69}
+@section Pragma Fast_Math
+
+
+Syntax:
+
+@example
+pragma Fast_Math;
+@end example
+
+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,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6a}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6b}
+@section Pragma Favor_Top_Level
+
+
+Syntax:
+
+@example
+pragma Favor_Top_Level (type_NAME);
+@end example
+
+The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram
+type. This pragma is an efficiency hint to the compiler, regarding the use of
+@code{'Access} or @code{'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 restriction @code{No_Implicit_Dynamic_Code}.
+
+@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6c}
+@section Pragma Finalize_Storage_Only
+
+
+Syntax:
+
+@example
+pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
+@end example
+
+The argument of pragma @code{Finalize_Storage_Only} must denote a local type which
+is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The
+pragma suppresses the call to @code{Finalize} for declared library-level objects
+of the argument type. 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. Note that this pragma does not suppress Finalize calls for library-level
+heap-allocated objects (see pragma @code{No_Heap_Finalization}).
+
+@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6d}
+@section Pragma Float_Representation
+
+
+Syntax:
+
+@example
+pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
+
+FLOAT_REP ::= VAX_Float | IEEE_Float
+@end example
+
+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}. This pragma is only provided for compatibility and has no effect.
+
+The two argument form specifies the representation to be used for
+the specified floating-point type. The argument must
+be @code{IEEE_Float} to specify the use of IEEE format, as follows:
+
+
+@itemize *
+
+@item
+For a digits value of 6, 32-bit IEEE short format will be used.
+
+@item
+For a digits value of 15, 64-bit IEEE long format will be used.
+
+@item
+No other value of digits is permitted.
+@end itemize
+
+@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6e}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{6f}
+@section Pragma Ghost
+
+
+Syntax:
+
+@example
+pragma Ghost [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK
+2014 Reference Manual, section 6.9.
+
+@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{70}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{71}
+@section Pragma Global
+
+
+Syntax:
+
+@example
+pragma Global (GLOBAL_SPECIFICATION);
+
+GLOBAL_SPECIFICATION ::=
+ null
+ | (GLOBAL_LIST)
+ | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
+
+MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
+
+MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
+GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
+GLOBAL_ITEM ::= NAME
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Global} in the
+SPARK 2014 Reference Manual, section 6.1.4.
+
+@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{72}
+@section Pragma Ident
+
+
+Syntax:
+
+@example
+pragma Ident (static_string_EXPRESSION);
+@end example
+
+This pragma is identical in effect to pragma @code{Comment}. It is provided
+for compatibility with other Ada compilers providing this pragma.
+
+@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{73}
+@section Pragma Ignore_Pragma
+
+
+Syntax:
+
+@example
+pragma Ignore_Pragma (pragma_IDENTIFIER);
+@end example
+
+This is a configuration pragma
+that takes a single argument that is a simple identifier. Any subsequent
+use of a pragma whose pragma identifier matches this argument will be
+silently ignored. This may be useful when legacy code or code intended
+for compilation with some other compiler contains pragmas that match the
+name, but not the exact implementation, of a GNAT pragma. The use of this
+pragma allows such pragmas to be ignored, which may be useful in CodePeer
+mode, or during porting of legacy code.
+
+@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{74}
+@section Pragma Implementation_Defined
+
+
+Syntax:
+
+@example
+pragma Implementation_Defined (local_NAME);
+@end example
+
+This pragma marks a previously declared entity as implementation-defined.
+For an overloaded entity, applies to the most recent homonym.
+
+@example
+pragma Implementation_Defined;
+@end example
+
+The form with no arguments appears anywhere within a scope, most
+typically a package spec, and indicates that all entities that are
+defined within the package spec are Implementation_Defined.
+
+This pragma is used within the GNAT runtime library to identify
+implementation-defined entities introduced in language-defined units,
+for the purpose of implementing the No_Implementation_Identifiers
+restriction.
+
+@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{75}
+@section Pragma Implemented
+
+
+Syntax:
+
+@example
+pragma Implemented (procedure_LOCAL_NAME, implementation_kind);
+
+implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any
+@end example
+
+This is an Ada 2012 representation pragma which applies to protected, task
+and synchronized interface primitives. The use of pragma Implemented provides
+a way to impose a static requirement on the overriding operation by adhering
+to one of the three implementation kinds: entry, protected procedure or any of
+the above. This pragma is available in all earlier versions of Ada as an
+implementation-defined pragma.
+
+@example
+type Synch_Iface is synchronized interface;
+procedure Prim_Op (Obj : in out Iface) is abstract;
+pragma Implemented (Prim_Op, By_Protected_Procedure);
+
+protected type Prot_1 is new Synch_Iface with
+ procedure Prim_Op; -- Legal
+end Prot_1;
+
+protected type Prot_2 is new Synch_Iface with
+ entry Prim_Op; -- Illegal
+end Prot_2;
+
+task type Task_Typ is new Synch_Iface with
+ entry Prim_Op; -- Illegal
+end Task_Typ;
+@end example
+
+When applied to the procedure_or_entry_NAME of a requeue statement, pragma
+Implemented determines the runtime behavior of the requeue. Implementation kind
+By_Entry guarantees that the action of requeueing will proceed from an entry to
+another entry. Implementation kind By_Protected_Procedure transforms the
+requeue into a dispatching call, thus eliminating the chance of blocking. Kind
+By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on
+the target’s overriding subprogram kind.
+
+@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{76}
+@section Pragma Implicit_Packing
+
+
+@geindex Rational Profile
+
+Syntax:
+
+@example
+pragma Implicit_Packing;
+@end example
+
+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. It also applies to records
+where no record representation clause is present. Consider this example:
+
+@example
+type R is array (0 .. 7) of Boolean;
+for R'Size use 8;
+@end example
+
+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 number of elements in the array
+multiplied by the size in bits of the component type (both single and
+multi-dimensioned arrays can be controlled with this pragma).
+
+@geindex Array packing
+
+Similarly, the following example shows the use in the record case
+
+@example
+type r is record
+ a, b, c, d, e, f, g, h : boolean;
+ chr : character;
+end record;
+for r'size use 16;
+@end example
+
+Without a pragma Pack, each Boolean field requires 8 bits, so the
+minimum size is 72 bits, but with a pragma Pack, 16 bits would be
+sufficient. The use of pragma Implicit_Packing allows this record
+declaration to compile without an explicit pragma Pack.
+
+@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{77}
+@section Pragma Import_Function
+
+
+Syntax:
+
+@example
+pragma Import_Function (
+ [Internal =>] LOCAL_NAME,
+ [, [External =>] EXTERNAL_SYMBOL]
+ [, [Parameter_Types =>] PARAMETER_TYPES]
+ [, [Result_Type =>] 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
+@end example
+
+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 @code{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
+@code{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 @code{Mechanism} and @code{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.
+
+@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{78}
+@section Pragma Import_Object
+
+
+Syntax:
+
+@example
+pragma Import_Object (
+ [Internal =>] LOCAL_NAME
+ [, [External =>] EXTERNAL_SYMBOL]
+ [, [Size =>] EXTERNAL_SYMBOL]);
+
+EXTERNAL_SYMBOL ::=
+ IDENTIFIER
+| static_string_EXPRESSION
+@end example
+
+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). @code{size} is syntax checked, but otherwise ignored by
+GNAT.
+
+@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{79}
+@section Pragma Import_Procedure
+
+
+Syntax:
+
+@example
+pragma Import_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
+@end example
+
+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,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7a}
+@section Pragma Import_Valued_Procedure
+
+
+Syntax:
+
+@example
+pragma Import_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
+@end example
+
+This pragma is identical to @code{Import_Procedure} except that the
+first parameter of @code{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 Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7b}
+@section Pragma Independent
+
+
+Syntax:
+
+@example
+pragma Independent (Local_NAME);
+@end example
+
+This pragma is standard in Ada 2012 mode (which also provides an aspect
+of the same name). It is also available as an implementation-defined
+pragma in all earlier versions. It specifies that the
+designated object or all objects of the designated type must be
+independently addressable. This means that separate tasks can safely
+manipulate such objects. For example, if two components of a record are
+independent, then two separate tasks may access these two components.
+This may place
+constraints on the representation of the object (for instance prohibiting
+tight packing).
+
+@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7c}
+@section Pragma Independent_Components
+
+
+Syntax:
+
+@example
+pragma Independent_Components (Local_NAME);
+@end example
+
+This pragma is standard in Ada 2012 mode (which also provides an aspect
+of the same name). It is also available as an implementation-defined
+pragma in all earlier versions. It specifies that the components of the
+designated object, or the components of each object of the designated
+type, must be
+independently addressable. This means that separate tasks can safely
+manipulate separate components in the composite object. This may place
+constraints on the representation of the object (for instance prohibiting
+tight packing).
+
+@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7d}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7e}
+@section Pragma Initial_Condition
+
+
+Syntax:
+
+@example
+pragma Initial_Condition (boolean_EXPRESSION);
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Initial_Condition}
+in the SPARK 2014 Reference Manual, section 7.1.6.
+
+@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{7f}
+@section Pragma Initialize_Scalars
+
+
+@geindex debugging with Initialize_Scalars
+
+Syntax:
+
+@example
+pragma Initialize_Scalars
+ [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ];
+
+TYPE_VALUE_PAIR ::=
+ SCALAR_TYPE => static_EXPRESSION
+
+SCALAR_TYPE :=
+ Short_Float
+| Float
+| Long_Float
+| Long_Long_Flat
+| Signed_8
+| Signed_16
+| Signed_32
+| Signed_64
+| Unsigned_8
+| Unsigned_16
+| Unsigned_32
+| Unsigned_64
+@end example
+
+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 the programmer can control the value
+used for initializing scalar objects. This effect can be achieved in several
+different ways:
+
+
+@itemize *
+
+@item
+At compile time, the programmer can specify the invalid value for a
+particular family of scalar types using the optional arguments of the pragma.
+
+The compile-time approach is intended to optimize the generated code for the
+pragma, by possibly using fast operations such as @code{memset}. Note that such
+optimizations require using values where the bytes all have the same binary
+representation.
+
+@item
+At bind time, the programmer has several options:
+
+
+@itemize *
+
+@item
+Initialization 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 nonstandard
+sizes).
+
+@item
+Initialization with high values.
+
+@item
+Initialization with low values.
+
+@item
+Initialization with a specific bit pattern.
+@end itemize
+
+See the GNAT User’s Guide for binder options for specifying these cases.
+
+The bind-time approach is intended to provide fast turnaround for testing
+with different values, without having to recompile the program.
+
+@item
+At execution time, the programmer can specify the invalid values using an
+environment variable. See the GNAT User’s Guide for details.
+
+The execution-time approach is intended to provide fast turnaround for
+testing with different values, without having to recompile and rebind the
+program.
+@end itemize
+
+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 `-gnatV' flag in the GNAT User’s 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 User’s Guide) when using this pragma.
+
+@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{81}
+@section Pragma Initializes
+
+
+Syntax:
+
+@example
+pragma Initializes (INITIALIZATION_LIST);
+
+INITIALIZATION_LIST ::=
+ null
+ | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@})
+
+INITIALIZATION_ITEM ::= name [=> INPUT_LIST]
+
+INPUT_LIST ::=
+ null
+ | INPUT
+ | (INPUT @{, INPUT@})
+
+INPUT ::= name
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Initializes} in the
+SPARK 2014 Reference Manual, section 7.1.5.
+
+@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{82}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{83}
+@section Pragma Inline_Always
+
+
+Syntax:
+
+@example
+pragma Inline_Always (NAME [, NAME]);
+@end example
+
+Similar to pragma @code{Inline} except that inlining is unconditional.
+Inline_Always instructs the compiler to inline every direct call to the
+subprogram or else to emit a compilation error, independently of any
+option, in particular `-gnatn' or `-gnatN' or the optimization level.
+It is an error to take the address or access of @code{NAME}. It is also an error to
+apply this pragma to a primitive operation of a tagged type. Thanks to such
+restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}.
+
+@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{84}
+@section Pragma Inline_Generic
+
+
+Syntax:
+
+@example
+pragma Inline_Generic (GNAME @{, GNAME@});
+
+GNAME ::= generic_unit_NAME | generic_instance_NAME
+@end example
+
+This pragma is provided for compatibility with Dec Ada 83. It has
+no effect in GNAT (which always inlines generics), other
+than to check that the given names are all names of generic units or
+generic instances.
+
+@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{85}
+@section Pragma Interface
+
+
+Syntax:
+
+@example
+pragma Interface (
+ [Convention =>] convention_identifier,
+ [Entity =>] local_NAME
+ [, [External_Name =>] static_string_expression]
+ [, [Link_Name =>] static_string_expression]);
+@end example
+
+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. The only difference between pragma @code{Interface}
+and pragma @code{Import} is that there is special circuitry to allow
+both pragmas to appear for the same subprogram entity (normally it
+is illegal to have multiple @code{Import} pragmas). This is useful in
+maintaining Ada 83/Ada 95 compatibility and is compatible with other
+Ada 83 compilers.
+
+@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{86}
+@section Pragma Interface_Name
+
+
+Syntax:
+
+@example
+pragma Interface_Name (
+ [Entity =>] LOCAL_NAME
+ [, [External_Name =>] static_string_EXPRESSION]
+ [, [Link_Name =>] static_string_EXPRESSION]);
+@end example
+
+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 @code{External_Name} or @code{Link_Name}.
+
+@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{87}
+@section Pragma Interrupt_Handler
+
+
+Syntax:
+
+@example
+pragma Interrupt_Handler (procedure_LOCAL_NAME);
+@end example
+
+This program unit pragma is supported for parameterless protected procedures
+as described in Annex C of the Ada Reference Manual.
+
+@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{88}
+@section Pragma Interrupt_State
+
+
+Syntax:
+
+@example
+pragma Interrupt_State
+ ([Name =>] value,
+ [State =>] SYSTEM | RUNTIME | USER);
+@end example
+
+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 @code{Ctrl-C} interrupt. Normally this interrupt is
+reserved to the implementation, so that @code{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 Windows. 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 *
+
+@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. This also allows
+installing a low level handler via C APIs such as sigaction(), outside
+of Ada control.
+
+@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 an Ada handler via
+Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide
+some other action.
+@end itemize
+
+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 Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{89}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8a}
+@section Pragma Invariant
+
+
+Syntax:
+
+@example
+pragma Invariant
+ ([Entity =>] private_type_LOCAL_NAME,
+ [Check =>] EXPRESSION
+ [,[Message =>] String_Expression]);
+@end example
+
+This pragma provides exactly the same capabilities as the Type_Invariant aspect
+defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The
+Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it
+requires the use of the aspect syntax, which is not available except in 2012
+mode, it is not possible to use the Type_Invariant aspect in earlier versions
+of Ada. However the Invariant pragma may be used in any version of Ada. Also
+note that the aspect Invariant is a synonym in GNAT for the aspect
+Type_Invariant, but there is no pragma Type_Invariant.
+
+The pragma must appear within the visible part of the package specification,
+after the type to which its Entity argument appears. As with the Invariant
+aspect, the Check expression is not analyzed until the end of the visible
+part of the package, so it may contain forward references. The Message
+argument, if present, provides the exception message used if the invariant
+is violated. If no Message parameter is provided, a default message that
+identifies the line on which the pragma appears is used.
+
+It is permissible to have multiple Invariants for the same type entity, in
+which case they are and’ed together. It is permissible to use this pragma
+in Ada 2012 mode, but you cannot have both an invariant aspect and an
+invariant pragma for the same entity.
+
+For further details on the use of this pragma, see the Ada 2012 documentation
+of the Type_Invariant aspect.
+
+@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8b}
+@section Pragma Keep_Names
+
+
+Syntax:
+
+@example
+pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
+@end example
+
+The @code{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 @code{gnat.adc} file, but you
+want to retain the names for specific enumeration types.
+
+@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8c}
+@section Pragma License
+
+
+@geindex License checking
+
+Syntax:
+
+@example
+pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
+@end example
+
+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 @code{gnat.adc} file, specifies
+the licensing conditions of a unit as follows:
+
+
+@itemize *
+
+@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
+
+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.
+
+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.
+
+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:
+
+@example
+with Sem_Ch3;
+with GNAT.Sockets;
+procedure Secret_Stuff is
+ ...
+end Secret_Stuff
+@end example
+
+if compiled with pragma @code{License} (@code{Restricted}) in a
+@code{gnat.adc} file will generate the warning:
+
+@example
+1. with Sem_Ch3;
+ |
+ >>> license of withed unit "Sem_Ch3" is incompatible
+
+2. with GNAT.Sockets;
+3. procedure Secret_Stuff is
+@end example
+
+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,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8d}
+@section Pragma Link_With
+
+
+Syntax:
+
+@example
+pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
+@end example
+
+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:
+
+@example
+pragma Link_With ("-labc -ldef");
+@end example
+
+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,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8e}
+@section Pragma Linker_Alias
+
+
+Syntax:
+
+@example
+pragma Linker_Alias (
+ [Entity =>] LOCAL_NAME,
+ [Target =>] static_string_EXPRESSION);
+@end example
+
+@code{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 @code{LOCAL_NAME} to be emitted as an alias for the symbol
+@code{static_string_EXPRESSION} in the object file, that is to say no space
+is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved
+to the same address as @code{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 @code{LOCAL_NAME}.
+
+@example
+-- 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 example
+
+@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{8f}
+@section Pragma Linker_Constructor
+
+
+Syntax:
+
+@example
+pragma Linker_Constructor (procedure_LOCAL_NAME);
+@end example
+
+@code{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 @code{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,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{90}
+@section Pragma Linker_Destructor
+
+
+Syntax:
+
+@example
+pragma Linker_Destructor (procedure_LOCAL_NAME);
+@end example
+
+@code{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 @code{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,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{91}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{92}
+@section Pragma Linker_Section
+
+
+Syntax:
+
+@example
+pragma Linker_Section (
+ [Entity =>] LOCAL_NAME,
+ [Section =>] static_string_EXPRESSION);
+@end example
+
+@code{LOCAL_NAME} must refer to an object, type, or subprogram 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 @code{LOCAL_NAME} to
+be placed in the @code{static_string_EXPRESSION} section of the
+executable (assuming the linker doesn’t rename the section).
+GNAT also provides an implementation defined aspect of the same name.
+
+In the case of specifying this aspect for a type, the effect is to
+specify the corresponding section for all library-level objects of
+the type that do not have an explicit linker section set. Note that
+this only applies to whole objects, not to components of composite objects.
+
+In the case of a subprogram, the linker section applies to all previously
+declared matching overloaded subprograms in the current declarative part
+which do not already have a linker section assigned. The linker section
+aspect is useful in this case for specifying different linker sections
+for different elements of such an overloaded set.
+
+Note that an empty string specifies that no linker section is specified.
+This is not quite the same as omitting the pragma or aspect, since it
+can be used to specify that one element of an overloaded set of subprograms
+has the default linker section, or that one object of a type for which a
+linker section is specified should has the default linker section.
+
+The compiler normally places library-level entities in standard sections
+depending on the class: 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}.
+
+@example
+-- 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");
+
+ type Port_Type is new Integer with Linker_Section => ".bss";
+ PA : Port_Type with Linker_Section => ".bss.PA";
+ PB : Port_Type; -- ends up in linker section ".bss"
+
+ procedure Q with Linker_Section => "Qsection";
+end IO_Card;
+@end example
+
+@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{93}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{94}
+@section Pragma Lock_Free
+
+
+Syntax:
+This pragma may be specified for protected types or objects. It specifies that
+the implementation of protected operations must be implemented without locks.
+Compilation fails if the compiler cannot generate lock-free code for the
+operations.
+
+The current conditions required to support this pragma are:
+
+
+@itemize *
+
+@item
+Protected type declarations may not contain entries
+
+@item
+Protected subprogram declarations may not have nonelementary parameters
+@end itemize
+
+In addition, each protected subprogram body must satisfy:
+
+
+@itemize *
+
+@item
+May reference only one protected component
+
+@item
+May not reference nonconstant entities outside the protected subprogram
+scope
+
+@item
+May not contain address representation items, allocators, or quantified
+expressions
+
+@item
+May not contain delay, goto, loop, or procedure-call statements
+
+@item
+May not contain exported and imported entities
+
+@item
+May not dereferenced access values
+
+@item
+Function calls and attribute references must be static
+@end itemize
+
+If the Lock_Free aspect is specified to be True for a protected unit
+and the Ceiling_Locking locking policy is in effect, then the run-time
+actions associated with the Ceiling_Locking locking policy (described in
+Ada RM D.3) are not performed when a protected operation of the protected
+unit is executed.
+
+@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{95}
+@section Pragma Loop_Invariant
+
+
+Syntax:
+
+@example
+pragma Loop_Invariant ( boolean_EXPRESSION );
+@end example
+
+The effect of this pragma is similar to that of pragma @code{Assert},
+except that in an @code{Assertion_Policy} pragma, the identifier
+@code{Loop_Invariant} is used to control whether it is ignored or checked
+(or disabled).
+
+@code{Loop_Invariant} can only appear as one of the items in the sequence
+of statements of a loop body, or nested inside block statements that
+appear in the sequence of statements of a loop body.
+The intention is that it be used to
+represent a “loop invariant” assertion, i.e. something that is true each
+time through the loop, and which can be used to show that the loop is
+achieving its purpose.
+
+Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
+apply to the same loop should be grouped in the same sequence of
+statements.
+
+To aid in writing such invariants, the special attribute @code{Loop_Entry}
+may be used to refer to the value of an expression on entry to the loop. This
+attribute can only be used within the expression of a @code{Loop_Invariant}
+pragma. For full details, see documentation of attribute @code{Loop_Entry}.
+
+@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{96}
+@section Pragma Loop_Optimize
+
+
+Syntax:
+
+@example
+pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@});
+
+OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector
+@end example
+
+This pragma must appear immediately within a loop statement. It allows the
+programmer to specify optimization hints for the enclosing loop. The hints
+are not mutually exclusive and can be freely mixed, but not all combinations
+will yield a sensible outcome.
+
+There are five supported optimization hints for a loop:
+
+
+@itemize *
+
+@item
+Ivdep
+
+The programmer asserts that there are no loop-carried dependencies
+which would prevent consecutive iterations of the loop from being
+executed simultaneously.
+
+@item
+No_Unroll
+
+The loop must not be unrolled. This is a strong hint: the compiler will not
+unroll a loop marked with this hint.
+
+@item
+Unroll
+
+The loop should be unrolled. This is a weak hint: the compiler will try to
+apply unrolling to this loop preferably to other optimizations, notably
+vectorization, but there is no guarantee that the loop will be unrolled.
+
+@item
+No_Vector
+
+The loop must not be vectorized. This is a strong hint: the compiler will not
+vectorize a loop marked with this hint.
+
+@item
+Vector
+
+The loop should be vectorized. This is a weak hint: the compiler will try to
+apply vectorization to this loop preferably to other optimizations, notably
+unrolling, but there is no guarantee that the loop will be vectorized.
+@end itemize
+
+These hints do not remove the need to pass the appropriate switches to the
+compiler in order to enable the relevant optimizations, that is to say
+`-funroll-loops' for unrolling and `-ftree-vectorize' for
+vectorization.
+
+@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{97}
+@section Pragma Loop_Variant
+
+
+Syntax:
+
+@example
+pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} );
+LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION
+CHANGE_DIRECTION ::= Increases | Decreases
+@end example
+
+@code{Loop_Variant} can only appear as one of the items in the sequence
+of statements of a loop body, or nested inside block statements that
+appear in the sequence of statements of a loop body.
+It allows the specification of quantities which must always
+decrease or increase in successive iterations of the loop. In its simplest
+form, just one expression is specified, whose value must increase or decrease
+on each iteration of the loop.
+
+In a more complex form, multiple arguments can be given which are interpreted
+in a nesting lexicographic manner. For example:
+
+@example
+pragma Loop_Variant (Increases => X, Decreases => Y);
+@end example
+
+specifies that each time through the loop either X increases, or X stays
+the same and Y decreases. A @code{Loop_Variant} pragma ensures that the
+loop is making progress. It can be useful in helping to show informally
+or prove formally that the loop always terminates.
+
+@code{Loop_Variant} is an assertion whose effect can be controlled using
+an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The
+policy can be @code{Check} to enable the loop variant check, @code{Ignore}
+to ignore the check (in which case the pragma has no effect on the program),
+or @code{Disable} in which case the pragma is not even checked for correct
+syntax.
+
+Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
+apply to the same loop should be grouped in the same sequence of
+statements.
+
+The @code{Loop_Entry} attribute may be used within the expressions of the
+@code{Loop_Variant} pragma to refer to values on entry to the loop.
+
+@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{98}
+@section Pragma Machine_Attribute
+
+
+Syntax:
+
+@example
+pragma Machine_Attribute (
+ [Entity =>] LOCAL_NAME,
+ [Attribute_Name =>] static_string_EXPRESSION
+ [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] );
+@end example
+
+Machine-dependent attributes can be specified for types and/or
+declarations. This pragma is semantically equivalent to
+@code{__attribute__((@var{attribute_name}))} (if @code{info} is not
+specified) or @code{__attribute__((@var{attribute_name(info})))}
+or @code{__attribute__((@var{attribute_name(info,...})))} in GNU C,
+where `attribute_name' is recognized by the compiler middle-end
+or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note
+that a string literal for the optional parameter @code{info} or the
+following ones is transformed by default into an identifier,
+which may make this pragma unusable for some attributes.
+For further information see @cite{GNU Compiler Collection (GCC) Internals}.
+
+@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{99}
+@section Pragma Main
+
+
+Syntax:
+
+@example
+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 example
+
+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,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9a}
+@section Pragma Main_Storage
+
+
+Syntax:
+
+@example
+pragma Main_Storage
+ (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
+
+MAIN_STORAGE_OPTION ::=
+ [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
+| [TOP_GUARD =>] static_SIMPLE_EXPRESSION
+@end example
+
+This pragma is provided for compatibility with OpenVMS VAX Systems. It has
+no effect in GNAT, other than being syntax checked.
+
+@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9b}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9c}
+@section Pragma Max_Queue_Length
+
+
+Syntax:
+
+@example
+pragma Max_Entry_Queue (static_integer_EXPRESSION);
+@end example
+
+This pragma is used to specify the maximum callers per entry queue for
+individual protected entries and entry families. It accepts a single
+integer (-1 or more) as a parameter and must appear after the declaration of an
+entry.
+
+A value of -1 represents no additional restriction on queue length.
+
+@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9d}
+@section Pragma No_Body
+
+
+Syntax:
+
+@example
+pragma No_Body;
+@end example
+
+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_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{9f}
+@section Pragma No_Caching
+
+
+Syntax:
+
+@example
+pragma No_Caching [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{No_Caching} in
+the SPARK 2014 Reference Manual, section 7.1.2.
+
+@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a0}
+@section Pragma No_Component_Reordering
+
+
+Syntax:
+
+@example
+pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)];
+@end example
+
+@code{type_LOCAL_NAME} must refer to a record type declaration in the current
+declarative part. The effect is to preclude any reordering of components
+for the layout of the record, i.e. the record is laid out by the compiler
+in the order in which the components are declared textually. The form with
+no argument is a configuration pragma which applies to all record types
+declared in units to which the pragma applies and there is a requirement
+that this pragma be used consistently within a partition.
+
+@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a2}
+@section Pragma No_Elaboration_Code_All
+
+
+Syntax:
+
+@example
+pragma No_Elaboration_Code_All [(program_unit_NAME)];
+@end example
+
+This is a program unit pragma (there is also an equivalent aspect of the
+same name) that establishes the restriction @code{No_Elaboration_Code} for
+the current unit and any extended main source units (body and subunits).
+It also has the effect of enforcing a transitive application of this
+aspect, so that if any unit is implicitly or explicitly with’ed by the
+current unit, it must also have the No_Elaboration_Code_All aspect set.
+It may be applied to package or subprogram specs or their generic versions.
+
+@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a3}
+@section Pragma No_Heap_Finalization
+
+
+Syntax:
+
+@example
+pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
+@end example
+
+Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a
+type-specific pragma.
+
+In its configuration form, the pragma must appear within a configuration file
+such as gnat.adc, without an argument. The pragma suppresses the call to
+@code{Finalize} for heap-allocated objects created through library-level named
+access-to-object types in cases where the designated type requires finalization
+actions.
+
+In its type-specific form, the argument of the pragma must denote a
+library-level named access-to-object type. The pragma suppresses the call to
+@code{Finalize} for heap-allocated objects created through the specific access type
+in cases where the designated type requires finalization actions.
+
+It is still possible to finalize such heap-allocated objects by explicitly
+deallocating them.
+
+A library-level named access-to-object type declared within a generic unit will
+lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not
+appear at the library level.
+
+@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a4}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a5}
+@section Pragma No_Inline
+
+
+Syntax:
+
+@example
+pragma No_Inline (NAME @{, NAME@});
+@end example
+
+This pragma suppresses inlining for the callable entity or the instances of
+the generic subprogram designated by @code{NAME}, including inlining that
+results from the use of pragma @code{Inline}. This pragma is always active,
+in particular it is not subject to the use of option `-gnatn' or
+`-gnatN'. It is illegal to specify both pragma @code{No_Inline} and
+pragma @code{Inline_Always} for the same @code{NAME}.
+
+@node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a6}
+@section Pragma No_Return
+
+
+Syntax:
+
+@example
+pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
+@end example
+
+Each @code{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. It is
+available in all earlier versions of Ada as an implementation-defined
+pragma.
+
+@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a7}
+@section Pragma No_Strict_Aliasing
+
+
+Syntax:
+
+@example
+pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
+@end example
+
+@code{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 the section on Optimization and Strict Aliasing
+in the @cite{GNAT User’s Guide}.
+
+This pragma currently has no effects on access to unconstrained array types.
+
+@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a8}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a9}
+@section Pragma No_Tagged_Streams
+
+
+Syntax:
+
+@example
+pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)];
+@end example
+
+Normally when a tagged type is introduced using a full type declaration,
+part of the processing includes generating stream access routines to be
+used by stream attributes referencing the type (or one of its subtypes
+or derived types). This can involve the generation of significant amounts
+of code which is wasted space if stream routines are not needed for the
+type in question.
+
+The @code{No_Tagged_Streams} pragma causes the generation of these stream
+routines to be skipped, and any attempt to use stream operations on
+types subject to this pragma will be statically rejected as illegal.
+
+There are two forms of the pragma. The form with no arguments must appear
+in a declarative sequence or in the declarations of a package spec. This
+pragma affects all subsequent root tagged types declared in the declaration
+sequence, and specifies that no stream routines be generated. The form with
+an argument (for which there is also a corresponding aspect) specifies a
+single root tagged type for which stream routines are not to be generated.
+
+Once the pragma has been given for a particular root tagged type, all subtypes
+and derived types of this type inherit the pragma automatically, so the effect
+applies to a complete hierarchy (this is necessary to deal with the class-wide
+dispatching versions of the stream routines).
+
+When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously
+applied to a tagged type its Expanded_Name and External_Tag are initialized
+with empty strings. This is useful to avoid exposing entity names at binary
+level but has a negative impact on the debuggability of tagged types.
+
+@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{aa}
+@section Pragma Normalize_Scalars
+
+
+Syntax:
+
+@example
+pragma Normalize_Scalars;
+@end example
+
+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 @asis
+
+@item `Standard.Character'
+
+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'
+
+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'
+
+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'
+
+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,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ab}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ac}
+@section Pragma Obsolescent
+
+
+Syntax:
+
+@example
+pragma Obsolescent;
+
+pragma Obsolescent (
+ [Message =>] static_string_EXPRESSION
+[,[Version =>] Ada_05]);
+
+pragma Obsolescent (
+ [Entity =>] NAME
+[,[Message =>] static_string_EXPRESSION
+[,[Version =>] Ada_05]]);
+@end example
+
+This pragma can occur immediately following a declaration of an entity,
+including the case of a record component. If no Entity argument is present,
+then this declaration is the one to which the pragma applies. If an Entity
+parameter is present, it must either match the name of the entity in this
+declaration, or 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 reference to
+an entity thus marked that the subprogram is obsolescent if the appropriate
+warning option in the compiler is activated. If the @code{Message} parameter is
+present, then a second warning message is given containing this text. In
+addition, a reference to the entity is considered to be a violation of pragma
+@code{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} clause is
+flagged with warnings if the warning option is set.
+
+If the @code{Version} parameter is present (which must be exactly
+the identifier @code{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 @code{Ada.Characters.Handling}), but may be used anywhere.
+
+The following examples show typical uses of this pragma:
+
+@example
+package p is
+ pragma Obsolescent (p, Message => "use pp instead of p");
+end p;
+
+package q is
+ procedure q2;
+ pragma Obsolescent ("use q2new instead");
+
+ type R is new integer;
+ pragma Obsolescent
+ (Entity => R,
+ Message => "use RR in Ada 2005",
+ Version => Ada_05);
+
+ type M is record
+ F1 : Integer;
+ F2 : Integer;
+ pragma Obsolescent;
+ 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 example
+
+Note that, as for all pragmas, if you use a pragma argument identifier,
+then all subsequent parameters must also use a pragma argument identifier.
+So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message}
+argument is present, it must be preceded by @code{Message =>}.
+
+@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ad}
+@section Pragma Optimize_Alignment
+
+
+@geindex Alignment
+@geindex default settings
+
+Syntax:
+
+@example
+pragma Optimize_Alignment (TIME | SPACE | OFF);
+@end example
+
+This is a configuration pragma which affects the choice of default alignments
+for types and objects 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 for types
+and individual alignment promotions for objects (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:
+
+@example
+type R is record
+ X : Integer;
+ Y : Character;
+end record;
+
+for R'Size use 5*8;
+@end example
+
+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.
+
+However, there is one case in which SPACE is ignored. If a variable length
+record (that is a discriminated record with a component which is an array
+whose length depends on a discriminant), has a pragma Pack, then it is not
+in general possible to set the alignment of such a record to one, so the
+pragma is ignored in this case (with a warning).
+
+Specifying SPACE also disables alignment promotions for standalone objects,
+which occur when the compiler increases the alignment of a specific object
+without changing the alignment of its type.
+
+Specifying SPACE also disables component reordering in unpacked record types,
+which can result in larger sizes in order to meet alignment requirements.
+
+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:
+
+@example
+type R is record
+ A : Character;
+ B : Character;
+ C : Boolean;
+end record;
+
+pragma Pack (R);
+for R'Size use 17;
+@end example
+
+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 Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{ae}
+@section Pragma Ordered
+
+
+Syntax:
+
+@example
+pragma Ordered (enumeration_first_subtype_LOCAL_NAME);
+@end example
+
+Most enumeration types are from a conceptual point of view unordered.
+For example, consider:
+
+@example
+type Color is (Red, Blue, Green, Yellow);
+@end example
+
+By Ada semantics @code{Blue > Red} and @code{Green > Blue},
+but really these relations make no sense; the enumeration type merely
+specifies a set of possible colors, and the order is unimportant.
+
+For unordered enumeration types, it is generally a good idea if
+clients avoid comparisons (other than equality or inequality) and
+explicit ranges. (A `client' is a unit where the type is referenced,
+other than the unit where the type is declared, its body, and its subunits.)
+For example, if code buried in some client says:
+
+@example
+if Current_Color < Yellow then ...
+if Current_Color in Blue .. Green then ...
+@end example
+
+then the client code is relying on the order, which is undesirable.
+It makes the code hard to read and creates maintenance difficulties if
+entries have to be added to the enumeration type. Instead,
+the code in the client should list the possibilities, or an
+appropriate subtype should be declared in the unit that declares
+the original enumeration type. E.g., the following subtype could
+be declared along with the type @code{Color}:
+
+@example
+subtype RBG is Color range Red .. Green;
+@end example
+
+and then the client could write:
+
+@example
+if Current_Color in RBG then ...
+if Current_Color = Blue or Current_Color = Green then ...
+@end example
+
+However, some enumeration types are legitimately ordered from a conceptual
+point of view. For example, if you declare:
+
+@example
+type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
+@end example
+
+then the ordering imposed by the language is reasonable, and
+clients can depend on it, writing for example:
+
+@example
+if D in Mon .. Fri then ...
+if D < Wed then ...
+@end example
+
+The pragma `Ordered' is provided to mark enumeration types that
+are conceptually ordered, alerting the reader that clients may depend
+on the ordering. GNAT provides a pragma to mark enumerations as ordered
+rather than one to mark them as unordered, since in our experience,
+the great majority of enumeration types are conceptually unordered.
+
+The types @code{Boolean}, @code{Character}, @code{Wide_Character},
+and @code{Wide_Wide_Character}
+are considered to be ordered types, so each is declared with a
+pragma @code{Ordered} in package @code{Standard}.
+
+Normally pragma @code{Ordered} serves only as documentation and a guide for
+coding standards, but GNAT provides a warning switch `-gnatw.u' that
+requests warnings for inappropriate uses (comparisons and explicit
+subranges) for unordered types. If this switch is used, then any
+enumeration type not marked with pragma @code{Ordered} will be considered
+as unordered, and will generate warnings for inappropriate uses.
+
+Note that generic types are not considered ordered or unordered (since the
+template can be instantiated for both cases), so we never generate warnings
+for the case of generic enumerated types.
+
+For additional information please refer to the description of the
+`-gnatw.u' switch in the GNAT User’s Guide.
+
+@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{af}
+@section Pragma Overflow_Mode
+
+
+Syntax:
+
+@example
+pragma Overflow_Mode
+ ( [General =>] MODE
+ [,[Assertions =>] MODE]);
+
+MODE ::= STRICT | MINIMIZED | ELIMINATED
+@end example
+
+This pragma sets the current overflow mode to the given setting. For details
+of the meaning of these modes, please refer to the
+‘Overflow Check Handling in GNAT’ appendix in the
+GNAT User’s Guide. If only the @code{General} parameter is present,
+the given mode applies to all expressions. If both parameters are present,
+the @code{General} mode applies to expressions outside assertions, and
+the @code{Eliminated} mode applies to expressions within assertions.
+
+The case of the @code{MODE} parameter is ignored,
+so @code{MINIMIZED}, @code{Minimized} and
+@code{minimized} all have the same effect.
+
+The @code{Overflow_Mode} pragma has the same scoping and placement
+rules as pragma @code{Suppress}, so it can occur either as a
+configuration pragma, specifying a default for the whole
+program, or in a declarative scope, where it applies to the
+remaining declarations and statements in that scope.
+
+The pragma @code{Suppress (Overflow_Check)} suppresses
+overflow checking, but does not affect the overflow mode.
+
+The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables)
+overflow checking, but does not affect the overflow mode.
+
+@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b0}
+@section Pragma Overriding_Renamings
+
+
+@geindex Rational profile
+
+@geindex Rational compatibility
+
+Syntax:
+
+@example
+pragma Overriding_Renamings;
+@end example
+
+This is a GNAT configuration pragma to simplify porting
+legacy code accepted by the Rational
+Ada compiler. In the presence of this pragma, a renaming declaration that
+renames an inherited operation declared in the same scope is legal if selected
+notation is used as in:
+
+@example
+pragma Overriding_Renamings;
+...
+package R is
+ function F (..);
+ ...
+ function F (..) renames R.F;
+end R;
+@end example
+
+even though
+RM 8.3 (15) stipulates that an overridden operation is not visible within the
+declaration of the overriding operation.
+
+@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b1}
+@section Pragma Partition_Elaboration_Policy
+
+
+Syntax:
+
+@example
+pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER);
+
+POLICY_IDENTIFIER ::= Concurrent | Sequential
+@end example
+
+This pragma is standard in Ada 2005, but is available in all earlier
+versions of Ada as an implementation-defined pragma.
+See Ada 2012 Reference Manual for details.
+
+@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b2}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b3}
+@section Pragma Part_Of
+
+
+Syntax:
+
+@example
+pragma Part_Of (ABSTRACT_STATE);
+
+ABSTRACT_STATE ::= NAME
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the
+SPARK 2014 Reference Manual, section 7.2.6.
+
+@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b4}
+@section Pragma Passive
+
+
+Syntax:
+
+@example
+pragma Passive [(Semaphore | No)];
+@end example
+
+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).
+
+For more information on the subject of passive tasks, see the section
+‘Passive Task Optimization’ in the GNAT Users Guide.
+
+@node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b5}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b6}
+@section Pragma Persistent_BSS
+
+
+Syntax:
+
+@example
+pragma Persistent_BSS [(LOCAL_NAME)]
+@end example
+
+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 an untagged,
+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 Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b7}
+@section Pragma Post
+
+
+@geindex Post
+
+@geindex Checks
+@geindex postconditions
+
+Syntax:
+
+@example
+pragma Post (Boolean_Expression);
+@end example
+
+The @code{Post} pragma is intended to be an exact replacement for
+the language-defined
+@code{Post} aspect, and shares its restrictions and semantics.
+It must appear either immediately following the corresponding
+subprogram declaration (only other pragmas may intervene), or
+if there is no separate subprogram declaration, then it can
+appear at the start of the declarations in a subprogram body
+(preceded only by other pragmas).
+
+@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b8}
+@section Pragma Postcondition
+
+
+@geindex Postcondition
+
+@geindex Checks
+@geindex postconditions
+
+Syntax:
+
+@example
+pragma Postcondition (
+ [Check =>] Boolean_Expression
+ [,[Message =>] String_Expression]);
+@end example
+
+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 (including
+implicit returns at the end of procedure bodies and associated
+exception handlers).
+
+In addition, 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 immediately 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 `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:
+
+@example
+function Direction return Integer;
+pragma Postcondition
+ (Direction'Result = +1
+ or else
+ Direction'Result = -1);
+@end example
+
+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:
+
+@example
+Sqrt_Calls : Natural := 0;
+
+function Sqrt (Arg : Float) return Float is
+ pragma Postcondition
+ (Sqrt_Calls = Sqrt_Calls'Old + 1);
+ ...
+end Sqrt
+@end example
+
+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_name: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:
+
+@example
+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 example
+
+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.
+
+@example
+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 example
+
+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.
+
+Note that pragma @code{Postcondition} differs from the language-defined
+@code{Post} aspect (and corresponding @code{Post} pragma) in allowing
+multiple occurrences, allowing occurences in the body even if there
+is a separate spec, and allowing a second string parameter, and the
+use of the pragma identifier @code{Check}. Historically, pragma
+@code{Postcondition} was implemented prior to the development of
+Ada 2012, and has been retained in its original form for
+compatibility purposes.
+
+@node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{b9}
+@section Pragma Post_Class
+
+
+@geindex Post
+
+@geindex Checks
+@geindex postconditions
+
+Syntax:
+
+@example
+pragma Post_Class (Boolean_Expression);
+@end example
+
+The @code{Post_Class} pragma is intended to be an exact replacement for
+the language-defined
+@code{Post'Class} aspect, and shares its restrictions and semantics.
+It must appear either immediately following the corresponding
+subprogram declaration (only other pragmas may intervene), or
+if there is no separate subprogram declaration, then it can
+appear at the start of the declarations in a subprogram body
+(preceded only by other pragmas).
+
+Note: This pragma is called @code{Post_Class} rather than
+@code{Post'Class} because the latter would not be strictly
+conforming to the allowed syntax for pragmas. The motivation
+for providing pragmas equivalent to the aspects is to allow a program
+to be written using the pragmas, and then compiled if necessary
+using an Ada compiler that does not recognize the pragmas or
+aspects, but is prepared to ignore the pragmas. The assertion
+policy that controls this pragma is @code{Post'Class}, not
+@code{Post_Class}.
+
+@node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{ba}
+@section Pragma Pre
+
+
+@geindex Pre
+
+@geindex Checks
+@geindex preconditions
+
+Syntax:
+
+@example
+pragma Pre (Boolean_Expression);
+@end example
+
+The @code{Pre} pragma is intended to be an exact replacement for
+the language-defined
+@code{Pre} aspect, and shares its restrictions and semantics.
+It must appear either immediately following the corresponding
+subprogram declaration (only other pragmas may intervene), or
+if there is no separate subprogram declaration, then it can
+appear at the start of the declarations in a subprogram body
+(preceded only by other pragmas).
+
+@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bb}
+@section Pragma Precondition
+
+
+@geindex Preconditions
+
+@geindex Checks
+@geindex preconditions
+
+Syntax:
+
+@example
+pragma Precondition (
+ [Check =>] Boolean_Expression
+ [,[Message =>] String_Expression]);
+@end example
+
+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:
+
+@example
+package Math_Functions is
+ ...
+ function Sqrt (Arg : Float) return Float;
+ pragma Precondition (Arg >= 0.0)
+ ...
+end Math_Functions;
+@end example
+
+@code{Precondition} pragmas may appear either immediately 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: precondition 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 precondition
+checking is enabled.
+
+Note that pragma @code{Precondition} differs from the language-defined
+@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing
+multiple occurrences, allowing occurences in the body even if there
+is a separate spec, and allowing a second string parameter, and the
+use of the pragma identifier @code{Check}. Historically, pragma
+@code{Precondition} was implemented prior to the development of
+Ada 2012, and has been retained in its original form for
+compatibility purposes.
+
+@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{bc}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{bd}
+@section Pragma Predicate
+
+
+Syntax:
+
+@example
+pragma Predicate
+ ([Entity =>] type_LOCAL_NAME,
+ [Check =>] EXPRESSION);
+@end example
+
+This pragma (available in all versions of Ada in GNAT) encompasses both
+the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in
+Ada 2012. A predicate is regarded as static if it has an allowed form
+for @code{Static_Predicate} and is otherwise treated as a
+@code{Dynamic_Predicate}. Otherwise, predicates specified by this
+pragma behave exactly as described in the Ada 2012 reference manual.
+For example, if we have
+
+@example
+type R is range 1 .. 10;
+subtype S is R;
+pragma Predicate (Entity => S, Check => S not in 4 .. 6);
+subtype Q is R
+pragma Predicate (Entity => Q, Check => F(Q) or G(Q));
+@end example
+
+the effect is identical to the following Ada 2012 code:
+
+@example
+type R is range 1 .. 10;
+subtype S is R with
+ Static_Predicate => S not in 4 .. 6;
+subtype Q is R with
+ Dynamic_Predicate => F(Q) or G(Q);
+@end example
+
+Note that there are no pragmas @code{Dynamic_Predicate}
+or @code{Static_Predicate}. That is
+because these pragmas would affect legality and semantics of
+the program and thus do not have a neutral effect if ignored.
+The motivation behind providing pragmas equivalent to
+corresponding aspects is to allow a program to be written
+using the pragmas, and then compiled with a compiler that
+will ignore the pragmas. That doesn’t work in the case of
+static and dynamic predicates, since if the corresponding
+pragmas are ignored, then the behavior of the program is
+fundamentally changed (for example a membership test
+@code{A in B} would not take into account a predicate
+defined for subtype B). When following this approach, the
+use of predicates should be avoided.
+
+@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{be}
+@section Pragma Predicate_Failure
+
+
+Syntax:
+
+@example
+pragma Predicate_Failure
+ ([Entity =>] type_LOCAL_NAME,
+ [Message =>] String_Expression);
+@end example
+
+The @code{Predicate_Failure} pragma is intended to be an exact replacement for
+the language-defined
+@code{Predicate_Failure} aspect, and shares its restrictions and semantics.
+
+@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{bf}
+@section Pragma Preelaborable_Initialization
+
+
+Syntax:
+
+@example
+pragma Preelaborable_Initialization (DIRECT_NAME);
+@end example
+
+This pragma is standard in Ada 2005, but is available in all earlier
+versions of Ada as an implementation-defined pragma.
+See Ada 2012 Reference Manual for details.
+
+@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c0}
+@section Pragma Prefix_Exception_Messages
+
+
+@geindex Prefix_Exception_Messages
+
+@geindex exception
+
+@geindex Exception_Message
+
+Syntax:
+
+@example
+pragma Prefix_Exception_Messages;
+@end example
+
+This is an implementation-defined configuration pragma that affects the
+behavior of raise statements with a message given as a static string
+constant (typically a string literal). In such cases, the string will
+be automatically prefixed by the name of the enclosing entity (giving
+the package and subprogram containing the raise statement). This helps
+to identify where messages are coming from, and this mode is automatic
+for the run-time library.
+
+The pragma has no effect if the message is computed with an expression other
+than a static string constant, since the assumption in this case is that
+the program computes exactly the string it wants. If you still want the
+prefixing in this case, you can always call
+@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually.
+
+@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c1}
+@section Pragma Pre_Class
+
+
+@geindex Pre_Class
+
+@geindex Checks
+@geindex preconditions
+
+Syntax:
+
+@example
+pragma Pre_Class (Boolean_Expression);
+@end example
+
+The @code{Pre_Class} pragma is intended to be an exact replacement for
+the language-defined
+@code{Pre'Class} aspect, and shares its restrictions and semantics.
+It must appear either immediately following the corresponding
+subprogram declaration (only other pragmas may intervene), or
+if there is no separate subprogram declaration, then it can
+appear at the start of the declarations in a subprogram body
+(preceded only by other pragmas).
+
+Note: This pragma is called @code{Pre_Class} rather than
+@code{Pre'Class} because the latter would not be strictly
+conforming to the allowed syntax for pragmas. The motivation
+for providing pragmas equivalent to the aspects is to allow a program
+to be written using the pragmas, and then compiled if necessary
+using an Ada compiler that does not recognize the pragmas or
+aspects, but is prepared to ignore the pragmas. The assertion
+policy that controls this pragma is @code{Pre'Class}, not
+@code{Pre_Class}.
+
+@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c2}
+@section Pragma Priority_Specific_Dispatching
+
+
+Syntax:
+
+@example
+pragma Priority_Specific_Dispatching (
+ POLICY_IDENTIFIER,
+ first_priority_EXPRESSION,
+ last_priority_EXPRESSION)
+
+POLICY_IDENTIFIER ::=
+ EDF_Across_Priorities |
+ FIFO_Within_Priorities |
+ Non_Preemptive_Within_Priorities |
+ Round_Robin_Within_Priorities
+@end example
+
+This pragma is standard in Ada 2005, but is available in all earlier
+versions of Ada as an implementation-defined pragma.
+See Ada 2012 Reference Manual for details.
+
+@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c3}
+@section Pragma Profile
+
+
+Syntax:
+
+@example
+pragma Profile (Ravenscar | Restricted | Rational | Jorvik |
+ GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF );
+@end example
+
+This pragma is standard in Ada 2005, but is available in all earlier
+versions of Ada as an implementation-defined pragma. This is a
+configuration pragma that establishes a set of configuration pragmas
+that depend on the argument. @code{Ravenscar} is standard in Ada 2005.
+@code{Jorvik} is standard in Ada 202x.
+The other possibilities (@code{Restricted}, @code{Rational},
+@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF})
+are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}.
+
+The set of configuration pragmas is defined in the following sections.
+
+
+@itemize *
+
+@item
+Pragma Profile (Ravenscar)
+
+The @code{Ravenscar} profile is standard in Ada 2005,
+but is available in all earlier
+versions of Ada as an implementation-defined pragma. This profile
+establishes the following set of configuration pragmas:
+
+
+@itemize *
+
+@item
+@code{Task_Dispatching_Policy (FIFO_Within_Priorities)}
+
+[RM D.2.2] Tasks are dispatched following a preemptive
+priority-ordered scheduling policy.
+
+@item
+@code{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.
+
+@item
+@code{Detect_Blocking}
+
+This pragma forces the detection of potentially blocking operations within a
+protected operation, and to raise Program_Error if that happens.
+@end itemize
+
+plus the following set of restrictions:
+
+
+@itemize *
+
+@item
+@code{Max_Entry_Queue_Length => 1}
+
+No task can be queued on a protected entry.
+
+@item
+@code{Max_Protected_Entries => 1}
+
+@item
+@code{Max_Task_Entries => 0}
+
+No rendezvous statements are allowed.
+
+@item
+@code{No_Abort_Statements}
+
+@item
+@code{No_Dynamic_Attachment}
+
+@item
+@code{No_Dynamic_Priorities}
+
+@item
+@code{No_Implicit_Heap_Allocations}
+
+@item
+@code{No_Local_Protected_Objects}
+
+@item
+@code{No_Local_Timing_Events}
+
+@item
+@code{No_Protected_Type_Allocators}
+
+@item
+@code{No_Relative_Delay}
+
+@item
+@code{No_Requeue_Statements}
+
+@item
+@code{No_Select_Statements}
+
+@item
+@code{No_Specific_Termination_Handlers}
+
+@item
+@code{No_Task_Allocators}
+
+@item
+@code{No_Task_Hierarchy}
+
+@item
+@code{No_Task_Termination}
+
+@item
+@code{Simple_Barriers}
+@end itemize
+
+The Ravenscar profile also includes the following restrictions that specify
+that there are no semantic dependencies on the corresponding predefined
+packages:
+
+
+@itemize *
+
+@item
+@code{No_Dependence => Ada.Asynchronous_Task_Control}
+
+@item
+@code{No_Dependence => Ada.Calendar}
+
+@item
+@code{No_Dependence => Ada.Execution_Time.Group_Budget}
+
+@item
+@code{No_Dependence => Ada.Execution_Time.Timers}
+
+@item
+@code{No_Dependence => Ada.Task_Attributes}
+
+@item
+@code{No_Dependence => System.Multiprocessors.Dispatching_Domains}
+@end itemize
+
+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@comma{} 1997}.
+A description is also available at
+@indicateurl{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 was made part of the Ada 2005 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
+@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and
+@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}.
+
+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 library.
+
+@item
+Pragma Profile (Jorvik)
+
+@code{Jorvik} is the new profile added to the Ada 202x draft standard,
+previously implemented under the name @code{GNAT_Extended_Ravenscar}.
+
+The @code{No_Implicit_Heap_Allocations} restriction has been replaced
+by @code{No_Implicit_Task_Allocations} and
+@code{No_Implicit_Protected_Object_Allocations}.
+
+The @code{Simple_Barriers} restriction has been replaced by
+@code{Pure_Barriers}.
+
+The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and
+@code{No_Relative_Delay} restrictions have been removed.
+
+Details on the rationale for @code{Jorvik} and implications for use may be
+found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz,
+T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science,
+Number 10300.
+
+@item
+Pragma Profile (GNAT_Ravenscar_EDF)
+
+This profile corresponds to the Ravenscar profile but using
+EDF_Across_Priority as the Task_Scheduling_Policy.
+
+@item
+Pragma Profile (Restricted)
+
+This profile corresponds to the GNAT restricted run time. It
+establishes the following set of restrictions:
+
+
+@itemize *
+
+@item
+@code{No_Abort_Statements}
+
+@item
+@code{No_Entry_Queue}
+
+@item
+@code{No_Task_Hierarchy}
+
+@item
+@code{No_Task_Allocators}
+
+@item
+@code{No_Dynamic_Priorities}
+
+@item
+@code{No_Terminate_Alternatives}
+
+@item
+@code{No_Dynamic_Attachment}
+
+@item
+@code{No_Protected_Type_Allocators}
+
+@item
+@code{No_Local_Protected_Objects}
+
+@item
+@code{No_Requeue_Statements}
+
+@item
+@code{No_Task_Attributes_Package}
+
+@item
+@code{Max_Asynchronous_Select_Nesting = 0}
+
+@item
+@code{Max_Task_Entries = 0}
+
+@item
+@code{Max_Protected_Entries = 1}
+
+@item
+@code{Max_Select_Alternatives = 0}
+@end itemize
+
+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.
+
+@item
+Pragma Profile (Rational)
+
+The Rational profile is intended to facilitate porting legacy code that
+compiles with the Rational APEX compiler, even when the code includes non-
+conforming Ada constructs. The profile enables the following three pragmas:
+
+
+@itemize *
+
+@item
+@code{pragma Implicit_Packing}
+
+@item
+@code{pragma Overriding_Renamings}
+
+@item
+@code{pragma Use_VADS_Size}
+@end itemize
+@end itemize
+
+@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c4}
+@section Pragma Profile_Warnings
+
+
+Syntax:
+
+@example
+pragma Profile_Warnings (Ravenscar | Restricted | Rational);
+@end example
+
+This is an implementation-defined pragma that is similar in
+effect to @code{pragma Profile} except that instead of
+generating @code{Restrictions} pragmas, it generates
+@code{Restriction_Warnings} pragmas. The result is that
+violations of the profile generate warning messages instead
+of error messages.
+
+@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c5}
+@section Pragma Propagate_Exceptions
+
+
+@geindex Interfacing to C++
+
+Syntax:
+
+@example
+pragma Propagate_Exceptions;
+@end example
+
+This pragma is now obsolete and, other than generating a warning if warnings
+on obsolescent features are enabled, is ignored.
+It is retained for compatibility
+purposes. It used to be used in connection with optimization of
+a now-obsolete mechanism for implementation of exceptions.
+
+@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c6}
+@section Pragma Provide_Shift_Operators
+
+
+@geindex Shift operators
+
+Syntax:
+
+@example
+pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME);
+@end example
+
+This pragma can be applied to a first subtype local name that specifies
+either an unsigned or signed type. It has the effect of providing the
+five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic,
+Rotate_Left and Rotate_Right) for the given type. It is similar to
+including the function declarations for these five operators, together
+with the pragma Import (Intrinsic, …) statements.
+
+@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c7}
+@section Pragma Psect_Object
+
+
+Syntax:
+
+@example
+pragma Psect_Object (
+ [Internal =>] LOCAL_NAME,
+ [, [External =>] EXTERNAL_SYMBOL]
+ [, [Size =>] EXTERNAL_SYMBOL]);
+
+EXTERNAL_SYMBOL ::=
+ IDENTIFIER
+| static_string_EXPRESSION
+@end example
+
+This pragma is identical in effect to pragma @code{Common_Object}.
+
+@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{c8}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{c9}
+@section Pragma Pure_Function
+
+
+Syntax:
+
+@example
+pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
+@end example
+
+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 identical calls produce the same result in
+the same context. 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).
+
+Note also that the normal rules excluding optimization of subprograms
+in pure units (when parameter types are descended from System.Address,
+or when the full view of a parameter type is limited), do not apply
+for the Pure_Function case. If you explicitly specify Pure_Function,
+the compiler may optimize away calls with identical arguments, and
+if that results in unexpected behavior, the proper action is not to
+use the pragma for subprograms that are not (conceptually) 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 Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{ca}
+@section Pragma Rational
+
+
+Syntax:
+
+@example
+pragma Rational;
+@end example
+
+This pragma is considered obsolescent, but is retained for
+compatibility purposes. It is equivalent to:
+
+@example
+pragma Profile (Rational);
+@end example
+
+@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cb}
+@section Pragma Ravenscar
+
+
+Syntax:
+
+@example
+pragma Ravenscar;
+@end example
+
+This pragma is considered obsolescent, but is retained for
+compatibility purposes. It is equivalent to:
+
+@example
+pragma Profile (Ravenscar);
+@end example
+
+which is the preferred method of setting the @code{Ravenscar} profile.
+
+@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cc}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{cd}
+@section Pragma Refined_Depends
+
+
+Syntax:
+
+@example
+pragma Refined_Depends (DEPENDENCY_RELATION);
+
+DEPENDENCY_RELATION ::=
+ null
+ | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
+
+DEPENDENCY_CLAUSE ::=
+ OUTPUT_LIST =>[+] INPUT_LIST
+ | NULL_DEPENDENCY_CLAUSE
+
+NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
+
+OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
+
+INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
+
+OUTPUT ::= NAME | FUNCTION_RESULT
+INPUT ::= NAME
+
+where FUNCTION_RESULT is a function Result attribute_reference
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in
+the SPARK 2014 Reference Manual, section 6.1.5.
+
+@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{cf}
+@section Pragma Refined_Global
+
+
+Syntax:
+
+@example
+pragma Refined_Global (GLOBAL_SPECIFICATION);
+
+GLOBAL_SPECIFICATION ::=
+ null
+ | (GLOBAL_LIST)
+ | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
+
+MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
+
+MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
+GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
+GLOBAL_ITEM ::= NAME
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in
+the SPARK 2014 Reference Manual, section 6.1.4.
+
+@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d1}
+@section Pragma Refined_Post
+
+
+Syntax:
+
+@example
+pragma Refined_Post (boolean_EXPRESSION);
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in
+the SPARK 2014 Reference Manual, section 7.2.7.
+
+@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d3}
+@section Pragma Refined_State
+
+
+Syntax:
+
+@example
+pragma Refined_State (REFINEMENT_LIST);
+
+REFINEMENT_LIST ::=
+ (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@})
+
+REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST
+
+CONSTITUENT_LIST ::=
+ null
+ | CONSTITUENT
+ | (CONSTITUENT @{, CONSTITUENT@})
+
+CONSTITUENT ::= object_NAME | state_NAME
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Refined_State} in
+the SPARK 2014 Reference Manual, section 7.2.2.
+
+@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d4}
+@section Pragma Relative_Deadline
+
+
+Syntax:
+
+@example
+pragma Relative_Deadline (time_span_EXPRESSION);
+@end example
+
+This pragma is standard in Ada 2005, but is available in all earlier
+versions of Ada as an implementation-defined pragma.
+See Ada 2012 Reference Manual for details.
+
+@node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d6}
+@section Pragma Remote_Access_Type
+
+
+Syntax:
+
+@example
+pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME);
+@end example
+
+This pragma appears in the formal part of a generic declaration.
+It specifies an exception to the RM rule from E.2.2(17/2), which forbids
+the use of a remote access to class-wide type as actual for a formal
+access type.
+
+When this pragma applies to a formal access type @code{Entity}, that
+type is treated as a remote access to class-wide type in the generic.
+It must be a formal general access type, and its designated type must
+be the class-wide type of a formal tagged limited private type from the
+same generic declaration.
+
+In the generic unit, the formal type is subject to all restrictions
+pertaining to remote access to class-wide types. At instantiation, the
+actual type must be a remote access to class-wide type.
+
+@node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{d7}
+@section Pragma Rename_Pragma
+
+
+@geindex Pragmas
+@geindex synonyms
+
+Syntax:
+
+@example
+pragma Rename_Pragma (
+ [New_Name =>] IDENTIFIER,
+ [Renamed =>] pragma_IDENTIFIER);
+@end example
+
+This pragma provides a mechanism for supplying new names for existing
+pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for
+the Renamed pragma. For example, suppose you have code that was originally
+developed on a compiler that supports Inline_Only as an implementation defined
+pragma. And suppose the semantics of pragma Inline_Only are identical to (or at
+least very similar to) the GNAT implementation defined pragma
+Inline_Always. You could globally replace Inline_Only with Inline_Always.
+
+However, to avoid that source modification, you could instead add a
+configuration pragma:
+
+@example
+pragma Rename_Pragma (
+ New_Name => Inline_Only,
+ Renamed => Inline_Always);
+@end example
+
+Then GNAT will treat “pragma Inline_Only …” as if you had written
+“pragma Inline_Always …”.
+
+Pragma Inline_Only will not necessarily mean the same thing as the other Ada
+compiler; it’s up to you to make sure the semantics are close enough.
+
+@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d8}
+@section Pragma Restricted_Run_Time
+
+
+Syntax:
+
+@example
+pragma Restricted_Run_Time;
+@end example
+
+This pragma is considered obsolescent, but is retained for
+compatibility purposes. It is equivalent to:
+
+@example
+pragma Profile (Restricted);
+@end example
+
+which is the preferred method of setting the restricted run time
+profile.
+
+@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{d9}
+@section Pragma Restriction_Warnings
+
+
+Syntax:
+
+@example
+pragma Restriction_Warnings
+ (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
+@end example
+
+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.
+
+One use of this is in situations where you want to know
+about violations of a restriction, but you want to ignore some of
+these violations. Consider this example, where you want to set
+Ada_95 mode and enable style checks, but you want to know about
+any other use of implementation pragmas:
+
+@example
+pragma Restriction_Warnings (No_Implementation_Pragmas);
+pragma Warnings (Off, "violation of No_Implementation_Pragmas");
+pragma Ada_95;
+pragma Style_Checks ("2bfhkM160");
+pragma Warnings (On, "violation of No_Implementation_Pragmas");
+@end example
+
+By including the above lines in a configuration pragmas file,
+the Ada_95 and Style_Checks pragmas are accepted without
+generating a warning, but any other use of implementation
+defined pragmas will cause a warning to be generated.
+
+@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{da}
+@section Pragma Reviewable
+
+
+Syntax:
+
+@example
+pragma Reviewable;
+@end example
+
+This pragma is an RM-defined standard pragma, but has no effect on the
+program being compiled, or on the code generated for the program.
+
+To obtain the required output specified in RM H.3.1, the compiler must be
+run with various special switches as follows:
+
+
+@itemize *
+
+@item
+`Where compiler-generated run-time checks remain'
+
+The switch `-gnatGL'
+may be used to list the expanded code in pseudo-Ada form.
+Runtime checks show up in the listing either as explicit
+checks or operators marked with @{@} to indicate a check is present.
+
+@item
+`An identification of known exceptions at compile time'
+
+If the program is compiled with `-gnatwa',
+the compiler warning messages will indicate all cases where the compiler
+detects that an exception is certain to occur at run time.
+
+@item
+`Possible reads of uninitialized variables'
+
+The compiler warns of many such cases, but its output is incomplete.
+@end itemize
+
+
+A supplemental static analysis tool
+may be used to obtain a comprehensive list of all
+possible points at which uninitialized data may be read.
+
+
+@itemize *
+
+@item
+`Where run-time support routines are implicitly invoked'
+
+In the output from `-gnatGL',
+run-time calls are explicitly listed as calls to the relevant
+run-time routine.
+
+@item
+`Object code listing'
+
+This may be obtained either by using the `-S' switch,
+or the objdump utility.
+
+@item
+`Constructs known to be erroneous at compile time'
+
+These are identified by warnings issued by the compiler (use `-gnatwa').
+
+@item
+`Stack usage information'
+
+Static stack usage data (maximum per-subprogram) can be obtained via the
+`-fstack-usage' switch to the compiler.
+Dynamic stack usage data (per task) can be obtained via the `-u' switch
+to gnatbind
+@end itemize
+
+
+
+@itemize *
+
+@item
+`Object code listing of entire partition'
+
+This can be obtained by compiling the partition with `-S',
+or by applying objdump
+to all the object files that are part of the partition.
+
+@item
+`A description of the run-time model'
+
+The full sources of the run-time are available, and the documentation of
+these routines describes how these run-time routines interface to the
+underlying operating system facilities.
+
+@item
+`Control and data-flow information'
+@end itemize
+
+
+A supplemental static analysis tool
+may be used to obtain complete control and data-flow information, as well as
+comprehensive messages identifying possible problems based on this
+information.
+
+@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{db}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dc}
+@section Pragma Secondary_Stack_Size
+
+
+Syntax:
+
+@example
+pragma Secondary_Stack_Size (integer_EXPRESSION);
+@end example
+
+This pragma appears within the task definition of a single task declaration
+or a task type declaration (like pragma @code{Storage_Size}) and applies to all
+task objects of that type. The argument specifies the size of the secondary
+stack to be used by these task objects, and must be of an integer type. The
+secondary stack is used to handle functions that return a variable-sized
+result, for example a function returning an unconstrained String.
+
+Note this pragma only applies to targets using fixed secondary stacks, like
+VxWorks 653 and bare board targets, where a fixed block for the
+secondary stack is allocated from the primary stack of the task. By default,
+these targets assign a percentage of the primary stack for the secondary stack,
+as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma,
+an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead.
+
+For most targets, the pragma does not apply as the secondary stack grows on
+demand: allocated as a chain of blocks in the heap. The default size of these
+blocks can be modified via the @code{-D} binder option as described in
+@cite{GNAT User’s Guide}.
+
+Note that no check is made to see if the secondary stack can fit inside the
+primary stack.
+
+Note the pragma cannot appear when the restriction @code{No_Secondary_Stack}
+is in effect.
+
+@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{dd}
+@section Pragma Share_Generic
+
+
+Syntax:
+
+@example
+pragma Share_Generic (GNAME @{, GNAME@});
+
+GNAME ::= generic_unit_NAME | generic_instance_NAME
+@end example
+
+This pragma is provided for compatibility with Dec Ada 83. It has
+no effect in GNAT (which does not implement shared generics), other
+than to check that the given names are all names of generic units or
+generic instances.
+
+@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{df}
+@section Pragma Shared
+
+
+This pragma is provided for compatibility with Ada 83. The syntax and
+semantics are identical to pragma Atomic.
+
+@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e0}
+@section Pragma Short_Circuit_And_Or
+
+
+Syntax:
+
+@example
+pragma Short_Circuit_And_Or;
+@end example
+
+This configuration pragma causes any occurrence of the AND operator applied to
+operands of type Standard.Boolean to be short-circuited (i.e. the AND operator
+is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This
+may be useful in the context of certification protocols requiring the use of
+short-circuited logical operators. If this configuration pragma occurs locally
+within the file being compiled, it applies only to the file being compiled.
+There is no requirement that all units in a partition use this option.
+
+@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e1}
+@section Pragma Short_Descriptors
+
+
+Syntax:
+
+@example
+pragma Short_Descriptors;
+@end example
+
+This pragma is provided for compatibility with other Ada implementations. It
+is recognized but ignored by all current versions of GNAT.
+
+@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e2}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e3}
+@section Pragma Simple_Storage_Pool_Type
+
+
+@geindex Storage pool
+@geindex simple
+
+@geindex Simple storage pool
+
+Syntax:
+
+@example
+pragma Simple_Storage_Pool_Type (type_LOCAL_NAME);
+@end example
+
+A type can be established as a ‘simple storage pool type’ by applying
+the representation pragma @code{Simple_Storage_Pool_Type} to the type.
+A type named in the pragma must be a library-level immutably limited record
+type or limited tagged type declared immediately within a package declaration.
+The type can also be a limited private type whose full type is allowed as
+a simple storage pool type.
+
+For a simple storage pool type @code{SSP}, nonabstract primitive subprograms
+@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that
+are subtype conformant with the following subprogram declarations:
+
+@example
+procedure Allocate
+ (Pool : in out SSP;
+ Storage_Address : out System.Address;
+ Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
+ Alignment : System.Storage_Elements.Storage_Count);
+
+procedure Deallocate
+ (Pool : in out SSP;
+ Storage_Address : System.Address;
+ Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
+ Alignment : System.Storage_Elements.Storage_Count);
+
+function Storage_Size (Pool : SSP)
+ return System.Storage_Elements.Storage_Count;
+@end example
+
+Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and
+@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then
+applying an unchecked deallocation has no effect other than to set its actual
+parameter to null. If @code{Storage_Size} is not declared, then the
+@code{Storage_Size} attribute applied to an access type associated with
+a pool object of type SSP returns zero. Additional operations can be declared
+for a simple storage pool type (such as for supporting a mark/release
+storage-management discipline).
+
+An object of a simple storage pool type can be associated with an access
+type by specifying the attribute
+@ref{e4,,Simple_Storage_Pool}. For example:
+
+@example
+My_Pool : My_Simple_Storage_Pool_Type;
+
+type Acc is access My_Data_Type;
+
+for Acc'Simple_Storage_Pool use My_Pool;
+@end example
+
+See attribute @ref{e4,,Simple_Storage_Pool}
+for further details.
+
+@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e6}
+@section Pragma Source_File_Name
+
+
+Syntax:
+
+@example
+pragma Source_File_Name (
+ [Unit_Name =>] unit_NAME,
+ Spec_File_Name => STRING_LITERAL,
+ [Index => INTEGER_LITERAL]);
+
+pragma Source_File_Name (
+ [Unit_Name =>] unit_NAME,
+ Body_File_Name => STRING_LITERAL,
+ [Index => INTEGER_LITERAL]);
+@end example
+
+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).
+@code{unit_name} is mapped to @code{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.
+
+The optional Index argument should be used when a file contains multiple
+units, and when you do not want to use @code{gnatchop} to separate then
+into multiple files (which is the recommended procedure to limit the
+number of recompilations that are needed when some sources change).
+For instance, if the source file @code{source.ada} contains
+
+@example
+package B is
+...
+end B;
+
+with B;
+procedure A is
+begin
+ ..
+end A;
+@end example
+
+you could use the following configuration pragmas:
+
+@example
+pragma Source_File_Name
+ (B, Spec_File_Name => "source.ada", Index => 1);
+pragma Source_File_Name
+ (A, Body_File_Name => "source.ada", Index => 2);
+@end example
+
+Note that the @code{gnatname} utility can also be used to generate those
+configuration pragmas.
+
+Another form of the @code{Source_File_Name} pragma allows
+the specification of patterns defining alternative file naming schemes
+to apply to all files.
+
+@example
+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 example
+
+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.
+
+Note that Source_File_Name pragmas should not be used if you are using
+project files. The reason for this rule is that the project manager is not
+aware of these pragmas, and so other tools that use the project file would not
+be aware of the intended naming conventions. If you are using project files,
+file naming is controlled by Source_File_Name_Project pragmas, which are
+usually supplied automatically by the project manager. A pragma
+Source_File_Name cannot appear after a @ref{e7,,Pragma Source_File_Name_Project}.
+
+For more details on the use of the @code{Source_File_Name} pragma, see the
+sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes}
+in the @cite{GNAT User’s Guide}.
+
+@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e7}
+@section Pragma Source_File_Name_Project
+
+
+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{e6,,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 or Source_File_Name_Project pragmas (which would not be
+known to the project manager).
+
+@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{e9}
+@section Pragma Source_Reference
+
+
+Syntax:
+
+@example
+pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
+@end example
+
+This pragma must appear as the first line of a source file.
+@code{integer_literal} is the logical line number of the line following
+the pragma line (for use in error messages and debugging
+information). @code{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 `-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 SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{eb}
+@section Pragma SPARK_Mode
+
+
+Syntax:
+
+@example
+pragma SPARK_Mode [(On | Off)] ;
+@end example
+
+In general a program can have some parts that are in SPARK 2014 (and
+follow all the rules in the SPARK Reference Manual), and some parts
+that are full Ada 2012.
+
+The SPARK_Mode pragma is used to identify which parts are in SPARK
+2014 (by default programs are in full Ada). The SPARK_Mode pragma can
+be used in the following places:
+
+
+@itemize *
+
+@item
+As a configuration pragma, in which case it sets the default mode for
+all units compiled with this pragma.
+
+@item
+Immediately following a library-level subprogram spec
+
+@item
+Immediately within a library-level package body
+
+@item
+Immediately following the @code{private} keyword of a library-level
+package spec
+
+@item
+Immediately following the @code{begin} keyword of a library-level
+package body
+
+@item
+Immediately within a library-level subprogram body
+@end itemize
+
+Normally a subprogram or package spec/body inherits the current mode
+that is active at the point it is declared. But this can be overridden
+by pragma within the spec or body as above.
+
+The basic consistency rule is that you can’t turn SPARK_Mode back
+@code{On}, once you have explicitly (with a pragma) turned if
+@code{Off}. So the following rules apply:
+
+If a subprogram spec has SPARK_Mode @code{Off}, then the body must
+also have SPARK_Mode @code{Off}.
+
+For a package, we have four parts:
+
+
+@itemize *
+
+@item
+the package public declarations
+
+@item
+the package private part
+
+@item
+the body of the package
+
+@item
+the elaboration code after @code{begin}
+@end itemize
+
+For a package, the rule is that if you explicitly turn SPARK_Mode
+@code{Off} for any part, then all the following parts must have
+SPARK_Mode @code{Off}. Note that this may require repeating a pragma
+SPARK_Mode (@code{Off}) in the body. For example, if we have a
+configuration pragma SPARK_Mode (@code{On}) that turns the mode on by
+default everywhere, and one particular package spec has pragma
+SPARK_Mode (@code{Off}), then that pragma will need to be repeated in
+the package body.
+
+@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ec}
+@section Pragma Static_Elaboration_Desired
+
+
+Syntax:
+
+@example
+pragma Static_Elaboration_Desired;
+@end example
+
+This pragma is used to indicate that the compiler should attempt to initialize
+statically the objects declared in the library unit to which the pragma applies,
+when these objects are initialized (explicitly or implicitly) by an aggregate.
+In the absence of this pragma, aggregates in object declarations are expanded
+into assignments and loops, even when the aggregate components are static
+constants. When the aggregate is present the compiler builds a static expression
+that requires no run-time code, so that the initialized object can be placed in
+read-only data space. If the components are not static, or the aggregate has
+more that 100 components, the compiler emits a warning that the pragma cannot
+be obeyed. (See also the restriction No_Implicit_Loops, which supports static
+construction of larger aggregates with static components that include an others
+choice.)
+
+@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ed}
+@section Pragma Stream_Convert
+
+
+Syntax:
+
+@example
+pragma Stream_Convert (
+ [Entity =>] type_LOCAL_NAME,
+ [Read =>] function_NAME,
+ [Write =>] function_NAME);
+@end example
+
+This pragma provides an efficient way of providing user-defined stream
+attributes. Not only is it simpler to use than specifying the attributes
+directly, but more importantly, it allows the specification to be made in such
+a way that the predefined unit Ada.Streams is not loaded unless it is actually
+needed (i.e. unless the stream attributes are actually used); 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 @code{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 @code{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:
+
+@example
+function To_Unbounded (S : String) return Unbounded_String
+ renames To_Unbounded_String;
+
+pragma Stream_Convert
+ (Unbounded_String, To_Unbounded, To_String);
+@end example
+
+The specifications of the referenced functions, as given in the Ada
+Reference Manual are:
+
+@example
+function To_Unbounded_String (Source : String)
+ return Unbounded_String;
+
+function To_String (Source : Unbounded_String)
+ return String;
+@end example
+
+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 that
+would be used for @code{Standard.String'Output}, and this same representation
+is expected when a value of this type is read from the stream. Note that the
+value written always includes the bounds, even for Unbounded_String’Write,
+since Unbounded_String is not an array type.
+
+Note that the @code{Stream_Convert} pragma is not effective in the case of
+a derived type of a non-limited tagged type. If such a type is specified then
+the pragma is silently ignored, and the default implementation of the stream
+attributes is used instead.
+
+@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ee}
+@section Pragma Style_Checks
+
+
+Syntax:
+
+@example
+pragma Style_Checks (string_LITERAL | ALL_CHECKS |
+ On | Off [, LOCAL_NAME]);
+@end example
+
+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 @code{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 `-gnaty' switch to `gcc' or `gnatmake'.
+For example the following two methods can be used to enable
+layout checking:
+
+
+@itemize *
+
+@item
+@example
+pragma Style_Checks ("l");
+@end example
+
+@item
+@example
+gcc -c -gnatyl ...
+@end example
+@end itemize
+
+The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent
+to the use of the @code{gnaty} switch with no options.
+See the @cite{GNAT User’s Guide} for details.)
+
+Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used).
+In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check
+options (i.e. equivalent to @code{-gnatyg}).
+
+The forms with @code{Off} and @code{On}
+can be used to temporarily disable style checks
+as shown in the following example:
+
+@example
+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 example
+
+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:
+
+@example
+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 example
+
+@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{ef}
+@section Pragma Subtitle
+
+
+Syntax:
+
+@example
+pragma Subtitle ([Subtitle =>] STRING_LITERAL);
+@end example
+
+This pragma is recognized for compatibility with other Ada compilers
+but is ignored by GNAT.
+
+@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f0}
+@section Pragma Suppress
+
+
+Syntax:
+
+@example
+pragma Suppress (Identifier [, [On =>] Name]);
+@end example
+
+This is a standard pragma, and supports all the check names required in
+the RM. It is included here because GNAT recognizes some additional check
+names that are implementation defined (as permitted by the RM):
+
+
+@itemize *
+
+@item
+@code{Alignment_Check} 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 @code{Alignment_Check} is suppressed by default on machines (such as
+the x86) with non-strict alignment.
+
+@item
+@code{Atomic_Synchronization} can be used to suppress the special memory
+synchronization instructions that are normally generated for access to
+@code{Atomic} variables to ensure correct synchronization between tasks
+that use such variables for synchronization purposes.
+
+@item
+@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated
+for a duplicated tag value when a tagged type is declared.
+
+@item
+@code{Container_Checks} Can be used to suppress all checks within Ada.Containers
+and instances of its children, including Tampering_Check.
+
+@item
+@code{Tampering_Check} Can be used to suppress tampering check in the containers.
+
+@item
+@code{Predicate_Check} can be used to control whether predicate checks are
+active. It is applicable only to predicates for which the policy is
+@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given
+predicate is ignored or checked for the whole program, the use of
+@code{Suppress} and @code{Unsuppress} with this check name allows a given
+predicate to be turned on and off at specific points in the program.
+
+@item
+@code{Validity_Check} can be used specifically to control validity checks.
+If @code{Suppress} is used to suppress validity checks, then no validity
+checks are performed, including those specified by the appropriate compiler
+switch or the @code{Validity_Checks} pragma.
+
+@item
+Additional check names previously introduced by use of the @code{Check_Name}
+pragma are also allowed.
+@end itemize
+
+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,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f1}
+@section Pragma Suppress_All
+
+
+Syntax:
+
+@example
+pragma Suppress_All;
+@end example
+
+This pragma can appear anywhere within a unit.
+The effect is to apply @code{Suppress (All_Checks)} to the unit
+in which it appears. This pragma is implemented for compatibility with DEC
+Ada 83 usage where it appears at the end of a unit, and for compatibility
+with Rational Ada, where it appears as a program unit pragma.
+The use of the standard Ada pragma @code{Suppress (All_Checks)}
+as a normal configuration pragma is the preferred usage in GNAT.
+
+@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f2}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f3}
+@section Pragma Suppress_Debug_Info
+
+
+Syntax:
+
+@example
+pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME);
+@end example
+
+This pragma can be used to suppress generation of debug information
+for the specified entity. It is intended primarily for use in debugging
+the debugger, and navigating around debugger problems.
+
+@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f4}
+@section Pragma Suppress_Exception_Locations
+
+
+Syntax:
+
+@example
+pragma Suppress_Exception_Locations;
+@end example
+
+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,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f5}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f6}
+@section Pragma Suppress_Initialization
+
+
+@geindex Suppressing initialization
+
+@geindex Initialization
+@geindex suppression of
+
+Syntax:
+
+@example
+pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name);
+@end example
+
+Here variable_or_subtype_Name is the name introduced by a type declaration
+or subtype declaration or the name of a variable introduced by an
+object declaration.
+
+In the case of a type or subtype
+this pragma suppresses any implicit or explicit initialization
+for all variables of the given type or subtype,
+including initialization resulting from the use of pragmas
+Normalize_Scalars or Initialize_Scalars.
+
+This is considered a representation item, so it cannot be given after
+the type is frozen. It applies to all subsequent object declarations,
+and also any allocator that creates objects of the type.
+
+If the pragma is given for the first subtype, then it is considered
+to apply to the base type and all its subtypes. If the pragma is given
+for other than a first subtype, then it applies only to the given subtype.
+The pragma may not be given after the type is frozen.
+
+Note that this includes eliminating initialization of discriminants
+for discriminated types, and tags for tagged types. In these cases,
+you will have to use some non-portable mechanism (e.g. address
+overlays or unchecked conversion) to achieve required initialization
+of these fields before accessing any object of the corresponding type.
+
+For the variable case, implicit initialization for the named variable
+is suppressed, just as though its subtype had been given in a pragma
+Suppress_Initialization, as described above.
+
+@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f7}
+@section Pragma Task_Name
+
+
+Syntax
+
+@example
+pragma Task_Name (string_EXPRESSION);
+@end example
+
+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.
+
+@example
+-- 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 example
+
+@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f8}
+@section Pragma Task_Storage
+
+
+Syntax:
+
+@example
+pragma Task_Storage (
+ [Task_Type =>] LOCAL_NAME,
+ [Top_Guard =>] static_integer_EXPRESSION);
+@end example
+
+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 Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{f9}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fa}
+@section Pragma Test_Case
+
+
+@geindex Test cases
+
+Syntax:
+
+@example
+pragma Test_Case (
+ [Name =>] static_string_Expression
+ ,[Mode =>] (Nominal | Robustness)
+ [, Requires => Boolean_Expression]
+ [, Ensures => Boolean_Expression]);
+@end example
+
+The @code{Test_Case} pragma allows defining fine-grain specifications
+for use by testing tools.
+The compiler checks the validity of the @code{Test_Case} pragma, but its
+presence does not lead to any modification of the code generated by the
+compiler.
+
+@code{Test_Case} pragmas may only appear immediately following the
+(separate) declaration of a subprogram in a package declaration, inside
+a package spec unit. Only other pragmas may intervene (that is appear
+between the subprogram declaration and a test case).
+
+The compiler checks that boolean expressions given in @code{Requires} and
+@code{Ensures} are valid, where the rules for @code{Requires} are the
+same as the rule for an expression in @code{Precondition} and the rules
+for @code{Ensures} are the same as the rule for an expression in
+@code{Postcondition}. In particular, attributes @code{'Old} and
+@code{'Result} can only be used within the @code{Ensures}
+expression. The following is an example of use within a package spec:
+
+@example
+package Math_Functions is
+ ...
+ function Sqrt (Arg : Float) return Float;
+ pragma Test_Case (Name => "Test 1",
+ Mode => Nominal,
+ Requires => Arg < 10000.0,
+ Ensures => Sqrt'Result < 10.0);
+ ...
+end Math_Functions;
+@end example
+
+The meaning of a test case is that there is at least one context where
+@code{Requires} holds such that, if the associated subprogram is executed in
+that context, then @code{Ensures} holds when the subprogram returns.
+Mode @code{Nominal} indicates that the input context should also satisfy the
+precondition of the subprogram, and the output context should also satisfy its
+postcondition. Mode @code{Robustness} indicates that the precondition and
+postcondition of the subprogram should be ignored for this test case.
+
+@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fb}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fc}
+@section Pragma Thread_Local_Storage
+
+
+@geindex Task specific storage
+
+@geindex TLS (Thread Local Storage)
+
+@geindex Task_Attributes
+
+Syntax:
+
+@example
+pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
+@end example
+
+This pragma specifies that the specified entity, which must be
+a variable declared in a library-level package, is to be marked as
+“Thread Local Storage” (@code{TLS}). On systems supporting this (which
+include Windows, Solaris, GNU/Linux, and VxWorks), this causes each
+thread (and hence each Ada task) to see a distinct copy of the variable.
+
+The variable must not have default initialization, and if there is
+an explicit initialization, it must be either @code{null} for an
+access variable, a static expression for a scalar variable, or a fully
+static aggregate for a composite type, that is to say, an aggregate all
+of whose components are static, and which does not include packed or
+discriminated components.
+
+This provides a low-level mechanism similar to that provided by
+the @code{Ada.Task_Attributes} package, but much more efficient
+and is also useful in writing interface code that will interact
+with foreign threads.
+
+If this pragma is used on a system where @code{TLS} is not supported,
+then an error message will be generated and the program will be rejected.
+
+@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fd}
+@section Pragma Time_Slice
+
+
+Syntax:
+
+@example
+pragma Time_Slice (static_duration_EXPRESSION);
+@end example
+
+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.
+
+@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{fe}
+@section Pragma Title
+
+
+Syntax:
+
+@example
+pragma Title (TITLING_OPTION [, TITLING OPTION]);
+
+TITLING_OPTION ::=
+ [Title =>] STRING_LITERAL,
+| [Subtitle =>] STRING_LITERAL
+@end example
+
+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 Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{ff}
+@section Pragma Type_Invariant
+
+
+Syntax:
+
+@example
+pragma Type_Invariant
+ ([Entity =>] type_LOCAL_NAME,
+ [Check =>] EXPRESSION);
+@end example
+
+The @code{Type_Invariant} pragma is intended to be an exact
+replacement for the language-defined @code{Type_Invariant}
+aspect, and shares its restrictions and semantics. It differs
+from the language defined @code{Invariant} pragma in that it
+does not permit a string parameter, and it is
+controlled by the assertion identifier @code{Type_Invariant}
+rather than @code{Invariant}.
+
+@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{100}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{101}
+@section Pragma Type_Invariant_Class
+
+
+Syntax:
+
+@example
+pragma Type_Invariant_Class
+ ([Entity =>] type_LOCAL_NAME,
+ [Check =>] EXPRESSION);
+@end example
+
+The @code{Type_Invariant_Class} pragma is intended to be an exact
+replacement for the language-defined @code{Type_Invariant'Class}
+aspect, and shares its restrictions and semantics.
+
+Note: This pragma is called @code{Type_Invariant_Class} rather than
+@code{Type_Invariant'Class} because the latter would not be strictly
+conforming to the allowed syntax for pragmas. The motivation
+for providing pragmas equivalent to the aspects is to allow a program
+to be written using the pragmas, and then compiled if necessary
+using an Ada compiler that does not recognize the pragmas or
+aspects, but is prepared to ignore the pragmas. The assertion
+policy that controls this pragma is @code{Type_Invariant'Class},
+not @code{Type_Invariant_Class}.
+
+@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{102}
+@section Pragma Unchecked_Union
+
+
+@geindex Unions in C
+
+Syntax:
+
+@example
+pragma Unchecked_Union (first_subtype_LOCAL_NAME);
+@end example
+
+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 2012 Reference Manual, section B.3.3.
+
+@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{103}
+@section Pragma Unevaluated_Use_Of_Old
+
+
+@geindex Attribute Old
+
+@geindex Attribute Loop_Entry
+
+@geindex Unevaluated_Use_Of_Old
+
+Syntax:
+
+@example
+pragma Unevaluated_Use_Of_Old (Error | Warn | Allow);
+@end example
+
+This pragma controls the processing of attributes Old and Loop_Entry.
+If either of these attributes is used in a potentially unevaluated
+expression (e.g. the then or else parts of an if expression), then
+normally this usage is considered illegal if the prefix of the attribute
+is other than an entity name. The language requires this
+behavior for Old, and GNAT copies the same rule for Loop_Entry.
+
+The reason for this rule is that otherwise, we can have a situation
+where we save the Old value, and this results in an exception, even
+though we might not evaluate the attribute. Consider this example:
+
+@example
+package UnevalOld is
+ K : Character;
+ procedure U (A : String; C : Boolean) -- ERROR
+ with Post => (if C then A(1)'Old = K else True);
+end;
+@end example
+
+If procedure U is called with a string with a lower bound of 2, and
+C false, then an exception would be raised trying to evaluate A(1)
+on entry even though the value would not be actually used.
+
+Although the rule guarantees against this possibility, it is sometimes
+too restrictive. For example if we know that the string has a lower
+bound of 1, then we will never raise an exception.
+The pragma @code{Unevaluated_Use_Of_Old} can be
+used to modify this behavior. If the argument is @code{Error} then an
+error is given (this is the default RM behavior). If the argument is
+@code{Warn} then the usage is allowed as legal but with a warning
+that an exception might be raised. If the argument is @code{Allow}
+then the usage is allowed as legal without generating a warning.
+
+This pragma may appear as a configuration pragma, or in a declarative
+part or package specification. In the latter case it applies to
+uses up to the end of the corresponding statement sequence or
+sequence of package declarations.
+
+@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{104}
+@section Pragma Unimplemented_Unit
+
+
+Syntax:
+
+@example
+pragma Unimplemented_Unit;
+@end example
+
+If this pragma occurs in a unit that is processed by the compiler, GNAT
+aborts with the message @code{xxx not implemented}, where
+@code{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,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{106}
+@section Pragma Universal_Aliasing
+
+
+Syntax:
+
+@example
+pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
+@end example
+
+@code{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, see the section on
+@code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}.
+
+@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{107}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{108}
+@section Pragma Unmodified
+
+
+@geindex Warnings
+@geindex unmodified
+
+Syntax:
+
+@example
+pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
+@end example
+
+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.
+
+For the variable case, warnings are never given for unreferenced variables
+whose name contains one of the substrings
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSE, TMP, TEMP} in any casing. Such names
+are typically to be used in cases where such warnings are expected.
+Thus it is never necessary to use @code{pragma Unmodified} for such
+variables, though it is harmless to do so.
+
+@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{109}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10a}
+@section Pragma Unreferenced
+
+
+@geindex Warnings
+@geindex unreferenced
+
+Syntax:
+
+@example
+pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
+pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
+@end example
+
+This pragma signals that the entities whose names are listed are
+deliberately not referenced in the current source unit after the
+occurrence of the pragma. This
+suppresses warnings about the
+entities being unreferenced, and in addition a warning will be
+generated if one of these entities is in fact subsequently 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. However, use of an entity as an actual for
+an out parameter does count as a reference unless warnings for unread output
+parameters are enabled via @code{-gnatw.o}.
+
+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 @ref{ac,,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.
+
+For the variable case, warnings are never given for unreferenced variables
+whose name contains one of the substrings
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
+are typically to be used in cases where such warnings are expected.
+Thus it is never necessary to use @code{pragma Unreferenced} for such
+variables, though it is harmless to do so.
+
+@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10b}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10c}
+@section Pragma Unreferenced_Objects
+
+
+@geindex Warnings
+@geindex unreferenced
+
+Syntax:
+
+@example
+pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
+@end example
+
+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,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10d}
+@section Pragma Unreserve_All_Interrupts
+
+
+Syntax:
+
+@example
+pragma Unreserve_All_Interrupts;
+@end example
+
+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 @code{Ctrl-C} interrupt. Normally this interrupt is
+reserved to the implementation, so that @code{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
+@code{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 @code{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,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10e}
+@section Pragma Unsuppress
+
+
+Syntax:
+
+@example
+pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
+@end example
+
+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. For example, in a program that depends on external names of tagged
+types and wants to ensure that the duplicated tag check occurs even if all
+run-time checks are suppressed by a compiler switch, the following
+configuration pragma will ensure this test is not suppressed:
+
+@example
+pragma Unsuppress (Duplicated_Tag_Check);
+@end example
+
+This pragma is standard in Ada 2005. It is available in all earlier versions
+of Ada as an implementation-defined pragma.
+
+Note that in addition to the checks defined in the Ada RM, GNAT recognizes a
+number of implementation-defined check names. See the description of pragma
+@code{Suppress} for full details.
+
+@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{10f}
+@section Pragma Use_VADS_Size
+
+
+@geindex Size
+@geindex VADS compatibility
+
+@geindex Rational profile
+
+Syntax:
+
+@example
+pragma Use_VADS_Size;
+@end example
+
+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 Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{110}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{111}
+@section Pragma Unused
+
+
+@geindex Warnings
+@geindex unused
+
+Syntax:
+
+@example
+pragma Unused (LOCAL_NAME @{, LOCAL_NAME@});
+@end example
+
+This pragma signals that the assignable entities (variables,
+@code{out} parameters, and @code{in out} parameters) whose names are listed
+deliberately do not get assigned or referenced in the current source unit
+after the occurrence of the pragma in the current source unit. This
+suppresses warnings about the entities that are unreferenced and/or not
+assigned, and, in addition, a warning will be generated if one of these
+entities gets assigned or subsequently referenced in the same unit as the
+pragma (in the corresponding body or one of its subunits).
+
+This is particularly useful for clearly signaling that a particular
+parameter is not modified or referenced, even though the spec suggests
+that it might be.
+
+For the variable case, warnings are never given for unreferenced
+variables whose name contains one of the substrings
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
+are typically to be used in cases where such warnings are expected.
+Thus it is never necessary to use @code{pragma Unused} for such
+variables, though it is harmless to do so.
+
+@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{112}
+@section Pragma Validity_Checks
+
+
+Syntax:
+
+@example
+pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
+@end example
+
+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 @code{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 `-gnatVx' compiler switch (see the
+GNAT User’s 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 *
+
+@item
+@example
+pragma Validity_Checks ("im");
+@end example
+
+@item
+@example
+$ gcc -c -gnatVim ...
+@end example
+@end itemize
+
+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:
+
+@example
+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 example
+
+@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{113}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{114}
+@section Pragma Volatile
+
+
+Syntax:
+
+@example
+pragma Volatile (LOCAL_NAME);
+@end example
+
+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 Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{116}
+@section Pragma Volatile_Full_Access
+
+
+Syntax:
+
+@example
+pragma Volatile_Full_Access (LOCAL_NAME);
+@end example
+
+This is similar in effect to pragma Volatile, except that any reference to the
+object is guaranteed to be done only with instructions that read or write all
+the bits of the object. Furthermore, if the object is of a composite type,
+then any reference to a subcomponent of the object is guaranteed to read
+and/or write all the bits of the object.
+
+The intention is that this be suitable for use with memory-mapped I/O devices
+on some machines. Note that there are two important respects in which this is
+different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access}
+object is not a sequential action in the RM 9.10 sense and, therefore, does
+not create a synchronization point. Second, in the case of @code{pragma Atomic},
+there is no guarantee that all the bits will be accessed if the reference
+is not to the whole object; the compiler is allowed (and generally will)
+access only part of the object in this case.
+
+@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{118}
+@section Pragma Volatile_Function
+
+
+Syntax:
+
+@example
+pragma Volatile_Function [ (static_boolean_EXPRESSION) ];
+@end example
+
+For the semantics of this pragma, see the entry for aspect @code{Volatile_Function}
+in the SPARK 2014 Reference Manual, section 7.1.2.
+
+@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{119}
+@section Pragma Warning_As_Error
+
+
+Syntax:
+
+@example
+pragma Warning_As_Error (static_string_EXPRESSION);
+@end example
+
+This configuration pragma allows the programmer to specify a set
+of warnings that will be treated as errors. Any warning that
+matches the pattern given by the pragma argument will be treated
+as an error. This gives more precise control than -gnatwe,
+which treats warnings as errors.
+
+This pragma can apply to regular warnings (messages enabled by -gnatw)
+and to style warnings (messages that start with “(style)”,
+enabled by -gnaty).
+
+The pattern may contain asterisks, which match zero or more characters
+in the message. For example, you can use @code{pragma Warning_As_Error
+("bits of*unused")} to treat the warning message @code{warning: 960 bits of
+"a" unused} as an error. All characters other than asterisk are treated
+as literal characters in the match. The match is case insensitive; for
+example XYZ matches xyz.
+
+Note that the pattern matches if it occurs anywhere within the warning
+message string (it is not necessary to put an asterisk at the start and
+the end of the message, since this is implied).
+
+Another possibility for the static_string_EXPRESSION which works whether
+or not error tags are enabled (`-gnatw.d') is to use a single
+`-gnatw' tag string, enclosed in brackets,
+as shown in the example below, to treat one category of warnings as errors.
+Note that if you want to treat multiple categories of warnings as errors,
+you can use multiple pragma Warning_As_Error.
+
+The above use of patterns to match the message applies only to warning
+messages generated by the front end. This pragma can also be applied to
+warnings provided by the back end and mentioned in @ref{11a,,Pragma Warnings}.
+By using a single full `-Wxxx' switch in the pragma, such warnings
+can also be treated as errors.
+
+The pragma can appear either in a global configuration pragma file
+(e.g. @code{gnat.adc}), or at the start of a file. Given a global
+configuration pragma file containing:
+
+@example
+pragma Warning_As_Error ("[-gnatwj]");
+@end example
+
+which will treat all obsolescent feature warnings as errors, the
+following program compiles as shown (compile options here are
+`-gnatwa.d -gnatl -gnatj55').
+
+@example
+ 1. pragma Warning_As_Error ("*never assigned*");
+ 2. function Warnerr return String is
+ 3. X : Integer;
+ |
+ >>> error: variable "X" is never read and
+ never assigned [-gnatwv] [warning-as-error]
+
+ 4. Y : Integer;
+ |
+ >>> warning: variable "Y" is assigned but
+ never read [-gnatwu]
+
+ 5. begin
+ 6. Y := 0;
+ 7. return %ABC%;
+ |
+ >>> error: use of "%" is an obsolescent
+ feature (RM J.2(4)), use """ instead
+ [-gnatwj] [warning-as-error]
+
+ 8. end;
+
+8 lines: No errors, 3 warnings (2 treated as errors)
+@end example
+
+Note that this pragma does not affect the set of warnings issued in
+any way, it merely changes the effect of a matching warning if one
+is produced as a result of other warnings options. As shown in this
+example, if the pragma results in a warning being treated as an error,
+the tag is changed from “warning:” to “error:” and the string
+“[warning-as-error]” is appended to the end of the message.
+
+@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11a}
+@section Pragma Warnings
+
+
+Syntax:
+
+@example
+pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]);
+
+DETAILS ::= On | Off
+DETAILS ::= On | Off, local_NAME
+DETAILS ::= static_string_EXPRESSION
+DETAILS ::= On | Off, static_string_EXPRESSION
+
+TOOL_NAME ::= GNAT | GNATprove
+
+REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@}
+@end example
+
+Note: in Ada 83 mode, a string literal may be used in place of a static string
+expression (which does not exist in Ada 83).
+
+Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the
+second form is always understood. If the intention is to use
+the fourth form, then you can write @code{NAME & ""} to force the
+interpretation as a `static_string_EXPRESSION'.
+
+Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted
+that way. The use of the @code{TOOL_NAME} argument is relevant only to users
+of SPARK and GNATprove, see last part of this section for details.
+
+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 some or all of the warning messages are suppressed,
+regardless of the setting of the command line switches.
+
+The @code{Reason} parameter may optionally appear as the last argument
+in any of the forms of this pragma. It is intended purely for the
+purposes of documenting the reason for the @code{Warnings} pragma.
+The compiler will check that the argument is a static string but
+otherwise ignore this argument. Other tools may provide specialized
+processing for this string.
+
+The form with a single argument (or two arguments if Reason present),
+where the first argument is @code{ON} or @code{OFF}
+may be used as a configuration pragma.
+
+If the @code{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}). This form cannot be used as a configuration
+pragma.
+
+In the case where the first argument is other than @code{ON} or
+@code{OFF},
+the third form with a single static_string_EXPRESSION argument (and possible
+reason) 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. For a brief summary, use the gnatmake
+command with no arguments, which will generate usage information containing
+the list of warnings switches supported. For
+full details see the section on @code{Warning Message Control} in the
+@cite{GNAT User’s Guide}.
+This form can also be used as a configuration pragma.
+
+The warnings controlled by the @code{-gnatw} switch are generated by the
+front end of the compiler. The GCC back end can provide additional warnings
+and they are controlled by the @code{-W} switch. Such warnings can be
+identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the
+message which designates the @code{-W`xxx'} switch that controls the message.
+The form with a single `static_string_EXPRESSION' argument also works for these
+warnings, but the string must be a single full @code{-W`xxx'} switch in this
+case. The above reference lists a few examples of these additional warnings.
+
+The specified warnings will be in effect until the end of the program
+or another pragma @code{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 @code{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 “warning: “ 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.
+The match is case insensitive, for example XYZ matches xyz.
+
+Note that the pattern matches if it occurs anywhere within the warning
+message string (it is not necessary to put an asterisk at the start and
+the end of the message, since this is implied).
+
+The above use of patterns to match the message applies only to warning
+messages generated by the front end. This form of the pragma with a string
+argument can also be used to control warnings provided by the back end and
+mentioned above. By using a single full @code{-W`xxx'} switch in the pragma,
+such warnings can be turned on and off.
+
+There are two ways to use the pragma in this form. 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 (or match the
+-W switch in the back end case).
+
+The second usage is to suppress a warning locally, and in this case, two
+pragmas must appear in sequence:
+
+@example
+pragma Warnings (Off, Pattern);
+... code where given warning is to be suppressed
+pragma Warnings (On, Pattern);
+@end example
+
+In this usage, the pattern string must match in the Off and On
+pragmas, and (if `-gnatw.w' is given) at least one matching
+warning must be suppressed.
+
+Note: if the ON form is not found, then the effect of the OFF form extends
+until the end of the file (pragma Warnings is purely textual, so its effect
+does not stop at the end of the enclosing scope).
+
+Note: to write a string that will match any warning, use the string
+@code{"***"}. It will not work to use a single asterisk or two
+asterisks since this looks like an operator name. This form with three
+asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching
+@code{pragma Warnings (On, "***")} will be required. This can be
+helpful in avoiding forgetting to turn warnings back on.
+
+Note: the debug flag @code{-gnatd.i} can be
+used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
+be useful in checking whether obsolete pragmas in existing programs are hiding
+real problems.
+
+Note: pragma Warnings does not affect the processing of style messages. See
+separate entry for pragma Style_Checks for control of style messages.
+
+Users of the formal verification tool GNATprove for the SPARK subset of Ada may
+use the version of the pragma with a @code{TOOL_NAME} parameter.
+
+If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the
+compiler or @code{GNATprove} for the formal verification tool. A given tool only
+takes into account pragma Warnings that do not specify a tool name, or that
+specify the matching tool name. This makes it possible to disable warnings
+selectively for each tool, and as a consequence to detect useless pragma
+Warnings with switch @code{-gnatw.w}.
+
+@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11c}
+@section Pragma Weak_External
+
+
+Syntax:
+
+@example
+pragma Weak_External ([Entity =>] LOCAL_NAME);
+@end example
+
+@code{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 @code{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.
+
+@example
+-- 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 example
+
+@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11d}
+@section Pragma Wide_Character_Encoding
+
+
+Syntax:
+
+@example
+pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
+@end example
+
+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.
+
+However, note that the pragma cannot immediately precede the relevant
+wide character, because then the previous encoding will still be in
+effect, causing “illegal character” errors.
+
+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 @code{h}, @code{u},
+@code{s}, @code{e}, @code{8}, or @code{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 Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top
+@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11e}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{120}
+@chapter Implementation Defined Aspects
+
+
+Ada defines (throughout the Ada 2012 reference manual, summarized
+in Annex K) a set of aspects that can be specified for certain entities.
+These language defined aspects are implemented in GNAT in Ada 2012 mode
+and work as described in the Ada 2012 Reference Manual.
+
+In addition, Ada 2012 allows implementations to define additional aspects
+whose meaning is defined by the implementation. GNAT provides
+a number of these implementation-defined aspects which can be used
+to extend and enhance the functionality of the compiler. This section of
+the GNAT reference manual describes these additional aspects.
+
+Note that any program using these aspects may not be portable to
+other compilers (although GNAT implements this set of aspects on all
+platforms). Therefore if portability to other compilers is an important
+consideration, you should minimize the use of these aspects.
+
+Note that for many of these aspects, the effect is essentially similar
+to the use of a pragma or attribute specification with the same name
+applied to the entity. For example, if we write:
+
+@example
+type R is range 1 .. 100
+ with Value_Size => 10;
+@end example
+
+then the effect is the same as:
+
+@example
+type R is range 1 .. 100;
+for R'Value_Size use 10;
+@end example
+
+and if we write:
+
+@example
+type R is new Integer
+ with Shared => True;
+@end example
+
+then the effect is the same as:
+
+@example
+type R is new Integer;
+pragma Shared (R);
+@end example
+
+In the documentation below, such cases are simply marked
+as being boolean aspects equivalent to the corresponding pragma
+or attribute definition clause.
+
+@menu
+* Aspect Abstract_State::
+* Aspect Annotate::
+* Aspect Async_Readers::
+* Aspect Async_Writers::
+* Aspect Constant_After_Elaboration::
+* Aspect Contract_Cases::
+* Aspect Depends::
+* Aspect Default_Initial_Condition::
+* Aspect Dimension::
+* Aspect Dimension_System::
+* Aspect Disable_Controlled::
+* Aspect Effective_Reads::
+* Aspect Effective_Writes::
+* Aspect Extensions_Visible::
+* Aspect Favor_Top_Level::
+* Aspect Ghost::
+* Aspect Global::
+* Aspect Initial_Condition::
+* Aspect Initializes::
+* Aspect Inline_Always::
+* Aspect Invariant::
+* Aspect Invariant’Class::
+* Aspect Iterable::
+* Aspect Linker_Section::
+* Aspect Lock_Free::
+* Aspect Max_Queue_Length::
+* Aspect No_Caching::
+* Aspect No_Elaboration_Code_All::
+* Aspect No_Inline::
+* Aspect No_Tagged_Streams::
+* Aspect No_Task_Parts::
+* Aspect Object_Size::
+* Aspect Obsolescent::
+* Aspect Part_Of::
+* Aspect Persistent_BSS::
+* Aspect Predicate::
+* Aspect Pure_Function::
+* Aspect Refined_Depends::
+* Aspect Refined_Global::
+* Aspect Refined_Post::
+* Aspect Refined_State::
+* Aspect Relaxed_Initialization::
+* Aspect Remote_Access_Type::
+* Aspect Secondary_Stack_Size::
+* Aspect Scalar_Storage_Order::
+* Aspect Shared::
+* Aspect Simple_Storage_Pool::
+* Aspect Simple_Storage_Pool_Type::
+* Aspect SPARK_Mode::
+* Aspect Suppress_Debug_Info::
+* Aspect Suppress_Initialization::
+* Aspect Test_Case::
+* Aspect Thread_Local_Storage::
+* Aspect Universal_Aliasing::
+* Aspect Unmodified::
+* Aspect Unreferenced::
+* Aspect Unreferenced_Objects::
+* Aspect Value_Size::
+* Aspect Volatile_Full_Access::
+* Aspect Volatile_Function::
+* Aspect Warnings::
+
+@end menu
+
+@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{121}
+@section Aspect Abstract_State
+
+
+@geindex Abstract_State
+
+This aspect is equivalent to @ref{1e,,pragma Abstract_State}.
+
+@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{122}
+@section Aspect Annotate
+
+
+@geindex Annotate
+
+There are three forms of this aspect (where ID is an identifier,
+and ARG is a general expression),
+corresponding to @ref{29,,pragma Annotate}.
+
+
+@table @asis
+
+@item `Annotate => ID'
+
+Equivalent to @code{pragma Annotate (ID, Entity => Name);}
+
+@item `Annotate => (ID)'
+
+Equivalent to @code{pragma Annotate (ID, Entity => Name);}
+
+@item `Annotate => (ID ,ID @{, ARG@})'
+
+Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);}
+@end table
+
+@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{123}
+@section Aspect Async_Readers
+
+
+@geindex Async_Readers
+
+This boolean aspect is equivalent to @ref{30,,pragma Async_Readers}.
+
+@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{124}
+@section Aspect Async_Writers
+
+
+@geindex Async_Writers
+
+This boolean aspect is equivalent to @ref{32,,pragma Async_Writers}.
+
+@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{125}
+@section Aspect Constant_After_Elaboration
+
+
+@geindex Constant_After_Elaboration
+
+This aspect is equivalent to @ref{42,,pragma Constant_After_Elaboration}.
+
+@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{126}
+@section Aspect Contract_Cases
+
+
+@geindex Contract_Cases
+
+This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence
+of clauses being enclosed in parentheses so that syntactically it is an
+aggregate.
+
+@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{127}
+@section Aspect Depends
+
+
+@geindex Depends
+
+This aspect is equivalent to @ref{54,,pragma Depends}.
+
+@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{128}
+@section Aspect Default_Initial_Condition
+
+
+@geindex Default_Initial_Condition
+
+This aspect is equivalent to @ref{4e,,pragma Default_Initial_Condition}.
+
+@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{129}
+@section Aspect Dimension
+
+
+@geindex Dimension
+
+The @code{Dimension} aspect is used to specify the dimensions of a given
+subtype of a dimensioned numeric type. The aspect also specifies a symbol
+used when doing formatted output of dimensioned quantities. The syntax is:
+
+@example
+with Dimension =>
+ ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@})
+
+SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL
+
+DIMENSION_VALUE ::=
+ RATIONAL
+| others => RATIONAL
+| DISCRETE_CHOICE_LIST => RATIONAL
+
+RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL]
+@end example
+
+This aspect can only be applied to a subtype whose parent type has
+a @code{Dimension_System} aspect. The aspect must specify values for
+all dimensions of the system. The rational values are the powers of the
+corresponding dimensions that are used by the compiler to verify that
+physical (numeric) computations are dimensionally consistent. For example,
+the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
+For further examples of the usage
+of this aspect, see package @code{System.Dim.Mks}.
+Note that when the dimensioned type is an integer type, then any
+dimension value must be an integer literal.
+
+@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12a}
+@section Aspect Dimension_System
+
+
+@geindex Dimension_System
+
+The @code{Dimension_System} aspect is used to define a system of
+dimensions that will be used in subsequent subtype declarations with
+@code{Dimension} aspects that reference this system. The syntax is:
+
+@example
+with Dimension_System => (DIMENSION @{, DIMENSION@});
+
+DIMENSION ::= ([Unit_Name =>] IDENTIFIER,
+ [Unit_Symbol =>] SYMBOL,
+ [Dim_Symbol =>] SYMBOL)
+
+SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL
+@end example
+
+This aspect is applied to a type, which must be a numeric derived type
+(typically a floating-point type), that
+will represent values within the dimension system. Each @code{DIMENSION}
+corresponds to one particular dimension. A maximum of 7 dimensions may
+be specified. @code{Unit_Name} is the name of the dimension (for example
+@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities
+of this dimension (for example @code{m} for @code{Meter}).
+@code{Dim_Symbol} gives
+the identification within the dimension system (typically this is a
+single letter, e.g. @code{L} standing for length for unit name @code{Meter}).
+The @code{Unit_Symbol} is used in formatted output of dimensioned quantities.
+The @code{Dim_Symbol} is used in error messages when numeric operations have
+inconsistent dimensions.
+
+GNAT provides the standard definition of the International MKS system in
+the run-time package @code{System.Dim.Mks}. You can easily define
+similar packages for cgs units or British units, and define conversion factors
+between values in different systems. The MKS system is characterized by the
+following aspect:
+
+@example
+type Mks_Type is new Long_Long_Float with
+ Dimension_System => (
+ (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
+ (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
+ (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
+ (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
+ (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'),
+ (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
+ (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
+@end example
+
+Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to
+represent a theta character (avoiding the use of extended Latin-1
+characters in this context).
+
+See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users
+Guide for detailed examples of use of the dimension system.
+
+@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12b}
+@section Aspect Disable_Controlled
+
+
+@geindex Disable_Controlled
+
+The aspect @code{Disable_Controlled} is defined for controlled record types. If
+active, this aspect causes suppression of all related calls to @code{Initialize},
+@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation,
+where for example you might want a record to be controlled or not depending on
+whether some run-time check is enabled or suppressed.
+
+@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12c}
+@section Aspect Effective_Reads
+
+
+@geindex Effective_Reads
+
+This aspect is equivalent to @ref{59,,pragma Effective_Reads}.
+
+@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12d}
+@section Aspect Effective_Writes
+
+
+@geindex Effective_Writes
+
+This aspect is equivalent to @ref{5b,,pragma Effective_Writes}.
+
+@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12e}
+@section Aspect Extensions_Visible
+
+
+@geindex Extensions_Visible
+
+This aspect is equivalent to @ref{66,,pragma Extensions_Visible}.
+
+@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{12f}
+@section Aspect Favor_Top_Level
+
+
+@geindex Favor_Top_Level
+
+This boolean aspect is equivalent to @ref{6b,,pragma Favor_Top_Level}.
+
+@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{130}
+@section Aspect Ghost
+
+
+@geindex Ghost
+
+This aspect is equivalent to @ref{6f,,pragma Ghost}.
+
+@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{131}
+@section Aspect Global
+
+
+@geindex Global
+
+This aspect is equivalent to @ref{71,,pragma Global}.
+
+@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{132}
+@section Aspect Initial_Condition
+
+
+@geindex Initial_Condition
+
+This aspect is equivalent to @ref{7e,,pragma Initial_Condition}.
+
+@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{133}
+@section Aspect Initializes
+
+
+@geindex Initializes
+
+This aspect is equivalent to @ref{81,,pragma Initializes}.
+
+@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{134}
+@section Aspect Inline_Always
+
+
+@geindex Inline_Always
+
+This boolean aspect is equivalent to @ref{83,,pragma Inline_Always}.
+
+@node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{135}
+@section Aspect Invariant
+
+
+@geindex Invariant
+
+This aspect is equivalent to @ref{8a,,pragma Invariant}. It is a
+synonym for the language defined aspect @code{Type_Invariant} except
+that it is separately controllable using pragma @code{Assertion_Policy}.
+
+@node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{136}
+@section Aspect Invariant’Class
+
+
+@geindex Invariant'Class
+
+This aspect is equivalent to @ref{101,,pragma Type_Invariant_Class}. It is a
+synonym for the language defined aspect @code{Type_Invariant'Class} except
+that it is separately controllable using pragma @code{Assertion_Policy}.
+
+@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{137}
+@section Aspect Iterable
+
+
+@geindex Iterable
+
+This aspect provides a light-weight mechanism for loops and quantified
+expressions over container types, without the overhead imposed by the tampering
+checks of standard Ada 2012 iterators. The value of the aspect is an aggregate
+with six named components, of which the last three are optional: @code{First},
+@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}.
+When only the first three components are specified, only the
+@code{for .. in} form of iteration over cursors is available. When @code{Element}
+is specified, both this form and the @code{for .. of} form of iteration over
+elements are available. If the last two components are specified, reverse
+iterations over the container can be specified (analogous to what can be done
+over predefined containers that support the @code{Reverse_Iterator} interface).
+The following is a typical example of use:
+
+@example
+type List is private with
+ Iterable => (First => First_Cursor,
+ Next => Advance,
+ Has_Element => Cursor_Has_Element
+ [,Element => Get_Element]
+ [,Last => Last_Cursor]
+ [,Previous => Retreat]);
+@end example
+
+
+@itemize *
+
+@item
+The values of @code{First} and @code{Last} are primitive operations of the
+container type that return a @code{Cursor}, which must be a type declared in
+the container package or visible from it. For example:
+@end itemize
+
+@example
+function First_Cursor (Cont : Container) return Cursor;
+function Last_Cursor (Cont : Container) return Cursor;
+@end example
+
+
+@itemize *
+
+@item
+The values of @code{Next} and @code{Previous} are primitive operations of the container type that take
+both a container and a cursor and yield a cursor. For example:
+@end itemize
+
+@example
+function Advance (Cont : Container; Position : Cursor) return Cursor;
+function Retreat (Cont : Container; Position : Cursor) return Cursor;
+@end example
+
+
+@itemize *
+
+@item
+The value of @code{Has_Element} is a primitive operation of the container type
+that takes both a container and a cursor and yields a boolean. For example:
+@end itemize
+
+@example
+function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
+@end example
+
+
+@itemize *
+
+@item
+The value of @code{Element} is a primitive operation of the container type that
+takes both a container and a cursor and yields an @code{Element_Type}, which must
+be a type declared in the container package or visible from it. For example:
+@end itemize
+
+@example
+function Get_Element (Cont : Container; Position : Cursor) return Element_Type;
+@end example
+
+This aspect is used in the GNAT-defined formal container packages.
+
+@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{138}
+@section Aspect Linker_Section
+
+
+@geindex Linker_Section
+
+This aspect is equivalent to @ref{92,,pragma Linker_Section}.
+
+@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{139}
+@section Aspect Lock_Free
+
+
+@geindex Lock_Free
+
+This boolean aspect is equivalent to @ref{94,,pragma Lock_Free}.
+
+@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13a}
+@section Aspect Max_Queue_Length
+
+
+@geindex Max_Queue_Length
+
+This aspect is equivalent to @ref{9c,,pragma Max_Queue_Length}.
+
+@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13b}
+@section Aspect No_Caching
+
+
+@geindex No_Caching
+
+This boolean aspect is equivalent to @ref{9f,,pragma No_Caching}.
+
+@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13c}
+@section Aspect No_Elaboration_Code_All
+
+
+@geindex No_Elaboration_Code_All
+
+This aspect is equivalent to @ref{a2,,pragma No_Elaboration_Code_All}
+for a program unit.
+
+@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13d}
+@section Aspect No_Inline
+
+
+@geindex No_Inline
+
+This boolean aspect is equivalent to @ref{a5,,pragma No_Inline}.
+
+@node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13e}
+@section Aspect No_Tagged_Streams
+
+
+@geindex No_Tagged_Streams
+
+This aspect is equivalent to @ref{a9,,pragma No_Tagged_Streams} with an
+argument specifying a root tagged type (thus this aspect can only be
+applied to such a type).
+
+@node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{13f}
+@section Aspect No_Task_Parts
+
+
+@geindex No_Task_Parts
+
+Applies to a type. If True, requires that the type and any descendants
+do not have any task parts. The rules for this aspect are the same as
+for the language-defined No_Controlled_Parts aspect (see RM-H.4.1),
+replacing “controlled” with “task”.
+
+If No_Task_Parts is True for a type T, then the compiler can optimize
+away certain tasking-related code that would otherwise be needed
+for T’Class, because descendants of T might contain tasks.
+
+@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{140}
+@section Aspect Object_Size
+
+
+@geindex Object_Size
+
+This aspect is equivalent to @ref{141,,attribute Object_Size}.
+
+@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{142}
+@section Aspect Obsolescent
+
+
+@geindex Obsolescent
+
+This aspect is equivalent to @ref{ac,,pragma Obsolescent}. Note that the
+evaluation of this aspect happens at the point of occurrence, it is not
+delayed until the freeze point.
+
+@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{143}
+@section Aspect Part_Of
+
+
+@geindex Part_Of
+
+This aspect is equivalent to @ref{b3,,pragma Part_Of}.
+
+@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{144}
+@section Aspect Persistent_BSS
+
+
+@geindex Persistent_BSS
+
+This boolean aspect is equivalent to @ref{b6,,pragma Persistent_BSS}.
+
+@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{145}
+@section Aspect Predicate
+
+
+@geindex Predicate
+
+This aspect is equivalent to @ref{bd,,pragma Predicate}. It is thus
+similar to the language defined aspects @code{Dynamic_Predicate}
+and @code{Static_Predicate} except that whether the resulting
+predicate is static or dynamic is controlled by the form of the
+expression. It is also separately controllable using pragma
+@code{Assertion_Policy}.
+
+@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{146}
+@section Aspect Pure_Function
+
+
+@geindex Pure_Function
+
+This boolean aspect is equivalent to @ref{c9,,pragma Pure_Function}.
+
+@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{147}
+@section Aspect Refined_Depends
+
+
+@geindex Refined_Depends
+
+This aspect is equivalent to @ref{cd,,pragma Refined_Depends}.
+
+@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{148}
+@section Aspect Refined_Global
+
+
+@geindex Refined_Global
+
+This aspect is equivalent to @ref{cf,,pragma Refined_Global}.
+
+@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{149}
+@section Aspect Refined_Post
+
+
+@geindex Refined_Post
+
+This aspect is equivalent to @ref{d1,,pragma Refined_Post}.
+
+@node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14a}
+@section Aspect Refined_State
+
+
+@geindex Refined_State
+
+This aspect is equivalent to @ref{d3,,pragma Refined_State}.
+
+@node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14b}
+@section Aspect Relaxed_Initialization
+
+
+@geindex Refined_Initialization
+
+For the syntax and semantics of this aspect, see the SPARK 2014 Reference
+Manual, section 6.10.
+
+@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14c}
+@section Aspect Remote_Access_Type
+
+
+@geindex Remote_Access_Type
+
+This aspect is equivalent to @ref{d6,,pragma Remote_Access_Type}.
+
+@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14d}
+@section Aspect Secondary_Stack_Size
+
+
+@geindex Secondary_Stack_Size
+
+This aspect is equivalent to @ref{dc,,pragma Secondary_Stack_Size}.
+
+@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14e}
+@section Aspect Scalar_Storage_Order
+
+
+@geindex Scalar_Storage_Order
+
+This aspect is equivalent to a @ref{14f,,attribute Scalar_Storage_Order}.
+
+@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{150}
+@section Aspect Shared
+
+
+@geindex Shared
+
+This boolean aspect is equivalent to @ref{df,,pragma Shared}
+and is thus a synonym for aspect @code{Atomic}.
+
+@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{151}
+@section Aspect Simple_Storage_Pool
+
+
+@geindex Simple_Storage_Pool
+
+This aspect is equivalent to @ref{e4,,attribute Simple_Storage_Pool}.
+
+@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{152}
+@section Aspect Simple_Storage_Pool_Type
+
+
+@geindex Simple_Storage_Pool_Type
+
+This boolean aspect is equivalent to @ref{e3,,pragma Simple_Storage_Pool_Type}.
+
+@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{153}
+@section Aspect SPARK_Mode
+
+
+@geindex SPARK_Mode
+
+This aspect is equivalent to @ref{eb,,pragma SPARK_Mode} and
+may be specified for either or both of the specification and body
+of a subprogram or package.
+
+@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{154}
+@section Aspect Suppress_Debug_Info
+
+
+@geindex Suppress_Debug_Info
+
+This boolean aspect is equivalent to @ref{f3,,pragma Suppress_Debug_Info}.
+
+@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{155}
+@section Aspect Suppress_Initialization
+
+
+@geindex Suppress_Initialization
+
+This boolean aspect is equivalent to @ref{f6,,pragma Suppress_Initialization}.
+
+@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{156}
+@section Aspect Test_Case
+
+
+@geindex Test_Case
+
+This aspect is equivalent to @ref{fa,,pragma Test_Case}.
+
+@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{157}
+@section Aspect Thread_Local_Storage
+
+
+@geindex Thread_Local_Storage
+
+This boolean aspect is equivalent to @ref{fc,,pragma Thread_Local_Storage}.
+
+@node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{158}
+@section Aspect Universal_Aliasing
+
+
+@geindex Universal_Aliasing
+
+This boolean aspect is equivalent to @ref{106,,pragma Universal_Aliasing}.
+
+@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{159}
+@section Aspect Unmodified
+
+
+@geindex Unmodified
+
+This boolean aspect is equivalent to @ref{108,,pragma Unmodified}.
+
+@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15a}
+@section Aspect Unreferenced
+
+
+@geindex Unreferenced
+
+This boolean aspect is equivalent to @ref{10a,,pragma Unreferenced}.
+
+When using the @code{-gnat2022} switch, this aspect is also supported on formal
+parameters, which is in particular the only form possible for expression
+functions.
+
+@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15b}
+@section Aspect Unreferenced_Objects
+
+
+@geindex Unreferenced_Objects
+
+This boolean aspect is equivalent to @ref{10c,,pragma Unreferenced_Objects}.
+
+@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15c}
+@section Aspect Value_Size
+
+
+@geindex Value_Size
+
+This aspect is equivalent to @ref{15d,,attribute Value_Size}.
+
+@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15e}
+@section Aspect Volatile_Full_Access
+
+
+@geindex Volatile_Full_Access
+
+This boolean aspect is equivalent to @ref{116,,pragma Volatile_Full_Access}.
+
+@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{15f}
+@section Aspect Volatile_Function
+
+
+@geindex Volatile_Function
+
+This boolean aspect is equivalent to @ref{118,,pragma Volatile_Function}.
+
+@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{160}
+@section Aspect Warnings
+
+
+@geindex Warnings
+
+This aspect is equivalent to the two argument form of @ref{11a,,pragma Warnings},
+where the first argument is @code{ON} or @code{OFF} and the second argument
+is the entity.
+
+@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top
+@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{161}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{162}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}
+@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. It also
+describes additional implementation-dependent features of standard
+language-defined 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
+* Attribute Abort_Signal::
+* Attribute Address_Size::
+* Attribute Asm_Input::
+* Attribute Asm_Output::
+* Attribute Atomic_Always_Lock_Free::
+* Attribute Bit::
+* Attribute Bit_Position::
+* Attribute Code_Address::
+* Attribute Compiler_Version::
+* Attribute Constrained::
+* Attribute Default_Bit_Order::
+* Attribute Default_Scalar_Storage_Order::
+* Attribute Deref::
+* Attribute Descriptor_Size::
+* Attribute Elaborated::
+* Attribute Elab_Body::
+* Attribute Elab_Spec::
+* Attribute Elab_Subp_Body::
+* Attribute Emax::
+* Attribute Enabled::
+* Attribute Enum_Rep::
+* Attribute Enum_Val::
+* Attribute Epsilon::
+* Attribute Fast_Math::
+* Attribute Finalization_Size::
+* Attribute Fixed_Value::
+* Attribute From_Any::
+* Attribute Has_Access_Values::
+* Attribute Has_Discriminants::
+* Attribute Has_Tagged_Values::
+* Attribute Img::
+* Attribute Initialized::
+* Attribute Integer_Value::
+* Attribute Invalid_Value::
+* Attribute Iterable::
+* Attribute Large::
+* Attribute Library_Level::
+* Attribute Loop_Entry::
+* Attribute Machine_Size::
+* Attribute Mantissa::
+* Attribute Maximum_Alignment::
+* Attribute Max_Integer_Size::
+* Attribute Mechanism_Code::
+* Attribute Null_Parameter::
+* Attribute Object_Size::
+* Attribute Old::
+* Attribute Passed_By_Reference::
+* Attribute Pool_Address::
+* Attribute Range_Length::
+* Attribute Restriction_Set::
+* Attribute Result::
+* Attribute Safe_Emax::
+* Attribute Safe_Large::
+* Attribute Safe_Small::
+* Attribute Scalar_Storage_Order::
+* Attribute Simple_Storage_Pool::
+* Attribute Small::
+* Attribute Small_Denominator::
+* Attribute Small_Numerator::
+* Attribute Storage_Unit::
+* Attribute Stub_Type::
+* Attribute System_Allocator_Alignment::
+* Attribute Target_Name::
+* Attribute To_Address::
+* Attribute To_Any::
+* Attribute Type_Class::
+* Attribute Type_Key::
+* Attribute TypeCode::
+* Attribute Unconstrained_Array::
+* Attribute Universal_Literal_String::
+* Attribute Unrestricted_Access::
+* Attribute Update::
+* Attribute Valid_Value::
+* Attribute Valid_Scalars::
+* Attribute VADS_Size::
+* Attribute Value_Size::
+* Attribute Wchar_T_Size::
+* Attribute Word_Size::
+
+@end menu
+
+@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{163}
+@section Attribute Abort_Signal
+
+
+@geindex Abort_Signal
+
+@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 Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{164}
+@section Attribute Address_Size
+
+
+@geindex Size of `@w{`}Address`@w{`}
+
+@geindex Address_Size
+
+@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 nonstatic because Address
+is a private type.
+
+@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{165}
+@section Attribute Asm_Input
+
+
+@geindex Asm_Input
+
+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{166,,Machine Code Insertions}
+
+@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{167}
+@section Attribute Asm_Output
+
+
+@geindex Asm_Output
+
+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{166,,Machine Code Insertions}
+
+@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{168}
+@section Attribute Atomic_Always_Lock_Free
+
+
+@geindex Atomic_Always_Lock_Free
+
+The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type.
+The result is a Boolean value which is True if the type has discriminants,
+and False otherwise. The result indicate whether atomic operations are
+supported by the target for the given type.
+
+@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{169}
+@section Attribute Bit
+
+
+@geindex Bit
+
+@code{obj'Bit}, where @code{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 `universal_integer' and is always a nonnegative number smaller
+than @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{obj.all'Bit} is subject to an @code{Access_Check} for the
+designated object. Similarly for a record component
+@code{X.C'Bit} is subject to a discriminant check and
+@code{X(I).Bit} and @code{X(I1..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 Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16a}
+@section Attribute Bit_Position
+
+
+@geindex Bit_Position
+
+@code{R.C'Bit_Position}, where @code{R} is a record object and @code{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 `universal_integer'. The value depends only on the field
+@code{C} and is independent of the alignment of
+the containing record @code{R}.
+
+@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16b}
+@section Attribute Code_Address
+
+
+@geindex Code_Address
+
+@geindex Subprogram address
+
+@geindex Address of subprogram code
+
+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:
+
+@example
+procedure K is ...
+
+procedure L;
+for L'Address use K'Address;
+pragma Import (Ada, L);
+@end example
+
+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 Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16c}
+@section Attribute Compiler_Version
+
+
+@geindex Compiler_Version
+
+@code{Standard'Compiler_Version} (@code{Standard} is the only allowed
+prefix) yields a static string identifying the version of the compiler
+being used to compile the unit containing the attribute reference.
+
+@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16d}
+@section Attribute Constrained
+
+
+@geindex Constrained
+
+In addition to the usage of this attribute in the Ada RM, GNAT
+also permits the use of the @code{'Constrained} attribute
+in a generic template
+for any type, including types without discriminants. The value of this
+attribute in the generic instance when applied to a scalar type or a
+record type without discriminants is always @code{True}. This usage is
+compatible with older Ada compilers, including notably DEC Ada.
+
+@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16e}
+@section Attribute Default_Bit_Order
+
+
+@geindex Big endian
+
+@geindex Little endian
+
+@geindex Default_Bit_Order
+
+@code{Standard'Default_Bit_Order} (@code{Standard} is the only
+allowed 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 Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{16f}
+@section Attribute Default_Scalar_Storage_Order
+
+
+@geindex Big endian
+
+@geindex Little endian
+
+@geindex Default_Scalar_Storage_Order
+
+@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only
+allowed prefix), provides the current value of the default scalar storage
+order (as specified using pragma @code{Default_Scalar_Storage_Order}, or
+equal to @code{Default_Bit_Order} if unspecified) as a
+@code{System.Bit_Order} value. This is a static attribute.
+
+@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{170}
+@section Attribute Deref
+
+
+@geindex Deref
+
+The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields
+the variable of type @code{typ} that is located at the given address. It is similar
+to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to
+a named access-to-@cite{typ} type, except that it yields a variable, so it can be
+used on the left side of an assignment.
+
+@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{171}
+@section Attribute Descriptor_Size
+
+
+@geindex Descriptor
+
+@geindex Dope vector
+
+@geindex Descriptor_Size
+
+Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the
+descriptor allocated for a type. The result is non-zero only for unconstrained
+array types and the returned value is of type universal integer. In GNAT, an
+array descriptor contains bounds information and is located immediately before
+the first element of the array.
+
+@example
+type Unconstr_Array is array (Short_Short_Integer range <>) of Positive;
+Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
+@end example
+
+The attribute takes into account any padding due to the alignment of the
+component type. In the example above, the descriptor contains two values
+of type @code{Short_Short_Integer} representing the low and high bound. But,
+since @code{Positive} has an alignment of 4, the size of the descriptor is
+@code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32,
+which yields a size of 32 bits, i.e. including 16 bits of padding.
+
+@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{172}
+@section Attribute Elaborated
+
+
+@geindex Elaborated
+
+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 Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{173}
+@section Attribute Elab_Body
+
+
+@geindex Elab_Body
+
+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 Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{174}
+@section Attribute Elab_Spec
+
+
+@geindex Elab_Spec
+
+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 Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{175}
+@section Attribute Elab_Subp_Body
+
+
+@geindex Elab_Subp_Body
+
+This attribute can only be applied to a library level subprogram
+name and is only allowed in CodePeer mode. It returns the entity
+for the corresponding elaboration procedure for elaborating the body
+of the referenced subprogram unit. This is used in the main generated
+elaboration procedure by the binder in CodePeer mode only and is unrecognized
+otherwise.
+
+@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{176}
+@section Attribute Emax
+
+
+@geindex Ada 83 attributes
+
+@geindex Emax
+
+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 Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{177}
+@section Attribute Enabled
+
+
+@geindex Enabled
+
+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 Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{178}
+@section Attribute Enum_Rep
+
+
+@geindex Representation of enums
+
+@geindex Enum_Rep
+
+Note that this attribute is now standard in Ada 202x and is available
+as an implementation defined attribute for earlier Ada versions.
+
+For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a
+function with the following spec:
+
+@example
+function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>;
+@end example
+
+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{S'Enum_Rep} is equivalent to
+@code{typ'Enum_Rep(S)} where @code{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{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 Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{179}
+@section Attribute Enum_Val
+
+
+@geindex Representation of enums
+
+@geindex Enum_Val
+
+Note that this attribute is now standard in Ada 202x and is available
+as an implementation defined attribute for earlier Ada versions.
+
+For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a
+function with the following spec:
+
+@example
+function S'Enum_Val (Arg : <Universal_Integer>) return S'Base;
+@end example
+
+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 Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17a}
+@section Attribute Epsilon
+
+
+@geindex Ada 83 attributes
+
+@geindex Epsilon
+
+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 Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17b}
+@section Attribute Fast_Math
+
+
+@geindex Fast_Math
+
+@code{Standard'Fast_Math} (@code{Standard} is the only allowed
+prefix) yields a static Boolean value that is True if pragma
+@code{Fast_Math} is active, and False otherwise.
+
+@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17c}
+@section Attribute Finalization_Size
+
+
+@geindex Finalization_Size
+
+The prefix of attribute @code{Finalization_Size} must be an object or
+a non-class-wide type. This attribute returns the size of any hidden data
+reserved by the compiler to handle finalization-related actions. The type of
+the attribute is `universal_integer'.
+
+@code{Finalization_Size} yields a value of zero for a type with no controlled
+parts, an object whose type has no controlled parts, or an object of a
+class-wide type whose tag denotes a type with no controlled parts.
+
+Note that only heap-allocated objects contain finalization data.
+
+@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17d}
+@section Attribute Fixed_Value
+
+
+@geindex Fixed_Value
+
+For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a
+function with the following specification:
+
+@example
+function S'Fixed_Value (Arg : <Universal_Integer>) return S;
+@end example
+
+The value returned is the fixed-point value @code{V} such that:
+
+@example
+V = Arg * S'Small
+@end example
+
+The effect is thus similar to first converting the argument to the
+integer type used to represent @code{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 Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17e}
+@section Attribute From_Any
+
+
+@geindex From_Any
+
+This internal attribute is used for the generation of remote subprogram
+stubs in the context of the Distributed Systems Annex.
+
+@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{17f}
+@section Attribute Has_Access_Values
+
+
+@geindex Access values
+@geindex testing for
+
+@geindex Has_Access_Values
+
+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 Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{180}
+@section Attribute Has_Discriminants
+
+
+@geindex Discriminants
+@geindex testing for
+
+@geindex Has_Discriminants
+
+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 Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{181}
+@section Attribute Has_Tagged_Values
+
+
+@geindex Tagged values
+@geindex testing for
+
+@geindex Has_Tagged_Values
+
+The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a
+Boolean value which is True if the type is a composite type (array or record)
+that is either a tagged type or has a subcomponent that is tagged, 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 Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{182}
+@section Attribute Img
+
+
+@geindex Img
+
+The @code{Img} attribute differs from @code{Image} in that, while both can be
+applied directly to an object, @code{Img} cannot be applied to types.
+
+Example usage of the attribute:
+
+@example
+Put_Line ("X = " & X'Img);
+@end example
+
+which has the same meaning as the more verbose:
+
+@example
+Put_Line ("X = " & T'Image (X));
+@end example
+
+where @code{T} is the (sub)type of the object @code{X}.
+
+Note that technically, in analogy to @code{Image},
+@code{X'Img} returns a parameterless function
+that returns the appropriate string when called. This means that
+@code{X'Img} can be renamed as a function-returning-string, or used
+in an instantiation as a function parameter.
+
+@node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{183}
+@section Attribute Initialized
+
+
+@geindex Initialized
+
+For the syntax and semantics of this attribute, see the SPARK 2014 Reference
+Manual, section 6.10.
+
+@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{184}
+@section Attribute Integer_Value
+
+
+@geindex Integer_Value
+
+For every integer type @code{S}, @code{S'Integer_Value} denotes a
+function with the following spec:
+
+@example
+function S'Integer_Value (Arg : <Universal_Fixed>) return S;
+@end example
+
+The value returned is the integer value @code{V}, such that:
+
+@example
+Arg = V * T'Small
+@end example
+
+where @code{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 Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{185}
+@section Attribute Invalid_Value
+
+
+@geindex Invalid_Value
+
+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 Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{186}
+@section Attribute Iterable
+
+
+@geindex Iterable
+
+Equivalent to Aspect Iterable.
+
+@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{187}
+@section Attribute Large
+
+
+@geindex Ada 83 attributes
+
+@geindex Large
+
+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 Attribute Library_Level,Attribute Loop_Entry,Attribute Large,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{188}
+@section Attribute Library_Level
+
+
+@geindex Library_Level
+
+@code{P'Library_Level}, where P is an entity name,
+returns a Boolean value which is True if the entity is declared
+at the library level, and False otherwise. Note that within a
+generic instantiation, the name of the generic unit denotes the
+instance, which means that this attribute can be used to test
+if a generic is instantiated at the library level, as shown
+in this example:
+
+@example
+generic
+ ...
+package Gen is
+ pragma Compile_Time_Error
+ (not Gen'Library_Level,
+ "Gen can only be instantiated at library level");
+ ...
+end Gen;
+@end example
+
+@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Library_Level,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{189}
+@section Attribute Loop_Entry
+
+
+@geindex Loop_Entry
+
+Syntax:
+
+@example
+X'Loop_Entry [(loop_name)]
+@end example
+
+The @code{Loop_Entry} attribute is used to refer to the value that an
+expression had upon entry to a given loop in much the same way that the
+@code{Old} attribute in a subprogram postcondition can be used to refer
+to the value an expression had upon entry to the subprogram. The
+relevant loop is either identified by the given loop name, or it is the
+innermost enclosing loop when no loop name is given.
+
+A @code{Loop_Entry} attribute can only occur within an @code{Assert},
+@code{Assert_And_Cut}, @code{Assume}, @code{Loop_Variant} or @code{Loop_Invariant} pragma.
+In addition, such a pragma must be one of the items in the sequence
+of statements of a loop body, or nested inside block statements that
+appear in the sequence of statements of a loop body.
+A common use of @code{Loop_Entry} is to compare the current value of objects with
+their initial value at loop entry, in a @code{Loop_Invariant} pragma.
+
+The effect of using @code{X'Loop_Entry} is the same as declaring
+a constant initialized with the initial value of @code{X} at loop
+entry. This copy is not performed if the loop is not entered, or if the
+corresponding pragmas are ignored or disabled.
+
+@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18a}
+@section Attribute Machine_Size
+
+
+@geindex Machine_Size
+
+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 Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18b}
+@section Attribute Mantissa
+
+
+@geindex Ada 83 attributes
+
+@geindex Mantissa
+
+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 Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18c}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18d}
+@section Attribute Maximum_Alignment
+
+
+@geindex Alignment
+@geindex maximum
+
+@geindex Maximum_Alignment
+
+@code{Standard'Maximum_Alignment} (@code{Standard} is the only
+allowed 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 Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{18e}
+@section Attribute Max_Integer_Size
+
+
+@geindex Max_Integer_Size
+
+@code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed
+prefix) provides the size of the largest supported integer type for
+the target. The result is a static constant.
+
+@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{18f}
+@section Attribute Mechanism_Code
+
+
+@geindex Return values
+@geindex passing mechanism
+
+@geindex Parameters
+@geindex passing mechanism
+
+@geindex Mechanism_Code
+
+@code{func'Mechanism_Code} yields an integer code for the
+mechanism used for the result of function @code{func}, and
+@code{subprog'Mechanism_Code (n)} yields the mechanism
+used for formal parameter number `n' (a static integer value, with 1
+meaning the first parameter) of subprogram @code{subprog}. The code returned is:
+
+
+@table @asis
+
+@item `1'
+
+by copy (value)
+
+@item `2'
+
+by reference
+@end table
+
+@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{190}
+@section Attribute Null_Parameter
+
+
+@geindex Zero address
+@geindex passing
+
+@geindex Null_Parameter
+
+A reference @code{T'Null_Parameter} denotes an imaginary object of
+type or subtype @code{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 Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{141}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{191}
+@section Attribute Object_Size
+
+
+@geindex Size
+@geindex used for objects
+
+@geindex Object_Size
+
+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:
+
+@example
+type Rec is record
+ I : Integer;
+ C : Character;
+end record;
+@end example
+
+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).
+
+If the alignment of the above record is specified to be 1, then the
+object size will be 40 (5 bytes). This is true by default, and also
+an object size of 40 can be explicitly specified in this case.
+
+A consequence of this capability is that different object sizes can be
+given to subtypes that would otherwise be considered in Ada to be
+statically matching. But it makes no sense to consider such subtypes
+as statically matching. Consequently, GNAT adds a rule
+to the static matching rules that requires object sizes to match.
+Consider this example:
+
+@example
+ 1. procedure BadAVConvert is
+ 2. type R is new Integer;
+ 3. subtype R1 is R range 1 .. 10;
+ 4. subtype R2 is R range 1 .. 10;
+ 5. for R1'Object_Size use 8;
+ 6. for R2'Object_Size use 16;
+ 7. type R1P is access all R1;
+ 8. type R2P is access all R2;
+ 9. R1PV : R1P := new R1'(4);
+10. R2PV : R2P;
+11. begin
+12. R2PV := R2P (R1PV);
+ |
+ >>> target designated subtype not compatible with
+ type "R1" defined at line 3
+
+13. end;
+@end example
+
+In the absence of lines 5 and 6,
+types @code{R1} and @code{R2} statically match and
+hence the conversion on line 12 is legal. But since lines 5 and 6
+cause the object sizes to differ, GNAT considers that types
+@code{R1} and @code{R2} are not statically matching, and line 12
+generates the diagnostic shown above.
+
+Similar additional checks are performed in other contexts requiring
+statically matching subtypes.
+
+@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{192}
+@section Attribute Old
+
+
+@geindex Old
+
+In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage
+within @code{Post} aspect), GNAT also permits the use of this attribute
+in implementation defined pragmas @code{Postcondition},
+@code{Contract_Cases} and @code{Test_Case}. Also usages of
+@code{Old} which would be illegal according to the Ada 2012 RM
+definition are allowed under control of
+implementation defined pragma @code{Unevaluated_Use_Of_Old}.
+
+@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{193}
+@section Attribute Passed_By_Reference
+
+
+@geindex Parameters
+@geindex when passed by reference
+
+@geindex Passed_By_Reference
+
+@code{typ'Passed_By_Reference} for any subtype @cite{typ} 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 nonstatic.
+
+@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{194}
+@section Attribute Pool_Address
+
+
+@geindex Pool_Address
+
+@code{X'Pool_Address} for any object @code{X} returns the address
+of X within its storage pool. This is the same as
+@code{X'Address}, except that for an unconstrained array whose
+bounds are allocated just before the first component,
+@code{X'Pool_Address} returns the address of those bounds,
+whereas @code{X'Address} returns the address of the first
+component.
+
+Here, we are interpreting ‘storage pool’ broadly to mean
+@code{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{Ptr.all'Pool_Address} is
+what is passed to @code{Allocate} and returned from @code{Deallocate}.
+
+@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{195}
+@section Attribute Range_Length
+
+
+@geindex Range_Length
+
+@code{typ'Range_Length} for any discrete type @cite{typ} 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{Length} applied to the array itself.
+
+@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{196}
+@section Attribute Restriction_Set
+
+
+@geindex Restriction_Set
+
+@geindex Restrictions
+
+This attribute allows compile time testing of restrictions that
+are currently in effect. It is primarily intended for specializing
+code in the run-time based on restrictions that are active (e.g.
+don’t need to save fpt registers if restriction No_Floating_Point
+is known to be in effect), but can be used anywhere.
+
+There are two forms:
+
+@example
+System'Restriction_Set (partition_boolean_restriction_NAME)
+System'Restriction_Set (No_Dependence => library_unit_NAME);
+@end example
+
+In the case of the first form, the only restriction names
+allowed are parameterless restrictions that are checked
+for consistency at bind time. For a complete list see the
+subtype @code{System.Rident.Partition_Boolean_Restrictions}.
+
+The result returned is True if the restriction is known to
+be in effect, and False if the restriction is known not to
+be in effect. An important guarantee is that the value of
+a Restriction_Set attribute is known to be consistent throughout
+all the code of a partition.
+
+This is trivially achieved if the entire partition is compiled
+with a consistent set of restriction pragmas. However, the
+compilation model does not require this. It is possible to
+compile one set of units with one set of pragmas, and another
+set of units with another set of pragmas. It is even possible
+to compile a spec with one set of pragmas, and then WITH the
+same spec with a different set of pragmas. Inconsistencies
+in the actual use of the restriction are checked at bind time.
+
+In order to achieve the guarantee of consistency for the
+Restriction_Set pragma, we consider that a use of the pragma
+that yields False is equivalent to a violation of the
+restriction.
+
+So for example if you write
+
+@example
+if System'Restriction_Set (No_Floating_Point) then
+ ...
+else
+ ...
+end if;
+@end example
+
+And the result is False, so that the else branch is executed,
+you can assume that this restriction is not set for any unit
+in the partition. This is checked by considering this use of
+the restriction pragma to be a violation of the restriction
+No_Floating_Point. This means that no other unit can attempt
+to set this restriction (if some unit does attempt to set it,
+the binder will refuse to bind the partition).
+
+Technical note: The restriction name and the unit name are
+intepreted entirely syntactically, as in the corresponding
+Restrictions pragma, they are not analyzed semantically,
+so they do not have a type.
+
+@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{197}
+@section Attribute Result
+
+
+@geindex Result
+
+@code{function'Result} can only be used with in a Postcondition pragma
+for a function. The prefix must be the name of the corresponding function. This
+is used to refer to the result of the function in the postcondition expression.
+For a further discussion of the use of this attribute and examples of its use,
+see the description of pragma Postcondition.
+
+@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{198}
+@section Attribute Safe_Emax
+
+
+@geindex Ada 83 attributes
+
+@geindex Safe_Emax
+
+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 Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{199}
+@section Attribute Safe_Large
+
+
+@geindex Ada 83 attributes
+
+@geindex Safe_Large
+
+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 Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19a}
+@section Attribute Safe_Small
+
+
+@geindex Ada 83 attributes
+
+@geindex Safe_Small
+
+The @code{Safe_Small} 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 Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{14f}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19b}
+@section Attribute Scalar_Storage_Order
+
+
+@geindex Endianness
+
+@geindex Scalar storage order
+
+@geindex Scalar_Storage_Order
+
+For every array or record type @code{S}, the representation attribute
+@code{Scalar_Storage_Order} denotes the order in which storage elements
+that make up scalar components are ordered within S. The value given must
+be a static expression of type System.Bit_Order. The following is an example
+of the use of this feature:
+
+@example
+-- Component type definitions
+
+subtype Yr_Type is Natural range 0 .. 127;
+subtype Mo_Type is Natural range 1 .. 12;
+subtype Da_Type is Natural range 1 .. 31;
+
+-- Record declaration
+
+type Date is record
+ Years_Since_1980 : Yr_Type;
+ Month : Mo_Type;
+ Day_Of_Month : Da_Type;
+end record;
+
+-- Record representation clause
+
+for Date use record
+ Years_Since_1980 at 0 range 0 .. 6;
+ Month at 0 range 7 .. 10;
+ Day_Of_Month at 0 range 11 .. 15;
+end record;
+
+-- Attribute definition clauses
+
+for Date'Bit_Order use System.High_Order_First;
+for Date'Scalar_Storage_Order use System.High_Order_First;
+-- If Scalar_Storage_Order is specified, it must be consistent with
+-- Bit_Order, so it's best to always define the latter explicitly if
+-- the former is used.
+@end example
+
+Other properties are as for the standard representation attribute @code{Bit_Order}
+defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}.
+
+For a record type @code{T}, if @code{T'Scalar_Storage_Order} is
+specified explicitly, it shall be equal to @code{T'Bit_Order}. Note:
+this means that if a @code{Scalar_Storage_Order} attribute definition
+clause is not confirming, then the type’s @code{Bit_Order} shall be
+specified explicitly and set to the same value.
+
+Derived types inherit an explicitly set scalar storage order from their parent
+types. This may be overridden for the derived type by giving an explicit scalar
+storage order for it. However, for a record extension, the derived type must
+have the same scalar storage order as the parent type.
+
+A component of a record type that is itself a record or an array and that does
+not start and end on a byte boundary must have have the same scalar storage
+order as the record type. A component of a bit-packed array type that is itself
+a record or an array must have the same scalar storage order as the array type.
+
+No component of a type that has an explicit @code{Scalar_Storage_Order}
+attribute definition may be aliased.
+
+A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e.
+with a value equal to @code{System.Default_Bit_Order}) has no effect.
+
+If the opposite storage order is specified, then whenever the value of
+a scalar component of an object of type @code{S} is read, the storage
+elements of the enclosing machine scalar are first reversed (before
+retrieving the component value, possibly applying some shift and mask
+operatings on the enclosing machine scalar), and the opposite operation
+is done for writes.
+
+In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components
+are relaxed. Instead, the following rules apply:
+
+
+@itemize *
+
+@item
+the underlying storage elements are those at positions
+@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)}
+
+@item
+the sequence of underlying storage elements shall have
+a size no greater than the largest machine scalar
+
+@item
+the enclosing machine scalar is defined as the smallest machine
+scalar starting at a position no greater than
+@code{position + first_bit / storage_element_size} and covering
+storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size}
+
+@item
+the position of the component is interpreted relative to that machine
+scalar.
+@end itemize
+
+If no scalar storage order is specified for a type (either directly, or by
+inheritance in the case of a derived type), then the default is normally
+the native ordering of the target, but this default can be overridden using
+pragma @code{Default_Scalar_Storage_Order}.
+
+If a component of @code{T} is itself of a record or array type, the specfied
+@code{Scalar_Storage_Order} does `not' apply to that nested type: an explicit
+attribute definition clause must be provided for the component type as well
+if desired.
+
+Representation changes that explicitly or implicitly toggle the scalar storage
+order are not supported and may result in erroneous execution of the program,
+except when performed by means of an instance of @code{Ada.Unchecked_Conversion}.
+
+In particular, overlays are not supported and a warning is given for them:
+
+@example
+type Rec_LE is record
+ I : Integer;
+end record;
+
+for Rec_LE use record
+ I at 0 range 0 .. 31;
+end record;
+
+for Rec_LE'Bit_Order use System.Low_Order_First;
+for Rec_LE'Scalar_Storage_Order use System.Low_Order_First;
+
+type Rec_BE is record
+ I : Integer;
+end record;
+
+for Rec_BE use record
+ I at 0 range 0 .. 31;
+end record;
+
+for Rec_BE'Bit_Order use System.High_Order_First;
+for Rec_BE'Scalar_Storage_Order use System.High_Order_First;
+
+R_LE : Rec_LE;
+
+R_BE : Rec_BE;
+for R_BE'Address use R_LE'Address;
+@end example
+
+@code{warning: overlay changes scalar storage order [enabled by default]}
+
+In most cases, such representation changes ought to be replaced by an
+instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}.
+
+Note that the scalar storage order only affects the in-memory data
+representation. It has no effect on the representation used by stream
+attributes.
+
+Note that debuggers may be unable to display the correct value of scalar
+components of a type for which the opposite storage order is specified.
+
+@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e4}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{19c}
+@section Attribute Simple_Storage_Pool
+
+
+@geindex Storage pool
+@geindex simple
+
+@geindex Simple storage pool
+
+@geindex Simple_Storage_Pool
+
+For every nonformal, nonderived access-to-object type @code{Acc}, the
+representation attribute @code{Simple_Storage_Pool} may be specified
+via an attribute_definition_clause (or by specifying the equivalent aspect):
+
+@example
+My_Pool : My_Simple_Storage_Pool_Type;
+
+type Acc is access My_Data_Type;
+
+for Acc'Simple_Storage_Pool use My_Pool;
+@end example
+
+The name given in an attribute_definition_clause for the
+@code{Simple_Storage_Pool} attribute shall denote a variable of
+a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}).
+
+The use of this attribute is only allowed for a prefix denoting a type
+for which it has been specified. The type of the attribute is the type
+of the variable specified as the simple storage pool of the access type,
+and the attribute denotes that variable.
+
+It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool}
+for the same access type.
+
+If the @code{Simple_Storage_Pool} attribute has been specified for an access
+type, then applying the @code{Storage_Pool} attribute to the type is flagged
+with a warning and its evaluation raises the exception @code{Program_Error}.
+
+If the Simple_Storage_Pool attribute has been specified for an access
+type @code{S}, then the evaluation of the attribute @code{S'Storage_Size}
+returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)},
+which is intended to indicate the number of storage elements reserved for
+the simple storage pool. If the Storage_Size function has not been defined
+for the simple storage pool type, then this attribute returns zero.
+
+If an access type @code{S} has a specified simple storage pool of type
+@code{SSP}, then the evaluation of an allocator for that access type calls
+the primitive @code{Allocate} procedure for type @code{SSP}, passing
+@code{S'Simple_Storage_Pool} as the pool parameter. The detailed
+semantics of such allocators is the same as those defined for allocators
+in section 13.11 of the @cite{Ada Reference Manual}, with the term
+`simple storage pool' substituted for `storage pool'.
+
+If an access type @code{S} has a specified simple storage pool of type
+@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation}
+for that access type invokes the primitive @code{Deallocate} procedure
+for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool
+parameter. The detailed semantics of such unchecked deallocations is the same
+as defined in section 13.11.2 of the Ada Reference Manual, except that the
+term `simple storage pool' is substituted for `storage pool'.
+
+@node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{19d}
+@section Attribute Small
+
+
+@geindex Ada 83 attributes
+
+@geindex Small
+
+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 Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{19e}
+@section Attribute Small_Denominator
+
+
+@geindex Small
+
+@geindex Small_Denominator
+
+@code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the
+denominator in the representation of @code{typ'Small} as a rational number
+with coprime factors (i.e. as an irreducible fraction).
+
+@node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{19f}
+@section Attribute Small_Numerator
+
+
+@geindex Small
+
+@geindex Small_Numerator
+
+@code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the
+numerator in the representation of @code{typ'Small} as a rational number
+with coprime factors (i.e. as an irreducible fraction).
+
+@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a0}
+@section Attribute Storage_Unit
+
+
+@geindex Storage_Unit
+
+@code{Standard'Storage_Unit} (@code{Standard} is the only allowed
+prefix) provides the same value as @code{System.Storage_Unit}.
+
+@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a1}
+@section Attribute Stub_Type
+
+
+@geindex Stub_Type
+
+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 Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a2}
+@section Attribute System_Allocator_Alignment
+
+
+@geindex Alignment
+@geindex allocator
+
+@geindex System_Allocator_Alignment
+
+@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
+allowed prefix) provides the observable guaranteed to be honored by
+the system allocator (malloc). This is a static value that can be used
+in user storage pools based on malloc either to reject allocation
+with alignment too large or to enable a realignment circuitry if the
+alignment request is larger than this value.
+
+@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a3}
+@section Attribute Target_Name
+
+
+@geindex Target_Name
+
+@code{Standard'Target_Name} (@code{Standard} is the only allowed
+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 Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a4}
+@section Attribute To_Address
+
+
+@geindex To_Address
+
+The @code{System'To_Address}
+(@code{System} is the only allowed 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. This means 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 nonstatic, even if its
+argument is static). The argument must be in the range
+-(2**(m-1)) .. 2**m-1, where m is the memory size
+(typically 32 or 64). Negative values are intepreted in a
+modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on
+a 32 bits machine).
+
+@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a5}
+@section Attribute To_Any
+
+
+@geindex To_Any
+
+This internal attribute is used for the generation of remote subprogram
+stubs in the context of the Distributed Systems Annex.
+
+@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a6}
+@section Attribute Type_Class
+
+
+@geindex Type_Class
+
+@code{typ'Type_Class} for any type or subtype @cite{typ} yields
+the value of the type class for the full type of @cite{typ}. If
+@cite{typ} 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:
+
+@example
+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 example
+
+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 Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a7}
+@section Attribute Type_Key
+
+
+@geindex Type_Key
+
+The @code{Type_Key} attribute is applicable to a type or subtype and
+yields a value of type Standard.String containing encoded information
+about the type or subtype. This provides improved compatibility with
+other implementations that support this attribute.
+
+@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1a8}
+@section Attribute TypeCode
+
+
+@geindex TypeCode
+
+This internal attribute is used for the generation of remote subprogram
+stubs in the context of the Distributed Systems Annex.
+
+@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1a9}
+@section Attribute Unconstrained_Array
+
+
+@geindex Unconstrained_Array
+
+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 Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1aa}
+@section Attribute Universal_Literal_String
+
+
+@geindex Named numbers
+@geindex representation of
+
+@geindex Universal_Literal_String
+
+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).
+
+For example, the following program prints the first 50 digits of pi:
+
+@example
+with Text_IO; use Text_IO;
+with Ada.Numerics;
+procedure Pi is
+begin
+ Put (Ada.Numerics.Pi'Universal_Literal_String);
+end;
+@end example
+
+@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1ab}
+@section Attribute Unrestricted_Access
+
+
+@geindex Access
+@geindex unrestricted
+
+@geindex Unrestricted_Access
+
+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.
+
+For objects, 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 similar to first applying the
+@code{Address} attribute and then doing an unchecked conversion to a
+desired access type.
+
+For subprograms, @code{P'Unrestricted_Access} may be used where
+@code{P'Access} would be illegal, to construct a value of a
+less-nested named access type that designates a more-nested
+subprogram. This value may be used in indirect calls, so long as the
+more-nested subprogram still exists; once the subprogram containing it
+has returned, such calls are erroneous. For example:
+
+@example
+package body P is
+
+ type Less_Nested is not null access procedure;
+ Global : Less_Nested;
+
+ procedure P1 is
+ begin
+ Global.all;
+ end P1;
+
+ procedure P2 is
+ Local_Var : Integer;
+
+ procedure More_Nested is
+ begin
+ ... Local_Var ...
+ end More_Nested;
+ begin
+ Global := More_Nested'Unrestricted_Access;
+ P1;
+ end P2;
+
+end P;
+@end example
+
+When P1 is called from P2, the call via Global is OK, but if P1 were
+called after P2 returns, it would be an erroneous use of a dangling
+pointer.
+
+For objects, it is possible to use @code{Unrestricted_Access} for any
+type. However, if the result is of an access-to-unconstrained array
+subtype, then the resulting pointer has the same scope as the context
+of the attribute, and must not be returned to some enclosing scope.
+For instance, if a function uses @code{Unrestricted_Access} to create
+an access-to-unconstrained-array and returns that value to the caller,
+the result will involve dangling pointers. In addition, it is only
+valid to create pointers to unconstrained arrays using this attribute
+if the pointer has the normal default ‘fat’ representation where a
+pointer has two components, one points to the array and one points to
+the bounds. If a size clause is used to force ‘thin’ representation
+for a pointer to unconstrained where there is only space for a single
+pointer, then the resulting pointer is not usable.
+
+In the simple case where a direct use of Unrestricted_Access attempts
+to make a thin pointer for a non-aliased object, the compiler will
+reject the use as illegal, as shown in the following example:
+
+@example
+with System; use System;
+procedure SliceUA2 is
+ type A is access all String;
+ for A'Size use Standard'Address_Size;
+
+ procedure P (Arg : A) is
+ begin
+ null;
+ end P;
+
+ X : String := "hello world!";
+ X2 : aliased String := "hello world!";
+
+ AV : A := X'Unrestricted_Access; -- ERROR
+ |
+>>> illegal use of Unrestricted_Access attribute
+>>> attempt to generate thin pointer to unaliased object
+
+begin
+ P (X'Unrestricted_Access); -- ERROR
+ |
+>>> illegal use of Unrestricted_Access attribute
+>>> attempt to generate thin pointer to unaliased object
+
+ P (X(7 .. 12)'Unrestricted_Access); -- ERROR
+ |
+>>> illegal use of Unrestricted_Access attribute
+>>> attempt to generate thin pointer to unaliased object
+
+ P (X2'Unrestricted_Access); -- OK
+end;
+@end example
+
+but other cases cannot be detected by the compiler, and are
+considered to be erroneous. Consider the following example:
+
+@example
+with System; use System;
+with System; use System;
+procedure SliceUA is
+ type AF is access all String;
+
+ type A is access all String;
+ for A'Size use Standard'Address_Size;
+
+ procedure P (Arg : A) is
+ begin
+ if Arg'Length /= 6 then
+ raise Program_Error;
+ end if;
+ end P;
+
+ X : String := "hello world!";
+ Y : AF := X (7 .. 12)'Unrestricted_Access;
+
+begin
+ P (A (Y));
+end;
+@end example
+
+A normal unconstrained array value
+or a constrained array object marked as aliased has the bounds in memory
+just before the array, so a thin pointer can retrieve both the data and
+the bounds. But in this case, the non-aliased object @code{X} does not have the
+bounds before the string. If the size clause for type @code{A}
+were not present, then the pointer
+would be a fat pointer, where one component is a pointer to the bounds,
+and all would be well. But with the size clause present, the conversion from
+fat pointer to thin pointer in the call loses the bounds, and so this
+is erroneous, and the program likely raises a @code{Program_Error} exception.
+
+In general, it is advisable to completely
+avoid mixing the use of thin pointers and the use of
+@code{Unrestricted_Access} where the designated type is an
+unconstrained array. The use of thin pointers should be restricted to
+cases of porting legacy code that implicitly assumes the size of pointers,
+and such code should not in any case be using this attribute.
+
+Another erroneous situation arises if the attribute is
+applied to a constant. The resulting pointer can be used to access the
+constant, but the effect of trying to modify a constant in this manner
+is not well-defined. Consider this example:
+
+@example
+P : constant Integer := 4;
+type R is access all Integer;
+RV : R := P'Unrestricted_Access;
+..
+RV.all := 3;
+@end example
+
+Here we attempt to modify the constant P from 4 to 3, but the compiler may
+or may not notice this attempt, and subsequent references to P may yield
+either the value 3 or the value 4 or the assignment may blow up if the
+compiler decides to put P in read-only memory. One particular case where
+@code{Unrestricted_Access} can be used in this way is to modify the
+value of an @code{in} parameter:
+
+@example
+procedure K (S : in String) is
+ type R is access all Character;
+ RV : R := S (3)'Unrestricted_Access;
+begin
+ RV.all := 'a';
+end;
+@end example
+
+In general this is a risky approach. It may appear to “work” but such uses of
+@code{Unrestricted_Access} are potentially non-portable, even from one version
+of GNAT to another, so are best avoided if possible.
+
+@node Attribute Update,Attribute Valid_Value,Attribute Unrestricted_Access,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1ac}
+@section Attribute Update
+
+
+@geindex Update
+
+The @code{Update} attribute creates a copy of an array or record value
+with one or more modified components. The syntax is:
+
+@example
+PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST )
+PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} )
+PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION
+ @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} )
+
+MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION
+INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @}
+INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} )
+@end example
+
+where @code{PREFIX} is the name of an array or record object, the
+association list in parentheses does not contain an @code{others}
+choice and the box symbol @code{<>} may not appear in any
+expression. The effect is to yield a copy of the array or record value
+which is unchanged apart from the components mentioned in the
+association list, which are changed to the indicated value. The
+original value of the array or record value is not affected. For
+example:
+
+@example
+type Arr is Array (1 .. 5) of Integer;
+...
+Avar1 : Arr := (1,2,3,4,5);
+Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
+@end example
+
+yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1}
+begin unmodified. Similarly:
+
+@example
+type Rec is A, B, C : Integer;
+...
+Rvar1 : Rec := (A => 1, B => 2, C => 3);
+Rvar2 : Rec := Rvar1'Update (B => 20);
+@end example
+
+yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3),
+with @code{Rvar1} being unmodifed.
+Note that the value of the attribute reference is computed
+completely before it is used. This means that if you write:
+
+@example
+Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
+@end example
+
+then the value of @code{Avar1} is not modified if @code{Function_Call}
+raises an exception, unlike the effect of a series of direct assignments
+to elements of @code{Avar1}. In general this requires that
+two extra complete copies of the object are required, which should be
+kept in mind when considering efficiency.
+
+The @code{Update} attribute cannot be applied to prefixes of a limited
+type, and cannot reference discriminants in the case of a record type.
+The accessibility level of an Update attribute result object is defined
+as for an aggregate.
+
+In the record case, no component can be mentioned more than once. In
+the array case, two overlapping ranges can appear in the association list,
+in which case the modifications are processed left to right.
+
+Multi-dimensional arrays can be modified, as shown by this example:
+
+@example
+A : array (1 .. 10, 1 .. 10) of Integer;
+..
+A := A'Update ((1, 2) => 20, (3, 4) => 30);
+@end example
+
+which changes element (1,2) to 20 and (3,4) to 30.
+
+@node Attribute Valid_Value,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-valid-value}@anchor{1ad}
+@section Attribute Valid_Value
+
+
+@geindex Valid_Value
+
+The @code{'Valid_Value} attribute is defined for enumeration types other than
+those in package Standard. This attribute is a function that takes
+a String, and returns Boolean. @code{T'Valid_Value (S)} returns True
+if and only if @code{T'Value (S)} would not raise Constraint_Error.
+
+@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Value,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1ae}
+@section Attribute Valid_Scalars
+
+
+@geindex Valid_Scalars
+
+The @code{'Valid_Scalars} attribute is intended to make it easier to check the
+validity of scalar subcomponents of composite objects. The attribute is defined
+for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type
+except for tagged private or @code{Unchecked_Union} types. The value of the
+attribute is of type @code{Boolean}.
+
+@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of
+@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if
+@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent
+to attribute @code{'Valid} for scalar types.
+
+It is not specified in what order the subcomponents are checked, nor whether
+any more are checked after any one of them is determined to be invalid. If the
+prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated
+specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then
+only the subcomponents of @code{T} are checked; in other words, components of
+extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}.
+
+The compiler will issue a warning if it can be determined at compile time that
+the prefix of the attribute has no scalar subcomponents.
+
+Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of
+a large variant record. If the attribute is called in many places in the same
+program applied to objects of the same type, it can reduce program size to
+write a function with a single use of the attribute, and then call that
+function from multiple places.
+
+@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1af}
+@section Attribute VADS_Size
+
+
+@geindex Size
+@geindex VADS compatibility
+
+@geindex VADS_Size
+
+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 Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15d}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b0}
+@section Attribute Value_Size
+
+
+@geindex Size
+@geindex setting for not-first subtype
+
+@geindex Value_Size
+
+@code{type'Value_Size} is the number of bits required to represent
+a value of the given subtype. It is the same as @code{type'Size},
+but, unlike @code{Size}, may be set for non-first subtypes.
+
+@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b1}
+@section Attribute Wchar_T_Size
+
+
+@geindex Wchar_T_Size
+
+@code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed
+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}. The result is a static constant.
+
+@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes
+@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b2}
+@section Attribute Word_Size
+
+
+@geindex Word_Size
+
+@code{Standard'Word_Size} (@code{Standard} is the only allowed
+prefix) provides the value @code{System.Word_Size}. The result is
+a static constant.
+
+@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1b3}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b4}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9}
+@chapter Standard and Implementation Defined Restrictions
+
+
+All Ada Reference Manual-defined Restriction identifiers are implemented:
+
+
+@itemize *
+
+@item
+language-defined restrictions (see 13.12.1)
+
+@item
+tasking restrictions (see D.7)
+
+@item
+high integrity restrictions (see H.4)
+@end itemize
+
+GNAT implements additional restriction identifiers. All restrictions, whether
+language defined or GNAT-specific, are listed in the following.
+
+@menu
+* Partition-Wide Restrictions::
+* Program Unit Level Restrictions::
+
+@end menu
+
+@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b5}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b6}
+@section Partition-Wide Restrictions
+
+
+There are two separate lists of 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).
+
+@menu
+* Immediate_Reclamation::
+* Max_Asynchronous_Select_Nesting::
+* Max_Entry_Queue_Length::
+* Max_Protected_Entries::
+* Max_Select_Alternatives::
+* Max_Storage_At_Blocking::
+* Max_Task_Entries::
+* Max_Tasks::
+* No_Abort_Statements::
+* No_Access_Parameter_Allocators::
+* No_Access_Subprograms::
+* No_Allocators::
+* No_Anonymous_Allocators::
+* No_Asynchronous_Control::
+* No_Calendar::
+* No_Coextensions::
+* No_Default_Initialization::
+* No_Delay::
+* No_Dependence::
+* No_Direct_Boolean_Operators::
+* No_Dispatch::
+* No_Dispatching_Calls::
+* No_Dynamic_Attachment::
+* No_Dynamic_Priorities::
+* No_Entry_Calls_In_Elaboration_Code::
+* No_Enumeration_Maps::
+* No_Exception_Handlers::
+* No_Exception_Propagation::
+* No_Exception_Registration::
+* No_Exceptions::
+* No_Finalization::
+* No_Fixed_Point::
+* No_Floating_Point::
+* No_Implicit_Conditionals::
+* No_Implicit_Dynamic_Code::
+* No_Implicit_Heap_Allocations::
+* No_Implicit_Protected_Object_Allocations::
+* No_Implicit_Task_Allocations::
+* No_Initialize_Scalars::
+* No_IO::
+* No_Local_Allocators::
+* No_Local_Protected_Objects::
+* No_Local_Tagged_Types::
+* No_Local_Timing_Events::
+* No_Long_Long_Integers::
+* No_Multiple_Elaboration::
+* No_Nested_Finalization::
+* No_Protected_Type_Allocators::
+* No_Protected_Types::
+* No_Recursion::
+* No_Reentrancy::
+* No_Relative_Delay::
+* No_Requeue_Statements::
+* No_Secondary_Stack::
+* No_Select_Statements::
+* No_Specific_Termination_Handlers::
+* No_Specification_of_Aspect::
+* No_Standard_Allocators_After_Elaboration::
+* No_Standard_Storage_Pools::
+* No_Stream_Optimizations::
+* No_Streams::
+* No_Tagged_Type_Registration::
+* No_Task_Allocators::
+* No_Task_At_Interrupt_Priority::
+* No_Task_Attributes_Package::
+* No_Task_Hierarchy::
+* No_Task_Termination::
+* No_Tasking::
+* No_Terminate_Alternatives::
+* No_Unchecked_Access::
+* No_Unchecked_Conversion::
+* No_Unchecked_Deallocation::
+* No_Use_Of_Entity::
+* Pure_Barriers::
+* Simple_Barriers::
+* Static_Priorities::
+* Static_Storage_Size::
+
+@end menu
+
+@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b7}
+@subsection Immediate_Reclamation
+
+
+@geindex Immediate_Reclamation
+
+[RM H.4] This restriction ensures that, except for storage occupied by
+objects created by allocators and not deallocated via unchecked
+deallocation, any storage reserved at run time for an object is
+immediately reclaimed when the object no longer exists.
+
+@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1b8}
+@subsection Max_Asynchronous_Select_Nesting
+
+
+@geindex Max_Asynchronous_Select_Nesting
+
+[RM D.7] Specifies the maximum dynamic nesting level of asynchronous
+selects. Violations of this restriction with a value of zero are
+detected at compile time. Violations of this restriction with values
+other than zero cause Storage_Error to be raised.
+
+@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1b9}
+@subsection Max_Entry_Queue_Length
+
+
+@geindex Max_Entry_Queue_Length
+
+[RM D.7] 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.
+Note that this restriction is checked at run time. Violation of this
+restriction results in the raising of Program_Error exception at the point of
+the call.
+
+@geindex Max_Entry_Queue_Depth
+
+The restriction @code{Max_Entry_Queue_Depth} is recognized as a
+synonym for @code{Max_Entry_Queue_Length}. This is retained for historical
+compatibility purposes (and a warning will be generated for its use if
+warnings on obsolescent features are activated).
+
+@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1ba}
+@subsection Max_Protected_Entries
+
+
+@geindex Max_Protected_Entries
+
+[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.
+
+@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bb}
+@subsection Max_Select_Alternatives
+
+
+@geindex Max_Select_Alternatives
+
+[RM D.7] Specifies the maximum number of alternatives in a selective accept.
+
+@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1bc}
+@subsection Max_Storage_At_Blocking
+
+
+@geindex Max_Storage_At_Blocking
+
+[RM D.7] Specifies the maximum portion (in storage elements) of a task’s
+Storage_Size that can be retained by a blocked task. A violation of this
+restriction causes Storage_Error to be raised.
+
+@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1bd}
+@subsection Max_Task_Entries
+
+
+@geindex Max_Task_Entries
+
+[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.
+
+@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1be}
+@subsection Max_Tasks
+
+
+@geindex Max_Tasks
+
+[RM D.7] Specifies the maximum number of task that may be created, not
+counting the creation of the environment task. Violations of this
+restriction with a value of zero are detected at compile
+time. Violations of this restriction with values other than zero cause
+Storage_Error to be raised.
+
+@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1bf}
+@subsection No_Abort_Statements
+
+
+@geindex No_Abort_Statements
+
+[RM D.7] There are no abort_statements, and there are
+no calls to Task_Identification.Abort_Task.
+
+@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c0}
+@subsection No_Access_Parameter_Allocators
+
+
+@geindex No_Access_Parameter_Allocators
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of an allocator as the actual parameter to an access
+parameter.
+
+@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c1}
+@subsection No_Access_Subprograms
+
+
+@geindex No_Access_Subprograms
+
+[RM H.4] This restriction ensures at compile time that there are no
+declarations of access-to-subprogram types.
+
+@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c2}
+@subsection No_Allocators
+
+
+@geindex No_Allocators
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of an allocator.
+
+@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c3}
+@subsection No_Anonymous_Allocators
+
+
+@geindex No_Anonymous_Allocators
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of an allocator of anonymous access type.
+
+@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c4}
+@subsection No_Asynchronous_Control
+
+
+@geindex No_Asynchronous_Control
+
+[RM J.13] This restriction ensures at compile time that there are no semantic
+dependences on the predefined package Asynchronous_Task_Control.
+
+@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c5}
+@subsection No_Calendar
+
+
+@geindex No_Calendar
+
+[GNAT] This restriction ensures at compile time that there are no semantic
+dependences on package Calendar.
+
+@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c6}
+@subsection No_Coextensions
+
+
+@geindex No_Coextensions
+
+[RM H.4] This restriction ensures at compile time that there are no
+coextensions. See 3.10.2.
+
+@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c7}
+@subsection No_Default_Initialization
+
+
+@geindex No_Default_Initialization
+
+[GNAT] 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).
+
+@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1c8}
+@subsection No_Delay
+
+
+@geindex No_Delay
+
+[RM H.4] This restriction ensures at compile time that there are no
+delay statements and no semantic dependences on package Calendar.
+
+@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1c9}
+@subsection No_Dependence
+
+
+@geindex No_Dependence
+
+[RM 13.12.1] This restriction ensures at compile time that there are no
+dependences on a library unit. For GNAT, this includes implicit implementation
+dependences on units of the runtime library that are created by the compiler
+to support specific constructs of the language.
+
+@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1ca}
+@subsection No_Direct_Boolean_Operators
+
+
+@geindex No_Direct_Boolean_Operators
+
+[GNAT] This restriction ensures that no logical operators (and/or/xor)
+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.
+
+@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cb}
+@subsection No_Dispatch
+
+
+@geindex No_Dispatch
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of @code{T'Class}, for any (tagged) subtype @code{T}.
+
+@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1cc}
+@subsection No_Dispatching_Calls
+
+
+@geindex No_Dispatching_Calls
+
+[GNAT] 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.
+
+@example
+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 example
+
+@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1cd}
+@subsection No_Dynamic_Attachment
+
+
+@geindex No_Dynamic_Attachment
+
+[RM D.7] This restriction ensures that 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).
+
+@geindex No_Dynamic_Interrupts
+
+The restriction @code{No_Dynamic_Interrupts} is recognized as a
+synonym for @code{No_Dynamic_Attachment}. This is retained for historical
+compatibility purposes (and a warning will be generated for its use if
+warnings on obsolescent features are activated).
+
+@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1ce}
+@subsection No_Dynamic_Priorities
+
+
+@geindex No_Dynamic_Priorities
+
+[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
+
+@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1cf}
+@subsection No_Entry_Calls_In_Elaboration_Code
+
+
+@geindex No_Entry_Calls_In_Elaboration_Code
+
+[GNAT] 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.
+
+@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d0}
+@subsection No_Enumeration_Maps
+
+
+@geindex No_Enumeration_Maps
+
+[GNAT] This restriction ensures at compile time that no operations requiring
+enumeration maps are used (that is Image and Value attributes applied
+to enumeration types).
+
+@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d1}
+@subsection No_Exception_Handlers
+
+
+@geindex No_Exception_Handlers
+
+[GNAT] 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:
+
+@example
+procedure Last_Chance_Handler
+ (Source_Location : System.Address; Line : Integer);
+pragma Export (C, Last_Chance_Handler,
+ "__gnat_last_chance_handler");
+@end example
+
+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.
+
+@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d2}
+@subsection No_Exception_Propagation
+
+
+@geindex No_Exception_Propagation
+
+[GNAT] 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.
+
+@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d3}
+@subsection No_Exception_Registration
+
+
+@geindex No_Exception_Registration
+
+[GNAT] 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 restriction is active, the generated
+code is simplified by omitting the otherwise-required global registration
+of exceptions when they are declared.
+
+@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d4}
+@subsection No_Exceptions
+
+
+@geindex No_Exceptions
+
+[RM H.4] This restriction ensures at compile time that there are no
+raise statements and no exception handlers and also suppresses the
+generation of language-defined run-time checks.
+
+@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d5}
+@subsection No_Finalization
+
+
+@geindex No_Finalization
+
+[GNAT] This restriction disables the language features described in
+chapter 7.6 of the Ada 2005 RM as well as all form of code generation
+performed by the compiler to support these features. The following types
+are no longer considered controlled when this restriction is in effect:
+
+
+@itemize *
+
+@item
+@code{Ada.Finalization.Controlled}
+
+@item
+@code{Ada.Finalization.Limited_Controlled}
+
+@item
+Derivations from @code{Controlled} or @code{Limited_Controlled}
+
+@item
+Class-wide types
+
+@item
+Protected types
+
+@item
+Task types
+
+@item
+Array and record types with controlled components
+@end itemize
+
+The compiler no longer generates code to initialize, finalize or adjust an
+object or a nested component, either declared on the stack or on the heap. The
+deallocation of a controlled object no longer finalizes its contents.
+
+@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d6}
+@subsection No_Fixed_Point
+
+
+@geindex No_Fixed_Point
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of fixed point types and operations.
+
+@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d7}
+@subsection No_Floating_Point
+
+
+@geindex No_Floating_Point
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of floating point types and operations.
+
+@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1d8}
+@subsection No_Implicit_Conditionals
+
+
+@geindex No_Implicit_Conditionals
+
+[GNAT] 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.
+
+@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1d9}
+@subsection No_Implicit_Dynamic_Code
+
+
+@geindex No_Implicit_Dynamic_Code
+
+@geindex trampoline
+
+[GNAT] 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.
+
+@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1da}
+@subsection No_Implicit_Heap_Allocations
+
+
+@geindex No_Implicit_Heap_Allocations
+
+[RM D.7] No constructs are allowed to cause implicit heap allocation.
+
+@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1db}
+@subsection No_Implicit_Protected_Object_Allocations
+
+
+@geindex No_Implicit_Protected_Object_Allocations
+
+[GNAT] No constructs are allowed to cause implicit heap allocation of a
+protected object.
+
+@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1dc}
+@subsection No_Implicit_Task_Allocations
+
+
+@geindex No_Implicit_Task_Allocations
+
+[GNAT] No constructs are allowed to cause implicit heap allocation of a task.
+
+@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1dd}
+@subsection No_Initialize_Scalars
+
+
+@geindex No_Initialize_Scalars
+
+[GNAT] 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.
+
+@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1de}
+@subsection No_IO
+
+
+@geindex No_IO
+
+[RM H.4] This restriction ensures at compile time that there are no
+dependences on any of the library units Sequential_IO, Direct_IO,
+Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO.
+
+@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1df}
+@subsection No_Local_Allocators
+
+
+@geindex No_Local_Allocators
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of an allocator in subprograms, generic subprograms, tasks,
+and entry bodies.
+
+@node No_Local_Protected_Objects,No_Local_Tagged_Types,No_Local_Allocators,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e0}
+@subsection No_Local_Protected_Objects
+
+
+@geindex No_Local_Protected_Objects
+
+[RM D.7] This restriction ensures at compile time that protected objects are
+only declared at the library level.
+
+@node No_Local_Tagged_Types,No_Local_Timing_Events,No_Local_Protected_Objects,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-tagged-types}@anchor{1e1}
+@subsection No_Local_Tagged_Types
+
+
+@geindex No_Local_Tagged_Types
+
+[GNAT] This restriction ensures at compile time that tagged types are only
+declared at the library level.
+
+@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Tagged_Types,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e2}
+@subsection No_Local_Timing_Events
+
+
+@geindex No_Local_Timing_Events
+
+[RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are
+declared at the library level.
+
+@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e3}
+@subsection No_Long_Long_Integers
+
+
+@geindex No_Long_Long_Integers
+
+[GNAT] This partition-wide restriction forbids any explicit reference to
+type Standard.Long_Long_Integer, and also forbids declaring range types whose
+implicit base type is Long_Long_Integer, and modular types whose size exceeds
+Long_Integer’Size.
+
+@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e4}
+@subsection No_Multiple_Elaboration
+
+
+@geindex No_Multiple_Elaboration
+
+[GNAT] When this restriction is active and the static elaboration model is
+used, and -fpreserve-control-flow is not used, the compiler is allowed to
+suppress the elaboration counter normally associated with the unit, even if
+the unit has elaboration code. This counter is typically used to check for
+access before elaboration and to control multiple elaboration attempts. If the
+restriction is used, then the situations in which multiple elaboration is
+possible, including non-Ada main programs and Stand Alone libraries, are not
+permitted and will be diagnosed by the binder.
+
+@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e5}
+@subsection No_Nested_Finalization
+
+
+@geindex No_Nested_Finalization
+
+[RM D.7] All objects requiring finalization are declared at the library level.
+
+@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e6}
+@subsection No_Protected_Type_Allocators
+
+
+@geindex No_Protected_Type_Allocators
+
+[RM D.7] This restriction ensures at compile time that there are no allocator
+expressions that attempt to allocate protected objects.
+
+@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e7}
+@subsection No_Protected_Types
+
+
+@geindex No_Protected_Types
+
+[RM H.4] This restriction ensures at compile time that there are no
+declarations of protected types or protected objects.
+
+@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e8}
+@subsection No_Recursion
+
+
+@geindex No_Recursion
+
+[RM H.4] A program execution is erroneous if a subprogram is invoked as
+part of its execution.
+
+@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1e9}
+@subsection No_Reentrancy
+
+
+@geindex No_Reentrancy
+
+[RM H.4] A program execution is erroneous if a subprogram is executed by
+two tasks at the same time.
+
+@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1ea}
+@subsection No_Relative_Delay
+
+
+@geindex No_Relative_Delay
+
+[RM D.7] This restriction ensures at compile time that there are no delay
+relative statements and prevents expressions such as @code{delay 1.23;} from
+appearing in source code.
+
+@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1eb}
+@subsection No_Requeue_Statements
+
+
+@geindex No_Requeue_Statements
+
+[RM D.7] This restriction ensures at compile time that no requeue statements
+are permitted and prevents keyword @code{requeue} from being used in source
+code.
+
+@geindex No_Requeue
+
+The restriction @code{No_Requeue} is recognized as a
+synonym for @code{No_Requeue_Statements}. This is retained for historical
+compatibility purposes (and a warning will be generated for its use if
+warnings on oNobsolescent features are activated).
+
+@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ec}
+@subsection No_Secondary_Stack
+
+
+@geindex No_Secondary_Stack
+
+[GNAT] 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. Suppresses the allocation of
+secondary stacks for tasks (excluding the environment task) at run time.
+
+@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ed}
+@subsection No_Select_Statements
+
+
+@geindex No_Select_Statements
+
+[RM D.7] This restriction ensures at compile time no select statements of any
+kind are permitted, that is the keyword @code{select} may not appear.
+
+@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ee}
+@subsection No_Specific_Termination_Handlers
+
+
+@geindex 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.
+
+@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1ef}
+@subsection No_Specification_of_Aspect
+
+
+@geindex No_Specification_of_Aspect
+
+[RM 13.12.1] This restriction checks at compile time that no aspect
+specification, attribute definition clause, or pragma is given for a
+given aspect.
+
+@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f0}
+@subsection No_Standard_Allocators_After_Elaboration
+
+
+@geindex No_Standard_Allocators_After_Elaboration
+
+[RM D.7] Specifies that an allocator using a standard storage pool
+should never be evaluated at run time after the elaboration of the
+library items of the partition has completed. Otherwise, Storage_Error
+is raised.
+
+@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f1}
+@subsection No_Standard_Storage_Pools
+
+
+@geindex No_Standard_Storage_Pools
+
+[GNAT] 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.
+
+@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f2}
+@subsection No_Stream_Optimizations
+
+
+@geindex No_Stream_Optimizations
+
+[GNAT] This restriction affects the performance of stream operations on types
+@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the
+compiler uses block reads and writes when manipulating @code{String} objects
+due to their superior performance. When this restriction is in effect, the
+compiler performs all IO operations on a per-character basis.
+
+@node No_Streams,No_Tagged_Type_Registration,No_Stream_Optimizations,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f3}
+@subsection No_Streams
+
+
+@geindex No_Streams
+
+[GNAT] This restriction ensures at compile/bind time that there are no
+stream objects created and no use of stream attributes.
+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 and no
+stream attributes are used.
+
+Note that the use of restriction allows optimization of tagged types,
+since they do not need to worry about dispatching stream operations.
+To take maximum advantage of this space-saving optimization, any
+unit declaring a tagged type should be compiled with the restriction,
+though this is not required.
+
+@node No_Tagged_Type_Registration,No_Task_Allocators,No_Streams,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tagged-type-registration}@anchor{1f4}
+@subsection No_Tagged_Type_Registration
+
+
+@geindex No_Tagged_Type_Registration
+
+[GNAT] If this restriction is active, then class-wide streaming
+attributes are not supported. In addition, the subprograms in
+Ada.Tags are not supported.
+If this restriction is active, the generated code is simplified by
+omitting the otherwise-required global registration of tagged types when they
+are declared. This restriction may be necessary in order to also apply
+the No_Elaboration_Code restriction.
+
+@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Tagged_Type_Registration,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f5}
+@subsection No_Task_Allocators
+
+
+@geindex No_Task_Allocators
+
+[RM D.7] There are no allocators for task types
+or types containing task subcomponents.
+
+@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f6}
+@subsection No_Task_At_Interrupt_Priority
+
+
+@geindex No_Task_At_Interrupt_Priority
+
+[GNAT] This restriction ensures at compile time that there is no
+Interrupt_Priority aspect or pragma for a task or a task type. As
+a consequence, the tasks are always created with a priority below
+that an interrupt priority.
+
+@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f7}
+@subsection No_Task_Attributes_Package
+
+
+@geindex No_Task_Attributes_Package
+
+[GNAT] This restriction ensures at compile time that there are no implicit or
+explicit dependencies on the package @code{Ada.Task_Attributes}.
+
+@geindex No_Task_Attributes
+
+The restriction @code{No_Task_Attributes} is recognized as a synonym
+for @code{No_Task_Attributes_Package}. This is retained for historical
+compatibility purposes (and a warning will be generated for its use if
+warnings on obsolescent features are activated).
+
+@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f8}
+@subsection No_Task_Hierarchy
+
+
+@geindex No_Task_Hierarchy
+
+[RM D.7] All (non-environment) tasks depend
+directly on the environment task of the partition.
+
+@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f9}
+@subsection No_Task_Termination
+
+
+@geindex No_Task_Termination
+
+[RM D.7] Tasks that terminate are erroneous.
+
+@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fa}
+@subsection No_Tasking
+
+
+@geindex No_Tasking
+
+[GNAT] 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.
+
+@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fb}
+@subsection No_Terminate_Alternatives
+
+
+@geindex No_Terminate_Alternatives
+
+[RM D.7] There are no selective accepts with terminate alternatives.
+
+@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fc}
+@subsection No_Unchecked_Access
+
+
+@geindex No_Unchecked_Access
+
+[RM H.4] This restriction ensures at compile time that there are no
+occurrences of the Unchecked_Access attribute.
+
+@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fd}
+@subsection No_Unchecked_Conversion
+
+
+@geindex No_Unchecked_Conversion
+
+[RM J.13] This restriction ensures at compile time that there are no semantic
+dependences on the predefined generic function Unchecked_Conversion.
+
+@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1fe}
+@subsection No_Unchecked_Deallocation
+
+
+@geindex No_Unchecked_Deallocation
+
+[RM J.13] This restriction ensures at compile time that there are no semantic
+dependences on the predefined generic procedure Unchecked_Deallocation.
+
+@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1ff}
+@subsection No_Use_Of_Entity
+
+
+@geindex No_Use_Of_Entity
+
+[GNAT] This restriction ensures at compile time that there are no references
+to the entity given in the form
+
+@example
+No_Use_Of_Entity => Name
+@end example
+
+where @code{Name} is the fully qualified entity, for example
+
+@example
+No_Use_Of_Entity => Ada.Text_IO.Put_Line
+@end example
+
+@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{200}
+@subsection Pure_Barriers
+
+
+@geindex Pure_Barriers
+
+[GNAT] This restriction ensures at compile time that protected entry
+barriers are restricted to:
+
+
+@itemize *
+
+@item
+components of the protected object (excluding selection from dereferences),
+
+@item
+constant declarations,
+
+@item
+named numbers,
+
+@item
+enumeration literals,
+
+@item
+integer literals,
+
+@item
+real literals,
+
+@item
+character literals,
+
+@item
+implicitly defined comparison operators,
+
+@item
+uses of the Standard.”not” operator,
+
+@item
+short-circuit operator,
+
+@item
+the Count attribute
+@end itemize
+
+This restriction is a relaxation of the Simple_Barriers restriction,
+but still ensures absence of side effects, exceptions, and recursion
+during the evaluation of the barriers.
+
+@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{201}
+@subsection Simple_Barriers
+
+
+@geindex Simple_Barriers
+
+[RM D.7] 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.
+
+@geindex Boolean_Entry_Barriers
+
+The restriction @code{Boolean_Entry_Barriers} is recognized as a
+synonym for @code{Simple_Barriers}. This is retained for historical
+compatibility purposes (and a warning will be generated for its use if
+warnings on obsolescent features are activated).
+
+@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{202}
+@subsection Static_Priorities
+
+
+@geindex Static_Priorities
+
+[GNAT] This restriction ensures at compile time that all priority expressions
+are static, and that there are no dependences on the package
+@code{Ada.Dynamic_Priorities}.
+
+@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{203}
+@subsection Static_Storage_Size
+
+
+@geindex Static_Storage_Size
+
+[GNAT] This restriction ensures at compile time that any expression appearing
+in a Storage_Size pragma or attribute definition clause is static.
+
+@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{204}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{205}
+@section Program Unit Level Restrictions
+
+
+The second set of 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.
+
+@menu
+* No_Elaboration_Code::
+* No_Dynamic_Accessibility_Checks::
+* No_Dynamic_Sized_Objects::
+* No_Entry_Queue::
+* No_Implementation_Aspect_Specifications::
+* No_Implementation_Attributes::
+* No_Implementation_Identifiers::
+* No_Implementation_Pragmas::
+* No_Implementation_Restrictions::
+* No_Implementation_Units::
+* No_Implicit_Aliasing::
+* No_Implicit_Loops::
+* No_Obsolescent_Features::
+* No_Wide_Characters::
+* Static_Dispatch_Tables::
+* SPARK_05::
+
+@end menu
+
+@node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{206}
+@subsection No_Elaboration_Code
+
+
+@geindex No_Elaboration_Code
+
+[GNAT] 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:
+
+@example
+Val : constant Integer := X;
+@end example
+
+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.
+
+When this restriction is active, we are not requesting control-flow
+preservation with -fpreserve-control-flow, and the static elaboration model is
+used, the compiler is allowed to suppress the elaboration counter normally
+associated with the unit. This counter is typically used to check for access
+before elaboration and to control multiple elaboration attempts.
+
+@node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{207}
+@subsection No_Dynamic_Accessibility_Checks
+
+
+@geindex No_Dynamic_Accessibility_Checks
+
+[GNAT] No dynamic accessibility checks are generated when this restriction is
+in effect. Instead, dangling references are prevented via more conservative
+compile-time checking. More specifically, existing compile-time checks are
+enforced but with more conservative assumptions about the accessibility levels
+of the relevant entities. These conservative assumptions eliminate the need for
+dynamic accessibility checks.
+
+These new rules for computing (at compile-time) the accessibility level of an
+anonymous access type T are as follows:
+
+
+@itemize *
+
+@item
+If T is a function result type then, from the caller’s perspective, its level
+is that of the innermost master enclosing the function call. From the callee’s
+perspective, the level of parameters and local variables of the callee is
+statically deeper than the level of T.
+
+For any other accessibility level L such that the level of parameters and local
+variables of the callee is statically deeper than L, the level of T (from the
+callee’s perspective) is also statically deeper than L.
+
+@item
+If T is the type of a formal parameter then, from the caller’s perspective,
+its level is at least as deep as that of the type of the corresponding actual
+parameter (whatever that actual parameter might be). From the callee’s
+perspective, the level of parameters and local variables of the callee is
+statically deeper than the level of T.
+
+@item
+If T is the type of a discriminant then its level is that of the discriminated
+type.
+
+@item
+If T is the type of a stand-alone object then its level is the level of the
+object.
+
+@item
+In all other cases, the level of T is as defined by the existing rules of Ada.
+@end itemize
+
+@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{208}
+@subsection No_Dynamic_Sized_Objects
+
+
+@geindex No_Dynamic_Sized_Objects
+
+[GNAT] This restriction disallows certain constructs that might lead to the
+creation of dynamic-sized composite objects (or array or discriminated type).
+An array subtype indication is illegal if the bounds are not static
+or references to discriminants of an enclosing type.
+A discriminated subtype indication is illegal if the type has
+discriminant-dependent array components or a variant part, and the
+discriminants are not static. In addition, array and record aggregates are
+illegal in corresponding cases. Note that this restriction does not forbid
+access discriminants. It is often a good idea to combine this restriction
+with No_Secondary_Stack.
+
+@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{209}
+@subsection No_Entry_Queue
+
+
+@geindex No_Entry_Queue
+
+[GNAT] 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.
+
+@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{20a}
+@subsection No_Implementation_Aspect_Specifications
+
+
+@geindex No_Implementation_Aspect_Specifications
+
+[RM 13.12.1] This restriction checks at compile time that no
+GNAT-defined aspects are present. With this restriction, the only
+aspects that can be used are those defined in the Ada Reference Manual.
+
+@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{20b}
+@subsection No_Implementation_Attributes
+
+
+@geindex No_Implementation_Attributes
+
+[RM 13.12.1] 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.
+
+@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20c}
+@subsection No_Implementation_Identifiers
+
+
+@geindex No_Implementation_Identifiers
+
+[RM 13.12.1] This restriction checks at compile time that no
+implementation-defined identifiers (marked with pragma Implementation_Defined)
+occur within language-defined packages.
+
+@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20d}
+@subsection No_Implementation_Pragmas
+
+
+@geindex No_Implementation_Pragmas
+
+[RM 13.12.1] 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.
+
+@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20e}
+@subsection No_Implementation_Restrictions
+
+
+@geindex No_Implementation_Restrictions
+
+[GNAT] 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.
+
+@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20f}
+@subsection No_Implementation_Units
+
+
+@geindex No_Implementation_Units
+
+[RM 13.12.1] This restriction checks at compile time that there is no
+mention in the context clause of any implementation-defined descendants
+of packages Ada, Interfaces, or System.
+
+@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{210}
+@subsection No_Implicit_Aliasing
+
+
+@geindex No_Implicit_Aliasing
+
+[GNAT] This restriction, which is not required to be partition-wide consistent,
+requires an explicit aliased keyword for an object to which ‘Access,
+‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of
+the ‘Unrestricted_Access attribute for objects. Note: the reason that
+Unrestricted_Access is forbidden is that it would require the prefix
+to be aliased, and in such cases, it can always be replaced by
+the standard attribute Unchecked_Access which is preferable.
+
+@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{211}
+@subsection No_Implicit_Loops
+
+
+@geindex No_Implicit_Loops
+
+[GNAT] This restriction ensures that the generated code of the unit marked
+with this restriction 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. Note that if this restriction
+is set in the spec of a package, it will not apply to its body.
+
+@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{212}
+@subsection No_Obsolescent_Features
+
+
+@geindex No_Obsolescent_Features
+
+[RM 13.12.1] This restriction checks at compile time that no obsolescent
+features are used, as defined in Annex J of the Ada Reference Manual.
+
+@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{213}
+@subsection No_Wide_Characters
+
+
+@geindex No_Wide_Characters
+
+[GNAT] 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}).
+
+@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{214}
+@subsection Static_Dispatch_Tables
+
+
+@geindex Static_Dispatch_Tables
+
+[GNAT] This restriction checks at compile time that all the artifacts
+associated with dispatch tables can be placed in read-only memory.
+
+@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{215}
+@subsection SPARK_05
+
+
+@geindex SPARK_05
+
+[GNAT] This restriction no longer has any effect and is superseded by
+SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that
+a codebase respects SPARK 2014 restrictions, mark the code with pragma or
+aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as
+follows:
+
+@example
+gnatprove -P project.gpr --mode=stone
+@end example
+
+or equivalently:
+
+@example
+gnatprove -P project.gpr --mode=check_all
+@end example
+
+@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top
+@anchor{gnat_rm/implementation_advice doc}@anchor{216}@anchor{gnat_rm/implementation_advice id1}@anchor{217}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}
+@chapter Implementation Advice
+
+
+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.
+They are not requirements, because they describe behavior that cannot
+be provided on all systems, or may be undesirable on some systems.
+
+As far as practical, GNAT follows the implementation advice in
+the Ada Reference Manual. Each such RM section corresponds to a section
+in this chapter whose title specifies the
+RM section number and paragraph number and the subject of
+the advice. The contents of each section consists of the RM text within
+quotation marks,
+followed by the GNAT interpretation of the 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.
+
+@geindex Error detection
+
+@menu
+* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection.
+* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units.
+* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors.
+* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas.
+* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas.
+* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets.
+* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types.
+* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types.
+* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values.
+* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types.
+* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays.
+* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small.
+* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation.
+* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information.
+* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks.
+* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses.
+* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types.
+* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses.
+* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses.
+* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses.
+* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses.
+* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses.
+* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses.
+* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses.
+* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes.
+* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering.
+* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private.
+* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations.
+* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion.
+* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage.
+* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation.
+* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes.
+* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types.
+* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling.
+* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling.
+* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation.
+* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate.
+* RM A.18; Containers: RM A 18 Containers.
+* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export.
+* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces.
+* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C.
+* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL.
+* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran.
+* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations.
+* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations.
+* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support.
+* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers.
+* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts.
+* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements.
+* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names.
+* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes.
+* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies.
+* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies.
+* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort.
+* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions.
+* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time.
+* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem.
+* RM F(7); COBOL Support: RM F 7 COBOL Support.
+* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support.
+* RM G; Numerics: RM G Numerics.
+* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types.
+* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions.
+* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements.
+* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy.
+* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy.
+
+@end menu
+
+@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{218}
+@section RM 1.1.3(20): Error Detection
+
+
+@quotation
+
+“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 quotation
+
+Not relevant. All specialized needs annex features are either supported,
+or diagnosed at compile time.
+
+@geindex Child Units
+
+@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{219}
+@section RM 1.1.3(31): Child Units
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Bounded errors
+
+@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{21a}
+@section RM 1.1.5(12): Bounded Errors
+
+
+@quotation
+
+“If an implementation detects a bounded error or erroneous
+execution, it should raise @code{Program_Error}.”
+@end quotation
+
+Followed in all cases in which the implementation detects a bounded
+error or erroneous execution. Not all such situations are detected at
+runtime.
+
+@geindex Pragmas
+
+@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice
+@anchor{gnat_rm/implementation_advice id2}@anchor{21b}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21c}
+@section RM 2.8(16): Pragmas
+
+
+@quotation
+
+“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 quotation
+
+The following implementation defined pragmas are exceptions to this
+rule:
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+Pragma
+
+@tab
+
+Explanation
+
+@item
+
+`Abort_Defer'
+
+@tab
+
+Affects semantics
+
+@item
+
+`Ada_83'
+
+@tab
+
+Affects legality
+
+@item
+
+`Assert'
+
+@tab
+
+Affects semantics
+
+@item
+
+`CPP_Class'
+
+@tab
+
+Affects semantics
+
+@item
+
+`CPP_Constructor'
+
+@tab
+
+Affects semantics
+
+@item
+
+`Debug'
+
+@tab
+
+Affects semantics
+
+@item
+
+`Interface_Name'
+
+@tab
+
+Affects semantics
+
+@item
+
+`Machine_Attribute'
+
+@tab
+
+Affects semantics
+
+@item
+
+`Unimplemented_Unit'
+
+@tab
+
+Affects legality
+
+@item
+
+`Unchecked_Union'
+
+@tab
+
+Affects semantics
+
+@end multitable
+
+
+In each of the above cases, it is essential to the purpose of the pragma
+that this advice not be followed. For details see
+@ref{7,,Implementation Defined Pragmas}.
+
+@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21d}
+@section RM 2.8(17-19): Pragmas
+
+
+@quotation
+
+“Normally, an implementation should not define pragmas that can
+make an illegal program legal, except as follows:
+
+
+@itemize *
+
+@item
+A pragma used to complete a declaration, such as a pragma @code{Import};
+
+@item
+A pragma used to configure the environment by adding, removing, or
+replacing @code{library_items}.”
+@end itemize
+@end quotation
+
+See @ref{21c,,RM 2.8(16); Pragmas}.
+
+@geindex Character Sets
+
+@geindex Alternative Character Sets
+
+@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21e}
+@section RM 3.5.2(5): Alternative Character Sets
+
+
+@quotation
+
+“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 quotation
+
+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.
+
+@geindex Integer types
+
+@node RM 3 5 4 28 Integer Types,RM 3 5 4 29 Integer Types,RM 3 5 2 5 Alternative Character Sets,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21f}
+@section RM 3.5.4(28): Integer Types
+
+
+@quotation
+
+“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 quotation
+
+@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.
+
+@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{220}
+@section RM 3.5.4(29): Integer Types
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Enumeration values
+
+@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{221}
+@section RM 3.5.5(8): Enumeration Values
+
+
+@quotation
+
+“For the evaluation of a call on @code{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 quotation
+
+Followed.
+
+@geindex Float types
+
+@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{222}
+@section RM 3.5.7(17): Float Types
+
+
+@quotation
+
+“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 quotation
+
+@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 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.
+
+@geindex Multidimensional arrays
+
+@geindex Arrays
+@geindex multidimensional
+
+@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{223}
+@section RM 3.6.2(11): Multidimensional Arrays
+
+
+@quotation
+
+“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}, …) applies to a multidimensional array type, then
+column-major order should be used instead (see B.5, `Interfacing with Fortran').”
+@end quotation
+
+Followed.
+
+@geindex Duration'Small
+
+@node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{224}
+@section RM 9.6(30-31): Duration’Small
+
+
+@quotation
+
+“Whenever possible in an implementation, the value of @code{Duration'Small}
+should be no greater than 100 microseconds.”
+@end quotation
+
+Followed. (@code{Duration'Small} = 10**(-9)).
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{225}
+@section RM 10.2.1(12): Consistent Representation
+
+
+@quotation
+
+“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 quotation
+
+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.
+
+@geindex Exception information
+
+@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{226}
+@section RM 11.4.1(19): Exception Information
+
+
+@quotation
+
+“@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 quotation
+
+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_name:line’, where
+file_name 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}.
+
+@geindex Suppression of checks
+
+@geindex Checks
+@geindex suppression of
+
+@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{227}
+@section RM 11.5(28): Suppression of Checks
+
+
+@quotation
+
+“The implementation should minimize the code executed for checks that
+have been suppressed.”
+@end quotation
+
+Followed.
+
+@geindex Representation clauses
+
+@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{228}
+@section RM 13.1 (21-24): Representation Clauses
+
+
+@quotation
+
+“The recommended level of support for all representation items is
+qualified as follows:
+
+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
+
+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:
+
+@example
+ X : Integer;
+ Y : Float;
+ for Y'Address use X'Address;>>
+
+
+"An implementation need not support a specification for the `@w{`}Size`@w{`}
+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 example
+
+Followed. Size Clauses are not permitted on nonstatic components, as
+described above.
+
+@quotation
+
+“An aliased component, or a component whose type is by-reference, should
+always be allocated at an addressable location.”
+@end quotation
+
+Followed.
+
+@geindex Packed types
+
+@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{229}
+@section RM 13.2(6-8): Packed Types
+
+
+@quotation
+
+“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.
+
+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 `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 quotation
+
+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.
+
+@geindex Address clauses
+
+@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{22a}
+@section RM 13.3(14-19): Address Clauses
+
+
+@quotation
+
+“For an array @code{X}, @code{X'Address} should point at the first
+component of the array, and not at the array bounds.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“The recommended level of support for the @code{Address} attribute is:
+
+@code{X'Address} should produce a useful result if @code{X} is an
+object that is aliased or of a by-reference type, or is an entity whose
+@code{Address} has been specified.”
+@end quotation
+
+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.
+
+@quotation
+
+“An implementation should support @code{Address} clauses for imported
+subprograms.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“Objects (including subcomponents) that are aliased or of a by-reference
+type should be allocated on storage element boundaries.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Alignment clauses
+
+@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{22b}
+@section RM 13.3(29-35): Alignment Clauses
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@quotation
+
+“An implementation need not support specified Alignments for
+combinations of Sizes and Alignments that cannot be easily
+loaded and stored by available machine instructions.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An implementation need not support specified Alignments that are
+greater than the maximum @code{Alignment} the implementation ever returns by
+default.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“The recommended level of support for the @code{Alignment} attribute for
+objects is:
+
+Same as above, for subtypes, but in addition:”
+@end quotation
+
+Followed.
+
+@quotation
+
+“For stand-alone library-level objects of statically constrained
+subtypes, the implementation should support all alignments
+supported by the target linker. For example, page alignment is likely to
+be supported for such objects, but not for subtypes.”
+@end quotation
+
+Followed.
+
+@geindex Size clauses
+
+@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22c}
+@section RM 13.3(42-43): Size Clauses
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@node RM 13 3 50-56 Size Clauses,RM 13 3 71-73 Component Size Clauses,RM 13 3 42-43 Size Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22d}
+@section RM 13.3(50-56): Size Clauses
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@quotation
+
+“@cite{Size} clause on a composite subtype should not affect the
+internal layout of components.”
+@end quotation
+
+Followed. But note that this can be overridden by use of the implementation
+pragma Implicit_Packing in the case of packed arrays.
+
+@quotation
+
+“The recommended level of support for the @code{Size} attribute of subtypes is:
+
+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 quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Component_Size clauses
+
+@node RM 13 3 71-73 Component Size Clauses,RM 13 4 9-10 Enumeration Representation Clauses,RM 13 3 50-56 Size Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22e}
+@section RM 13.3(71-73): Component Size Clauses
+
+
+@quotation
+
+“The recommended level of support for the @code{Component_Size}
+attribute is:
+
+An implementation need not support specified @code{Component_Sizes} that are
+less than the @code{Size} of the component subtype.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An implementation should support specified Component_Sizes that
+are factors and multiples of the word size. For such
+Component_Sizes, the array should contain no gaps between
+components. For other Component_Sizes (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 quotation
+
+Followed.
+
+@geindex Enumeration representation clauses
+
+@geindex Representation clauses
+@geindex enumeration
+
+@node RM 13 4 9-10 Enumeration Representation Clauses,RM 13 5 1 17-22 Record Representation Clauses,RM 13 3 71-73 Component Size Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22f}
+@section RM 13.4(9-10): Enumeration Representation Clauses
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Record representation clauses
+
+@geindex Representation clauses
+@geindex records
+
+@node RM 13 5 1 17-22 Record Representation Clauses,RM 13 5 2 5 Storage Place Attributes,RM 13 4 9-10 Enumeration Representation Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{230}
+@section RM 13.5.1(17-22): Record Representation Clauses
+
+
+@quotation
+
+“The recommended level of support for
+`record_representation_clause's 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 quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@quotation
+
+“An implementation may reserve a storage place for the tag field of a
+tagged type, and disallow other components from overlapping that place.”
+@end quotation
+
+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.
+
+@quotation
+
+“An implementation need not support a `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 quotation
+
+Followed. The above advice on record representation clauses is followed,
+and all mentioned features are implemented.
+
+@geindex Storage place attributes
+
+@node RM 13 5 2 5 Storage Place Attributes,RM 13 5 3 7-8 Bit Ordering,RM 13 5 1 17-22 Record Representation Clauses,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{231}
+@section RM 13.5.2(5): Storage Place Attributes
+
+
+@quotation
+
+“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 quotation
+
+Followed. There are no such components in GNAT.
+
+@geindex Bit ordering
+
+@node RM 13 5 3 7-8 Bit Ordering,RM 13 7 37 Address as Private,RM 13 5 2 5 Storage Place Attributes,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{232}
+@section RM 13.5.3(7-8): Bit Ordering
+
+
+@quotation
+
+“The recommended level of support for the non-default bit ordering is:
+
+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 quotation
+
+Followed. Word size does not equal storage size in this implementation.
+Thus non-default bit ordering is not supported.
+
+@geindex Address
+@geindex as private type
+
+@node RM 13 7 37 Address as Private,RM 13 7 1 16 Address Operations,RM 13 5 3 7-8 Bit Ordering,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{233}
+@section RM 13.7(37): Address as Private
+
+
+@quotation
+
+“@cite{Address} should be of a private type.”
+@end quotation
+
+Followed.
+
+@geindex Operations
+@geindex on `@w{`}Address`@w{`}
+
+@geindex Address
+@geindex operations of
+
+@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{234}
+@section RM 13.7.1(16): Address Operations
+
+
+@quotation
+
+“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 quotation
+
+Followed. Address arithmetic is modular arithmetic that wraps around. No
+operation raises @code{Program_Error}, since all operations make sense.
+
+@geindex Unchecked conversion
+
+@node RM 13 9 14-17 Unchecked Conversion,RM 13 11 23-25 Implicit Heap Usage,RM 13 7 1 16 Address Operations,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{235}
+@section RM 13.9(14-17): Unchecked Conversion
+
+
+@quotation
+
+“The @code{Size} of an array object should not include its bounds; hence,
+the bounds should not be part of the converted data.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“The implementation should not generate unnecessary run-time checks to
+ensure that the representation of @code{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 quotation
+
+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.
+
+@quotation
+
+“The recommended level of support for unchecked conversions is:
+
+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 quotation
+
+Followed.
+
+@geindex Heap usage
+@geindex implicit
+
+@node RM 13 11 23-25 Implicit Heap Usage,RM 13 11 2 17 Unchecked Deallocation,RM 13 9 14-17 Unchecked Conversion,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{236}
+@section RM 13.11(23-25): Implicit Heap Usage
+
+
+@quotation
+
+“An implementation should document any cases in which it dynamically
+allocates heap storage for a purpose other than the evaluation of an
+allocator.”
+@end quotation
+
+Followed, the only other points at which heap storage is dynamically
+allocated are as follows:
+
+
+@itemize *
+
+@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
+
+
+@quotation
+
+“A default (implementation-provided) storage pool for an
+access-to-constant type should not have overhead to support deallocation of
+individual objects.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Unchecked deallocation
+
+@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 1 6 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{237}
+@section RM 13.11.2(17): Unchecked Deallocation
+
+
+@quotation
+
+“For a standard storage pool, @code{Free} should actually reclaim the
+storage.”
+@end quotation
+
+Followed.
+
+@geindex Stream oriented attributes
+
+@node RM 13 13 2 1 6 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{238}
+@section RM 13.13.2(1.6): Stream Oriented Attributes
+
+
+@quotation
+
+“If not specified, the value of Stream_Size for an elementary type
+should be the number of bits that corresponds to the minimum number of
+stream elements required by the first subtype of the type, rounded up
+to the nearest factor or multiple of the word size that is also a
+multiple of the stream element size.”
+@end quotation
+
+Followed, except that the number of stream elements is 1, 2, 3, 4 or 8.
+The Stream_Size may be used to override the default choice.
+
+The default 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. This XDR alternative can be enabled via the binder switch -xdr.
+
+@geindex XDR representation
+
+@geindex Read attribute
+
+@geindex Write attribute
+
+@geindex Stream oriented attributes
+
+@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 1 6 Stream Oriented Attributes,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{239}
+@section RM A.1(52): Names of Predefined Numeric Types
+
+
+@quotation
+
+“If an implementation provides additional named predefined integer types,
+then the names should end with @code{Integer} as in
+@code{Long_Integer}. If an implementation provides additional named
+predefined floating point types, then the names should end with
+@code{Float} as in @code{Long_Float}.”
+@end quotation
+
+Followed.
+
+@geindex Ada.Characters.Handling
+
+@node RM A 3 2 49 Ada Characters Handling,RM A 4 4 106 Bounded-Length String Handling,RM A 1 52 Names of Predefined Numeric Types,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{23a}
+@section RM A.3.2(49): @code{Ada.Characters.Handling}
+
+
+@quotation
+
+“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 quotation
+
+Followed. GNAT provides no such localized definitions.
+
+@geindex Bounded-length strings
+
+@node RM A 4 4 106 Bounded-Length String Handling,RM A 5 2 46-47 Random Number Generation,RM A 3 2 49 Ada Characters Handling,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{23b}
+@section RM A.4.4(106): Bounded-Length String Handling
+
+
+@quotation
+
+“Bounded string objects should not be implemented by implicit pointers
+and dynamic allocation.”
+@end quotation
+
+Followed. No implicit pointers or dynamic allocation are used.
+
+@geindex Random number generation
+
+@node RM A 5 2 46-47 Random Number Generation,RM A 10 7 23 Get_Immediate,RM A 4 4 106 Bounded-Length String Handling,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23c}
+@section RM A.5.2(46-47): Random Number Generation
+
+
+@quotation
+
+“Any storage associated with an object of type @code{Generator} should be
+reclaimed on exit from the scope of the object.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed. The generator period is sufficiently long for the first
+condition here to hold true.
+
+@geindex Get_Immediate
+
+@node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23d}
+@section RM A.10.7(23): @code{Get_Immediate}
+
+
+@quotation
+
+“The @code{Get_Immediate} procedures should be implemented with
+unbuffered input. For a device such as a keyboard, input should be
+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 quotation
+
+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.
+
+@geindex Containers
+
+@node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{23e}
+@section RM A.18: @code{Containers}
+
+
+All implementation advice pertaining to Ada.Containers and its
+child units (that is, all implementation advice occurring within
+section A.18 and its subsections) is followed except for A.18.24(17):
+
+@quotation
+
+“Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “
+@end quotation
+
+The implementations of the two Reference_Preserving_Key functions of
+the generic package Ada.Containers.Bounded_Ordered_Sets each currently make
+use of dynamic allocation; other operations on bounded ordered set objects
+follow the implementation advice.
+
+@geindex Export
+
+@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23f}
+@section RM B.1(39-41): Pragma @code{Export}
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@quotation
+
+“Automatic elaboration of pre-elaborated packages should be
+provided when pragma @code{Export} is supported.”
+@end quotation
+
+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.
+
+@quotation
+
+“For each supported convention `L' other than @code{Intrinsic}, an
+implementation should support @code{Import} and @code{Export} pragmas
+for objects of `L'-compatible types and for subprograms, and pragma
+@cite{Convention} for `L'-eligible types and for subprograms,
+presuming the other language has corresponding features. Pragma
+@code{Convention} need not be supported for scalar types.”
+@end quotation
+
+Followed.
+
+@geindex Package Interfaces
+
+@geindex Interfaces
+
+@node RM B 2 12-13 Package Interfaces,RM B 3 63-71 Interfacing with C,RM B 1 39-41 Pragma Export,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{240}
+@section RM B.2(12-13): Package @code{Interfaces}
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@quotation
+
+“An implementation supporting an interface to C, COBOL, or Fortran should
+provide the corresponding package or packages described in the following
+clauses.”
+@end quotation
+
+Followed. GNAT provides all the packages described in this section.
+
+@geindex C
+@geindex interfacing with
+
+@node RM B 3 63-71 Interfacing with C,RM B 4 95-98 Interfacing with COBOL,RM B 2 12-13 Package Interfaces,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{241}
+@section RM B.3(63-71): Interfacing with C
+
+
+@quotation
+
+“An implementation should support the following interface correspondences
+between Ada and C.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada procedure corresponds to a void-returning C function.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada function corresponds to a non-void C function.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada @code{in} scalar parameter is passed as a scalar argument to a C
+function.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada @code{in} parameter of an access-to-object type with designated
+type @code{T} is passed as a @code{t*} argument to a C function,
+where @code{t} is the C type corresponding to the Ada type @code{T}.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out}
+parameter of an elementary type @code{T}, is passed as a @code{t*}
+argument to a C function, where @code{t} is the C type corresponding to
+the Ada type @code{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 quotation
+
+Followed.
+
+@quotation
+
+“An Ada parameter of a record type @code{T}, of any mode, is passed as a
+@code{t*} argument to a C function, where @code{t} is the C
+structure corresponding to the Ada type @code{T}.”
+@end quotation
+
+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.
+
+@quotation
+
+“An Ada parameter of an array type with component type @code{T}, of any
+mode, is passed as a @code{t*} argument to a C function, where
+@code{t} is the C type corresponding to the Ada type @code{T}.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex COBOL
+@geindex interfacing with
+
+@node RM B 4 95-98 Interfacing with COBOL,RM B 5 22-26 Interfacing with Fortran,RM B 3 63-71 Interfacing with C,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{242}
+@section RM B.4(95-98): Interfacing with COBOL
+
+
+@quotation
+
+“An Ada implementation should support the following interface
+correspondences between Ada and COBOL.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of
+the COBOL type corresponding to @code{T}.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of
+the corresponding COBOL type.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“Any other Ada parameter is passed as a @code{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 quotation
+
+Followed.
+
+@geindex Fortran
+@geindex interfacing with
+
+@node RM B 5 22-26 Interfacing with Fortran,RM C 1 3-5 Access to Machine Operations,RM B 4 95-98 Interfacing with COBOL,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{243}
+@section RM B.5(22-26): Interfacing with Fortran
+
+
+@quotation
+
+“An Ada implementation should support the following interface
+correspondences between Ada and Fortran:”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada procedure corresponds to a Fortran subroutine.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada function corresponds to a Fortran function.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“An Ada parameter of an elementary, array, or record type @code{T} is
+passed as a @code{T} argument to a Fortran procedure, where @code{T} is
+the Fortran type corresponding to the Ada type @code{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 quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Machine operations
+
+@node RM C 1 3-5 Access to Machine Operations,RM C 1 10-16 Access to Machine Operations,RM B 5 22-26 Interfacing with Fortran,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{244}
+@section RM C.1(3-5): Access to Machine Operations
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@quotation
+
+“The interfacing pragmas (see Annex B) should support interface to
+assembler; the default assembler should be associated with the
+convention identifier @code{Assembler}.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@node RM C 1 10-16 Access to Machine Operations,RM C 3 28 Interrupt Support,RM C 1 3-5 Access to Machine Operations,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{245}
+@section RM C.1(10-16): Access to Machine Operations
+
+
+@quotation
+
+“The implementation should ensure that little or no overhead is
+associated with calling intrinsic and machine-code subprograms.”
+@end quotation
+
+Followed for both intrinsics and machine-code subprograms.
+
+@quotation
+
+“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 quotation
+
+Followed. A full set of machine operation intrinsic subprograms is provided.
+
+@quotation
+
+“Atomic read-modify-write operations—e.g., test and set, compare and
+swap, decrement and test, enqueue/dequeue.”
+@end quotation
+
+Followed on any target supporting such operations.
+
+@quotation
+
+“Standard numeric functions—e.g.:, sin, log.”
+@end quotation
+
+Followed on any target supporting such operations.
+
+@quotation
+
+“String manipulation operations—e.g.:, translate and test.”
+@end quotation
+
+Followed on any target supporting such operations.
+
+@quotation
+
+“Vector operations—e.g.:, compare vector against thresholds.”
+@end quotation
+
+Followed on any target supporting such operations.
+
+@quotation
+
+“Direct operations on I/O ports.”
+@end quotation
+
+Followed on any target supporting such operations.
+
+@geindex Interrupt support
+
+@node RM C 3 28 Interrupt Support,RM C 3 1 20-21 Protected Procedure Handlers,RM C 1 10-16 Access to Machine Operations,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{246}
+@section RM C.3(28): Interrupt Support
+
+
+@quotation
+
+“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 quotation
+
+Followed. The underlying system does not allow for finer-grain control
+of interrupt blocking.
+
+@geindex Protected procedure handlers
+
+@node RM C 3 1 20-21 Protected Procedure Handlers,RM C 3 2 25 Package Interrupts,RM C 3 28 Interrupt Support,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{247}
+@section RM C.3.1(20-21): Protected Procedure Handlers
+
+
+@quotation
+
+“Whenever possible, the implementation should allow interrupt handlers to
+be called directly by the hardware.”
+@end quotation
+
+Followed on any target where the underlying operating system permits
+such direct calls.
+
+@quotation
+
+“Whenever practical, violations of any
+implementation-defined restrictions should be detected before run time.”
+@end quotation
+
+Followed. Compile time warnings are given when possible.
+
+@geindex Package `@w{`}Interrupts`@w{`}
+
+@geindex Interrupts
+
+@node RM C 3 2 25 Package Interrupts,RM C 4 14 Pre-elaboration Requirements,RM C 3 1 20-21 Protected Procedure Handlers,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{248}
+@section RM C.3.2(25): Package @code{Interrupts}
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Pre-elaboration requirements
+
+@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{249}
+@section RM C.4(14): Pre-elaboration Requirements
+
+
+@quotation
+
+“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 quotation
+
+Followed. Executable code is generated in some cases, e.g., loops
+to initialize large arrays.
+
+@node RM C 5 8 Pragma Discard_Names,RM C 7 2 30 The Package Task_Attributes,RM C 4 14 Pre-elaboration Requirements,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{24a}
+@section RM C.5(8): Pragma @code{Discard_Names}
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Package Task_Attributes
+
+@geindex Task_Attributes
+
+@node RM C 7 2 30 The Package Task_Attributes,RM D 3 17 Locking Policies,RM C 5 8 Pragma Discard_Names,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{24b}
+@section RM C.7.2(30): The Package Task_Attributes
+
+
+@quotation
+
+“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 @code{N}
+attribute objects, and the heap for the others. In the latter case,
+@code{N} should be documented.”
+@end quotation
+
+Not followed. This implementation is not targeted to such a domain.
+
+@geindex Locking Policies
+
+@node RM D 3 17 Locking Policies,RM D 4 16 Entry Queuing Policies,RM C 7 2 30 The Package Task_Attributes,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{24c}
+@section RM D.3(17): Locking Policies
+
+
+@quotation
+
+“The implementation should use names that end with @code{_Locking} for
+locking policies defined by the implementation.”
+@end quotation
+
+Followed. Two implementation-defined locking policies are defined,
+whose names (@code{Inheritance_Locking} and
+@code{Concurrent_Readers_Locking}) follow this suggestion.
+
+@geindex Entry queuing policies
+
+@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24d}
+@section RM D.4(16): Entry Queuing Policies
+
+
+@quotation
+
+“Names that end with @code{_Queuing} should be used
+for all implementation-defined queuing policies.”
+@end quotation
+
+Followed. No such implementation-defined queuing policies exist.
+
+@geindex Preemptive abort
+
+@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24e}
+@section RM D.6(9-10): Preemptive Abort
+
+
+@quotation
+
+“Even though the `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 `abort_statement' to block.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Tasking restrictions
+
+@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24f}
+@section RM D.7(21): Tasking Restrictions
+
+
+@quotation
+
+“When feasible, the implementation should take advantage of the specified
+restrictions to produce a more efficient implementation.”
+@end quotation
+
+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.
+
+@geindex Time
+@geindex monotonic
+
+@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{250}
+@section RM D.8(47-49): Monotonic Time
+
+
+@quotation
+
+“When appropriate, implementations should provide configuration
+mechanisms to change the value of @code{Tick}.”
+@end quotation
+
+Such configuration mechanisms are not appropriate to this implementation
+and are thus not supported.
+
+@quotation
+
+“It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
+be implemented as transformations of the same time base.”
+@end quotation
+
+Followed.
+
+@quotation
+
+“It is recommended that the best time base which exists in
+the underlying system be available to the application through
+@code{Clock}. @cite{Best} may mean highest accuracy or largest range.”
+@end quotation
+
+Followed.
+
+@geindex Partition communication subsystem
+
+@geindex PCS
+
+@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{251}
+@section RM E.5(28-29): Partition Communication Subsystem
+
+
+@quotation
+
+“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 quotation
+
+Followed by GLADE, a separately supplied PCS that can be used with
+GNAT.
+
+@quotation
+
+“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 quotation
+
+Followed by GLADE, a separately supplied PCS that can be used with
+GNAT.
+
+@geindex COBOL support
+
+@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{252}
+@section RM F(7): COBOL Support
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Decimal radix support
+
+@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{253}
+@section RM F.1(2): Decimal Radix Support
+
+
+@quotation
+
+“Packed decimal should be used as the internal representation for objects
+of subtype @code{S} when @code{S}’Machine_Radix = 10.”
+@end quotation
+
+Not followed. GNAT ignores @code{S}’Machine_Radix and always uses binary
+representations.
+
+@geindex Numerics
+
+@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{254}
+@section RM G: Numerics
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Complex types
+
+@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{255}
+@section RM G.1.1(56-58): Complex Types
+
+
+@quotation
+
+“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 quotation
+
+Not followed.
+
+@quotation
+
+“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 quotation
+
+Not followed.
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Complex elementary functions
+
+@node RM G 1 2 49 Complex Elementary Functions,RM G 2 4 19 Accuracy Requirements,RM G 1 1 56-58 Complex Types,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{256}
+@section RM G.1.2(49): Complex Elementary Functions
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Accuracy requirements
+
+@node RM G 2 4 19 Accuracy Requirements,RM G 2 6 15 Complex Arithmetic Accuracy,RM G 1 2 49 Complex Elementary Functions,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{257}
+@section RM G.2.4(19): Accuracy Requirements
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Complex arithmetic accuracy
+
+@geindex Accuracy
+@geindex complex arithmetic
+
+@node RM G 2 6 15 Complex Arithmetic Accuracy,RM H 6 15/2 Pragma Partition_Elaboration_Policy,RM G 2 4 19 Accuracy Requirements,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{258}
+@section RM G.2.6(15): Complex Arithmetic Accuracy
+
+
+@quotation
+
+“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 quotation
+
+Followed.
+
+@geindex Sequential elaboration policy
+
+@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice
+@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{259}
+@section RM H.6(15/2): Pragma Partition_Elaboration_Policy
+
+
+@quotation
+
+“If the partition elaboration policy is @code{Sequential} and the
+Environment task becomes permanently blocked during elaboration then the
+partition is deadlocked and it is recommended that the partition be
+immediately terminated.”
+@end quotation
+
+Not followed.
+
+@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top
+@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{25a}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{25b}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}
+@chapter Implementation Defined Characteristics
+
+
+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 and are designated as
+implementation-defined. 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 of how GNAT 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 entry below correspond to the paragraph numbers in the Ada
+Reference Manual.
+
+
+@itemize *
+
+@item
+“Whether or not each recommendation given in Implementation
+Advice is followed. See 1.1.2(37).”
+@end itemize
+
+See @ref{a,,Implementation Advice}.
+
+
+@itemize *
+
+@item
+“Capacity limitations of the implementation. See 1.1.3(3).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“Variations from the standard that are impractical to avoid
+given the implementation’s execution environment. See 1.1.3(6).”
+@end itemize
+
+There are no variations from the standard.
+
+
+@itemize *
+
+@item
+“Which code_statements cause external
+interactions. See 1.1.3(10).”
+@end itemize
+
+Any `code_statement' can potentially cause external interactions.
+
+
+@itemize *
+
+@item
+“The coded representation for the text of an Ada
+program. See 2.1(4).”
+@end itemize
+
+See separate section on source representation.
+
+
+@itemize *
+
+@item
+“The semantics of an Ada program whose text is not in
+Normalization Form C. See 2.1(4).”
+@end itemize
+
+See separate section on source representation.
+
+
+@itemize *
+
+@item
+“The representation for an end of line. See 2.2(2).”
+@end itemize
+
+See separate section on source representation.
+
+
+@itemize *
+
+@item
+“Maximum supported line length and lexical element
+length. See 2.2(15).”
+@end itemize
+
+The maximum line length is 255 characters and the maximum length of
+a lexical element is also 255 characters. This is the default setting
+if not overridden by the use of compiler switch `-gnaty' (which
+sets the maximum to 79) or `-gnatyMnn' which allows the maximum
+line length to be specified to be any value up to 32767. The maximum
+length of a lexical element is the same as the maximum line length.
+
+
+@itemize *
+
+@item
+“Implementation defined pragmas. See 2.8(14).”
+@end itemize
+
+See @ref{7,,Implementation Defined Pragmas}.
+
+
+@itemize *
+
+@item
+“Effect of pragma @code{Optimize}. See 2.8(27).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“The message string associated with the Assertion_Error exception raised
+by the failure of a predicate check if there is no applicable
+Predicate_Failure aspect. See 3.2.4(31).”
+@end itemize
+
+In the case of a Dynamic_Predicate aspect, the string is
+“Dynamic_Predicate failed at <source position>”, where
+“<source position>” might be something like “foo.adb:123”.
+The Static_Predicate case is handled analogously.
+
+
+@itemize *
+
+@item
+“The predefined integer types declared in
+@code{Standard}. See 3.5.4(25).”
+@end itemize
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+Type
+
+@tab
+
+Representation
+
+@item
+
+`Short_Short_Integer'
+
+@tab
+
+8-bit signed
+
+@item
+
+`Short_Integer'
+
+@tab
+
+16-bit signed
+
+@item
+
+`Integer'
+
+@tab
+
+32-bit signed
+
+@item
+
+`Long_Integer'
+
+@tab
+
+64-bit signed (on most 64-bit targets,
+depending on the C definition of long)
+32-bit signed (on all other targets)
+
+@item
+
+`Long_Long_Integer'
+
+@tab
+
+64-bit signed
+
+@item
+
+`Long_Long_Long_Integer'
+
+@tab
+
+128-bit signed (on 64-bit targets)
+64-bit signed (on 32-bit targets)
+
+@end multitable
+
+
+
+@itemize *
+
+@item
+“Any nonstandard integer types and the operators defined
+for them. See 3.5.4(26).”
+@end itemize
+
+There are no nonstandard integer types.
+
+
+@itemize *
+
+@item
+“Any nonstandard real types and the operators defined for
+them. See 3.5.6(8).”
+@end itemize
+
+There are no nonstandard real types.
+
+
+@itemize *
+
+@item
+“What combinations of requested decimal precision and range
+are supported for floating point types. See 3.5.7(7).”
+@end itemize
+
+The precision and range are defined by the IEEE Standard for Floating-Point
+Arithmetic (IEEE 754-2019).
+
+
+@itemize *
+
+@item
+“The predefined floating point types declared in
+@code{Standard}. See 3.5.7(16).”
+@end itemize
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+Type
+
+@tab
+
+Representation
+
+@item
+
+`Short_Float'
+
+@tab
+
+IEEE Binary32 (Single)
+
+@item
+
+`Float'
+
+@tab
+
+IEEE Binary32 (Single)
+
+@item
+
+`Long_Float'
+
+@tab
+
+IEEE Binary64 (Double)
+
+@item
+
+`Long_Long_Float'
+
+@tab
+
+IEEE Binary64 (Double) on non-x86 architectures
+IEEE 80-bit Extended on x86 architecture
+
+@end multitable
+
+
+The default rounding mode specified by the IEEE 754 Standard is assumed both
+for static and dynamic computations (that is, round to nearest, ties to even).
+The input routines yield correctly rounded values for Short_Float, Float, and
+Long_Float at least. The output routines can compute up to twice as many exact
+digits as the value of @code{T'Digits} for any type, for example 30 digits for
+Long_Float; if more digits are requested, zeros are printed.
+
+
+@itemize *
+
+@item
+“The small of an ordinary fixed point type. See 3.5.9(8).”
+@end itemize
+
+The small is the largest power of two that does not exceed the delta.
+
+
+@itemize *
+
+@item
+“What combinations of small, range, and digits are
+supported for fixed point types. See 3.5.9(10).”
+@end itemize
+
+For an ordinary fixed point type, on 32-bit platforms, the small must lie in
+2.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination
+is permitted that does not result in a mantissa larger than 63 bits.
+
+On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the
+range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not
+result in a mantissa larger than 63 bits, and any combination is permitted
+that results in a mantissa between 64 and 127 bits if the small is the
+ratio of two integers that lie in 1 .. 2.0**127.
+
+If the small is the ratio of two integers with 64-bit magnitude on 32-bit
+platforms and 128-bit magnitude on 64-bit platforms, which is the case if
+no @code{small} clause is provided, then the operations of the fixed point
+type are entirely implemented by means of integer instructions. In the
+other cases, some operations, in particular input and output, may be
+implemented by means of floating-point instructions and may be affected
+by accuracy issues on architectures other than x86.
+
+For a decimal fixed point type, on 32-bit platforms, the small must lie in
+1.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the
+small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38.
+
+
+@itemize *
+
+@item
+“The result of @code{Tags.Expanded_Name} for types declared
+within an unnamed `block_statement'. See 3.9(10).”
+@end itemize
+
+Block numbers of the form @code{B@var{nnn}}, where `nnn' is a
+decimal integer are allocated.
+
+
+@itemize *
+
+@item
+“The sequence of characters of the value returned by Tags.Expanded_Name
+(respectively, Tags.Wide_Expanded_Name) when some of the graphic
+characters of Tags.Wide_Wide_Expanded_Name are not defined in Character
+(respectively, Wide_Character). See 3.9(10.1).”
+@end itemize
+
+This is handled in the same way as the implementation-defined behavior
+referenced in A.4.12(34).
+
+
+@itemize *
+
+@item
+“Implementation-defined attributes. See 4.1.4(12).”
+@end itemize
+
+See @ref{8,,Implementation Defined Attributes}.
+
+
+@itemize *
+
+@item
+“The value of the parameter to Empty for some container aggregates.
+See 4.3.5(40).”
+@end itemize
+
+As per the suggestion given in the Annotated Ada RM, the default value
+of the formal parameter is used if one exists and zero is used otherwise.
+
+
+@itemize *
+
+@item
+“The maximum number of chunks for a parallel reduction expression without
+a chunk_specification. See 4.5.10(21).”
+@end itemize
+
+Feature unimplemented.
+
+
+@itemize *
+
+@item
+“Rounding of real static expressions which are exactly half-way between
+two machine numbers. See 4.9(38).”
+@end itemize
+
+Round to even is used in all such cases.
+
+
+@itemize *
+
+@item
+“The maximum number of chunks for a parallel generalized iterator without
+a chunk_specification. See 5.5.2(10).”
+@end itemize
+
+Feature unimplemented.
+
+
+@itemize *
+
+@item
+“The number of chunks for an array component iterator. See 5.5.2(11).”
+@end itemize
+
+Feature unimplemented.
+
+
+@itemize *
+
+@item
+“Any extensions of the Global aspect. See 6.1.2(43).”
+@end itemize
+
+Feature unimplemented.
+
+
+@itemize *
+
+@item
+“The circumstances the implementation passes in the null value for a view
+conversion of an access type used as an out parameter. See 6.4.1(19).”
+@end itemize
+
+Difficult to characterize.
+
+
+@itemize *
+
+@item
+“Any extensions of the Default_Initial_Condition aspect. See 7.3.3(11).”
+@end itemize
+
+SPARK allows specifying `null' as the Default_Initial_Condition
+aspect of a type. See the SPARK reference manual for further details.
+
+
+@itemize *
+
+@item
+“Any implementation-defined time types. See 9.6(6).”
+@end itemize
+
+There are no implementation-defined time types.
+
+
+@itemize *
+
+@item
+“The time base associated with relative delays. See 9.6(20).”
+@end itemize
+
+See 9.6(20). The time base used is that provided by the C library
+function @code{gettimeofday}.
+
+
+@itemize *
+
+@item
+“The time base of the type @code{Calendar.Time}. See 9.6(23).”
+@end itemize
+
+The time base used is that provided by the C library function
+@code{gettimeofday}.
+
+
+@itemize *
+
+@item
+“The time zone used for package @code{Calendar}
+operations. See 9.6(24).”
+@end itemize
+
+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}.
+
+
+@itemize *
+
+@item
+“Any limit on `delay_until_statements' of
+`select_statements'. See 9.6(29).”
+@end itemize
+
+There are no such limits.
+
+
+@itemize *
+
+@item
+“The result of Calendar.Formatting.Image if its argument represents more
+than 100 hours. See 9.6.1(86).”
+@end itemize
+
+Calendar.Time_Error is raised.
+
+
+@itemize *
+
+@item
+“Implementation-defined conflict check policies. See 9.10.1(5).”
+@end itemize
+
+There are no implementation-defined conflict check policies.
+
+
+@itemize *
+
+@item
+“The representation for a compilation. See 10.1(2).”
+@end itemize
+
+A compilation is represented by a sequence of files presented to the
+compiler in a single invocation of the `gcc' command.
+
+
+@itemize *
+
+@item
+“Any restrictions on compilations that contain multiple
+compilation_units. See 10.1(4).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“The mechanisms for creating an environment and for adding
+and replacing compilation units. See 10.1.4(3).”
+@end itemize
+
+See separate section on compilation model.
+
+
+@itemize *
+
+@item
+“The manner of explicitly assigning library units to a
+partition. See 10.2(2).”
+@end itemize
+
+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 `-z' and `-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 `GNAT Make Program gnatmake' in the
+@cite{GNAT User’s Guide}.
+
+
+@itemize *
+
+@item
+“The implementation-defined means, if any, of specifying which compilation
+units are needed by a given compilation unit. See 10.2(2).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“The manner of designating the main subprogram of a
+partition. See 10.2(7).”
+@end itemize
+
+The main program is designated by providing the name of the
+corresponding @code{ALI} file as the input parameter to the binder.
+
+
+@itemize *
+
+@item
+“The order of elaboration of `library_items'. See 10.2(18).”
+@end itemize
+
+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 analyzing
+the elaboration code of each unit and identifying implicit
+elaboration-order dependencies.
+
+
+@itemize *
+
+@item
+“Parameter passing and function return for the main
+subprogram. See 10.2(21).”
+@end itemize
+
+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}).
+
+
+@itemize *
+
+@item
+“The mechanisms for building and running partitions. See 10.2(24).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“The details of program execution, including program
+termination. See 10.2(25).”
+@end itemize
+
+See separate section on compilation model.
+
+
+@itemize *
+
+@item
+“The semantics of any non-active partitions supported by the
+implementation. See 10.2(28).”
+@end itemize
+
+Passive partitions are supported on targets where shared memory is
+provided by the operating system. See the GLADE reference manual for
+further details.
+
+
+@itemize *
+
+@item
+“The information returned by @code{Exception_Message}. See 11.4.1(10).”
+@end itemize
+
+Exception message returns the null string unless a specific message has
+been passed by the program.
+
+
+@itemize *
+
+@item
+“The result of @code{Exceptions.Exception_Name} for types
+declared within an unnamed `block_statement'. See 11.4.1(12).”
+@end itemize
+
+Blocks have implementation defined names of the form @code{B@var{nnn}}
+where `nnn' is an integer.
+
+
+@itemize *
+
+@item
+“The information returned by
+@code{Exception_Information}. See 11.4.1(13).”
+@end itemize
+
+@code{Exception_Information} returns a string in the following format:
+
+@example
+*Exception_Name:* nnnnn
+*Message:* mmmmm
+*PID:* ppp
+*Load address:* 0xhhhh
+*Call stack traceback locations:*
+0xhhhh 0xhhhh 0xhhhh ... 0xhhh
+@end example
+
+where
+
+@quotation
+
+
+@itemize *
+
+@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 Load address line, the Call stack traceback locations line and the
+following values are present only if at least one traceback location was
+recorded. The Load address indicates the address at which the main executable
+was loaded; this line may not be present if operating system hasn’t relocated
+the main executable. The values are given in C style format, with lower case
+letters for a-f, and only as many digits present as are necessary.
+The line terminator sequence at the end of each line, including
+the last line is a single @code{LF} character (@code{16#0A#}).
+@end itemize
+@end quotation
+
+
+@itemize *
+
+@item
+“The sequence of characters of the value returned by
+Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name)
+when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name
+are not defined in Character (respectively, Wide_Character).
+See 11.4.1(12.1).”
+@end itemize
+
+This is handled in the same way as the implementation-defined behavior
+referenced in A.4.12(34).
+
+
+@itemize *
+
+@item
+“The information returned by Exception_Information. See 11.4.1(13).”
+@end itemize
+
+The exception name and the source location at which the exception was
+raised are included.
+
+
+@itemize *
+
+@item
+“Implementation-defined policy_identifiers and assertion_aspect_marks
+allowed in a pragma Assertion_Policy. See 11.4.2(9).”
+@end itemize
+
+Implementation-defined assertion_aspect_marks include Assert_And_Cut,
+Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant,
+Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post,
+Statement_Assertions, and Subprogram_Variant. Implementation-defined
+policy_identifiers include Ignore and Suppressible.
+
+
+@itemize *
+
+@item
+“The default assertion policy. See 11.4.2(10).”
+@end itemize
+
+The default assertion policy is Ignore, although this can be overridden
+via compiler switches such as “-gnata”.
+
+
+@itemize *
+
+@item
+“Implementation-defined check names. See 11.5(27).”
+@end itemize
+
+The implementation defined check names include Alignment_Check,
+Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks,
+Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user
+program can add implementation-defined check names by means of the pragma
+Check_Name. See the description of pragma @code{Suppress} for full details.
+
+
+@itemize *
+
+@item
+“Existence and meaning of second parameter of pragma Unsuppress.
+See 11.5(27.1).”
+@end itemize
+
+The legality rules for and semantics of the second parameter of pragma
+Unsuppress match those for the second argument of pragma Suppress.
+
+
+@itemize *
+
+@item
+“The cases that cause conflicts between the representation of the
+ancestors of a type_declaration. See 13.1(13.1).”
+@end itemize
+
+No such cases exist.
+
+
+@itemize *
+
+@item
+“The interpretation of each representation aspect. See 13.1(20).”
+@end itemize
+
+See separate section on data representations.
+
+
+@itemize *
+
+@item
+“Any restrictions placed upon the specification of representation aspects.
+See 13.1(20).”
+@end itemize
+
+See separate section on data representations.
+
+
+@itemize *
+
+@item
+“Implementation-defined aspects, including the syntax for specifying
+such aspects and the legality rules for such aspects. See 13.1.1(38).”
+@end itemize
+
+See @ref{120,,Implementation Defined Aspects}.
+
+
+@itemize *
+
+@item
+“The set of machine scalars. See 13.3(8.1).”
+@end itemize
+
+See separate section on data representations.
+
+
+@itemize *
+
+@item
+“The meaning of @code{Size} for indefinite subtypes. See 13.3(48).”
+@end itemize
+
+The Size attribute of an indefinite subtype is not less than the Size
+attribute of any object of that type.
+
+
+@itemize *
+
+@item
+“The meaning of Object_Size for indefinite subtypes. See 13.3(58).”
+@end itemize
+
+The Object_Size attribute of an indefinite subtype is not less than the
+Object_Size attribute of any object of that type.
+
+
+@itemize *
+
+@item
+“The default external representation for a type tag. See 13.3(75).”
+@end itemize
+
+The default external representation for a type tag is the fully expanded
+name of the type in upper case letters.
+
+
+@itemize *
+
+@item
+“What determines whether a compilation unit is the same in
+two different partitions. See 13.3(76).”
+@end itemize
+
+A compilation unit is the same in two different partitions if and only
+if it derives from the same source file.
+
+
+@itemize *
+
+@item
+“Implementation-defined components. See 13.5.1(15).”
+@end itemize
+
+The only implementation defined component is the tag for a tagged type,
+which contains a pointer to the dispatching table.
+
+
+@itemize *
+
+@item
+“If @code{Word_Size} = @code{Storage_Unit}, the default bit
+ordering. See 13.5.3(5).”
+@end itemize
+
+@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.
+
+
+@itemize *
+
+@item
+“The contents of the visible part of package @code{System}. See 13.7(2).”
+@end itemize
+
+See the definition of package System in @code{system.ads}.
+Note that two declarations are added to package System.
+
+@example
+Max_Priority : constant Positive := Priority'Last;
+Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last;
+@end example
+
+
+@itemize *
+
+@item
+“The range of Storage_Elements.Storage_Offset, the modulus of
+Storage_Elements.Storage_Element, and the declaration of
+Storage_Elements.Integer_Address. See 13.7.1(11).”
+@end itemize
+
+See the definition of package System.Storage_Elements in @code{s-stoele.ads}.
+
+
+@itemize *
+
+@item
+“The contents of the visible part of package @code{System.Machine_Code},
+and the meaning of `code_statements'. See 13.8(7).”
+@end itemize
+
+See the definition and documentation in file @code{s-maccod.ads}.
+
+
+@itemize *
+
+@item
+“The result of unchecked conversion for instances with scalar result
+types whose result is not defined by the language. See 13.9(11).”
+@end itemize
+
+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
+
+
+@itemize *
+
+@item
+“The result of unchecked conversion for instances with nonscalar result
+types whose result is not defined by the language. See 13.9(11).”
+@end itemize
+
+See preceding definition for the scalar result case.
+
+
+@itemize *
+
+@item
+“Whether or not the implementation provides user-accessible
+names for the standard pool type(s). See 13.11(17).”
+@end itemize
+
+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`@w{`}is specified or not. See documentation in the runtime
+library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and
+@code{System.Pool_Local} in files @code{s-poosiz.ads},
+@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the
+default pools used. All these pools are accessible by means of @cite{with}ing
+these units.
+
+
+@itemize *
+
+@item
+“The meaning of @code{Storage_Size} when neither the Storage_Size nor the
+Storage_Pool is specified for an access type. See 13.11(18).”
+@end itemize
+
+@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.
+
+
+@itemize *
+
+@item
+“The effect of specifying aspect Default_Storage_Pool on an instance
+of a language-defined generic unit. See 13.11.3(5).”
+@end itemize
+
+Instances of language-defined generic units are treated the same as other
+instances with respect to the Default_Storage_Pool aspect.
+
+
+@itemize *
+
+@item
+“Implementation-defined restrictions allowed in a pragma
+@code{Restrictions}. See 13.12(8.7).”
+@end itemize
+
+See @ref{9,,Standard and Implementation Defined Restrictions}.
+
+
+@itemize *
+
+@item
+“The consequences of violating limitations on
+@code{Restrictions} pragmas. See 13.12(9).”
+@end itemize
+
+Restrictions that can be checked at compile time are enforced at
+compile time; violations are illegal. For other restrictions, any
+violation during program execution results in erroneous execution.
+
+
+@itemize *
+
+@item
+“Implementation-defined usage profiles allowed in a pragma Profile.
+See 13.12(15).”
+@end itemize
+
+See @ref{7,,Implementation Defined Pragmas}.
+
+
+@itemize *
+
+@item
+“The contents of the stream elements read and written by the Read and
+Write attributes of elementary types. See 13.13.2(9).”
+@end itemize
+
+The representation is the in-memory representation of the base type of
+the type, using the number of bits corresponding to the
+@code{type'Size} value, and the natural ordering of the machine.
+
+
+@itemize *
+
+@item
+“The names and characteristics of the numeric subtypes
+declared in the visible part of package @code{Standard}. See A.1(3).”
+@end itemize
+
+See items describing the integer and floating-point types supported.
+
+
+@itemize *
+
+@item
+“The values returned by Strings.Hash. See A.4.9(3).”
+@end itemize
+
+This hash function has predictable collisions and is subject to
+equivalent substring attacks. It is not suitable for construction of a
+hash table keyed on possibly malicious user input.
+
+
+@itemize *
+
+@item
+“The value returned by a call to a Text_Buffer Get procedure if any
+character in the returned sequence is not defined in Character.
+See A.4.12(34).”
+@end itemize
+
+The contents of a buffer is represented internally as a UTF_8 string.
+The value return by Text_Buffer.Get is the result of passing that
+UTF_8 string to UTF_Encoding.Strings.Decode.
+
+
+@itemize *
+
+@item
+“The value returned by a call to a Text_Buffer Wide_Get procedure if
+any character in the returned sequence is not defined in Wide_Character.
+See A.4.12(34).”
+@end itemize
+
+The contents of a buffer is represented internally as a UTF_8 string.
+The value return by Text_Buffer.Wide_Get is the result of passing that
+UTF_8 string to UTF_Encoding.Wide_Strings.Decode.
+
+
+@itemize *
+
+@item
+“The accuracy actually achieved by the elementary
+functions. See A.5.1(1).”
+@end itemize
+
+The elementary functions correspond to the functions available in the C
+library. Only fast math mode is implemented.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+The sign of zeroes follows the requirements of the IEEE 754 standard on
+floating-point.
+
+
+@itemize *
+
+@item
+“The value of
+@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).”
+@end itemize
+
+Maximum image width is 6864, see library file @code{s-rannum.ads}.
+
+
+@itemize *
+
+@item
+“The value of
+@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).”
+@end itemize
+
+Maximum image width is 6864, see library file @code{s-rannum.ads}.
+
+
+@itemize *
+
+@item
+“The string representation of a random number generator’s
+state. See A.5.2(38).”
+@end itemize
+
+The value returned by the Image function is the concatenation of
+the fixed-width decimal representations of the 624 32-bit integers
+of the state vector.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+Running the compiler with `-gnatS' to produce a listing of package
+@code{Standard} displays the values of these attributes.
+
+
+@itemize *
+
+@item
+“The value of @code{Buffer_Size} in @code{Storage_IO}. See A.9(10).”
+@end itemize
+
+All type representations are contiguous, and the @code{Buffer_Size} is
+the value of @code{type'Size} rounded up to the next storage unit
+boundary.
+
+
+@itemize *
+
+@item
+“External files for standard input, standard output, and
+standard error See A.10(5).”
+@end itemize
+
+These files are mapped onto the files provided by the C streams
+libraries. See source file @code{i-cstrea.ads} for further details.
+
+
+@itemize *
+
+@item
+“The accuracy of the value produced by @code{Put}. See A.10.9(36).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“Current size for a stream file for which positioning is not supported.
+See A.12.1(1.1).”
+@end itemize
+
+Positioning is supported.
+
+
+@itemize *
+
+@item
+“The meaning of @code{Argument_Count}, @code{Argument}, and
+@code{Command_Name}. See A.15(1).”
+@end itemize
+
+These are mapped onto the @code{argv} and @code{argc} parameters of the
+main program in the natural manner.
+
+
+@itemize *
+
+@item
+“The interpretation of file names and directory names. See A.16(46).”
+@end itemize
+
+These names are interpreted consistently with the underlying file system.
+
+
+@itemize *
+
+@item
+“The maxium value for a file size in Directories. See A.16(87).”
+@end itemize
+
+Directories.File_Size’Last is equal to Long_Long_Integer’Last .
+
+
+@itemize *
+
+@item
+“The result for Directories.Size for a directory or special file.
+See A.16(93).”
+@end itemize
+
+Name_Error is raised.
+
+
+@itemize *
+
+@item
+“The result for Directories.Modification_Time for a directory or special file.
+See A.16(93).”
+@end itemize
+
+Name_Error is raised.
+
+
+@itemize *
+
+@item
+“The interpretation of a nonnull search pattern in Directories.
+See A.16(104).”
+@end itemize
+
+When the @code{Pattern} parameter is not the null string, it is interpreted
+according to the syntax of regular expressions as defined in the
+@code{GNAT.Regexp} package.
+
+See @ref{25c,,GNAT.Regexp (g-regexp.ads)}.
+
+
+@itemize *
+
+@item
+“The results of a Directories search if the contents of the directory are
+altered while a search is in progress. See A.16(110).”
+@end itemize
+
+The effect of a call to Get_Next_Entry is determined by the current
+state of the directory.
+
+
+@itemize *
+
+@item
+“The definition and meaning of an environment variable. See A.17(1).”
+@end itemize
+
+This definition is determined by the underlying operating system.
+
+
+@itemize *
+
+@item
+“The circumstances where an environment variable cannot be defined.
+See A.17(16).”
+
+There are no such implementation-defined circumstances.
+
+@item
+“Environment names for which Set has the effect of Clear. See A.17(17).”
+@end itemize
+
+There are no such names.
+
+
+@itemize *
+
+@item
+“The value of Containers.Hash_Type’Modulus. The value of
+Containers.Count_Type’Last. See A.18.1(7).”
+@end itemize
+
+Containers.Hash_Type’Modulus is 2**32.
+Containers.Count_Type’Last is 2**31 - 1.
+
+
+@itemize *
+
+@item
+“Implementation-defined convention names. See B.1(11).”
+@end itemize
+
+The following convention names are supported
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+Convention Name
+
+@tab
+
+Interpretation
+
+@item
+
+`Ada'
+
+@tab
+
+Ada
+
+@item
+
+`Ada_Pass_By_Copy'
+
+@tab
+
+Allowed for any types except by-reference types such as limited
+records. Compatible with convention Ada, but causes any parameters
+with this convention to be passed by copy.
+
+@item
+
+`Ada_Pass_By_Reference'
+
+@tab
+
+Allowed for any types except by-copy types such as scalars.
+Compatible with convention Ada, but causes any parameters
+with this convention to be passed by reference.
+
+@item
+
+`Assembler'
+
+@tab
+
+Assembly language
+
+@item
+
+`Asm'
+
+@tab
+
+Synonym for Assembler
+
+@item
+
+`Assembly'
+
+@tab
+
+Synonym for Assembler
+
+@item
+
+`C'
+
+@tab
+
+C
+
+@item
+
+`C_Pass_By_Copy'
+
+@tab
+
+Allowed only for record types, like C, but also notes that record
+is to be passed by copy rather than reference.
+
+@item
+
+`COBOL'
+
+@tab
+
+COBOL
+
+@item
+
+`C_Plus_Plus (or CPP)'
+
+@tab
+
+C++
+
+@item
+
+`Default'
+
+@tab
+
+Treated the same as C
+
+@item
+
+`External'
+
+@tab
+
+Treated the same as C
+
+@item
+
+`Fortran'
+
+@tab
+
+Fortran
+
+@item
+
+`Intrinsic'
+
+@tab
+
+For support of pragma @code{Import} with convention Intrinsic, see
+separate section on Intrinsic Subprograms.
+
+@item
+
+`Stdcall'
+
+@tab
+
+Stdcall (used for Windows implementations only). This convention correspond
+to the WINAPI (previously called Pascal convention) C/C++ convention under
+Windows. A routine with this convention cleans the stack before
+exit. This pragma cannot be applied to a dispatching call.
+
+@item
+
+`DLL'
+
+@tab
+
+Synonym for Stdcall
+
+@item
+
+`Win32'
+
+@tab
+
+Synonym for Stdcall
+
+@item
+
+`Stubbed'
+
+@tab
+
+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.
+In addition, all otherwise unrecognized convention names are also
+treated as being synonymous with convention C. In all implementations,
+use of such other names results in a warning.
+
+@end multitable
+
+
+
+@itemize *
+
+@item
+“The meaning of link names. See B.1(36).”
+@end itemize
+
+Link names are the actual names used by the linker.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+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.
+
+
+@itemize *
+
+@item
+“The effect of pragma @code{Linker_Options}. See B.1(37).”
+@end itemize
+
+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
+
+@example
+pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
+@end example
+
+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.
+
+
+@itemize *
+
+@item
+“The contents of the visible part of package
+@code{Interfaces} and its language-defined descendants. See B.2(1).”
+@end itemize
+
+See files with prefix @code{i-} in the distributed library.
+
+
+@itemize *
+
+@item
+“Implementation-defined children of package
+@code{Interfaces}. The contents of the visible part of package
+@code{Interfaces}. See B.2(11).”
+@end itemize
+
+See files with prefix @code{i-} in the distributed library.
+
+
+@itemize *
+
+@item
+“The definitions of certain types and constants in Interfaces.C.
+See B.3(41).”
+@end itemize
+
+See source file @code{i-c.ads}.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+COBOL
+
+@tab
+
+Ada
+
+@item
+
+`Floating'
+
+@tab
+
+Float
+
+@item
+
+`Long_Floating'
+
+@tab
+
+(Floating) Long_Float
+
+@item
+
+`Binary'
+
+@tab
+
+Integer
+
+@item
+
+`Long_Binary'
+
+@tab
+
+Long_Long_Integer
+
+@item
+
+`Decimal_Element'
+
+@tab
+
+Character
+
+@item
+
+`COBOL_Character'
+
+@tab
+
+Character
+
+@end multitable
+
+
+For initialization, see the file @code{i-cobol.ads} in the distributed library.
+
+
+@itemize *
+
+@item
+“The types Fortran_Integer, Real, Double_Precision, and Character_Set
+in Interfaces.Fortran. See B.5(17).”
+@end itemize
+
+See source file @code{i-fortra.ads}. These types are derived, respectively,
+from Integer, Float, Long_Float, and Character.
+
+
+@itemize *
+
+@item
+“Implementation-defined intrinsic subprograms. See C.1(1).”
+@end itemize
+
+See separate section on Intrinsic Subprograms.
+
+
+@itemize *
+
+@item
+“Any restrictions on a protected procedure or its containing type when an
+aspect Attach_handler or Interrupt_Handler is specified. See C.3.1(17).”
+@end itemize
+
+There are no such restrictions.
+
+
+@itemize *
+
+@item
+“Any other forms of interrupt handler supported by the Attach_Handler and
+Interrupt_Handler aspects. See C.3.1(19).”
+@end itemize
+
+There are no such forms.
+
+
+@itemize *
+
+@item
+“The semantics of some attributes and functions of an entity for which
+aspect Discard_Names is True. See C.5(7).”
+@end itemize
+
+If Discard_Names is True for an enumeration type, the Image attribute
+provides the image of the Pos of the literal, and Value accepts
+Pos values.
+
+If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true
+for a tagged type, its Expanded_Name and External_Tag values are
+empty strings. This is useful to avoid exposing entity names at binary
+level.
+
+
+@itemize *
+
+@item
+“The modulus and size of Test_and_Set_Flag. See C.6.3(8).”
+@end itemize
+
+The modulus is 2**8. The size is 8.
+
+
+@itemize *
+
+@item
+“The value used to represent the set value for Atomic_Test_and_Set.
+See C.6.3(10).”
+@end itemize
+
+The value is 1.
+
+
+@itemize *
+
+@item
+“The result of the @code{Task_Identification.Image}
+attribute. See C.7.1(7).”
+@end itemize
+
+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 `XXXXXXXX'
+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.
+
+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.
+
+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.
+
+
+@itemize *
+
+@item
+“The value of @code{Current_Task} when in a protected entry
+or interrupt handler. See C.7.1(17).”
+@end itemize
+
+Protected entries or interrupt handlers can be executed by any
+convenient thread, so the value of @code{Current_Task} is undefined.
+
+
+@itemize *
+
+@item
+“Granularity of locking for Task_Attributes. See C.7.2(16).”
+@end itemize
+
+No locking is needed if the formal type Attribute has the size and
+alignment of either Integer or System.Address and the bit representation
+of Initial_Value is all zeroes. Otherwise, locking is performed.
+
+
+@itemize *
+
+@item
+“The declarations of @code{Any_Priority} and
+@code{Priority}. See D.1(11).”
+@end itemize
+
+See declarations in file @code{system.ads}.
+
+
+@itemize *
+
+@item
+“Implementation-defined execution resources. See D.1(15).”
+@end itemize
+
+There are no implementation-defined execution resources.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+On a multi-processor, a task that is waiting for access to a protected
+object does not keep its processor busy.
+
+
+@itemize *
+
+@item
+“The affect of implementation defined execution resources
+on task dispatching. See D.2.1(9).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“Implementation-defined task dispatching policies. See D.2.2(3).”
+@end itemize
+
+There are no implementation-defined task dispatching policies.
+
+
+@itemize *
+
+@item
+“The value of Default_Quantum in Dispatching.Round_Robin. See D.2.5(4).”
+@end itemize
+
+The value is 10 milliseconds.
+
+
+@itemize *
+
+@item
+“Implementation-defined `policy_identifiers' allowed
+in a pragma @code{Locking_Policy}. See D.3(4).”
+@end itemize
+
+The two implementation defined policies permitted in GNAT are
+@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On
+targets that support the @code{Inheritance_Locking} 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. On targets that support the
+@code{Concurrent_Readers_Locking} policy, locking is implemented with a
+read/write lock allowing multiple protected object functions to enter
+concurrently.
+
+
+@itemize *
+
+@item
+“Default ceiling priorities. See D.3(10).”
+@end itemize
+
+The ceiling priority of protected objects of the type
+@code{System.Interrupt_Priority'Last} as described in the Ada
+Reference Manual D.3(10),
+
+
+@itemize *
+
+@item
+“The ceiling of any protected object used internally by
+the implementation. See D.3(16).”
+@end itemize
+
+The ceiling priority of internal protected objects is
+@code{System.Priority'Last}.
+
+
+@itemize *
+
+@item
+“Implementation-defined queuing policies. See D.4(1).”
+@end itemize
+
+There are no implementation-defined queuing policies.
+
+
+@itemize *
+
+@item
+“Implementation-defined admission policies. See D.4.1(1).”
+@end itemize
+
+There are no implementation-defined admission policies.
+
+
+@itemize *
+
+@item
+“Any operations that implicitly require heap storage
+allocation. See D.7(8).”
+@end itemize
+
+The only operation that implicitly requires heap storage allocation is
+task creation.
+
+
+@itemize *
+
+@item
+“When restriction No_Dynamic_CPU_Assignment applies to a partition, the
+processor on which a task with a CPU value of a Not_A_Specific_CPU will
+execute. See D.7(10).”
+@end itemize
+
+Unknown.
+
+
+@itemize *
+
+@item
+“When restriction No_Task_Termination applies to a partition, what happens
+when a task terminates. See D.7(15.1).”
+@end itemize
+
+Execution is erroneous in that case.
+
+
+@itemize *
+
+@item
+“The behavior when restriction Max_Storage_At_Blocking is violated.
+See D.7(17).”
+@end itemize
+
+Execution is erroneous in that case.
+
+
+@itemize *
+
+@item
+“The behavior when restriction Max_Asynchronous_Select_Nesting is violated.
+See D.7(18).”
+@end itemize
+
+Execution is erroneous in that case.
+
+
+@itemize *
+
+@item
+“The behavior when restriction Max_Tasks is violated. See D.7(19).”
+@end itemize
+
+Execution is erroneous in that case.
+
+
+@itemize *
+
+@item
+“Whether the use of pragma Restrictions results in a reduction in program
+code or data size or execution time. See D.7(20).”
+
+Yes it can, but the precise circumstances and properties of such reductions
+are difficult to characterize.
+
+@item
+“The value of Barrier_Limit’Last in Synchronous_Barriers. See D.10.1(4).”
+@end itemize
+
+Synchronous_Barriers.Barrier_Limit’Last is Integer’Last .
+
+
+@itemize *
+
+@item
+“When an aborted task that is waiting on a Synchronous_Barrier is aborted.
+See D.10.1(13).”
+@end itemize
+
+Difficult to characterize.
+
+
+@itemize *
+
+@item
+“The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets.
+See D.14.2(7).”
+@end itemize
+
+See source file @code{a-etgrbu.ads}.
+
+
+@itemize *
+
+@item
+“The value of CPU_Range’Last in System.Multiprocessors. See D.16(4).”
+@end itemize
+
+See source file @code{s-multip.ads}.
+
+
+@itemize *
+
+@item
+“The processor on which the environment task executes in the absence
+of a value for the aspect CPU. See D.16(13).”
+@end itemize
+
+Unknown.
+
+
+@itemize *
+
+@item
+“The means for creating and executing distributed
+programs. See E(5).”
+@end itemize
+
+The GLADE package provides a utility GNATDIST for creating and executing
+distributed programs. See the GLADE reference manual for further details.
+
+
+@itemize *
+
+@item
+“Any events that can result in a partition becoming
+inaccessible. See E.1(7).”
+@end itemize
+
+See the GLADE reference manual for full details on such events.
+
+
+@itemize *
+
+@item
+“The scheduling policies, treatment of priorities, and management of
+shared resources between partitions in certain cases. See E.1(11).”
+@end itemize
+
+See the GLADE reference manual for full details on these aspects of
+multi-partition execution.
+
+
+@itemize *
+
+@item
+“Whether the execution of the remote subprogram is
+immediately aborted as a result of cancellation. See E.4(13).”
+@end itemize
+
+See the GLADE reference manual for details on the effect of abort in
+a distributed application.
+
+
+@itemize *
+
+@item
+“The range of type System.RPC.Partition_Id. See E.5(14).”
+@end itemize
+
+System.RPC.Partition_ID’Last is Integer’Last. See source file @code{s-rpc.ads}.
+
+
+@itemize *
+
+@item
+“Implementation-defined interfaces in the PCS. See E.5(26).”
+@end itemize
+
+See the GLADE reference manual for a full description of all
+implementation defined interfaces.
+
+
+@itemize *
+
+@item
+“The values of named numbers in the package
+@code{Decimal}. See F.2(7).”
+@end itemize
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx}
+@headitem
+
+Named Number
+
+@tab
+
+Value
+
+@item
+
+`Max_Scale'
+
+@tab
+
++18
+
+@item
+
+`Min_Scale'
+
+@tab
+
+-18
+
+@item
+
+`Min_Delta'
+
+@tab
+
+1.0E-18
+
+@item
+
+`Max_Delta'
+
+@tab
+
+1.0E+18
+
+@item
+
+`Max_Decimal_Digits'
+
+@tab
+
+18
+
+@end multitable
+
+
+
+@itemize *
+
+@item
+“The value of @code{Max_Picture_Length} in the package
+@code{Text_IO.Editing}. See F.3.3(16).”
+
+64
+
+@item
+“The value of @code{Max_Picture_Length} in the package
+@code{Wide_Text_IO.Editing}. See F.3.4(5).”
+
+64
+
+@item
+“The accuracy actually achieved by the complex elementary
+functions and by other complex arithmetic operations. See G.1(1).”
+@end itemize
+
+Standard library functions are used for the complex arithmetic
+operations. Only fast math mode is currently supported.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+The signs of zero values are as recommended by the relevant
+implementation advice.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+The signs of zero values are as recommended by the relevant
+implementation advice.
+
+
+@itemize *
+
+@item
+“Whether the strict mode or the relaxed mode is the
+default. See G.2(2).”
+@end itemize
+
+The strict mode is the default. There is no separate relaxed mode. GNAT
+provides a highly efficient implementation of strict mode.
+
+
+@itemize *
+
+@item
+“The result interval in certain cases of fixed-to-float
+conversion. See G.2.1(10).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+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 `-mieee' compiler flag
+must be used for achieving IEEE conforming behavior (although at the cost
+of a significant performance penalty), so infinite and NaN values are
+properly generated.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+Not relevant, division is IEEE exact.
+
+
+@itemize *
+
+@item
+“The definition of close result set, which determines the accuracy of
+certain fixed point multiplications and divisions. See G.2.3(5).”
+@end itemize
+
+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.
+
+
+@itemize *
+
+@item
+“Conditions on a `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 itemize
+
+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.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
+types.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+IEEE infinite and Nan values are produced as appropriate.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+Information on this subject is not yet available.
+
+
+@itemize *
+
+@item
+“The accuracy of certain elementary functions for
+parameters beyond the angle threshold. See G.2.4(10).”
+@end itemize
+
+Information on this subject is not yet available.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+IEEE infinite and Nan values are produced as appropriate.
+
+
+@itemize *
+
+@item
+“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 itemize
+
+Information on those subjects is not yet available.
+
+
+@itemize *
+
+@item
+“The accuracy requirements for the subprograms Solve, Inverse,
+Determinant, Eigenvalues and Eigensystem for type Real_Matrix.
+See G.3.1(81).”
+@end itemize
+
+Information on those subjects is not yet available.
+
+
+@itemize *
+
+@item
+“The accuracy requirements for the subprograms Solve, Inverse,
+Determinant, Eigenvalues and Eigensystem for type Complex_Matrix.
+See G.3.2(149).”
+@end itemize
+
+Information on those subjects is not yet available.
+
+
+@itemize *
+
+@item
+“The consequences of violating No_Hidden_Indirect_Globals. See H.4(23.9).”
+@end itemize
+
+Execution is erroneous in that case.
+
+@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top
+@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}
+@chapter Intrinsic Subprograms
+
+
+@geindex Intrinsic Subprograms
+
+GNAT allows a user application program to write the declaration:
+
+@example
+pragma Import (Intrinsic, name);
+@end example
+
+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.
+
+@menu
+* Intrinsic Operators::
+* Compilation_ISO_Date::
+* Compilation_Date::
+* Compilation_Time::
+* Enclosing_Entity::
+* Exception_Information::
+* Exception_Message::
+* Exception_Name::
+* File::
+* Line::
+* Shifts and Rotates::
+* Source_Location::
+
+@end menu
+
+@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{260}
+@section Intrinsic Operators
+
+
+@geindex Intrinsic operator
+
+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:
+
+@example
+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 example
+
+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 Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{262}
+@section Compilation_ISO_Date
+
+
+@geindex Compilation_ISO_Date
+
+This intrinsic subprogram is used in the implementation of the
+library package @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.Compilation_ISO_Date} to obtain the date of
+the current compilation (in local time format YYYY-MM-DD).
+
+@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{264}
+@section Compilation_Date
+
+
+@geindex Compilation_Date
+
+Same as Compilation_ISO_Date, except the string is in the form
+MMM DD YYYY.
+
+@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{266}
+@section Compilation_Time
+
+
+@geindex Compilation_Time
+
+This intrinsic subprogram is used in the implementation of the
+library package @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.Compilation_Time} to obtain the time of
+the current compilation (in local time format HH:MM:SS).
+
+@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{268}
+@section Enclosing_Entity
+
+
+@geindex Enclosing_Entity
+
+This intrinsic subprogram is used in the implementation of the
+library package @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,Exception_Message,Enclosing_Entity,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{26a}
+@section Exception_Information
+
+
+@geindex Exception_Information'
+
+This intrinsic subprogram is used in the implementation of the
+library package @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,Exception_Name,Exception_Information,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26c}
+@section Exception_Message
+
+
+@geindex Exception_Message
+
+This intrinsic subprogram is used in the implementation of the
+library package @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,File,Exception_Message,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26e}
+@section Exception_Name
+
+
+@geindex Exception_Name
+
+This intrinsic subprogram is used in the implementation of the
+library package @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,Line,Exception_Name,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms file}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{270}
+@section File
+
+
+@geindex File
+
+This intrinsic subprogram is used in the implementation of the
+library package @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,Shifts and Rotates,File,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{272}
+@section Line
+
+
+@geindex Line
+
+This intrinsic subprogram is used in the implementation of the
+library package @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 Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{274}
+@section Shifts and Rotates
+
+
+@geindex Shift_Left
+
+@geindex Shift_Right
+
+@geindex Shift_Right_Arithmetic
+
+@geindex Rotate_Left
+
+@geindex Rotate_Right
+
+In standard Ada, the shift and rotate functions are available only
+for the predefined modular types in package @code{Interfaces}. However, in
+GNAT it is possible to define these functions for any integer
+type (signed or modular), as in this example:
+
+@example
+function Shift_Left
+ (Value : T;
+ Amount : Natural) return T
+with Import, Convention => Intrinsic;
+@end example
+
+The function name must be one of
+Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
+Rotate_Right. T must be an integer type. T’Size must be
+8, 16, 32 or 64 bits; if T is modular, the modulus
+must be 2**8, 2**16, 2**32 or 2**64.
+The result type must be the same as the type of @code{Value}.
+The shift amount must be Natural.
+The formal parameter names can be anything.
+
+A more convenient way of providing these shift operators is to use the
+Provide_Shift_Operators pragma, which provides the function declarations and
+corresponding pragma Import’s for all five shift functions. For signed types
+the semantics of these operators is to interpret the bitwise result of the
+corresponding operator for modular type. In particular, shifting a negative
+number may change its sign bit to positive.
+
+@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms
+@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{276}
+@section Source_Location
+
+
+@geindex Source_Location
+
+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,Standard Library Routines,Intrinsic Subprograms,Top
+@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}
+@chapter Representation Clauses and Pragmas
+
+
+@geindex Representation Clauses
+
+@geindex Representation Clause
+
+@geindex Representation Pragma
+
+@geindex Pragma
+@geindex 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.
+
+@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::
+* Handling of Records with Holes::
+* Enumeration Clauses::
+* Address Clauses::
+* Use of Address Clauses for Memory-Mapped I/O::
+* Effect of Convention on Representation::
+* Conventions and Anonymous Access Types::
+* Determining the Representations chosen by GNAT::
+
+@end menu
+
+@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{27a}
+@section Alignment Clauses
+
+
+@geindex Alignment Clause
+
+GNAT requires that all alignment clauses specify 0 or a power of 2, and
+all default alignments are always a power of 2. Specifying 0 is the
+same as specifying 1.
+
+The default alignment values are as follows:
+
+
+@itemize *
+
+@item
+`Elementary Types'.
+
+For elementary 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{18c,,Attribute Maximum_Alignment}.)
+
+@geindex 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
+`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 either 4, 2, or 1 for long packed
+arrays or arrays whose length is not known at compile time, depending on
+whether the component size is divisible by 4, 2, or is odd. For short packed
+arrays, which are handled internally as modular types, the alignment
+will be as described for elementary types, e.g. a packed array of length
+31 bits will have an object size of four bytes, and an alignment of 4.
+
+@item
+`Records'.
+
+For the normal unpacked 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 *
+
+@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
+
+In this case, an alignment is chosen to match the
+size of the record. For example, if we have:
+
+@example
+type Small is record
+ A, B : Character;
+end record;
+for Small'Size use 16;
+@end example
+
+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
+
+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
+
+@example
+type V is record
+ A : Integer;
+end record;
+
+for V'alignment use 1;
+@end example
+
+@geindex Alignment
+@geindex 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.
+
+@geindex Alignment
+@geindex subtypes
+
+Note that according to the Ada standard, an alignment clause applies only
+to the first named subtype. If additional subtypes are declared, then the
+compiler is allowed to choose any alignment it likes, and there is no way
+to control this choice. Consider:
+
+@example
+type R is range 1 .. 10_000;
+for R'Alignment use 1;
+subtype RS is R range 1 .. 1000;
+@end example
+
+The alignment clause specifies an alignment of 1 for the first named subtype
+@code{R} but this does not necessarily apply to @code{RS}. When writing
+portable Ada code, you should avoid writing code that explicitly or
+implicitly relies on the alignment of such subtypes.
+
+For the GNAT compiler, if an explicit alignment clause is given, this
+value is also used for any subsequent subtypes. So for GNAT, in the
+above example, you can count on the alignment of @code{RS} being 1. But this
+assumption is non-portable, and other compilers may choose different
+alignments for the subtype @code{RS}.
+
+@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27c}
+@section Size Clauses
+
+
+@geindex Size Clause
+
+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:
+
+@example
+type Smallint is range 1 .. 6;
+
+type Rec is record
+ Y1 : integer;
+ Y2 : boolean;
+end record;
+@end example
+
+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
+
+An explicit size clause may be used to override the default size by
+increasing it. For example, if we have:
+
+@example
+type My_Boolean is new Boolean;
+for My_Boolean'Size use 32;
+@end example
+
+then values of this type will always be 32-bit long. In the case of discrete
+types, the size can be increased up to 64 bits on 32-bit targets and 128 bits
+on 64-bit targets, 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
+or 128 bits resp. 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-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,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27e}
+@section Storage_Size Clauses
+
+
+@geindex Storage_Size Clause
+
+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:
+
+@example
+pragma Storage_Size (Default_Stack_Size);
+@end example
+
+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 `-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:
+
+@example
+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);
+
+ -- ...
+
+begin
+ -- ...
+ y := new R;
+end;
+@end example
+
+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:
+
+@example
+p.adb:16:09: warning: allocation from empty storage pool
+p.adb:16:09: warning: Storage_Error will be raised at run time
+@end example
+
+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,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{280}
+@section Size of Variant Record Objects
+
+
+@geindex Size
+@geindex variant record objects
+
+@geindex Variant record objects
+@geindex size
+
+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
+
+@example
+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 example
+
+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:
+
+@example
+8
+16
+@end example
+
+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:
+
+@example
+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 example
+
+The output from this program is
+
+@example
+16
+8
+16
+16
+@end example
+
+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,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{282}
+@section Biased Representation
+
+
+@geindex Size for biased representation
+
+@geindex Biased representation
+
+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:
+
+@example
+type Small is range -7 .. -4;
+for Small'Size use 2;
+@end example
+
+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:
+
+@example
+-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 example
+
+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,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{284}
+@section Value_Size and Object_Size Clauses
+
+
+@geindex Value_Size
+
+@geindex Object_Size
+
+@geindex Size
+@geindex of objects
+
+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:
+
+@example
+type Rec is record
+ A : Natural;
+ B : Natural;
+end record;
+
+for Rec use record
+ A at 0 range 0 .. Natural'Size - 1;
+ B at 0 range Natural'Size .. 2 * Natural'Size - 1;
+end record;
+@end example
+
+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 *
+
+@item
+The @code{Object_Size} for base subtypes reflect the natural hardware
+size in bits (run the compiler with `-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
+
+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 *
+
+@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
+
+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 illegal to convert from one access subtype to the other. For a more
+complete description of this additional legality rule, see the
+description of the @code{Object_Size} attribute.
+
+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):
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx}
+@headitem
+
+Type or subtype declaration
+
+@tab
+
+Object_Size
+
+@tab
+
+Value_Size
+
+@item
+
+@code{type x1 is range 0 .. 5;}
+
+@tab
+
+8
+
+@tab
+
+3
+
+@item
+
+@code{type x2 is range 0 .. 5;}
+@code{for x2'size use 12;}
+
+@tab
+
+16
+
+@tab
+
+12
+
+@item
+
+@code{subtype x3 is x2 range 0 .. 3;}
+
+@tab
+
+16
+
+@tab
+
+2
+
+@item
+
+@code{subtype x4 is x2'base range 0 .. 10;}
+
+@tab
+
+8
+
+@tab
+
+4
+
+@item
+
+@code{dynamic : x2'Base range -64 .. +63;}
+
+@tab
+
+@tab
+
+@item
+
+@code{subtype x5 is x2 range 0 .. dynamic;}
+
+@tab
+
+16
+
+@tab
+
+3*
+
+@item
+
+@code{subtype x6 is x2'base range 0 .. dynamic;}
+
+@tab
+
+8
+
+@tab
+
+7*
+
+@end multitable
+
+
+Note: the entries marked ‘*’ are not actually specified by the Ada
+Reference Manual, which has nothing to say about size in the dynamic
+case. What GNAT does is to allocate sufficient bits to accommodate any
+possible dynamic values for the bounds at run-time.
+
+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 *
+
+@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
+
+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:
+
+@example
+type R is record
+ X : Integer;
+ Y : Character;
+end record;
+@end example
+
+On a typical 32-bit architecture, the X component will occupy four bytes
+and the Y component will occupy one byte, for a total of 5 bytes. As a
+result @code{R'Value_Size} will be 40 (bits) since this is the minimum size
+required to store a value of this type. For example, it is permissible
+to have a component of type R in an array whose component size is
+specified to be 40 bits.
+
+However, @code{R'Object_Size} will be 64 (bits). The difference is due to
+the alignment requirement for objects of the record type. The X
+component will require four-byte alignment because that is what type
+Integer requires, whereas the Y component, a Character, will only
+require 1-byte alignment. Since the alignment required for X is the
+greatest of all the components’ alignments, that is the alignment
+required for the enclosing record type, i.e., 4 bytes or 32 bits. As
+indicated above, the actual object size must be rounded up so that it is
+a multiple of the alignment value. Therefore, 40 bits rounded up to the
+next multiple of 32 yields 64 bits.
+
+For all other types, the @code{Object_Size}
+and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}).
+Only @code{Size} may be specified for such types.
+
+Note that @code{Value_Size} can be used to force biased representation
+for a particular subtype. Consider this example:
+
+@example
+type R is (A, B, C, D, E, F);
+subtype RAB is R range A .. B;
+subtype REF is R range E .. F;
+@end example
+
+By default, @code{RAB}
+has a size of 1 (sufficient to accommodate the representation
+of @code{A} and @code{B}, 0 and 1), and @code{REF}
+has a size of 3 (sufficient to accommodate the representation
+of @code{E} and @code{F}, 4 and 5). But if we add the
+following @code{Value_Size} attribute definition clause:
+
+@example
+for REF'Value_Size use 1;
+@end example
+
+then biased representation is forced for @code{REF},
+and 0 will represent @code{E} and 1 will represent @code{F}.
+A warning is issued when a @code{Value_Size} attribute
+definition clause forces biased representation. This
+warning can be turned off using @code{-gnatw.B}.
+
+@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{286}
+@section Component_Size Clauses
+
+
+@geindex Component_Size Clause
+
+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 on 32-bit targets,
+and 1 through 127 on 64-bit targets. The value specified may not
+be smaller than the Size of the subtype. GNAT will accurately
+honor all packing requests in this range. For example, if we have:
+
+@example
+type r is array (1 .. 8) of Natural;
+for r'Component_Size use 31;
+@end example
+
+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:
+
+@example
+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 example
+
+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,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{288}
+@section Bit_Order Clauses
+
+
+@geindex Bit_Order Clause
+
+@geindex bit ordering
+
+@geindex ordering
+@geindex of bits
+
+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 *
+
+@item
+Components fitting within a single storage unit.
+
+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:
+
+@example
+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 example
+
+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.
+
+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:
+
+@example
+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 example
+
+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.
+
+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
+
+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,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{28a}
+@section Effect of Bit_Order on Byte Ordering
+
+
+@geindex byte ordering
+
+@geindex ordering
+@geindex of bytes
+
+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 13.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
+
+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
+
+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 13.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
+
+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, … V7, where V7 is the rightmost
+(least significant) bit.
+
+On a big-endian machine, we can write the following representation clause
+
+@example
+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 example
+
+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:
+
+@example
+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 example
+
+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
+
+@example
+for Data'Bit_Order use High_Order_First;
+@end example
+
+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:
+
+@example
+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 example
+
+This is exactly equivalent to saying (a repeat of the first example):
+
+@example
+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 example
+
+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:
+
+@example
+Master_Byte_First constant Boolean := ...;
+
+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 example
+
+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,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{28c}
+@section Pragma Pack for Arrays
+
+
+@geindex Pragma Pack (for arrays)
+
+Pragma @code{Pack} applied to an array has an effect that depends upon whether the
+component type is `packable'. For a component type to be `packable', it must
+be one of the following cases:
+
+
+@itemize *
+
+@item
+Any elementary type.
+
+@item
+Any small packed array type with a static size.
+
+@item
+Any small simple record type with a static size.
+@end itemize
+
+For all these cases, if the component subtype size is in the range
+1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets,
+then the effect of the pragma @code{Pack} is exactly as though a
+component size were specified giving the component subtype size.
+
+All other types are non-packable, they occupy an integral number of storage
+units and the only effect of pragma Pack is to remove alignment gaps.
+
+For example if we have:
+
+@example
+type r is range 0 .. 17;
+
+type ar is array (1 .. 8) of r;
+pragma Pack (ar);
+@end example
+
+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 at most 64 bits on 32-bit targets, and at most
+128 bits on 64-bit targets, then internally the array is represented as a
+single modular type, of exactly the appropriate number of bits. If the
+length is greater than 64 bits on 32-bit targets, and greater than 128
+bits on 64-bit targets, or is not known at compile time, then the packed
+array is represented as an array of bytes, and its 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:
+
+@example
+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 example
+
+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.
+
+@geindex Pragma Pack (for type Natural)
+
+@geindex 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:
+
+@example
+type Arr is array (1 .. 32) of Natural;
+pragma Pack (Arr);
+@end example
+
+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:
+
+@example
+type Arr is array (1 .. 32) of Natural;
+for Arr'Component_Size use 31;
+@end example
+
+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,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28e}
+@section Pragma Pack for Records
+
+
+@geindex Pragma Pack (for records)
+
+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 `packable' components and
+`non-packable' components.
+Components of the following types are considered packable:
+
+
+@itemize *
+
+@item
+Components of an elementary type are packable unless they are aliased,
+independent or atomic.
+
+@item
+Small packed arrays, where the size is statically known, are represented
+internally as modular integers, and so they are also packable.
+
+@item
+Small simple records, where the size is statically known, are also packable.
+@end itemize
+
+For all these cases, if the @code{'Size} value is in the range 1 through 64 on
+32-bit targets, and 1 through 128 on 64-bit targets, the components occupy
+the exact number of bits corresponding to this 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 the only effect of pragma @code{Pack} is to remove alignment gaps.
+
+For example, consider the record
+
+@example
+type Rb1 is array (1 .. 13) of Boolean;
+pragma Pack (Rb1);
+
+type Rb2 is array (1 .. 65) of Boolean;
+pragma Pack (Rb2);
+
+type AF is new Float with Atomic;
+
+type X2 is record
+ L1 : Boolean;
+ L2 : Duration;
+ L3 : AF;
+ L4 : Boolean;
+ L5 : Rb1;
+ L6 : Rb2;
+end record;
+pragma Pack (X2);
+@end example
+
+The representation for the record @code{X2} is as follows on 32-bit targets:
+
+@example
+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 example
+
+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 (because
+it is aliased), 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 on
+32-bit targets. 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,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{290}
+@section Record Representation Clauses
+
+
+@geindex Record Representation Clause
+
+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.
+
+@geindex Component Clause
+
+For all components of an elementary type, the only restriction on component
+clauses is that the size must be at least the @code{'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 on 32-bit targets,
+and up to and including 128 bits on 64-bit targets, 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:
+
+@example
+type R is array (1 .. 49) of Boolean;
+pragma Pack (R);
+for R'Size use 49;
+@end example
+
+then a component clause for a component of type @code{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 on 32-bit targets,
+and longer than 128 bits on 64-bit targets, there are two cases. If the
+component size is a power of 2 (1,2,4,8,16,32,64 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 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 @code{T1}, of a type @code{T}, no component
+clause applied to the type @code{T1} can specify a storage location that
+would overlap the first @code{T'Object_Size} bits 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:
+
+@example
+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 example
+
+@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{292}
+@section Handling of Records with Holes
+
+
+@geindex Handling of Records with Holes
+
+As a result of alignment considerations, records may contain “holes”
+or gaps which do not correspond to the data bits of any of the components.
+Record representation clauses can also result in holes in records.
+
+GNAT does not attempt to clear these holes, so in record objects,
+they should be considered to hold undefined rubbish. The generated
+equality routine just tests components so does not access these
+undefined bits, and assignment and copy operations may or may not
+preserve the contents of these holes (for assignments, the holes
+in the target will in practice contain either the bits that are
+present in the holes in the source, or the bits that were present
+in the target before the assignment).
+
+If it is necessary to ensure that holes in records have all zero
+bits, then record objects for which this initialization is desired
+should be explicitly set to all zero values using Unchecked_Conversion
+or address overlays. For example
+
+@example
+type HRec is record
+ C : Character;
+ I : Integer;
+end record;
+@end example
+
+On typical machines, integers need to be aligned on a four-byte
+boundary, resulting in three bytes of undefined rubbish following
+the 8-bit field for C. To ensure that the hole in a variable of
+type HRec is set to all zero bits,
+you could for example do:
+
+@example
+type Base is record
+ Dummy1, Dummy2 : Integer := 0;
+end record;
+
+BaseVar : Base;
+RealVar : Hrec;
+for RealVar'Address use BaseVar'Address;
+@end example
+
+Now the 8-bytes of the value of RealVar start out containing all zero
+bits. A safer approach is to just define dummy fields, avoiding the
+holes, as in:
+
+@example
+type HRec is record
+ C : Character;
+ Dummy1 : Short_Short_Integer := 0;
+ Dummy2 : Short_Short_Integer := 0;
+ Dummy3 : Short_Short_Integer := 0;
+ I : Integer;
+end record;
+@end example
+
+And to make absolutely sure that the intent of this is followed, you
+can use representation clauses:
+
+@example
+for Hrec use record
+ C at 0 range 0 .. 7;
+ Dummy1 at 1 range 0 .. 7;
+ Dummy2 at 2 range 0 .. 7;
+ Dummy3 at 3 range 0 .. 7;
+ I at 4 range 0 .. 31;
+end record;
+for Hrec'Size use 64;
+@end example
+
+@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{294}
+@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:
+
+@example
+System.Min_Int .. System.Max_Int
+@end example
+
+For the unsigned case, where all values are nonnegative, the values must
+be in the range:
+
+@example
+0 .. System.Max_Binary_Modulus;
+@end example
+
+A `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:
+
+@example
+type r is (A, B, C);
+for r use (A => 1, B => 5, C => 10);
+type t is array (r) of Character;
+@end example
+
+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,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{296}
+@section Address Clauses
+
+
+@geindex 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
+
+In practice this is applicable only to address clauses, since this is the
+only case in which a nonstatic expression is permitted by the syntax. As
+the AARM notes in sections 13.1 (22.a-22.h):
+
+@quotation
+
+22.a Reason: This is to avoid the following sort of thing:
+
+22.b X : Integer := F(…);
+Y : Address := G(…);
+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(…);
+X : Integer := F(…);
+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 quotation
+
+GNAT does indeed permit many additional cases of nonstatic 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 *
+
+@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.
+
+@item
+The address value is nonstatic. 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.
+
+@example
+Anchor : Some_Initialized_Type;
+Overlay : Some_Initialized_Type;
+for Overlay'Address use Anchor'Address;
+@end example
+
+However, the prefix of the address clause cannot be an array component, or
+a component of a discriminated record.
+@end itemize
+
+As noted above in section 22.h, address values are typically nonstatic. In
+particular the To_Address function, even if applied to a literal value, is
+a nonstatic function call. To avoid this minor annoyance, GNAT provides
+the implementation defined attribute ‘To_Address. The following two
+expressions have identical values:
+
+@geindex Attribute
+
+@geindex To_Address
+
+@example
+To_Address (16#1234_0000#)
+System'To_Address (16#1234_0000#);
+@end example
+
+except that the second form is considered to be a static expression, and
+thus when used as an address clause value is always permitted.
+
+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 on
+machines with strict alignment requirements, 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. It is also
+suppressed by default on non-strict alignment machines (such as the x86).
+
+In some cases, GNAT does not support an address specification (using either
+form of aspect specification syntax) for the declaration of an object that has
+an indefinite nominal subtype. An object declaration has an indefinite
+nominal subtype if it takes its bounds (for an array type), discriminant
+values (for a discriminated type whose discriminants lack defaults), or tag
+(for a class-wide type) from its initial value, as in
+
+@example
+X : String := Some_Function_Call;
+-- String has no constraint, so bounds for X come from function call
+@end example
+
+This restriction does not apply if the size of the object’s initial value is
+known at compile time and the type of the object is not class-wide.
+
+@geindex 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.
+
+@geindex 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:
+
+@example
+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 example
+
+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):
+
+@example
+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 example
+
+A final issue with address clauses involves their use for overlaying
+variables, as in the following example:
+
+@geindex Overlaying of objects
+
+@example
+A : Integer;
+B : Integer;
+for B'Address use A'Address;
+@end example
+
+or alternatively, using the form recommended by the RM:
+
+@example
+A : Integer;
+Addr : constant Address := A'Address;
+B : Integer;
+for B'Address use Addr;
+@end example
+
+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
+
+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.
+
+More generally, GNAT interprets this recommendation conservatively for
+address clauses: in the cases other than overlays, it considers that the
+object is effectively subject to pragma @code{Volatile} and implements the
+associated semantics.
+
+Note that when address clause overlays are used in this way, there is an
+issue of unintentional initialization, as shown by this example:
+
+@example
+package Overwrite_Record is
+ type R is record
+ A : Character := 'C';
+ B : Character := 'A';
+ end record;
+ X : Short_Integer := 3;
+ Y : R;
+ for Y'Address use X'Address;
+ |
+>>> warning: default initialization of "Y" may
+ modify "X", use pragma Import for "Y" to
+ suppress initialization (RM B.1(24))
+
+end Overwrite_Record;
+@end example
+
+Here the default initialization of @code{Y} will clobber the value
+of @code{X}, which justifies the warning. The warning notes that
+this effect can be eliminated by adding a @code{pragma Import}
+which suppresses the initialization:
+
+@example
+package Overwrite_Record is
+ type R is record
+ A : Character := 'C';
+ B : Character := 'A';
+ end record;
+ X : Short_Integer := 3;
+ Y : R;
+ for Y'Address use X'Address;
+ pragma Import (Ada, Y);
+end Overwrite_Record;
+@end example
+
+Note that the use of @code{pragma Initialize_Scalars} may cause variables to
+be initialized when they would not otherwise have been in the absence
+of the use of this pragma. This may cause an overlay to have this
+unintended clobbering effect. The compiler avoids this for scalar
+types, but not for composite objects (where in general the effect
+of @code{Initialize_Scalars} is part of the initialization routine
+for the composite object):
+
+@example
+pragma Initialize_Scalars;
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Overwrite_Array is
+ type Arr is array (1 .. 5) of Integer;
+ X : Arr := (others => 1);
+ A : Arr;
+ for A'Address use X'Address;
+ |
+>>> warning: default initialization of "A" may
+ modify "X", use pragma Import for "A" to
+ suppress initialization (RM B.1(24))
+
+begin
+ if X /= Arr'(others => 1) then
+ Put_Line ("X was clobbered");
+ else
+ Put_Line ("X was not clobbered");
+ end if;
+end Overwrite_Array;
+@end example
+
+The above program generates the warning as shown, and at execution
+time, prints @code{X was clobbered}. If the @code{pragma Import} is
+added as suggested:
+
+@example
+pragma Initialize_Scalars;
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Overwrite_Array is
+ type Arr is array (1 .. 5) of Integer;
+ X : Arr := (others => 1);
+ A : Arr;
+ for A'Address use X'Address;
+ pragma Import (Ada, A);
+begin
+ if X /= Arr'(others => 1) then
+ Put_Line ("X was clobbered");
+ else
+ Put_Line ("X was not clobbered");
+ end if;
+end Overwrite_Array;
+@end example
+
+then the program compiles without the warning and when run will generate
+the output @code{X was not clobbered}.
+
+@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{297}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{298}
+@section Use of Address Clauses for Memory-Mapped I/O
+
+
+@geindex Memory-mapped I/O
+
+A common pattern is to use an address clause to map an atomic variable to
+a location in memory that corresponds to a memory-mapped I/O operation or
+operations, for example:
+
+@example
+type Mem_Word is record
+ A,B,C,D : Byte;
+end record;
+pragma Atomic (Mem_Word);
+for Mem_Word_Size use 32;
+
+Mem : Mem_Word;
+for Mem'Address use some-address;
+...
+Temp := Mem;
+Temp.A := 32;
+Mem := Temp;
+@end example
+
+For a full access (reference or modification) of the variable (Mem) in this
+case, as in the above examples, GNAT guarantees that the entire atomic word
+will be accessed, in accordance with the RM C.6(15) clause.
+
+A problem arises with a component access such as:
+
+@example
+Mem.A := 32;
+@end example
+
+Note that the component A is not declared as atomic. This means that it is
+not clear what this assignment means. It could correspond to full word read
+and write as given in the first example, or on architectures that supported
+such an operation it might be a single byte store instruction. The RM does
+not have anything to say in this situation, and GNAT does not make any
+guarantee. The code generated may vary from target to target. GNAT will issue
+a warning in such a case:
+
+@example
+Mem.A := 32;
+|
+>>> warning: access to non-atomic component of atomic array,
+ may cause unexpected accesses to atomic object
+@end example
+
+It is best to be explicit in this situation, by either declaring the
+components to be atomic if you want the byte store, or explicitly writing
+the full word access sequence if that is what the hardware requires.
+Alternatively, if the full word access sequence is required, GNAT also
+provides the pragma @code{Volatile_Full_Access} which can be used in lieu of
+pragma @code{Atomic} and will give the additional guarantee.
+
+@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{29a}
+@section Effect of Convention on Representation
+
+
+@geindex Convention
+@geindex effect on representation
+
+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 *
+
+@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:
+
+@example
+type Color is (Red, Green, Blue);
+@end example
+
+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:
+
+@example
+type C_Switch is new Boolean;
+pragma Convention (C, C_Switch);
+@end example
+
+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.
+@end itemize
+
+@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29c}
+@section Conventions and Anonymous Access Types
+
+
+@geindex Anonymous access types
+
+@geindex Convention for anonymous access types
+
+The RM is not entirely clear on convention handling in a number of cases,
+and in particular, it is not clear on the convention to be given to
+anonymous access types in general, and in particular what is to be
+done for the case of anonymous access-to-subprogram.
+
+In GNAT, we decide that if an explicit Convention is applied
+to an object or component, and its type is such an anonymous type,
+then the convention will apply to this anonymous type as well. This
+seems to make sense since it is anomolous in any case to have a
+different convention for an object and its type, and there is clearly
+no way to explicitly specify a convention for an anonymous type, since
+it doesn’t have a name to specify!
+
+Furthermore, we decide that if a convention is applied to a record type,
+then this convention is inherited by any of its components that are of an
+anonymous access type which do not have an explicitly specified convention.
+
+The following program shows these conventions in action:
+
+@example
+package ConvComp is
+ type Foo is range 1 .. 10;
+ type T1 is record
+ A : access function (X : Foo) return Integer;
+ B : Integer;
+ end record;
+ pragma Convention (C, T1);
+
+ type T2 is record
+ A : access function (X : Foo) return Integer;
+ pragma Convention (C, A);
+ B : Integer;
+ end record;
+ pragma Convention (COBOL, T2);
+
+ type T3 is record
+ A : access function (X : Foo) return Integer;
+ pragma Convention (COBOL, A);
+ B : Integer;
+ end record;
+ pragma Convention (C, T3);
+
+ type T4 is record
+ A : access function (X : Foo) return Integer;
+ B : Integer;
+ end record;
+ pragma Convention (COBOL, T4);
+
+ function F (X : Foo) return Integer;
+ pragma Convention (C, F);
+
+ function F (X : Foo) return Integer is (13);
+
+ TV1 : T1 := (F'Access, 12); -- OK
+ TV2 : T2 := (F'Access, 13); -- OK
+
+ TV3 : T3 := (F'Access, 13); -- ERROR
+ |
+>>> subprogram "F" has wrong convention
+>>> does not match access to subprogram declared at line 17
+ 38. TV4 : T4 := (F'Access, 13); -- ERROR
+ |
+>>> subprogram "F" has wrong convention
+>>> does not match access to subprogram declared at line 24
+ 39. end ConvComp;
+@end example
+
+@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas
+@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{29d}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29e}
+@section Determining the Representations chosen by GNAT
+
+
+@geindex Representation
+@geindex determination of
+
+@geindex -gnatR (gcc)
+
+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 `-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:
+
+@example
+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 example
+
+using the switch `-gnatR' we obtain the following output:
+
+@example
+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 example
+
+The Size values are actually the Object_Size, i.e., the default size that
+will be allocated for objects of the type.
+The @code{??} 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 @cite{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,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top
+@anchor{gnat_rm/standard_library_routines doc}@anchor{29f}@anchor{gnat_rm/standard_library_routines id1}@anchor{2a0}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}
+@chapter Standard Library Routines
+
+
+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,
+@ref{f,,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). For further details see the relevant
+package declarations in the run-time library. In particular, a few units
+are not implemented, as marked by the presence of pragma Unimplemented_Unit,
+and in this case the package declaration contains comments explaining why
+the unit is not implemented.
+
+
+@table @asis
+
+@item @code{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 @code{Ada.Assertions} `(11.4.2)'
+
+@code{Assertions} provides the @code{Assert} subprograms, and also
+the declaration of the @code{Assertion_Error} exception.
+
+@item @code{Ada.Asynchronous_Task_Control} `(D.11)'
+
+@code{Asynchronous_Task_Control} provides low level facilities for task
+synchronization. It is typically not implemented. See package spec for details.
+
+@item @code{Ada.Calendar} `(9.6)'
+
+@code{Calendar} provides time of day access, and routines for
+manipulating times and durations.
+
+@item @code{Ada.Calendar.Arithmetic} `(9.6.1)'
+
+This package provides additional arithmetic
+operations for @code{Calendar}.
+
+@item @code{Ada.Calendar.Formatting} `(9.6.1)'
+
+This package provides formatting operations for @code{Calendar}.
+
+@item @code{Ada.Calendar.Time_Zones} `(9.6.1)'
+
+This package provides additional @code{Calendar} facilities
+for handling time zones.
+
+@item @code{Ada.Characters} `(A.3.1)'
+
+This is a dummy parent package that contains no useful entities
+
+@item @code{Ada.Characters.Conversions} `(A.3.2)'
+
+This package provides character conversion functions.
+
+@item @code{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 @code{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 @code{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 @code{Ada.Complex_Text_IO} `(G.1.3)'
+
+This package provides text input and output of complex numbers.
+
+@item @code{Ada.Containers} `(A.18.1)'
+
+A top level package providing a few basic definitions used by all the
+following specific child packages that provide specific kinds of
+containers.
+@end table
+
+@code{Ada.Containers.Bounded_Priority_Queues} `(A.18.31)'
+
+@code{Ada.Containers.Bounded_Synchronized_Queues} `(A.18.29)'
+
+@code{Ada.Containers.Doubly_Linked_Lists} `(A.18.3)'
+
+@code{Ada.Containers.Generic_Array_Sort} `(A.18.26)'
+
+@code{Ada.Containers.Generic_Constrained_Array_Sort} `(A.18.26)'
+
+@code{Ada.Containers.Generic_Sort} `(A.18.26)'
+
+@code{Ada.Containers.Hashed_Maps} `(A.18.5)'
+
+@code{Ada.Containers.Hashed_Sets} `(A.18.8)'
+
+@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} `(A.18.12)'
+
+@code{Ada.Containers.Indefinite_Hashed_Maps} `(A.18.13)'
+
+@code{Ada.Containers.Indefinite_Hashed_Sets} `(A.18.15)'
+
+@code{Ada.Containers.Indefinite_Holders} `(A.18.18)'
+
+@code{Ada.Containers.Indefinite_Multiway_Trees} `(A.18.17)'
+
+@code{Ada.Containers.Indefinite_Ordered_Maps} `(A.18.14)'
+
+@code{Ada.Containers.Indefinite_Ordered_Sets} `(A.18.16)'
+
+@code{Ada.Containers.Indefinite_Vectors} `(A.18.11)'
+
+@code{Ada.Containers.Multiway_Trees} `(A.18.10)'
+
+@code{Ada.Containers.Ordered_Maps} `(A.18.6)'
+
+@code{Ada.Containers.Ordered_Sets} `(A.18.9)'
+
+@code{Ada.Containers.Synchronized_Queue_Interfaces} `(A.18.27)'
+
+@code{Ada.Containers.Unbounded_Priority_Queues} `(A.18.30)'
+
+@code{Ada.Containers.Unbounded_Synchronized_Queues} `(A.18.28)'
+
+@code{Ada.Containers.Vectors} `(A.18.2)'
+
+
+@table @asis
+
+@item @code{Ada.Directories} `(A.16)'
+
+This package provides operations on directories.
+
+@item @code{Ada.Directories.Hierarchical_File_Names} `(A.16.1)'
+
+This package provides additional directory operations handling
+hierarchical file names.
+
+@item @code{Ada.Directories.Information} `(A.16)'
+
+This is an implementation defined package for additional directory
+operations, which is not implemented in GNAT.
+
+@item @code{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 … GIVING … REMAINDER …)
+
+@item @code{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 @code{Ada.Dispatching} `(D.2.1)'
+
+A parent package containing definitions for task dispatching operations.
+
+@item @code{Ada.Dispatching.EDF} `(D.2.6)'
+
+Not implemented in GNAT.
+
+@item @code{Ada.Dispatching.Non_Preemptive} `(D.2.4)'
+
+Not implemented in GNAT.
+
+@item @code{Ada.Dispatching.Round_Robin} `(D.2.5)'
+
+Not implemented in GNAT.
+
+@item @code{Ada.Dynamic_Priorities} `(D.5)'
+
+This package allows the priorities of a task to be adjusted dynamically
+as the task is running.
+
+@item @code{Ada.Environment_Variables} `(A.17)'
+
+This package provides facilities for accessing environment variables.
+
+@item @code{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 @code{Ada.Execution_Time} `(D.14)'
+
+This package provides CPU clock functionalities. It is not implemented on
+all targets (see package spec for details).
+
+@item @code{Ada.Execution_Time.Group_Budgets} `(D.14.2)'
+
+Not implemented in GNAT.
+
+@item @code{Ada.Execution_Time.Timers} `(D.14.1)’'
+
+Not implemented in GNAT.
+
+@item @code{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 @code{Ada.Float_Text_IO} `(A.10.9)'
+
+A library level instantiation of Text_IO.Float_IO for type Float.
+
+@item @code{Ada.Float_Wide_Text_IO} `(A.10.9)'
+
+A library level instantiation of Wide_Text_IO.Float_IO for type Float.
+
+@item @code{Ada.Float_Wide_Wide_Text_IO} `(A.10.9)'
+
+A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float.
+
+@item @code{Ada.Integer_Text_IO} `(A.10.9)'
+
+A library level instantiation of Text_IO.Integer_IO for type Integer.
+
+@item @code{Ada.Integer_Wide_Text_IO} `(A.10.9)'
+
+A library level instantiation of Wide_Text_IO.Integer_IO for type Integer.
+
+@item @code{Ada.Integer_Wide_Wide_Text_IO} `(A.10.9)'
+
+A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer.
+
+@item @code{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 @code{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 @code{Ada.IO_Exceptions} `(A.13)'
+
+This package defines the set of exceptions that can be raised by use of
+the standard IO packages.
+
+@item @code{Ada.Iterator_Interfaces} `(5.5.1)'
+
+This package provides a generic interface to generalized iterators.
+
+@item @code{Ada.Locales} `(A.19)'
+
+This package provides declarations providing information (Language
+and Country) about the current locale.
+
+@item @code{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 @code{Ada.Numerics.Complex_Arrays} `(G.3.2)'
+
+Provides operations on arrays of complex numbers.
+
+@item @code{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 @code{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 @code{Ada.Numerics.Discrete_Random}
+
+This generic package provides a random number generator suitable for generating
+uniformly distributed values of a specified discrete subtype.
+
+@item @code{Ada.Numerics.Float_Random}
+
+This package provides a random number generator suitable for generating
+uniformly distributed floating point values in the unit interval.
+
+@item @code{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:
+
+
+@itemize *
+
+@item
+@code{Short_Float}
+
+@code{Ada.Numerics.Short_Complex_Elementary_Functions}
+
+@item
+@code{Float}
+
+@code{Ada.Numerics.Complex_Elementary_Functions}
+
+@item
+@code{Long_Float}
+
+@code{Ada.Numerics.Long_Complex_Elementary_Functions}
+@end itemize
+
+@item @code{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
+
+
+@itemize *
+
+@item
+@code{Short_Float}
+
+@code{Ada.Numerics.Short_Complex_Complex_Types}
+
+@item
+@code{Float}
+
+@code{Ada.Numerics.Complex_Complex_Types}
+
+@item
+@code{Long_Float}
+
+@code{Ada.Numerics.Long_Complex_Complex_Types}
+@end itemize
+
+@item @code{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
+
+
+@itemize *
+
+@item
+@code{Short_Float}
+
+@code{Ada.Numerics.Short_Elementary_Functions}
+
+@item
+@code{Float}
+
+@code{Ada.Numerics.Elementary_Functions}
+
+@item
+@code{Long_Float}
+
+@code{Ada.Numerics.Long_Elementary_Functions}
+@end itemize
+
+@item @code{Ada.Numerics.Generic_Real_Arrays} `(G.3.1)'
+
+Generic operations on arrays of reals
+
+@item @code{Ada.Numerics.Real_Arrays} `(G.3.1)'
+
+Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float).
+
+@item @code{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 @code{Ada.Real_Time.Timing_Events} `(D.15)'
+
+Not implemented in GNAT.
+
+@item @code{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 @code{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 @code{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 @code{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 @code{Ada.Strings} `(A.4.1)'
+
+This package provides some basic constants used by the string handling
+packages.
+
+@item @code{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 @code{Ada.Strings.Bounded.Equal_Case_Insensitive} `(A.4.10)'
+
+Provides case-insensitive comparisons of bounded strings
+
+@item @code{Ada.Strings.Bounded.Hash} `(A.4.9)'
+
+This package provides a generic hash function for bounded strings
+
+@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} `(A.4.9)'
+
+This package provides a generic hash function for bounded strings that
+converts the string to be hashed to lower case.
+
+@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} `(A.4.10)'
+
+This package provides a comparison function for bounded strings that works
+in a case insensitive manner by converting to lower case before the comparison.
+
+@item @code{Ada.Strings.Fixed} `(A.4.3)'
+
+This package provides facilities for handling fixed length strings.
+
+@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} `(A.4.10)'
+
+This package provides an equality function for fixed strings that compares
+the strings after converting both to lower case.
+
+@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} `(A.4.9)'
+
+This package provides a case insensitive hash function for fixed strings that
+converts the string to lower case before computing the hash.
+
+@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} `(A.4.10)'
+
+This package provides a comparison function for fixed strings that works
+in a case insensitive manner by converting to lower case before the comparison.
+
+@item @code{Ada.Strings.Hash} `(A.4.9)'
+
+This package provides a hash function for strings.
+
+@item @code{Ada.Strings.Hash_Case_Insensitive} `(A.4.9)'
+
+This package provides a hash function for strings that is case insensitive.
+The string is converted to lower case before computing the hash.
+
+@item @code{Ada.Strings.Less_Case_Insensitive} `(A.4.10)'
+
+This package provides a comparison function for\strings that works
+in a case insensitive manner by converting to lower case before the comparison.
+
+@item @code{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 @code{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 @code{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 @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} `(A.4.10)'
+
+Provides case-insensitive comparisons of unbounded strings
+
+@item @code{Ada.Strings.Unbounded.Hash} `(A.4.9)'
+
+This package provides a generic hash function for unbounded strings
+
+@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} `(A.4.9)'
+
+This package provides a generic hash function for unbounded strings that
+converts the string to be hashed to lower case.
+
+@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} `(A.4.10)'
+
+This package provides a comparison function for unbounded strings that works
+in a case insensitive manner by converting to lower case before the comparison.
+
+@item @code{Ada.Strings.UTF_Encoding} `(A.4.11)'
+
+This package provides basic definitions for dealing with UTF-encoded strings.
+
+@item @code{Ada.Strings.UTF_Encoding.Conversions} `(A.4.11)'
+
+This package provides conversion functions for UTF-encoded strings.
+@end table
+
+@code{Ada.Strings.UTF_Encoding.Strings} `(A.4.11)'
+
+@code{Ada.Strings.UTF_Encoding.Wide_Strings} `(A.4.11)'
+
+
+@table @asis
+
+@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} `(A.4.11)'
+
+These packages provide facilities for handling UTF encodings for
+Strings, Wide_Strings and Wide_Wide_Strings.
+@end table
+
+@code{Ada.Strings.Wide_Bounded} `(A.4.7)'
+
+@code{Ada.Strings.Wide_Fixed} `(A.4.7)'
+
+@code{Ada.Strings.Wide_Maps} `(A.4.7)'
+
+
+@table @asis
+
+@item @code{Ada.Strings.Wide_Unbounded} `(A.4.7)'
+
+These packages provide analogous capabilities to the corresponding
+packages without @code{Wide_} in the name, but operate with the types
+@code{Wide_String} and @code{Wide_Character} instead of @code{String}
+and @code{Character}. Versions of all the child packages are available.
+@end table
+
+@code{Ada.Strings.Wide_Wide_Bounded} `(A.4.7)'
+
+@code{Ada.Strings.Wide_Wide_Fixed} `(A.4.7)'
+
+@code{Ada.Strings.Wide_Wide_Maps} `(A.4.7)'
+
+
+@table @asis
+
+@item @code{Ada.Strings.Wide_Wide_Unbounded} `(A.4.7)'
+
+These packages provide analogous capabilities to the corresponding
+packages without @code{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 @code{Ada.Synchronous_Barriers} `(D.10.1)'
+
+This package provides facilities for synchronizing tasks at a low level
+with barriers.
+
+@item @code{Ada.Synchronous_Task_Control} `(D.10)'
+
+This package provides some standard facilities for controlling task
+communication in a synchronous manner.
+
+@item @code{Ada.Synchronous_Task_Control.EDF} `(D.10)'
+
+Not implemented in GNAT.
+
+@item @code{Ada.Tags}
+
+This package contains definitions for manipulation of the tags of tagged
+values.
+
+@item @code{Ada.Tags.Generic_Dispatching_Constructor} `(3.9)'
+
+This package provides a way of constructing tagged class-wide values given
+only the tag value.
+
+@item @code{Ada.Task_Attributes} `(C.7.2)'
+
+This package provides the capability of associating arbitrary
+task-specific data with separate tasks.
+
+@item @code{Ada.Task_Identification} `(C.7.1)'
+
+This package provides capabilities for task identification.
+
+@item @code{Ada.Task_Termination} `(C.7.3)'
+
+This package provides control over task termination.
+
+@item @code{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. Note that although these are defined
+as subpackages in the RM, they are actually transparently
+implemented as child packages in GNAT, meaning that they
+are only loaded if needed.
+
+@item @code{Ada.Text_IO.Decimal_IO}
+
+Provides input-output facilities for decimal fixed-point types
+
+@item @code{Ada.Text_IO.Enumeration_IO}
+
+Provides input-output facilities for enumeration types.
+
+@item @code{Ada.Text_IO.Fixed_IO}
+
+Provides input-output facilities for ordinary fixed-point types.
+
+@item @code{Ada.Text_IO.Float_IO}
+
+Provides input-output facilities for float types. The following
+predefined instantiations of this generic package are available:
+
+
+@itemize *
+
+@item
+@code{Short_Float}
+
+@code{Short_Float_Text_IO}
+
+@item
+@code{Float}
+
+@code{Float_Text_IO}
+
+@item
+@code{Long_Float}
+
+@code{Long_Float_Text_IO}
+@end itemize
+
+@item @code{Ada.Text_IO.Integer_IO}
+
+Provides input-output facilities for integer types. The following
+predefined instantiations of this generic package are available:
+
+
+@itemize *
+
+@item
+@code{Short_Short_Integer}
+
+@code{Ada.Short_Short_Integer_Text_IO}
+
+@item
+@code{Short_Integer}
+
+@code{Ada.Short_Integer_Text_IO}
+
+@item
+@code{Integer}
+
+@code{Ada.Integer_Text_IO}
+
+@item
+@code{Long_Integer}
+
+@code{Ada.Long_Integer_Text_IO}
+
+@item
+@code{Long_Long_Integer}
+
+@code{Ada.Long_Long_Integer_Text_IO}
+@end itemize
+
+@item @code{Ada.Text_IO.Modular_IO}
+
+Provides input-output facilities for modular (unsigned) types.
+
+@item @code{Ada.Text_IO.Bounded_IO (A.10.11)}
+
+Provides input-output facilities for bounded strings.
+
+@item @code{Ada.Text_IO.Complex_IO (G.1.3)}
+
+This package provides basic text input-output capabilities for complex
+data.
+
+@item @code{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 @code{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 @code{Ada.Text_IO.Unbounded_IO (A.10.12)}
+
+This package provides input-output facilities for unbounded strings.
+
+@item @code{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 @code{Ada.Unchecked_Deallocation} `(13.11.2)'
+
+This generic package allows explicit freeing of storage previously
+allocated by use of an allocator.
+
+@item @code{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}. The corresponding set of nested packages and child
+packages are defined.
+
+@item @code{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}. The corresponding set of nested packages and child
+packages are defined.
+@end table
+
+For packages in Interfaces and System, all the RM defined packages are
+available in GNAT, see the Ada 2012 RM for full details.
+
+@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top
+@anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f}
+@chapter The Implementation of Standard I/O
+
+
+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::
+* Text Translation::
+* Shared Files::
+* Filenames encoding::
+* File content encoding::
+* Open Modes::
+* Operations on C Streams::
+* Interfacing to C Streams::
+
+@end menu
+
+@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a4}
+@section Standard I/O Packages
+
+
+The Standard I/O packages described in Annex A for
+
+
+@itemize *
+
+@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
+
+are implemented using the C
+library streams facility; where
+
+
+@itemize *
+
+@item
+All files are opened using @code{fopen}.
+
+@item
+All input/output operations use @code{fread}/@cite{fwrite}.
+@end itemize
+
+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,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a6}
+@section FORM Strings
+
+
+The format of a FORM string in GNAT is:
+
+@example
+"keyword=value,keyword=value,...,keyword=value"
+@end example
+
+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
+the following keywords defined.
+
+@example
+TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT]
+SHARED=[YES|NO]
+WCEM=[n|h|u|s|e|8|b]
+ENCODING=[UTF8|8BITS]
+@end example
+
+The use of these parameters is described later in this section. If an
+unrecognized keyword appears in a form string, it is silently ignored
+and not considered invalid.
+
+@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a8}
+@section Direct_IO
+
+
+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{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 @code{K} starts at offset
+(@code{K}-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,Text_IO,Direct_IO,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2aa}
+@section Sequential_IO
+
+
+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}:
+
+@example
+package IO is new Sequential_IO (String);
+F : IO.File_Type;
+S : String (1..4);
+...
+IO.Create (F)
+IO.Write (F, "hello!")
+IO.Reset (F, Mode=>In_File);
+IO.Read (F, S);
+Put_Line (S);
+@end example
+
+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,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2ac}
+@section Text_IO
+
+
+Text_IO files consist of a stream of characters containing the following
+special control characters:
+
+@example
+LF (line feed, 16#0A#) Line Mark
+FF (form feed, 16#0C#) Page Mark
+@end example
+
+A canonical Text_IO file is defined as one in which the following
+conditions are met:
+
+
+@itemize *
+
+@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}-@cite{FF}
+(line mark, page mark). In the former case, the page mark is implicitly
+assumed to be present.
+@end itemize
+
+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 *
+
+@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
+
+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
+* Stream Pointer Positioning::
+* 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 Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ae}
+@subsection Stream Pointer Positioning
+
+
+@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 *
+
+@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
+
+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 @code{shared=yes} in the form string)
+between two Ada files, then the difference may be observable in some
+situations.
+
+@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2b0}
+@subsection Reading and Writing Non-Regular Files
+
+
+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 *
+
+@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
+
+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 @code{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,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b2}
+@subsection Get_Immediate
+
+
+@geindex Get_Immediate
+
+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,Text_IO Extensions,Get_Immediate,Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b4}
+@subsection Treating Text_IO Files as Streams
+
+
+@geindex Stream files
+
+The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated
+as a stream. Data written to a @code{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,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b6}
+@subsection Text_IO Extensions
+
+
+@geindex Text_IO extensions
+
+A package GNAT.IO_Aux in the GNAT library provides some useful extensions
+to the standard @code{Text_IO} package:
+
+
+@itemize *
+
+@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,,Text_IO Extensions,Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b8}
+@subsection Text_IO Facilities for Unbounded Strings
+
+
+@geindex Text_IO for unbounded strings
+
+@geindex Unbounded_String
+@geindex Text_IO operations
+
+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 *
+
+@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
+
+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 @code{a-swuwti.ads} and @code{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 @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended
+@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
+
+@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2ba}
+@section Wide_Text_IO
+
+
+@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:
+
+@example
+WCEM=`x`
+@end example
+
+as part of the FORM string (WCEM = wide character encoding method),
+where @code{x} is one of the following characters
+
+
+@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+Character
+
+@tab
+
+Encoding
+
+@item
+
+`h'
+
+@tab
+
+Hex ESC encoding
+
+@item
+
+`u'
+
+@tab
+
+Upper half encoding
+
+@item
+
+`s'
+
+@tab
+
+Shift-JIS encoding
+
+@item
+
+`e'
+
+@tab
+
+EUC Encoding
+
+@item
+
+`8'
+
+@tab
+
+UTF-8 encoding
+
+@item
+
+`b'
+
+@tab
+
+Brackets encoding
+
+@end multitable
+
+
+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:
+@end table
+
+@example
+ESC a b c d
+@end example
+
+
+@quotation
+
+where @code{a}, @code{b}, @code{c}, @code{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.
+@end quotation
+
+
+@table @asis
+
+@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:
+@end table
+
+@example
+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 example
+
+
+@quotation
+
+where the @code{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.)
+@end quotation
+
+
+@table @asis
+
+@item `Brackets Coding'
+
+In this encoding, a wide character is represented by the following eight
+character sequence:
+@end table
+
+@example
+[ " a b c d " ]
+@end example
+
+
+@quotation
+
+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:
+
+@example
+Put_Line ("Start of output [first run]");
+@end example
+
+we really do not want to have the left bracket in this message clobbered so
+that the output reads:
+@end quotation
+
+@example
+Start of output ["5B"]first run]
+@end example
+
+
+@quotation
+
+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 quotation
+
+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
+* Stream Pointer Positioning: Stream Pointer Positioning<2>.
+* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>.
+
+@end menu
+
+@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2bc}
+@subsection Stream Pointer Positioning
+
+
+@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
+of stream pointer positioning (@ref{2ac,,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:
+
+@example
+Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
+@end example
+
+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 Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2be}
+@subsection Reading and Writing Non-Regular Files
+
+
+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,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2c0}
+@section Wide_Wide_Text_IO
+
+
+@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:
+
+@example
+WCEM=`x`
+@end example
+
+as part of the FORM string (WCEM = wide character encoding method),
+where @code{x} is one of the following characters
+
+
+@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+Character
+
+@tab
+
+Encoding
+
+@item
+
+`h'
+
+@tab
+
+Hex ESC encoding
+
+@item
+
+`u'
+
+@tab
+
+Upper half encoding
+
+@item
+
+`s'
+
+@tab
+
+Shift-JIS encoding
+
+@item
+
+`e'
+
+@tab
+
+EUC Encoding
+
+@item
+
+`8'
+
+@tab
+
+UTF-8 encoding
+
+@item
+
+`b'
+
+@tab
+
+Brackets encoding
+
+@end multitable
+
+
+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:
+@end table
+
+@example
+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 example
+
+
+@quotation
+
+where the @code{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.
+@end quotation
+
+
+@table @asis
+
+@item `Brackets Coding'
+
+In this encoding, a wide wide character is represented by the following eight
+character sequence if is in wide character range
+@end table
+
+@example
+[ " a b c d " ]
+@end example
+
+
+@quotation
+
+and by the following ten character sequence if not
+@end quotation
+
+@example
+[ " a b c d e f " ]
+@end example
+
+
+@quotation
+
+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 quotation
+
+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
+* Stream Pointer Positioning: Stream Pointer Positioning<3>.
+* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>.
+
+@end menu
+
+@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2c2}
+@subsection Stream Pointer Positioning
+
+
+@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
+of stream pointer positioning (@ref{2ac,,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:
+
+@example
+Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
+@end example
+
+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 Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO
+@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c4}
+@subsection Reading and Writing Non-Regular Files
+
+
+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,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c6}
+@section Stream_IO
+
+
+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 *
+
+@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 Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c8}
+@section Text Translation
+
+
+@code{Text_Translation=xxx} may be used as the Form parameter
+passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx}
+has no effect on Unix systems. Possible values are:
+
+
+@itemize *
+
+@item
+@code{Yes} or @code{Text} is the default, which means to
+translate LF to/from CR/LF on Windows systems.
+
+@code{No} disables this translation; i.e. it
+uses binary mode. For output files, @code{Text_Translation=No}
+may be used to create Unix-style files on
+Windows.
+
+@item
+@code{wtext} translation enabled in Unicode mode.
+(corresponds to _O_WTEXT).
+
+@item
+@code{u8text} translation enabled in Unicode UTF-8 mode.
+(corresponds to O_U8TEXT).
+
+@item
+@code{u16text} translation enabled in Unicode UTF-16
+mode. (corresponds to_O_U16TEXT).
+@end itemize
+
+@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2ca}
+@section Shared Files
+
+
+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 *
+
+@item
+In the absence of a @code{shared=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 @code{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 @code{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
+
+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 @code{shared=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 @code{shared=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 @code{shared=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
+@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO
+for this purpose (using the stream attributes)
+
+@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2cc}
+@section Filenames encoding
+
+
+An encoding form parameter can be used to specify the filename
+encoding @code{encoding=xxx}.
+
+
+@itemize *
+
+@item
+If the form parameter @code{encoding=utf8} appears in the form string, the
+filename must be encoded in UTF-8.
+
+@item
+If the form parameter @code{encoding=8bits} appears in the form
+string, the filename must be a standard 8bits string.
+@end itemize
+
+In the absence of a @code{encoding=xxx} form parameter, the
+encoding is controlled by the @code{GNAT_CODE_PAGE} environment
+variable. And if not set @code{utf8} is assumed.
+
+
+@table @asis
+
+@item `CP_ACP'
+
+The current system Windows ANSI code page.
+
+@item `CP_UTF8'
+
+UTF-8 encoding
+@end table
+
+This encoding form parameter is only supported on the Windows
+platform. On the other Operating Systems the run-time is supporting
+UTF-8 natively.
+
+@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2ce}
+@section File content encoding
+
+
+For text files it is possible to specify the encoding to use. This is
+controlled by the by the @code{GNAT_CCS_ENCODING} environment
+variable. And if not set @code{TEXT} is assumed.
+
+The possible values are those supported on Windows:
+
+
+@table @asis
+
+@item `TEXT'
+
+Translated text mode
+
+@item `WTEXT'
+
+Translated unicode encoding
+
+@item `U16TEXT'
+
+Unicode 16-bit encoding
+
+@item `U8TEXT'
+
+Unicode 8-bit encoding
+@end table
+
+This encoding is only supported on the Windows platform.
+
+@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2d0}
+@section Open Modes
+
+
+@code{Open} and @code{Create} calls result in a call to @code{fopen}
+using the mode shown in the following table:
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+@code{Open} and @code{Create} Call Modes
+
+@tab
+
+@tab
+
+@item
+
+@tab
+
+`OPEN'
+
+@tab
+
+`CREATE'
+
+@item
+
+Append_File
+
+@tab
+
+“r+”
+
+@tab
+
+“w+”
+
+@item
+
+In_File
+
+@tab
+
+“r”
+
+@tab
+
+“w+”
+
+@item
+
+Out_File (Direct_IO)
+
+@tab
+
+“r+”
+
+@tab
+
+“w”
+
+@item
+
+Out_File (all other cases)
+
+@tab
+
+“w”
+
+@tab
+
+“w”
+
+@item
+
+Inout_File
+
+@tab
+
+“r+”
+
+@tab
+
+“w+”
+
+@end multitable
+
+
+If text file translation is required, then either @code{b} or @code{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 @code{r} or @code{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 @code{r+} mode to permit the required operation.
+
+@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2d2}
+@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:
+
+@example
+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 UNIX (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 example
+
+@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O
+@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d3}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d4}
+@section Interfacing to C Streams
+
+
+The packages in this section permit interfacing Ada files to C Stream
+operations.
+
+@example
+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 example
+
+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,Interfacing to Other Languages,The Implementation of Standard I/O,Top
+@anchor{gnat_rm/the_gnat_library doc}@anchor{2d5}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d6}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}
+@chapter The GNAT Library
+
+
+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 @code{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} clause 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 Latin_9 a-chlat9 ads.
+* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads.
+* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads.
+* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads.
+* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads.
+* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
+* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
+* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
+* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads.
+* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads.
+* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads.
+* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads.
+* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads.
+* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads.
+* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads.
+* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads.
+* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads.
+* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads.
+* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads.
+* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads.
+* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads.
+* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads.
+* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads.
+* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads.
+* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads.
+* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads.
+* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads.
+* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads.
+* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads.
+* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads.
+* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads.
+* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads.
+* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads.
+* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads.
+* GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads.
+* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads.
+* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads.
+* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads.
+* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads.
+* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads.
+* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads.
+* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads.
+* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads.
+* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads.
+* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads.
+* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads.
+* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads.
+* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads.
+* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads.
+* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads.
+* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads.
+* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads.
+* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads.
+* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads.
+* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads.
+* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads.
+* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads.
+* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads.
+* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads.
+* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads.
+* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads.
+* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads.
+* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads.
+* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads.
+* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads.
+* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads.
+* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads.
+* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads.
+* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads.
+* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads.
+* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads.
+* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads.
+* GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads.
+* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads.
+* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads.
+* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads.
+* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads.
+* GNAT.IO (g-io.ads): GNAT IO g-io ads.
+* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads.
+* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads.
+* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads.
+* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads.
+* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads.
+* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads.
+* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads.
+* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads.
+* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads.
+* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads.
+* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads.
+* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads.
+* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads.
+* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads.
+* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads.
+* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads.
+* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads.
+* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads.
+* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads.
+* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads.
+* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads.
+* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads.
+* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads.
+* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads.
+* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads.
+* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads.
+* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads.
+* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads.
+* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads.
+* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads.
+* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads.
+* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads.
+* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads.
+* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads.
+* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads.
+* GNAT.Strings (g-string.ads): GNAT Strings g-string ads.
+* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads.
+* GNAT.Table (g-table.ads): GNAT Table g-table ads.
+* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads.
+* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads.
+* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads.
+* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads.
+* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads.
+* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads.
+* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads.
+* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads.
+* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads.
+* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads.
+* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads.
+* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads.
+* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads.
+* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads.
+* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads.
+* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads.
+* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads.
+* System.Address_Image (s-addima.ads): System Address_Image s-addima ads.
+* System.Assertions (s-assert.ads): System Assertions s-assert ads.
+* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads.
+* System.Memory (s-memory.ads): System Memory s-memory ads.
+* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads.
+* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads.
+* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads.
+* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads.
+* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads.
+* System.Restrictions (s-restri.ads): System Restrictions s-restri ads.
+* System.Rident (s-rident.ads): System Rident s-rident ads.
+* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads.
+* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads.
+* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads.
+* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads.
+
+@end menu
+
+@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id2}@anchor{2d8}
+@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads})
+
+
+@geindex Ada.Characters.Latin_9 (a-chlat9.ads)
+
+@geindex Latin_9 constants for Character
+
+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,Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Latin_9 a-chlat9 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d9}@anchor{gnat_rm/the_gnat_library id3}@anchor{2da}
+@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads})
+
+
+@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
+
+@geindex Latin_1 constants for Wide_Character
+
+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-cwila1 ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id4}@anchor{2dc}
+@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads})
+
+
+@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads)
+
+@geindex Latin_9 constants for Wide_Character
+
+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,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2dd}@anchor{gnat_rm/the_gnat_library id5}@anchor{2de}
+@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads})
+
+
+@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
+
+@geindex Latin_1 constants for Wide_Wide_Character
+
+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,Ada Containers Bounded_Holders a-coboho ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2df}@anchor{gnat_rm/the_gnat_library id6}@anchor{2e0}
+@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads})
+
+
+@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
+
+@geindex Latin_9 constants for Wide_Wide_Character
+
+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 Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2e1}@anchor{gnat_rm/the_gnat_library id7}@anchor{2e2}
+@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads})
+
+
+@geindex Ada.Containers.Bounded_Holders (a-coboho.ads)
+
+@geindex Formal container for vectors
+
+This child of @code{Ada.Containers} defines a modified version of
+Indefinite_Holders that avoids heap allocation.
+
+@node Ada Command_Line Environment a-colien ads,Ada Command_Line Remove a-colire ads,Ada Containers Bounded_Holders a-coboho ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id8}@anchor{2e4}
+@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads})
+
+
+@geindex Ada.Command_Line.Environment (a-colien.ads)
+
+@geindex Environment entries
+
+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,Ada Command_Line Response_File a-clrefi ads,Ada Command_Line Environment a-colien ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id9}@anchor{2e6}
+@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads})
+
+
+@geindex Ada.Command_Line.Remove (a-colire.ads)
+
+@geindex Removing command line arguments
+
+@geindex Command line
+@geindex argument removal
+
+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,Ada Direct_IO C_Streams a-diocst ads,Ada Command_Line Remove a-colire ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id10}@anchor{2e8}
+@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads})
+
+
+@geindex Ada.Command_Line.Response_File (a-clrefi.ads)
+
+@geindex Response file for command line
+
+@geindex Command line
+@geindex response file
+
+@geindex Command line
+@geindex handling long command lines
+
+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,Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Command_Line Response_File a-clrefi ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id11}@anchor{2ea}
+@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads})
+
+
+@geindex Ada.Direct_IO.C_Streams (a-diocst.ads)
+
+@geindex C Streams
+@geindex Interfacing with Direct_IO
+
+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,Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Direct_IO C_Streams a-diocst ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id12}@anchor{2ec}
+@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads})
+
+
+@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
+
+@geindex Null_Occurrence
+@geindex testing for
+
+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,Ada Exceptions Traceback a-exctra ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id13}@anchor{2ee}
+@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads})
+
+
+@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
+
+@geindex Null_Occurrence
+@geindex testing for
+
+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,Ada Sequential_IO C_Streams a-siocst ads,Ada Exceptions Last_Chance_Handler a-elchha ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f0}
+@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads})
+
+
+@geindex Ada.Exceptions.Traceback (a-exctra.ads)
+
+@geindex Traceback for Exception Occurrence
+
+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,Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Exceptions Traceback a-exctra ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f2}
+@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads})
+
+
+@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads)
+
+@geindex C Streams
+@geindex Interfacing with Sequential_IO
+
+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,Ada Strings Unbounded Text_IO a-suteio ads,Ada Sequential_IO C_Streams a-siocst ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id16}@anchor{2f4}
+@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads})
+
+
+@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
+
+@geindex C Streams
+@geindex Interfacing with Stream_IO
+
+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,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Streams Stream_IO C_Streams a-ssicst ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f6}
+@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads})
+
+
+@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
+
+@geindex Unbounded_String
+@geindex IO support
+
+@geindex Text_IO
+@geindex extensions for unbounded strings
+
+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,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Strings Unbounded Text_IO a-suteio ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f8}
+@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads})
+
+
+@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
+
+@geindex Unbounded_Wide_String
+@geindex IO support
+
+@geindex Text_IO
+@geindex extensions for unbounded wide strings
+
+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,Ada Task_Initialization a-tasini ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id19}@anchor{2fa}
+@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads})
+
+
+@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
+
+@geindex Unbounded_Wide_Wide_String
+@geindex IO support
+
+@geindex Text_IO
+@geindex extensions for unbounded wide wide strings
+
+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 Task_Initialization a-tasini ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id20}@anchor{2fc}
+@section @code{Ada.Task_Initialization} (@code{a-tasini.ads})
+
+
+@geindex Ada.Task_Initialization (a-tasini.ads)
+
+This package provides a way to set a global initialization handler that
+is automatically invoked whenever a task is activated. Handlers are
+parameterless procedures. Note that such a handler is only invoked for
+those tasks activated after the handler is set.
+
+@node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Task_Initialization a-tasini ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id21}@anchor{2fe}
+@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads})
+
+
+@geindex Ada.Text_IO.C_Streams (a-tiocst.ads)
+
+@geindex C Streams
+@geindex Interfacing with `@w{`}Text_IO`@w{`}
+
+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 Text_IO Reset_Standard_Files a-tirsfi ads,Ada Wide_Characters Unicode a-wichun ads,Ada Text_IO C_Streams a-tiocst ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id22}@anchor{300}
+@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads})
+
+
+@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
+
+@geindex Text_IO resetting standard files
+
+This procedure is used to reset the status of the standard files used
+by Ada.Text_IO. This is useful in a situation (such as a restart in an
+embedded application) where the status of the files may change during
+execution (for example a standard input file may be redefined to be
+interactive).
+
+@node Ada Wide_Characters Unicode a-wichun ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id23}@anchor{302}
+@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads})
+
+
+@geindex Ada.Wide_Characters.Unicode (a-wichun.ads)
+
+@geindex Unicode categorization
+@geindex Wide_Character
+
+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,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Characters Unicode a-wichun ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id24}@anchor{304}
+@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads})
+
+
+@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
+
+@geindex C Streams
+@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`}
+
+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_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{305}@anchor{gnat_rm/the_gnat_library id25}@anchor{306}
+@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads})
+
+
+@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
+
+@geindex Wide_Text_IO resetting standard files
+
+This procedure is used to reset the status of the standard files used
+by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an
+embedded application) where the status of the files may change during
+execution (for example a standard input file may be redefined to be
+interactive).
+
+@node Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id26}@anchor{308}
+@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads})
+
+
+@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
+
+@geindex Unicode categorization
+@geindex Wide_Wide_Character
+
+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,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id27}@anchor{30a}
+@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads})
+
+
+@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
+
+@geindex C Streams
+@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`}
+
+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 Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,GNAT Altivec g-altive ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{30b}@anchor{gnat_rm/the_gnat_library id28}@anchor{30c}
+@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads})
+
+
+@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
+
+@geindex Wide_Wide_Text_IO resetting standard files
+
+This procedure is used to reset the status of the standard files used
+by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
+restart in an embedded application) where the status of the files may
+change during execution (for example a standard input file may be
+redefined to be interactive).
+
+@node GNAT Altivec g-altive ads,GNAT Altivec Conversions g-altcon ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id29}@anchor{30e}
+@section @code{GNAT.Altivec} (@code{g-altive.ads})
+
+
+@geindex GNAT.Altivec (g-altive.ads)
+
+@geindex AltiVec
+
+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,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id30}@anchor{310}
+@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads})
+
+
+@geindex GNAT.Altivec.Conversions (g-altcon.ads)
+
+@geindex AltiVec
+
+This package provides the Vector/View conversion routines.
+
+@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id31}@anchor{312}
+@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads})
+
+
+@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads)
+
+@geindex AltiVec
+
+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,GNAT Altivec Vector_Views g-alvevi ads,GNAT Altivec Vector_Operations g-alveop ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id32}@anchor{314}
+@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads})
+
+
+@geindex GNAT.Altivec.Vector_Types (g-alvety.ads)
+
+@geindex AltiVec
+
+This package exposes the various vector types part of the Ada binding
+to AltiVec facilities.
+
+@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id33}@anchor{316}
+@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads})
+
+
+@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads)
+
+@geindex AltiVec
+
+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,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id34}@anchor{318}
+@section @code{GNAT.Array_Split} (@code{g-arrspl.ads})
+
+
+@geindex GNAT.Array_Split (g-arrspl.ads)
+
+@geindex Array splitter
+
+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,GNAT Binary_Search g-binsea ads,GNAT Array_Split g-arrspl ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id35}@anchor{31a}
+@section @code{GNAT.AWK} (@code{g-awk.ads})
+
+
+@geindex GNAT.AWK (g-awk.ads)
+
+@geindex Parsing
+
+@geindex AWK
+
+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 Binary_Search g-binsea ads,GNAT Bind_Environment g-binenv ads,GNAT AWK g-awk ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-binary-search-g-binsea-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id36}@anchor{31c}
+@section @code{GNAT.Binary_Search} (@code{g-binsea.ads})
+
+
+@geindex GNAT.Binary_Search (g-binsea.ads)
+
+@geindex Binary search
+
+Allow binary search of a sorted array (or of an array-like container;
+the generic does not reference the array directly).
+
+@node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT Binary_Search g-binsea ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id37}@anchor{31e}
+@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads})
+
+
+@geindex GNAT.Bind_Environment (g-binenv.ads)
+
+@geindex Bind environment
+
+Provides access to key=value associations captured at bind time.
+These associations can be specified using the @code{-V} binder command
+line switch.
+
+@node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id38}@anchor{320}
+@section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads})
+
+
+@geindex GNAT.Branch_Prediction (g-brapre.ads)
+
+@geindex Branch Prediction
+
+Provides routines giving hints to the branch predictor of the code generator.
+
+@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id39}@anchor{322}
+@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads})
+
+
+@geindex GNAT.Bounded_Buffers (g-boubuf.ads)
+
+@geindex Parsing
+
+@geindex Bounded Buffers
+
+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,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id40}@anchor{324}
+@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads})
+
+
+@geindex GNAT.Bounded_Mailboxes (g-boumai.ads)
+
+@geindex Parsing
+
+@geindex Mailboxes
+
+Provides a thread-safe asynchronous intertask mailbox communication facility.
+
+@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id41}@anchor{326}
+@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads})
+
+
+@geindex GNAT.Bubble_Sort (g-bubsor.ads)
+
+@geindex Sorting
+
+@geindex Bubble sort
+
+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,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id42}@anchor{328}
+@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads})
+
+
+@geindex GNAT.Bubble_Sort_A (g-busora.ads)
+
+@geindex Sorting
+
+@geindex Bubble sort
+
+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,GNAT Byte_Order_Mark g-byorma ads,GNAT Bubble_Sort_A g-busora ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id43}@anchor{32a}
+@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads})
+
+
+@geindex GNAT.Bubble_Sort_G (g-busorg.ads)
+
+@geindex Sorting
+
+@geindex Bubble sort
+
+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,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id44}@anchor{32c}
+@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads})
+
+
+@geindex GNAT.Byte_Order_Mark (g-byorma.ads)
+
+@geindex UTF-8 representation
+
+@geindex Wide characte representations
+
+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,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id45}@anchor{32e}
+@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads})
+
+
+@geindex GNAT.Byte_Swapping (g-bytswa.ads)
+
+@geindex Byte swapping
+
+@geindex Endianness
+
+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,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id46}@anchor{330}
+@section @code{GNAT.Calendar} (@code{g-calend.ads})
+
+
+@geindex GNAT.Calendar (g-calend.ads)
+
+@geindex Calendar
+
+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,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id47}@anchor{332}
+@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads})
+
+
+@geindex Calendar
+
+@geindex Time
+
+@geindex GNAT.Calendar.Time_IO (g-catiio.ads)
+
+@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id48}@anchor{334}
+@section @code{GNAT.CRC32} (@code{g-crc32.ads})
+
+
+@geindex GNAT.CRC32 (g-crc32.ads)
+
+@geindex CRC32
+
+@geindex Cyclic Redundancy Check
+
+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,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id49}@anchor{336}
+@section @code{GNAT.Case_Util} (@code{g-casuti.ads})
+
+
+@geindex GNAT.Case_Util (g-casuti.ads)
+
+@geindex Casing utilities
+
+@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`})
+
+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,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id50}@anchor{338}
+@section @code{GNAT.CGI} (@code{g-cgi.ads})
+
+
+@geindex GNAT.CGI (g-cgi.ads)
+
+@geindex CGI (Common Gateway Interface)
+
+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,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id51}@anchor{33a}
+@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads})
+
+
+@geindex GNAT.CGI.Cookie (g-cgicoo.ads)
+
+@geindex CGI (Common Gateway Interface) cookie support
+
+@geindex Cookie support in CGI
+
+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,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id52}@anchor{33c}
+@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads})
+
+
+@geindex GNAT.CGI.Debug (g-cgideb.ads)
+
+@geindex CGI (Common Gateway Interface) debugging
+
+This is a package to help debugging CGI (Common Gateway Interface)
+programs written in Ada.
+
+@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id53}@anchor{33e}
+@section @code{GNAT.Command_Line} (@code{g-comlin.ads})
+
+
+@geindex GNAT.Command_Line (g-comlin.ads)
+
+@geindex Command line
+
+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 wildcard notations.
+
+@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id54}@anchor{340}
+@section @code{GNAT.Compiler_Version} (@code{g-comver.ads})
+
+
+@geindex GNAT.Compiler_Version (g-comver.ads)
+
+@geindex Compiler Version
+
+@geindex Version
+@geindex of compiler
+
+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,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id55}@anchor{342}
+@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads})
+
+
+@geindex GNAT.Ctrl_C (g-ctrl_c.ads)
+
+@geindex Interrupt
+
+Provides a simple interface to handle Ctrl-C keyboard events.
+
+@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id56}@anchor{344}
+@section @code{GNAT.Current_Exception} (@code{g-curexc.ads})
+
+
+@geindex GNAT.Current_Exception (g-curexc.ads)
+
+@geindex Current exception
+
+@geindex Exception retrieval
+
+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,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id57}@anchor{346}
+@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads})
+
+
+@geindex GNAT.Debug_Pools (g-debpoo.ads)
+
+@geindex Debugging
+
+@geindex Debug pools
+
+@geindex Memory corruption debugging
+
+Provide a debugging storage pools that helps tracking memory corruption
+problems.
+See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}.
+
+@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id58}@anchor{348}
+@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads})
+
+
+@geindex GNAT.Debug_Utilities (g-debuti.ads)
+
+@geindex Debugging
+
+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,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id59}@anchor{34a}
+@section @code{GNAT.Decode_String} (@code{g-decstr.ads})
+
+
+@geindex GNAT.Decode_String (g-decstr.ads)
+
+@geindex Decoding strings
+
+@geindex String decoding
+
+@geindex Wide character encoding
+
+@geindex UTF-8
+
+@geindex Unicode
+
+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,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id60}@anchor{34c}
+@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads})
+
+
+@geindex GNAT.Decode_UTF8_String (g-deutst.ads)
+
+@geindex Decoding strings
+
+@geindex Decoding UTF-8 strings
+
+@geindex UTF-8 string decoding
+
+@geindex Wide character decoding
+
+@geindex UTF-8
+
+@geindex Unicode
+
+A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
+
+@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id61}@anchor{34e}
+@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads})
+
+
+@geindex GNAT.Directory_Operations (g-dirope.ads)
+
+@geindex Directory operations
+
+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,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id62}@anchor{350}
+@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads})
+
+
+@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads)
+
+@geindex Directory operations iteration
+
+A child unit of GNAT.Directory_Operations providing additional operations
+for iterating through directories.
+
+@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id63}@anchor{352}
+@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads})
+
+
+@geindex GNAT.Dynamic_HTables (g-dynhta.ads)
+
+@geindex Hash tables
+
+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.
+
+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,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id64}@anchor{354}
+@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads})
+
+
+@geindex GNAT.Dynamic_Tables (g-dyntab.ads)
+
+@geindex Table implementation
+
+@geindex Arrays
+@geindex extendable
+
+A generic package providing a single dimension array abstraction where the
+length of the array can be dynamically modified.
+
+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,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id65}@anchor{356}
+@section @code{GNAT.Encode_String} (@code{g-encstr.ads})
+
+
+@geindex GNAT.Encode_String (g-encstr.ads)
+
+@geindex Encoding strings
+
+@geindex String encoding
+
+@geindex Wide character encoding
+
+@geindex UTF-8
+
+@geindex Unicode
+
+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,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id66}@anchor{358}
+@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads})
+
+
+@geindex GNAT.Encode_UTF8_String (g-enutst.ads)
+
+@geindex Encoding strings
+
+@geindex Encoding UTF-8 strings
+
+@geindex UTF-8 string encoding
+
+@geindex Wide character encoding
+
+@geindex UTF-8
+
+@geindex Unicode
+
+A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
+
+@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id67}@anchor{35a}
+@section @code{GNAT.Exception_Actions} (@code{g-excact.ads})
+
+
+@geindex GNAT.Exception_Actions (g-excact.ads)
+
+@geindex Exception actions
+
+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,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id68}@anchor{35c}
+@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads})
+
+
+@geindex GNAT.Exception_Traces (g-exctra.ads)
+
+@geindex Exception traces
+
+@geindex Debugging
+
+Provides an interface allowing to control automatic output upon exception
+occurrences.
+
+@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id69}@anchor{35e}
+@section @code{GNAT.Exceptions} (@code{g-except.ads})
+
+
+@geindex GNAT.Exceptions (g-except.ads)
+
+@geindex Exceptions
+@geindex Pure
+
+@geindex Pure packages
+@geindex exceptions
+
+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,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id70}@anchor{360}
+@section @code{GNAT.Expect} (@code{g-expect.ads})
+
+
+@geindex GNAT.Expect (g-expect.ads)
+
+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.
+It is not implemented for cross ports, and in particular is not
+implemented for VxWorks or LynxOS.
+
+@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id71}@anchor{362}
+@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads})
+
+
+@geindex GNAT.Expect.TTY (g-exptty.ads)
+
+As GNAT.Expect but using pseudo-terminal.
+Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT
+ports. It is not implemented for cross ports, and
+in particular is not implemented for VxWorks or LynxOS.
+
+@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id72}@anchor{364}
+@section @code{GNAT.Float_Control} (@code{g-flocon.ads})
+
+
+@geindex GNAT.Float_Control (g-flocon.ads)
+
+@geindex Floating-Point Processor
+
+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 Formatted_String g-forstr ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Float_Control g-flocon ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id73}@anchor{366}
+@section @code{GNAT.Formatted_String} (@code{g-forstr.ads})
+
+
+@geindex GNAT.Formatted_String (g-forstr.ads)
+
+@geindex Formatted String
+
+Provides support for C/C++ printf() formatted strings. The format is
+copied from the printf() routine and should therefore gives identical
+output. Some generic routines are provided to be able to use types
+derived from Integer, Float or enumerations as values for the
+formatted string.
+
+@node GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Heap_Sort g-heasor ads,GNAT Formatted_String g-forstr ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-generic-fast-math-functions-g-gfmafu-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id74}@anchor{368}
+@section @code{GNAT.Generic_Fast_Math_Functions} (@code{g-gfmafu.ads})
+
+
+@geindex GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads)
+
+@geindex Mathematical functions
+
+Provides direct access to the underlying implementation of the common
+mathematical functions, generally from the system mathematical library.
+This differs from @code{Ada.Numerics.Generic_Elementary_Functions} in that
+the implementation may deviate from the semantics specified for these
+functions in the Reference Manual, for example @code{Numerics.Argument_Error}
+is not raised. On selected platforms, some of these functions may also
+have a vector implementation that can be automatically used by the
+compiler when auto-vectorization is enabled.
+
+@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id75}@anchor{36a}
+@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads})
+
+
+@geindex GNAT.Heap_Sort (g-heasor.ads)
+
+@geindex Sorting
+
+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,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id76}@anchor{36c}
+@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads})
+
+
+@geindex GNAT.Heap_Sort_A (g-hesora.ads)
+
+@geindex Sorting
+
+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,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id77}@anchor{36e}
+@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads})
+
+
+@geindex GNAT.Heap_Sort_G (g-hesorg.ads)
+
+@geindex Sorting
+
+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,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id78}@anchor{370}
+@section @code{GNAT.HTable} (@code{g-htable.ads})
+
+
+@geindex GNAT.HTable (g-htable.ads)
+
+@geindex Hash tables
+
+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,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id79}@anchor{372}
+@section @code{GNAT.IO} (@code{g-io.ads})
+
+
+@geindex GNAT.IO (g-io.ads)
+
+@geindex Simple I/O
+
+@geindex Input/Output facilities
+
+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,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id80}@anchor{374}
+@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads})
+
+
+@geindex GNAT.IO_Aux (g-io_aux.ads)
+
+@geindex Text_IO
+
+@geindex 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,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id81}@anchor{376}
+@section @code{GNAT.Lock_Files} (@code{g-locfil.ads})
+
+
+@geindex GNAT.Lock_Files (g-locfil.ads)
+
+@geindex File locking
+
+@geindex Locking using files
+
+Provides a general interface for using files as locks. Can be used for
+providing program level synchronization.
+
+@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id82}@anchor{378}
+@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads})
+
+
+@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads)
+
+@geindex Random number generation
+
+The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses
+a modified version of the Blum-Blum-Shub generator.
+
+@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id83}@anchor{37a}
+@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads})
+
+
+@geindex GNAT.MBBS_Float_Random (g-mbflra.ads)
+
+@geindex Random number generation
+
+The original implementation of @code{Ada.Numerics.Float_Random}. Uses
+a modified version of the Blum-Blum-Shub generator.
+
+@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id84}@anchor{37c}
+@section @code{GNAT.MD5} (@code{g-md5.ads})
+
+
+@geindex GNAT.MD5 (g-md5.ads)
+
+@geindex Message Digest MD5
+
+Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and
+the HMAC-MD5 message authentication function as described in RFC 2104 and
+FIPS PUB 198.
+
+@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id85}@anchor{37e}
+@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads})
+
+
+@geindex GNAT.Memory_Dump (g-memdum.ads)
+
+@geindex Dump Memory
+
+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,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id86}@anchor{380}
+@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads})
+
+
+@geindex GNAT.Most_Recent_Exception (g-moreex.ads)
+
+@geindex Exception
+@geindex obtaining most recent
+
+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,GNAT Perfect_Hash_Generators g-pehage ads,GNAT Most_Recent_Exception g-moreex ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id87}@anchor{382}
+@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads})
+
+
+@geindex GNAT.OS_Lib (g-os_lib.ads)
+
+@geindex Operating System interface
+
+@geindex Spawn capability
+
+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,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id88}@anchor{384}
+@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads})
+
+
+@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads)
+
+@geindex Hash functions
+
+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,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{385}@anchor{gnat_rm/the_gnat_library id89}@anchor{386}
+@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads})
+
+
+@geindex GNAT.Random_Numbers (g-rannum.ads)
+
+@geindex Random number generation
+
+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,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{25c}@anchor{gnat_rm/the_gnat_library id90}@anchor{387}
+@section @code{GNAT.Regexp} (@code{g-regexp.ads})
+
+
+@geindex GNAT.Regexp (g-regexp.ads)
+
+@geindex Regular expressions
+
+@geindex Pattern matching
+
+A simple implementation of regular expressions, using a subset of regular
+expression syntax copied from familiar Unix style utilities. This is the
+simplest of the three pattern matching packages provided, and is particularly
+suitable for ‘file globbing’ applications.
+
+@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{388}@anchor{gnat_rm/the_gnat_library id91}@anchor{389}
+@section @code{GNAT.Registry} (@code{g-regist.ads})
+
+
+@geindex GNAT.Registry (g-regist.ads)
+
+@geindex Windows Registry
+
+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,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{38a}@anchor{gnat_rm/the_gnat_library id92}@anchor{38b}
+@section @code{GNAT.Regpat} (@code{g-regpat.ads})
+
+
+@geindex GNAT.Regpat (g-regpat.ads)
+
+@geindex Regular expressions
+
+@geindex Pattern matching
+
+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 Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{38c}@anchor{gnat_rm/the_gnat_library id93}@anchor{38d}
+@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads})
+
+
+@geindex GNAT.Rewrite_Data (g-rewdat.ads)
+
+@geindex Rewrite data
+
+A unit to rewrite on-the-fly string occurrences in a stream of
+data. The implementation has a very minimal memory footprint as the
+full content to be processed is not loaded into memory all at once. This makes
+this interface usable for large files or socket streams.
+
+@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{38e}@anchor{gnat_rm/the_gnat_library id94}@anchor{38f}
+@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads})
+
+
+@geindex GNAT.Secondary_Stack_Info (g-sestin.ads)
+
+@geindex Secondary Stack Info
+
+Provide the capability to query the high water mark of the current task’s
+secondary stack.
+
+@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id95}@anchor{391}
+@section @code{GNAT.Semaphores} (@code{g-semaph.ads})
+
+
+@geindex GNAT.Semaphores (g-semaph.ads)
+
+@geindex Semaphores
+
+Provides classic counting and binary semaphores using protected types.
+
+@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{392}@anchor{gnat_rm/the_gnat_library id96}@anchor{393}
+@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads})
+
+
+@geindex GNAT.Serial_Communications (g-sercom.ads)
+
+@geindex Serial_Communications
+
+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,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id97}@anchor{395}
+@section @code{GNAT.SHA1} (@code{g-sha1.ads})
+
+
+@geindex GNAT.SHA1 (g-sha1.ads)
+
+@geindex Secure Hash Algorithm SHA-1
+
+Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3
+and RFC 3174, and the HMAC-SHA1 message authentication function as described
+in RFC 2104 and FIPS PUB 198.
+
+@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{396}@anchor{gnat_rm/the_gnat_library id98}@anchor{397}
+@section @code{GNAT.SHA224} (@code{g-sha224.ads})
+
+
+@geindex GNAT.SHA224 (g-sha224.ads)
+
+@geindex Secure Hash Algorithm SHA-224
+
+Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3,
+and the HMAC-SHA224 message authentication function as described
+in RFC 2104 and FIPS PUB 198.
+
+@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id99}@anchor{399}
+@section @code{GNAT.SHA256} (@code{g-sha256.ads})
+
+
+@geindex GNAT.SHA256 (g-sha256.ads)
+
+@geindex Secure Hash Algorithm SHA-256
+
+Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3,
+and the HMAC-SHA256 message authentication function as described
+in RFC 2104 and FIPS PUB 198.
+
+@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id100}@anchor{39b}
+@section @code{GNAT.SHA384} (@code{g-sha384.ads})
+
+
+@geindex GNAT.SHA384 (g-sha384.ads)
+
+@geindex Secure Hash Algorithm SHA-384
+
+Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3,
+and the HMAC-SHA384 message authentication function as described
+in RFC 2104 and FIPS PUB 198.
+
+@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id101}@anchor{39d}
+@section @code{GNAT.SHA512} (@code{g-sha512.ads})
+
+
+@geindex GNAT.SHA512 (g-sha512.ads)
+
+@geindex Secure Hash Algorithm SHA-512
+
+Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3,
+and the HMAC-SHA512 message authentication function as described
+in RFC 2104 and FIPS PUB 198.
+
+@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id102}@anchor{39f}
+@section @code{GNAT.Signals} (@code{g-signal.ads})
+
+
+@geindex GNAT.Signals (g-signal.ads)
+
+@geindex Signals
+
+Provides the ability to manipulate the blocked status of signals on supported
+targets.
+
+@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id103}@anchor{3a1}
+@section @code{GNAT.Sockets} (@code{g-socket.ads})
+
+
+@geindex GNAT.Sockets (g-socket.ads)
+
+@geindex Sockets
+
+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 and on VxWorks cross prots. It is not implemented for
+the LynxOS cross port.
+
+@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a3}
+@section @code{GNAT.Source_Info} (@code{g-souinf.ads})
+
+
+@geindex GNAT.Source_Info (g-souinf.ads)
+
+@geindex Source Information
+
+Provides subprograms that give access to source code information known at
+compile time, such as the current file name and line number. Also provides
+subprograms yielding the date and time of the current compilation (like the
+C macros @code{__DATE__} and @code{__TIME__})
+
+@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a5}
+@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads})
+
+
+@geindex GNAT.Spelling_Checker (g-speche.ads)
+
+@geindex Spell checking
+
+Provides a function for determining whether one string is a plausible
+near misspelling of another string.
+
+@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a7}
+@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads})
+
+
+@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads)
+
+@geindex Spell checking
+
+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,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a9}
+@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads})
+
+
+@geindex GNAT.Spitbol.Patterns (g-spipat.ads)
+
+@geindex SPITBOL pattern matching
+
+@geindex Pattern matching
+
+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,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id108}@anchor{3ab}
+@section @code{GNAT.Spitbol} (@code{g-spitbo.ads})
+
+
+@geindex GNAT.Spitbol (g-spitbo.ads)
+
+@geindex SPITBOL interface
+
+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,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id109}@anchor{3ad}
+@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads})
+
+
+@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
+
+@geindex Sets of strings
+
+@geindex SPITBOL Tables
+
+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,GNAT Spitbol Table_VString g-sptavs ads,GNAT Spitbol Table_Boolean g-sptabo ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id110}@anchor{3af}
+@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads})
+
+
+@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads)
+
+@geindex Integer maps
+
+@geindex Maps
+
+@geindex SPITBOL Tables
+
+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,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b1}
+@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads})
+
+
+@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads)
+
+@geindex String maps
+
+@geindex Maps
+
+@geindex SPITBOL Tables
+
+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 SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b3}
+@section @code{GNAT.SSE} (@code{g-sse.ads})
+
+
+@geindex GNAT.SSE (g-sse.ads)
+
+Root of a set of units aimed at offering Ada bindings to a subset of
+the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
+targets. It exposes vector component types together with a general
+introduction to the binding contents and use.
+
+@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b5}
+@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads})
+
+
+@geindex GNAT.SSE.Vector_Types (g-ssvety.ads)
+
+SSE vector types for use with SSE related intrinsics.
+
+@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b7}
+@section @code{GNAT.String_Hash} (@code{g-strhas.ads})
+
+
+@geindex GNAT.String_Hash (g-strhas.ads)
+
+@geindex Hash functions
+
+Provides a generic hash function working on arrays of scalars. Both the scalar
+type and the hash result type are parameters.
+
+@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b9}
+@section @code{GNAT.Strings} (@code{g-string.ads})
+
+
+@geindex GNAT.Strings (g-string.ads)
+
+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,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id116}@anchor{3bb}
+@section @code{GNAT.String_Split} (@code{g-strspl.ads})
+
+
+@geindex GNAT.String_Split (g-strspl.ads)
+
+@geindex String splitter
+
+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,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3bc}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bd}
+@section @code{GNAT.Table} (@code{g-table.ads})
+
+
+@geindex GNAT.Table (g-table.ads)
+
+@geindex Table implementation
+
+@geindex Arrays
+@geindex extendable
+
+A generic package providing a single dimension array abstraction where the
+length of the array can be dynamically modified.
+
+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,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id118}@anchor{3bf}
+@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads})
+
+
+@geindex GNAT.Task_Lock (g-tasloc.ads)
+
+@geindex Task synchronization
+
+@geindex Task locking
+
+@geindex Locking
+
+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,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id119}@anchor{3c1}
+@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads})
+
+
+@geindex GNAT.Time_Stamp (g-timsta.ads)
+
+@geindex Time stamp
+
+@geindex Current time
+
+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,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c3}
+@section @code{GNAT.Threads} (@code{g-thread.ads})
+
+
+@geindex GNAT.Threads (g-thread.ads)
+
+@geindex Foreign threads
+
+@geindex Threads
+@geindex foreign
+
+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,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c5}
+@section @code{GNAT.Traceback} (@code{g-traceb.ads})
+
+
+@geindex GNAT.Traceback (g-traceb.ads)
+
+@geindex Trace back facilities
+
+Provides a facility for obtaining non-symbolic traceback information, useful
+in various debugging situations.
+
+@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c7}
+@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads})
+
+
+@geindex GNAT.Traceback.Symbolic (g-trasym.ads)
+
+@geindex Trace back facilities
+
+@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c9}
+@section @code{GNAT.UTF_32} (@code{g-table.ads})
+
+
+@geindex GNAT.UTF_32 (g-table.ads)
+
+@geindex Wide character codes
+
+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 Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id124}@anchor{3cb}
+@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads})
+
+
+@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads)
+
+@geindex Spell checking
+
+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,GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Spelling_Checker g-u3spch ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id125}@anchor{3cd}
+@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads})
+
+
+@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads)
+
+@geindex Spell checking
+
+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,GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Spelling_Checker g-wispch ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id126}@anchor{3cf}
+@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads})
+
+
+@geindex GNAT.Wide_String_Split (g-wistsp.ads)
+
+@geindex Wide_String splitter
+
+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,GNAT Wide_Wide_String_Split g-zistsp ads,GNAT Wide_String_Split g-wistsp ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id127}@anchor{3d1}
+@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads})
+
+
+@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
+
+@geindex Spell checking
+
+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,Interfaces C Extensions i-cexten ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d3}
+@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads})
+
+
+@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads)
+
+@geindex Wide_Wide_String splitter
+
+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,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id129}@anchor{3d4}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3d5}
+@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads})
+
+
+@geindex Interfaces.C.Extensions (i-cexten.ads)
+
+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,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id130}@anchor{3d6}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3d7}
+@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads})
+
+
+@geindex Interfaces.C.Streams (i-cstrea.ads)
+
+@geindex C streams
+@geindex interfacing
+
+This package is a binding for the most commonly used operations
+on C streams.
+
+@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id131}@anchor{3d8}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3d9}
+@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads})
+
+
+@geindex Interfaces.Packed_Decimal (i-pacdec.ads)
+
+@geindex IBM Packed Format
+
+@geindex Packed Decimal
+
+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,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id132}@anchor{3da}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3db}
+@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads})
+
+
+@geindex Interfaces.VxWorks (i-vxwork.ads)
+
+@geindex Interfacing to VxWorks
+
+@geindex VxWorks
+@geindex interfacing
+
+This package provides a limited binding to the VxWorks API.
+In particular, it interfaces with the
+VxWorks hardware interrupt facilities.
+
+@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id133}@anchor{3dc}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3dd}
+@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads})
+
+
+@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads)
+
+@geindex Interfacing to VxWorks
+
+@geindex VxWorks
+@geindex interfacing
+
+This package provides a way for users to replace the use of
+intConnect() with a custom routine for installing interrupt
+handlers.
+
+@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id134}@anchor{3de}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3df}
+@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads})
+
+
+@geindex Interfaces.VxWorks.IO (i-vxwoio.ads)
+
+@geindex Interfacing to VxWorks' I/O
+
+@geindex VxWorks
+@geindex I/O interfacing
+
+@geindex VxWorks
+@geindex Get_Immediate
+
+@geindex Get_Immediate
+@geindex VxWorks
+
+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,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id135}@anchor{3e0}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3e1}
+@section @code{System.Address_Image} (@code{s-addima.ads})
+
+
+@geindex System.Address_Image (s-addima.ads)
+
+@geindex Address image
+
+@geindex Image
+@geindex of an address
+
+This function provides a useful debugging
+function that gives an (implementation dependent)
+string which identifies an address.
+
+@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id136}@anchor{3e2}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3e3}
+@section @code{System.Assertions} (@code{s-assert.ads})
+
+
+@geindex System.Assertions (s-assert.ads)
+
+@geindex Assertions
+
+@geindex Assert_Failure
+@geindex exception
+
+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 Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id137}@anchor{3e4}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3e5}
+@section @code{System.Atomic_Counters} (@code{s-atocou.ads})
+
+
+@geindex System.Atomic_Counters (s-atocou.ads)
+
+This package provides the declaration of an atomic counter type,
+together with efficient routines (using hardware
+synchronization primitives) for incrementing, decrementing,
+and testing of these counters. This package is implemented
+on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9,
+x86, and x86_64 platforms.
+
+@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id138}@anchor{3e6}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3e7}
+@section @code{System.Memory} (@code{s-memory.ads})
+
+
+@geindex System.Memory (s-memory.ads)
+
+@geindex Memory allocation
+
+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 Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id139}@anchor{3e8}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3e9}
+@section @code{System.Multiprocessors} (@code{s-multip.ads})
+
+
+@geindex System.Multiprocessors (s-multip.ads)
+
+@geindex Multiprocessor interface
+
+This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
+in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
+technically an implementation-defined addition).
+
+@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id140}@anchor{3ea}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3eb}
+@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads})
+
+
+@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads)
+
+@geindex Multiprocessor interface
+
+This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
+in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
+technically an implementation-defined addition).
+
+@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id141}@anchor{3ec}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3ed}
+@section @code{System.Partition_Interface} (@code{s-parint.ads})
+
+
+@geindex System.Partition_Interface (s-parint.ads)
+
+@geindex Partition interfacing functions
+
+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,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id142}@anchor{3ee}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3ef}
+@section @code{System.Pool_Global} (@code{s-pooglo.ads})
+
+
+@geindex System.Pool_Global (s-pooglo.ads)
+
+@geindex Storage pool
+@geindex global
+
+@geindex Global storage pool
+
+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,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id143}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3f1}
+@section @code{System.Pool_Local} (@code{s-pooloc.ads})
+
+
+@geindex System.Pool_Local (s-pooloc.ads)
+
+@geindex Storage pool
+@geindex local
+
+@geindex Local storage pool
+
+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,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id144}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3f3}
+@section @code{System.Restrictions} (@code{s-restri.ads})
+
+
+@geindex System.Restrictions (s-restri.ads)
+
+@geindex Run-time restrictions access
+
+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,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id145}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3f5}
+@section @code{System.Rident} (@code{s-rident.ads})
+
+
+@geindex System.Rident (s-rident.ads)
+
+@geindex Restrictions definitions
+
+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 Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id146}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3f7}
+@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads})
+
+
+@geindex System.Strings.Stream_Ops (s-ststop.ads)
+
+@geindex Stream operations
+
+@geindex String stream operations
+
+This package provides a set of stream subprograms for standard string types.
+It is intended primarily to support implicit use of such subprograms when
+stream attributes are applied to string types, but the subprograms in this
+package can be used directly by application programs.
+
+@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id147}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3f9}
+@section @code{System.Unsigned_Types} (@code{s-unstyp.ads})
+
+
+@geindex System.Unsigned_Types (s-unstyp.ads)
+
+This package contains definitions of standard unsigned types that
+correspond in size to the standard signed types declared in Standard,
+and (unlike the types in Interfaces) have corresponding names. It
+also contains some related definitions for other specialized types
+used by the compiler in connection with packed array types.
+
+@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id148}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3fb}
+@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads})
+
+
+@geindex System.Wch_Cnv (s-wchcnv.ads)
+
+@geindex Wide Character
+@geindex Representation
+
+@geindex Wide String
+@geindex Conversion
+
+@geindex Representation of wide characters
+
+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,,System Wch_Cnv s-wchcnv ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id149}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{3fd}
+@section @code{System.Wch_Con} (@code{s-wchcon.ads})
+
+
+@geindex System.Wch_Con (s-wchcon.ads)
+
+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,Specialized Needs Annexes,The GNAT Library,Top
+@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{3fe}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{3ff}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}
+@chapter Interfacing to Other Languages
+
+
+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,Interfacing to C++,,Interfacing to Other Languages
+@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{400}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{401}
+@section Interfacing to C
+
+
+Interfacing to C with GNAT can use one of two approaches:
+
+
+@itemize *
+
+@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
+
+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.
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@headitem
+
+Ada Type
+
+@tab
+
+C Type
+
+@item
+
+@code{Integer}
+
+@tab
+
+@code{int}
+
+@item
+
+@code{Short_Integer}
+
+@tab
+
+@code{short}
+
+@item
+
+@code{Short_Short_Integer}
+
+@tab
+
+@code{signed char}
+
+@item
+
+@code{Long_Integer}
+
+@tab
+
+@code{long}
+
+@item
+
+@code{Long_Long_Integer}
+
+@tab
+
+@code{long long}
+
+@item
+
+@code{Short_Float}
+
+@tab
+
+@code{float}
+
+@item
+
+@code{Float}
+
+@tab
+
+@code{float}
+
+@item
+
+@code{Long_Float}
+
+@tab
+
+@code{double}
+
+@item
+
+@code{Long_Long_Float}
+
+@tab
+
+This is the longest floating-point type supported by the hardware.
+
+@end multitable
+
+
+Additionally, there are the following general correspondences between Ada
+and C types:
+
+
+@itemize *
+
+@item
+Ada enumeration types map to C enumeration types directly if pragma
+@code{Convention C} is specified, which causes them to have a length of
+32 bits, except for boolean types which map to C99 @code{bool} and for
+which the length is 8 bits.
+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{type'Size} value in Ada.
+@end itemize
+
+@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages
+@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{47}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{402}
+@section Interfacing to C++
+
+
+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.
+
+Using these pragmas it is possible to achieve complete
+inter-operability between Ada tagged types and C++ class definitions.
+See @ref{7,,Implementation Defined Pragmas}, for more details.
+
+
+@table @asis
+
+@item @code{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 @code{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
+
+A few restrictions are placed on the use of the @code{Access} attribute
+in conjunction with subprograms subject to convention @code{CPP}: the
+attribute may be used neither on primitive operations of a tagged
+record type with convention @code{CPP}, imported or not, nor on
+subprograms imported with pragma @code{CPP_Constructor}.
+
+In addition, C++ exceptions are propagated and can be handled in an
+@code{others} choice of an exception handler. The corresponding Ada
+occurrence has no message, and the simple name of the exception identity
+contains @code{Foreign_Exception}. Finalization and awaiting dependent
+tasks works properly when such foreign exceptions are propagated.
+
+It is also possible to import a C++ exception using the following syntax:
+
+@example
+LOCAL_NAME : exception;
+pragma Import (Cpp,
+ [Entity =>] LOCAL_NAME,
+ [External_Name =>] static_string_EXPRESSION);
+@end example
+
+The @code{External_Name} is the name of the C++ RTTI symbol. You can then
+cover a specific C++ exception in an exception handler.
+
+@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages
+@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{403}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{404}
+@section Interfacing to COBOL
+
+
+Interfacing to COBOL is achieved as described in section B.4 of
+the Ada Reference Manual.
+
+@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages
+@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{405}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{406}
+@section Interfacing to Fortran
+
+
+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,,Interfacing to Fortran,Interfacing to Other Languages
+@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{407}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{408}
+@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,Implementation of Specific Ada Features,Interfacing to Other Languages,Top
+@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{409}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{40a}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}
+@chapter Specialized Needs Annexes
+
+
+Ada 95, Ada 2005, and Ada 2012 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,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top
+@anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{40b}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{40c}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13}
+@chapter Implementation of Specific Ada Features
+
+
+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::
+* Image Values For Nonscalar Types::
+* Strict Conformance to the Ada Reference Manual::
+
+@end menu
+
+@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features
+@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{40d}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{166}
+@section Machine Code Insertions
+
+
+@geindex Machine Code insertions
+
+Package @code{Machine_Code} provides machine code support as described
+in the Ada Reference Manual in two separate forms:
+
+
+@itemize *
+
+@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
+
+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 the section on Extended Asm in
+@cite{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.
+
+Consider this C @code{asm} instruction:
+
+@example
+asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
+@end example
+
+The equivalent can be written for GNAT as:
+
+@example
+Asm ("fsinx %1 %0",
+ My_Float'Asm_Output ("=f", result),
+ My_Float'Asm_Input ("f", angle));
+@end example
+
+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 (see the section on Constraints in
+@cite{Using_the_GNU_Compiler_Collection_(GCC)})
+for the parameter; e.g., what kind of register is required. The second
+argument is the variable to be written or 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}.
+No support is provided for GNU C’s symbolic names for output parameters.
+
+The second argument of @code{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
+constraint are the same as those used in the RTL, and are dependent on
+the configuration file used to built the GCC back end.
+No support is provided for GNU C’s symbolic names for input parameters.
+
+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
+`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.
+In addition to registers, the special clobbers @code{memory} and
+@code{cc} as described in the GNU C docs are both supported.
+
+The fifth argument, not present in the above example, called the
+`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 in particular an instruction that has outputs
+will still be generated, even if none of the outputs are
+used. See @cite{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 to avoid unwanted
+optimizations. A warning is generated if this advice is not followed.
+
+No support is provided for GNU C’s @code{asm goto} feature.
+
+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:
+
+@example
+Asm_Insn'(Asm (...));
+Asm_Insn'(Asm_Volatile (...));
+@end example
+
+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:
+
+@example
+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 example
+
+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,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features
+@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{40e}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{40f}
+@section GNAT Implementation of Tasking
+
+
+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::
+* Support for Locking Policies::
+
+@end menu
+
+@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking
+@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{410}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{411}
+@subsection Mapping Ada Tasks onto the Underlying Kernel Threads
+
+
+GNAT’s run-time support comprises two layers:
+
+
+@itemize *
+
+@item
+GNARL (GNAT Run-time Layer)
+
+@item
+GNULL (GNAT Low-level Library)
+@end itemize
+
+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, Windows, 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 *
+
+@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
+
+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.
+
+@geindex Forking a new process
+
+@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking
+@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{412}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{413}
+@subsection Ensuring Compliance with the Real-Time Annex
+
+
+@geindex Real-Time Systems Annex compliance
+
+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
+
+`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
+
+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.
+
+@c Support_for_Locking_Policies
+
+@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking
+@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{414}
+@subsection Support for Locking Policies
+
+
+This section specifies which policies specified by pragma Locking_Policy
+are supported on which platforms.
+
+GNAT supports the standard @code{Ceiling_Locking} policy, and the
+implementation defined @code{Inheritance_Locking} and
+@code{Concurrent_Readers_Locking} policies.
+
+@code{Ceiling_Locking} is supported on all platforms if the operating system
+supports it. In particular, @code{Ceiling_Locking} is not supported on
+VxWorks.
+@code{Inheritance_Locking} is supported on
+Linux,
+Darwin (Mac OS X),
+LynxOS 178,
+and VxWorks.
+@code{Concurrent_Readers_Locking} is supported on Linux.
+
+Notes about @code{Ceiling_Locking} on Linux:
+If the process is running as ‘root’, ceiling locking is used.
+If the capabilities facility is installed
+(“sudo apt-get –assume-yes install libcap-dev” on Ubuntu,
+for example),
+and the program is linked against that library
+(“-largs -lcap”),
+and the executable file has the cap_sys_nice capability
+(“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”),
+then ceiling locking is used.
+Otherwise, the @code{Ceiling_Locking} policy is ignored.
+
+@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features
+@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{415}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{416}
+@section GNAT Implementation of Shared Passive Packages
+
+
+@geindex Shared passive packages
+
+GNAT fully implements the
+@geindex pragma Shared_Passive
+pragma
+@code{Shared_Passive} for
+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.
+
+@geindex Annex E
+
+@geindex Distribution Systems Annex
+
+However, the implementation approach used by GNAT provides for more
+extensive usage as follows:
+
+
+@table @asis
+
+@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
+
+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.
+
+@geindex SHARED_MEMORY_DIRECTORY environment variable
+
+The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
+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
+
+@example
+package X is
+ pragma Shared_Passive (X);
+ Y : Integer;
+ Z : Float;
+end X;
+@end example
+
+and the environment variable is set to @code{/stemp/}, then the files created
+will have the names:
+
+@example
+/stemp/x.y
+/stemp/x.z
+@end example
+
+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 @code{___lock}, with three underscores)
+is created in the shared memory directory.
+
+@geindex ___lock file (for shared passive packages)
+
+This is used to provide the required locking
+semantics for proper protected object synchronization.
+
+@node Code Generation for Array Aggregates,The Size of Discriminated Records with Default Discriminants,GNAT Implementation of Shared Passive Packages,Implementation of Specific Ada Features
+@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{418}
+@section Code Generation for Array Aggregates
+
+
+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.
+
+@menu
+* Static constant aggregates with static bounds::
+* Constant aggregates with unconstrained nominal types::
+* Aggregates with static bounds::
+* Aggregates with nonstatic bounds::
+* Aggregates in assignment statements::
+
+@end menu
+
+@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates
+@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{41a}
+@subsection Static constant aggregates with static bounds
+
+
+For the declarations:
+
+@example
+type One_Dim is array (1..10) of integer;
+ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
+@end example
+
+GNAT generates no executable code: the constant ar0 is placed in static memory.
+The same is true for constant aggregates with named associations:
+
+@example
+Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
+Cr3 : constant One_Dim := (others => 7777);
+@end example
+
+The same is true for multidimensional constant arrays such as:
+
+@example
+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 example
+
+The same is true for arrays of one-dimensional arrays: the following are
+static:
+
+@example
+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 example
+
+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:
+
+@example
+Zero1: constant two_dim := (1..3 => (1..3 => 0));
+Zero2: constant two_dim := (others => (others => 0));
+@end example
+
+@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates
+@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{41c}
+@subsection Constant aggregates with unconstrained nominal types
+
+
+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:
+
+@example
+type One_Unc is array (natural range <>) of integer;
+Cr_Unc : constant One_Unc := (12,24,36);
+@end example
+
+@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates
+@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{41e}
+@subsection Aggregates with static bounds
+
+
+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
+
+@example
+Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
+Cr_Var2 : One_Dim := (others > -1);
+@end example
+
+generate the equivalent of
+
+@example
+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 example
+
+@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates
+@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{41f}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{420}
+@subsection Aggregates with nonstatic bounds
+
+
+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,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates
+@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{422}
+@subsection Aggregates in assignment statements
+
+
+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:
+
+@example
+A := (A(2), A(1));
+@end example
+
+This cannot be converted into:
+
+@example
+A(1) := A(2);
+A(2) := A(1);
+@end example
+
+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 *
+
+@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
+
+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,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features
+@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{423}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{424}
+@section The Size of Discriminated Records with Default Discriminants
+
+
+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:
+
+@example
+type Size is range 1..100;
+
+type Rec (D : Size := 15) is record
+ Name : String (1..D);
+end T;
+
+Word : Rec;
+@end example
+
+Such an object is said to be `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:
+
+@example
+Word := (3, "yes");
+
+Word := (5, "maybe");
+
+Word := (5, "no"); -- raises Constraint_Error
+@end example
+
+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:
+
+@example
+type Rec (D : Positive := 15) is record
+ Name : String (1..D);
+end record;
+
+Too_Large : Rec;
+@end example
+
+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 `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 Image Values For Nonscalar Types,Strict Conformance to the Ada Reference Manual,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features
+@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{426}
+@section Image Values For Nonscalar Types
+
+
+Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes
+for nonscalar types; earlier Ada versions defined these attributes only
+for scalar types. Ada RM 4.10 provides some general guidance regarding
+the default implementation of these attributes and the GNAT compiler
+follows that guidance. However, beyond that the precise details of the
+image text generated in these cases are deliberately not documented and are
+subject to change. In particular, users should not rely on formatting details
+(such as spaces or line breaking), record field order, image values for access
+types, image values for types that have ancestor or subcomponent types
+declared in non-Ada2022 code, image values for predefined types, or the
+compiler’s choices regarding the implementation permissions described in
+Ada RM 4.10. This list is not intended to be exhaustive. If more precise
+control of image text is required for some type T, then T’Put_Image should be
+explicitly specified.
+
+@node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features
+@anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{428}
+@section Strict Conformance to the Ada Reference Manual
+
+
+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 two checks that are not enabled in
+the default mode for efficiency reasons: 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 two
+compiler options for dynamic checks for access-before-elaboration on subprogram
+calls and generic instantiations (`-gnatE'), and stack overflow checking
+(`-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
+`-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.
+
+@node Implementation of Ada 2012 Features,Security Hardening Features,Implementation of Specific Ada Features,Top
+@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{429}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{42a}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14}
+@chapter Implementation of Ada 2012 Features
+
+
+@geindex Ada 2012 implementation status
+
+@geindex -gnat12 option (gcc)
+
+@geindex pragma Ada_2012
+
+@geindex configuration pragma Ada_2012
+
+@geindex Ada_2012 configuration pragma
+
+This chapter contains a complete list of Ada 2012 features that have been
+implemented.
+Generally, these features are only
+available if the `-gnat12' (Ada 2012 features enabled) option is set,
+which is the default behavior,
+or if the configuration pragma @code{Ada_2012} is used.
+
+However, new pragmas, attributes, and restrictions are
+unconditionally available, since the Ada 95 standard allows the addition of
+new pragmas, attributes, and restrictions (there are exceptions, which are
+documented in the individual descriptions), and also certain packages
+were made available in earlier versions of Ada.
+
+An ISO date (YYYY-MM-DD) appears in parentheses on the description line.
+This date shows the implementation date of the feature. Any wavefront
+subsequent to this date will contain the indicated feature, as will any
+subsequent releases. A date of 0000-00-00 means that GNAT has always
+implemented the feature, or implemented it as soon as it appeared as a
+binding interpretation.
+
+Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada
+standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012.
+The features are ordered based on the relevant sections of the Ada
+Reference Manual (“RM”). When a given AI relates to multiple points
+in the RM, the earliest is used.
+
+A complete description of the AIs may be found in
+@indicateurl{http://www.ada-auth.org/ai05-summary.html}.
+
+@geindex AI-0176 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0176 Quantified expressions (2010-09-29)'
+
+Both universally and existentially quantified expressions are implemented.
+They use the new syntax for iterators proposed in AI05-139-2, as well as
+the standard Ada loop syntax.
+
+RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0)
+@end itemize
+
+@geindex AI-0079 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0079 Allow other_format characters in source (2010-07-10)'
+
+Wide characters in the unicode category `other_format' are now allowed in
+source programs between tokens, but not within a token such as an identifier.
+
+RM References: 2.01 (4/2) 2.02 (7)
+@end itemize
+
+@geindex AI-0091 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0091 Do not allow other_format in identifiers (0000-00-00)'
+
+Wide characters in the unicode category `other_format' are not permitted
+within an identifier, since this can be a security problem. The error
+message for this case has been improved to be more specific, but GNAT has
+never allowed such characters to appear in identifiers.
+
+RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2)
+@end itemize
+
+@geindex AI-0100 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0100 Placement of pragmas (2010-07-01)'
+
+This AI is an earlier version of AI-163. It simplifies the rules
+for legal placement of pragmas. In the case of lists that allow pragmas, if
+the list may have no elements, then the list may consist solely of pragmas.
+
+RM References: 2.08 (7)
+@end itemize
+
+@geindex AI-0163 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0163 Pragmas in place of null (2010-07-01)'
+
+A statement sequence may be composed entirely of pragmas. It is no longer
+necessary to add a dummy @code{null} statement to make the sequence legal.
+
+RM References: 2.08 (7) 2.08 (16)
+@end itemize
+
+@geindex AI-0080 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0080 ‘View of’ not needed if clear from context (0000-00-00)'
+
+This is an editorial change only, described as non-testable in the AI.
+
+RM References: 3.01 (7)
+@end itemize
+
+@geindex AI-0183 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0183 Aspect specifications (2010-08-16)'
+
+Aspect specifications have been fully implemented except for pre and post-
+conditions, and type invariants, which have their own separate AI’s. All
+forms of declarations listed in the AI are supported. The following is a
+list of the aspects supported (with GNAT implementation aspects marked)
+@end itemize
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
+@headitem
+
+Supported Aspect
+
+@tab
+
+Source
+
+@item
+
+@code{Ada_2005}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Ada_2012}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Address}
+
+@tab
+
+@item
+
+@code{Alignment}
+
+@tab
+
+@item
+
+@code{Atomic}
+
+@tab
+
+@item
+
+@code{Atomic_Components}
+
+@tab
+
+@item
+
+@code{Bit_Order}
+
+@tab
+
+@item
+
+@code{Component_Size}
+
+@tab
+
+@item
+
+@code{Contract_Cases}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Discard_Names}
+
+@tab
+
+@item
+
+@code{External_Tag}
+
+@tab
+
+@item
+
+@code{Favor_Top_Level}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Inline}
+
+@tab
+
+@item
+
+@code{Inline_Always}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Invariant}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Machine_Radix}
+
+@tab
+
+@item
+
+@code{No_Return}
+
+@tab
+
+@item
+
+@code{Object_Size}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Pack}
+
+@tab
+
+@item
+
+@code{Persistent_BSS}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Post}
+
+@tab
+
+@item
+
+@code{Pre}
+
+@tab
+
+@item
+
+@code{Predicate}
+
+@tab
+
+@item
+
+@code{Preelaborable_Initialization}
+
+@tab
+
+@item
+
+@code{Pure_Function}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Remote_Access_Type}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Shared}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Size}
+
+@tab
+
+@item
+
+@code{Storage_Pool}
+
+@tab
+
+@item
+
+@code{Storage_Size}
+
+@tab
+
+@item
+
+@code{Stream_Size}
+
+@tab
+
+@item
+
+@code{Suppress}
+
+@tab
+
+@item
+
+@code{Suppress_Debug_Info}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Test_Case}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Thread_Local_Storage}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Type_Invariant}
+
+@tab
+
+@item
+
+@code{Unchecked_Union}
+
+@tab
+
+@item
+
+@code{Universal_Aliasing}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Unmodified}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Unreferenced}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Unreferenced_Objects}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Unsuppress}
+
+@tab
+
+@item
+
+@code{Value_Size}
+
+@tab
+
+– GNAT
+
+@item
+
+@code{Volatile}
+
+@tab
+
+@item
+
+@code{Volatile_Components}
+
+@tab
+
+@item
+
+@code{Warnings}
+
+@tab
+
+– GNAT
+
+@end multitable
+
+
+@quotation
+
+Note that for aspects with an expression, e.g. @code{Size}, the expression is
+treated like a default expression (visibility is analyzed at the point of
+occurrence of the aspect, but evaluation of the expression occurs at the
+freeze point of the entity involved).
+
+RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6)
+3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03
+(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2)
+9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2)
+12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1)
+13.03.01 (0)
+@end quotation
+
+@geindex AI-0128 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0128 Inequality is a primitive operation (0000-00-00)'
+
+If an equality operator (“=”) is declared for a type, then the implicitly
+declared inequality operator (“/=”) is a primitive operation of the type.
+This is the only reasonable interpretation, and is the one always implemented
+by GNAT, but the RM was not entirely clear in making this point.
+
+RM References: 3.02.03 (6) 6.06 (6)
+@end itemize
+
+@geindex AI-0003 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0003 Qualified expressions as names (2010-07-11)'
+
+In Ada 2012, a qualified expression is considered to be syntactically a name,
+meaning that constructs such as @code{A'(F(X)).B} are now legal. This is
+useful in disambiguating some cases of overloading.
+
+RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3)
+5.04 (7)
+@end itemize
+
+@geindex AI-0120 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0120 Constant instance of protected object (0000-00-00)'
+
+This is an RM editorial change only. The section that lists objects that are
+constant failed to include the current instance of a protected object
+within a protected function. This has always been treated as a constant
+in GNAT.
+
+RM References: 3.03 (21)
+@end itemize
+
+@geindex AI-0008 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0008 General access to constrained objects (0000-00-00)'
+
+The wording in the RM implied that if you have a general access to a
+constrained object, it could be used to modify the discriminants. This was
+obviously not intended. @code{Constraint_Error} should be raised, and GNAT
+has always done so in this situation.
+
+RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2)
+@end itemize
+
+@geindex AI-0093 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0093 Additional rules use immutably limited (0000-00-00)'
+
+This is an editorial change only, to make more widespread use of the Ada 2012
+‘immutably limited’.
+
+RM References: 3.03 (23.4/3)
+@end itemize
+
+@geindex AI-0096 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0096 Deriving from formal private types (2010-07-20)'
+
+In general it is illegal for a type derived from a formal limited type to be
+nonlimited. This AI makes an exception to this rule: derivation is legal
+if it appears in the private part of the generic, and the formal type is not
+tagged. If the type is tagged, the legality check must be applied to the
+private part of the package.
+
+RM References: 3.04 (5.1/2) 6.02 (7)
+@end itemize
+
+@geindex AI-0181 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0181 Soft hyphen is a non-graphic character (2010-07-23)'
+
+From Ada 2005 on, soft hyphen is considered a non-graphic character, which
+means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the
+@code{Image} and @code{Value} attributes for the character types. Strictly
+speaking this is an inconsistency with Ada 95, but in practice the use of
+these attributes is so obscure that it will not cause problems.
+
+RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21)
+@end itemize
+
+@geindex AI-0182 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0182 Additional forms for' @code{Character'Value} `(0000-00-00)'
+
+This AI allows @code{Character'Value} to accept the string @code{'?'} where
+@code{?} is any character including non-graphic control characters. GNAT has
+always accepted such strings. It also allows strings such as
+@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this
+permission and raises @code{Constraint_Error}, as is certainly still
+permitted.
+
+RM References: 3.05 (56/2)
+@end itemize
+
+@geindex AI-0214 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0214 Defaulted discriminants for limited tagged (2010-10-01)'
+
+Ada 2012 relaxes the restriction that forbids discriminants of tagged types
+to have default expressions by allowing them when the type is limited. It
+is often useful to define a default value for a discriminant even though
+it can’t be changed by assignment.
+
+RM References: 3.07 (9.1/2) 3.07.02 (3)
+@end itemize
+
+@geindex AI-0102 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0102 Some implicit conversions are illegal (0000-00-00)'
+
+It is illegal to assign an anonymous access constant to an anonymous access
+variable. The RM did not have a clear rule to prevent this, but GNAT has
+always generated an error for this usage.
+
+RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2)
+@end itemize
+
+@geindex AI-0158 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0158 Generalizing membership tests (2010-09-16)'
+
+This AI extends the syntax of membership tests to simplify complex conditions
+that can be expressed as membership in a subset of values of any type. It
+introduces syntax for a list of expressions that may be used in loop contexts
+as well.
+
+RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27)
+@end itemize
+
+@geindex AI-0173 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0173 Testing if tags represent abstract types (2010-07-03)'
+
+The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked
+with the tag of an abstract type, and @code{False} otherwise.
+
+RM References: 3.09 (7.4/2) 3.09 (12.4/2)
+@end itemize
+
+@geindex AI-0076 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0076 function with controlling result (0000-00-00)'
+
+This is an editorial change only. The RM defines calls with controlling
+results, but uses the term ‘function with controlling result’ without an
+explicit definition.
+
+RM References: 3.09.02 (2/2)
+@end itemize
+
+@geindex AI-0126 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0126 Dispatching with no declared operation (0000-00-00)'
+
+This AI clarifies dispatching rules, and simply confirms that dispatching
+executes the operation of the parent type when there is no explicitly or
+implicitly declared operation for the descendant type. This has always been
+the case in all versions of GNAT.
+
+RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2)
+@end itemize
+
+@geindex AI-0097 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0097 Treatment of abstract null extension (2010-07-19)'
+
+The RM as written implied that in some cases it was possible to create an
+object of an abstract type, by having an abstract extension inherit a non-
+abstract constructor from its parent type. This mistake has been corrected
+in GNAT and in the RM, and this construct is now illegal.
+
+RM References: 3.09.03 (4/2)
+@end itemize
+
+@geindex AI-0203 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0203 Extended return cannot be abstract (0000-00-00)'
+
+A return_subtype_indication cannot denote an abstract subtype. GNAT has never
+permitted such usage.
+
+RM References: 3.09.03 (8/3)
+@end itemize
+
+@geindex AI-0198 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0198 Inheriting abstract operators (0000-00-00)'
+
+This AI resolves a conflict between two rules involving inherited abstract
+operations and predefined operators. If a derived numeric type inherits
+an abstract operator, it overrides the predefined one. This interpretation
+was always the one implemented in GNAT.
+
+RM References: 3.09.03 (4/3)
+@end itemize
+
+@geindex AI-0073 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0073 Functions returning abstract types (2010-07-10)'
+
+This AI covers a number of issues regarding returning abstract types. In
+particular generic functions cannot have abstract result types or access
+result types designated an abstract type. There are some other cases which
+are detailed in the AI. Note that this binding interpretation has not been
+retrofitted to operate before Ada 2012 mode, since it caused a significant
+number of regressions.
+
+RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2)
+@end itemize
+
+@geindex AI-0070 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0070 Elaboration of interface types (0000-00-00)'
+
+This is an editorial change only, there are no testable consequences short of
+checking for the absence of generated code for an interface declaration.
+
+RM References: 3.09.04 (18/2)
+@end itemize
+
+@geindex AI-0208 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0208 Characteristics of incomplete views (0000-00-00)'
+
+The wording in the Ada 2005 RM concerning characteristics of incomplete views
+was incorrect and implied that some programs intended to be legal were now
+illegal. GNAT had never considered such programs illegal, so it has always
+implemented the intent of this AI.
+
+RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2)
+@end itemize
+
+@geindex AI-0162 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0162 Incomplete type completed by partial view (2010-09-15)'
+
+Incomplete types are made more useful by allowing them to be completed by
+private types and private extensions.
+
+RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2)
+@end itemize
+
+@geindex AI-0098 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0098 Anonymous subprogram access restrictions (0000-00-00)'
+
+An unintentional omission in the RM implied some inconsistent restrictions on
+the use of anonymous access to subprogram values. These restrictions were not
+intentional, and have never been enforced by GNAT.
+
+RM References: 3.10.01 (6) 3.10.01 (9.2/2)
+@end itemize
+
+@geindex AI-0199 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0199 Aggregate with anonymous access components (2010-07-14)'
+
+A choice list in a record aggregate can include several components of
+(distinct) anonymous access types as long as they have matching designated
+subtypes.
+
+RM References: 4.03.01 (16)
+@end itemize
+
+@geindex AI-0220 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0220 Needed components for aggregates (0000-00-00)'
+
+This AI addresses a wording problem in the RM that appears to permit some
+complex cases of aggregates with nonstatic discriminants. GNAT has always
+implemented the intended semantics.
+
+RM References: 4.03.01 (17)
+@end itemize
+
+@geindex AI-0147 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0147 Conditional expressions (2009-03-29)'
+
+Conditional expressions are permitted. The form of such an expression is:
+
+@example
+(if expr then expr @{elsif expr then expr@} [else expr])
+@end example
+
+The parentheses can be omitted in contexts where parentheses are present
+anyway, such as subprogram arguments and pragma arguments. If the `else'
+clause is omitted, `else' `True' is assumed;
+thus @code{(if A then B)} is a way to conveniently represent
+`(A implies B)' in standard logic.
+
+RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2)
+4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2)
+@end itemize
+
+@geindex AI-0037 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0037 Out-of-range box associations in aggregate (0000-00-00)'
+
+This AI confirms that an association of the form @code{Indx => <>} in an
+array aggregate must raise @code{Constraint_Error} if @code{Indx}
+is out of range. The RM specified a range check on other associations, but
+not when the value of the association was defaulted. GNAT has always inserted
+a constraint check on the index value.
+
+RM References: 4.03.03 (29)
+@end itemize
+
+@geindex AI-0123 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0123 Composability of equality (2010-04-13)'
+
+Equality of untagged record composes, so that the predefined equality for a
+composite type that includes a component of some untagged record type
+@code{R} uses the equality operation of @code{R} (which may be user-defined
+or predefined). This makes the behavior of untagged records identical to that
+of tagged types in this respect.
+
+This change is an incompatibility with previous versions of Ada, but it
+corrects a non-uniformity that was often a source of confusion. Analysis of
+a large number of industrial programs indicates that in those rare cases
+where a composite type had an untagged record component with a user-defined
+equality, either there was no use of the composite equality, or else the code
+expected the same composability as for tagged types, and thus had a bug that
+would be fixed by this change.
+
+RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24)
+8.05.04 (8)
+@end itemize
+
+@geindex AI-0088 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0088 The value of exponentiation (0000-00-00)'
+
+This AI clarifies the equivalence rule given for the dynamic semantics of
+exponentiation: the value of the operation can be obtained by repeated
+multiplication, but the operation can be implemented otherwise (for example
+using the familiar divide-by-two-and-square algorithm, even if this is less
+accurate), and does not imply repeated reads of a volatile base.
+
+RM References: 4.05.06 (11)
+@end itemize
+
+@geindex AI-0188 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0188 Case expressions (2010-01-09)'
+
+Case expressions are permitted. This allows use of constructs such as:
+
+@example
+X := (case Y is when 1 => 2, when 2 => 3, when others => 31)
+@end example
+
+RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33)
+@end itemize
+
+@geindex AI-0104 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0104 Null exclusion and uninitialized allocator (2010-07-15)'
+
+The assignment @code{Ptr := new not null Some_Ptr;} will raise
+@code{Constraint_Error} because the default value of the allocated object is
+`null'. This useless construct is illegal in Ada 2012.
+
+RM References: 4.08 (2)
+@end itemize
+
+@geindex AI-0157 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0157 Allocation/Deallocation from empty pool (2010-07-11)'
+
+Allocation and Deallocation from an empty storage pool (i.e. allocation or
+deallocation of a pointer for which a static storage size clause of zero
+has been given) is now illegal and is detected as such. GNAT
+previously gave a warning but not an error.
+
+RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17)
+@end itemize
+
+@geindex AI-0179 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0179 Statement not required after label (2010-04-10)'
+
+It is not necessary to have a statement following a label, so a label
+can appear at the end of a statement sequence without the need for putting a
+null statement afterwards, but it is not allowable to have only labels and
+no real statements in a statement sequence.
+
+RM References: 5.01 (2)
+@end itemize
+
+@geindex AI-0139-2 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0139-2 Syntactic sugar for iterators (2010-09-29)'
+
+The new syntax for iterating over arrays and containers is now implemented.
+Iteration over containers is for now limited to read-only iterators. Only
+default iterators are supported, with the syntax: @code{for Elem of C}.
+
+RM References: 5.05
+@end itemize
+
+@geindex AI-0134 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0134 Profiles must match for full conformance (0000-00-00)'
+
+For full conformance, the profiles of anonymous-access-to-subprogram
+parameters must match. GNAT has always enforced this rule.
+
+RM References: 6.03.01 (18)
+@end itemize
+
+@geindex AI-0207 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0207 Mode conformance and access constant (0000-00-00)'
+
+This AI confirms that access_to_constant indication must match for mode
+conformance. This was implemented in GNAT when the qualifier was originally
+introduced in Ada 2005.
+
+RM References: 6.03.01 (16/2)
+@end itemize
+
+@geindex AI-0046 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0046 Null exclusion match for full conformance (2010-07-17)'
+
+For full conformance, in the case of access parameters, the null exclusion
+must match (either both or neither must have @code{not null}).
+
+RM References: 6.03.02 (18)
+@end itemize
+
+@geindex AI-0118 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0118 The association of parameter associations (0000-00-00)'
+
+This AI clarifies the rules for named associations in subprogram calls and
+generic instantiations. The rules have been in place since Ada 83.
+
+RM References: 6.04.01 (2) 12.03 (9)
+@end itemize
+
+@geindex AI-0196 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0196 Null exclusion tests for out parameters (0000-00-00)'
+
+Null exclusion checks are not made for @code{out} parameters when
+evaluating the actual parameters. GNAT has never generated these checks.
+
+RM References: 6.04.01 (13)
+@end itemize
+
+@geindex AI-0015 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0015 Constant return objects (0000-00-00)'
+
+The return object declared in an `extended_return_statement' may be
+declared constant. This was always intended, and GNAT has always allowed it.
+
+RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2)
+6.05 (5.7/2)
+@end itemize
+
+@geindex AI-0032 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0032 Extended return for class-wide functions (0000-00-00)'
+
+If a function returns a class-wide type, the object of an extended return
+statement can be declared with a specific type that is covered by the class-
+wide type. This has been implemented in GNAT since the introduction of
+extended returns. Note AI-0103 complements this AI by imposing matching
+rules for constrained return types.
+
+RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2)
+6.05 (8/2)
+@end itemize
+
+@geindex AI-0103 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0103 Static matching for extended return (2010-07-23)'
+
+If the return subtype of a function is an elementary type or a constrained
+type, the subtype indication in an extended return statement must match
+statically this return subtype.
+
+RM References: 6.05 (5.2/2)
+@end itemize
+
+@geindex AI-0058 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0058 Abnormal completion of an extended return (0000-00-00)'
+
+The RM had some incorrect wording implying wrong treatment of abnormal
+completion in an extended return. GNAT has always implemented the intended
+correct semantics as described by this AI.
+
+RM References: 6.05 (22/2)
+@end itemize
+
+@geindex AI-0050 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0050 Raising Constraint_Error early for function call (0000-00-00)'
+
+The implementation permissions for raising @code{Constraint_Error} early on a function call
+when it was clear an exception would be raised were over-permissive and allowed
+mishandling of discriminants in some cases. GNAT did
+not take advantage of these incorrect permissions in any case.
+
+RM References: 6.05 (24/2)
+@end itemize
+
+@geindex AI-0125 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0125 Nonoverridable operations of an ancestor (2010-09-28)'
+
+In Ada 2012, the declaration of a primitive operation of a type extension
+or private extension can also override an inherited primitive that is not
+visible at the point of this declaration.
+
+RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2)
+@end itemize
+
+@geindex AI-0062 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0062 Null exclusions and deferred constants (0000-00-00)'
+
+A full constant may have a null exclusion even if its associated deferred
+constant does not. GNAT has always allowed this.
+
+RM References: 7.04 (6/2) 7.04 (7.1/2)
+@end itemize
+
+@geindex AI-0178 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0178 Incomplete views are limited (0000-00-00)'
+
+This AI clarifies the role of incomplete views and plugs an omission in the
+RM. GNAT always correctly restricted the use of incomplete views and types.
+
+RM References: 7.05 (3/2) 7.05 (6/2)
+@end itemize
+
+@geindex AI-0087 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0087 Actual for formal nonlimited derived type (2010-07-15)'
+
+The actual for a formal nonlimited derived type cannot be limited. In
+particular, a formal derived type that extends a limited interface but which
+is not explicitly limited cannot be instantiated with a limited type.
+
+RM References: 7.05 (5/2) 12.05.01 (5.1/2)
+@end itemize
+
+@geindex AI-0099 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0099 Tag determines whether finalization needed (0000-00-00)'
+
+This AI clarifies that ‘needs finalization’ is part of dynamic semantics,
+and therefore depends on the run-time characteristics of an object (i.e. its
+tag) and not on its nominal type. As the AI indicates: “we do not expect
+this to affect any implementation’’.
+
+RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2)
+@end itemize
+
+@geindex AI-0064 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0064 Redundant finalization rule (0000-00-00)'
+
+This is an editorial change only. The intended behavior is already checked
+by an existing ACATS test, which GNAT has always executed correctly.
+
+RM References: 7.06.01 (17.1/1)
+@end itemize
+
+@geindex AI-0026 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0026 Missing rules for Unchecked_Union (2010-07-07)'
+
+Record representation clauses concerning Unchecked_Union types cannot mention
+the discriminant of the type. The type of a component declared in the variant
+part of an Unchecked_Union cannot be controlled, have controlled components,
+nor have protected or task parts. If an Unchecked_Union type is declared
+within the body of a generic unit or its descendants, then the type of a
+component declared in the variant part cannot be a formal private type or a
+formal private extension declared within the same generic unit.
+
+RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2)
+@end itemize
+
+@geindex AI-0205 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0205 Extended return declares visible name (0000-00-00)'
+
+This AI corrects a simple omission in the RM. Return objects have always
+been visible within an extended return statement.
+
+RM References: 8.03 (17)
+@end itemize
+
+@geindex AI-0042 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0042 Overriding versus implemented-by (0000-00-00)'
+
+This AI fixes a wording gap in the RM. An operation of a synchronized
+interface can be implemented by a protected or task entry, but the abstract
+operation is not being overridden in the usual sense, and it must be stated
+separately that this implementation is legal. This has always been the case
+in GNAT.
+
+RM References: 9.01 (9.2/2) 9.04 (11.1/2)
+@end itemize
+
+@geindex AI-0030 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0030 Requeue on synchronized interfaces (2010-07-19)'
+
+Requeue is permitted to a protected, synchronized or task interface primitive
+providing it is known that the overriding operation is an entry. Otherwise
+the requeue statement has the same effect as a procedure call. Use of pragma
+@code{Implemented} provides a way to impose a static requirement on the
+overriding operation by adhering to one of the implementation kinds: entry,
+protected procedure or any of the above.
+
+RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5)
+9.05.04 (6) 9.05.04 (7) 9.05.04 (12)
+@end itemize
+
+@geindex AI-0201 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0201 Independence of atomic object components (2010-07-22)'
+
+If an Atomic object has a pragma @code{Pack} or a @code{Component_Size}
+attribute, then individual components may not be addressable by independent
+tasks. However, if the representation clause has no effect (is confirming),
+then independence is not compromised. Furthermore, in GNAT, specification of
+other appropriately addressable component sizes (e.g. 16 for 8-bit
+characters) also preserves independence. GNAT now gives very clear warnings
+both for the declaration of such a type, and for any assignment to its components.
+
+RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2)
+@end itemize
+
+@geindex AI-0009 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0009 Pragma Independent[_Components] (2010-07-23)'
+
+This AI introduces the new pragmas @code{Independent} and
+@code{Independent_Components},
+which control guaranteeing independence of access to objects and components.
+The AI also requires independence not unaffected by confirming rep clauses.
+
+RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2)
+C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14)
+@end itemize
+
+@geindex AI-0072 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0072 Task signalling using ‘Terminated (0000-00-00)'
+
+This AI clarifies that task signalling for reading @code{'Terminated} only
+occurs if the result is True. GNAT semantics has always been consistent with
+this notion of task signalling.
+
+RM References: 9.10 (6.1/1)
+@end itemize
+
+@geindex AI-0108 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0108 Limited incomplete view and discriminants (0000-00-00)'
+
+This AI confirms that an incomplete type from a limited view does not have
+discriminants. This has always been the case in GNAT.
+
+RM References: 10.01.01 (12.3/2)
+@end itemize
+
+@geindex AI-0129 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0129 Limited views and incomplete types (0000-00-00)'
+
+This AI clarifies the description of limited views: a limited view of a
+package includes only one view of a type that has an incomplete declaration
+and a full declaration (there is no possible ambiguity in a client package).
+This AI also fixes an omission: a nested package in the private part has no
+limited view. GNAT always implemented this correctly.
+
+RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2)
+@end itemize
+
+@geindex AI-0077 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0077 Limited withs and scope of declarations (0000-00-00)'
+
+This AI clarifies that a declaration does not include a context clause,
+and confirms that it is illegal to have a context in which both a limited
+and a nonlimited view of a package are accessible. Such double visibility
+was always rejected by GNAT.
+
+RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2)
+@end itemize
+
+@geindex AI-0122 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0122 Private with and children of generics (0000-00-00)'
+
+This AI clarifies the visibility of private children of generic units within
+instantiations of a parent. GNAT has always handled this correctly.
+
+RM References: 10.01.02 (12/2)
+@end itemize
+
+@geindex AI-0040 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0040 Limited with clauses on descendant (0000-00-00)'
+
+This AI confirms that a limited with clause in a child unit cannot name
+an ancestor of the unit. This has always been checked in GNAT.
+
+RM References: 10.01.02 (20/2)
+@end itemize
+
+@geindex AI-0132 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0132 Placement of library unit pragmas (0000-00-00)'
+
+This AI fills a gap in the description of library unit pragmas. The pragma
+clearly must apply to a library unit, even if it does not carry the name
+of the enclosing unit. GNAT has always enforced the required check.
+
+RM References: 10.01.05 (7)
+@end itemize
+
+@geindex AI-0034 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0034 Categorization of limited views (0000-00-00)'
+
+The RM makes certain limited with clauses illegal because of categorization
+considerations, when the corresponding normal with would be legal. This is
+not intended, and GNAT has always implemented the recommended behavior.
+
+RM References: 10.02.01 (11/1) 10.02.01 (17/2)
+@end itemize
+
+@geindex AI-0035 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0035 Inconsistencies with Pure units (0000-00-00)'
+
+This AI remedies some inconsistencies in the legality rules for Pure units.
+Derived access types are legal in a pure unit (on the assumption that the
+rule for a zero storage pool size has been enforced on the ancestor type).
+The rules are enforced in generic instances and in subunits. GNAT has always
+implemented the recommended behavior.
+
+RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2)
+@end itemize
+
+@geindex AI-0219 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0219 Pure permissions and limited parameters (2010-05-25)'
+
+This AI refines the rules for the cases with limited parameters which do not
+allow the implementations to omit ‘redundant’. GNAT now properly conforms
+to the requirements of this binding interpretation.
+
+RM References: 10.02.01 (18/2)
+@end itemize
+
+@geindex AI-0043 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0043 Rules about raising exceptions (0000-00-00)'
+
+This AI covers various omissions in the RM regarding the raising of
+exceptions. GNAT has always implemented the intended semantics.
+
+RM References: 11.04.01 (10.1/2) 11 (2)
+@end itemize
+
+@geindex AI-0200 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0200 Mismatches in formal package declarations (0000-00-00)'
+
+This AI plugs a gap in the RM which appeared to allow some obviously intended
+illegal instantiations. GNAT has never allowed these instantiations.
+
+RM References: 12.07 (16)
+@end itemize
+
+@geindex AI-0112 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0112 Detection of duplicate pragmas (2010-07-24)'
+
+This AI concerns giving names to various representation aspects, but the
+practical effect is simply to make the use of duplicate
+@code{Atomic[_Components]},
+@code{Volatile[_Components]}, and
+@code{Independent[_Components]} pragmas illegal, and GNAT
+now performs this required check.
+
+RM References: 13.01 (8)
+@end itemize
+
+@geindex AI-0106 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0106 No representation pragmas on generic formals (0000-00-00)'
+
+The RM appeared to allow representation pragmas on generic formal parameters,
+but this was not intended, and GNAT has never permitted this usage.
+
+RM References: 13.01 (9.1/1)
+@end itemize
+
+@geindex AI-0012 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)'
+
+It is now illegal to give an inappropriate component size or a pragma
+@code{Pack} that attempts to change the component size in the case of atomic
+or aliased components. Previously GNAT ignored such an attempt with a
+warning.
+
+RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21)
+@end itemize
+
+@geindex AI-0039 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0039 Stream attributes cannot be dynamic (0000-00-00)'
+
+The RM permitted the use of dynamic expressions (such as @code{ptr.all})`
+for stream attributes, but these were never useful and are now illegal. GNAT
+has always regarded such expressions as illegal.
+
+RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2)
+@end itemize
+
+@geindex AI-0095 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0095 Address of intrinsic subprograms (0000-00-00)'
+
+The prefix of @code{'Address} cannot statically denote a subprogram with
+convention @code{Intrinsic}. The use of the @code{Address} attribute raises
+@code{Program_Error} if the prefix denotes a subprogram with convention
+@code{Intrinsic}.
+
+RM References: 13.03 (11/1)
+@end itemize
+
+@geindex AI-0116 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0116 Alignment of class-wide objects (0000-00-00)'
+
+This AI requires that the alignment of a class-wide object be no greater
+than the alignment of any type in the class. GNAT has always followed this
+recommendation.
+
+RM References: 13.03 (29) 13.11 (16)
+@end itemize
+
+@geindex AI-0146 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0146 Type invariants (2009-09-21)'
+
+Type invariants may be specified for private types using the aspect notation.
+Aspect @code{Type_Invariant} may be specified for any private type,
+@code{Type_Invariant'Class} can
+only be specified for tagged types, and is inherited by any descendent of the
+tagged types. The invariant is a boolean expression that is tested for being
+true in the following situations: conversions to the private type, object
+declarations for the private type that are default initialized, and
+[`in'] `out'
+parameters and returned result on return from any primitive operation for
+the type that is visible to a client.
+GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and
+@code{Invariant'Class} for @code{Type_Invariant'Class}.
+
+RM References: 13.03.03 (00)
+@end itemize
+
+@geindex AI-0078 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)'
+
+In Ada 2012, compilers are required to support unchecked conversion where the
+target alignment is a multiple of the source alignment. GNAT always supported
+this case (and indeed all cases of differing alignments, doing copies where
+required if the alignment was reduced).
+
+RM References: 13.09 (7)
+@end itemize
+
+@geindex AI-0195 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0195 Invalid value handling is implementation defined (2010-07-03)'
+
+The handling of invalid values is now designated to be implementation
+defined. This is a documentation change only, requiring Annex M in the GNAT
+Reference Manual to document this handling.
+In GNAT, checks for invalid values are made
+only when necessary to avoid erroneous behavior. Operations like assignments
+which cannot cause erroneous behavior ignore the possibility of invalid
+values and do not do a check. The date given above applies only to the
+documentation change, this behavior has always been implemented by GNAT.
+
+RM References: 13.09.01 (10)
+@end itemize
+
+@geindex AI-0193 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0193 Alignment of allocators (2010-09-16)'
+
+This AI introduces a new attribute @code{Max_Alignment_For_Allocation},
+analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead
+of size.
+
+RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1)
+13.11.01 (2) 13.11.01 (3)
+@end itemize
+
+@geindex AI-0177 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0177 Parameterized expressions (2010-07-10)'
+
+The new Ada 2012 notion of parameterized expressions is implemented. The form
+is:
+
+@example
+function-specification is (expression)
+@end example
+
+This is exactly equivalent to the
+corresponding function body that returns the expression, but it can appear
+in a package spec. Note that the expression must be parenthesized.
+
+RM References: 13.11.01 (3/2)
+@end itemize
+
+@geindex AI-0033 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)'
+
+Neither of these two pragmas may appear within a generic template, because
+the generic might be instantiated at other than the library level.
+
+RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2)
+@end itemize
+
+@geindex AI-0161 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)'
+
+A new restriction @code{No_Default_Stream_Attributes} prevents the use of any
+of the default stream attributes for elementary types. If this restriction is
+in force, then it is necessary to provide explicit subprograms for any
+stream attributes used.
+
+RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2)
+@end itemize
+
+@geindex AI-0194 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0194 Value of Stream_Size attribute (0000-00-00)'
+
+The @code{Stream_Size} attribute returns the default number of bits in the
+stream representation of the given type.
+This value is not affected by the presence
+of stream subprogram attributes for the type. GNAT has always implemented
+this interpretation.
+
+RM References: 13.13.02 (1.2/2)
+@end itemize
+
+@geindex AI-0109 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0109 Redundant check in S’Class’Input (0000-00-00)'
+
+This AI is an editorial change only. It removes the need for a tag check
+that can never fail.
+
+RM References: 13.13.02 (34/2)
+@end itemize
+
+@geindex AI-0007 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0007 Stream read and private scalar types (0000-00-00)'
+
+The RM as written appeared to limit the possibilities of declaring read
+attribute procedures for private scalar types. This limitation was not
+intended, and has never been enforced by GNAT.
+
+RM References: 13.13.02 (50/2) 13.13.02 (51/2)
+@end itemize
+
+@geindex AI-0065 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0065 Remote access types and external streaming (0000-00-00)'
+
+This AI clarifies the fact that all remote access types support external
+streaming. This fixes an obvious oversight in the definition of the
+language, and GNAT always implemented the intended correct rules.
+
+RM References: 13.13.02 (52/2)
+@end itemize
+
+@geindex AI-0019 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0019 Freezing of primitives for tagged types (0000-00-00)'
+
+The RM suggests that primitive subprograms of a specific tagged type are
+frozen when the tagged type is frozen. This would be an incompatible change
+and is not intended. GNAT has never attempted this kind of freezing and its
+behavior is consistent with the recommendation of this AI.
+
+RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2)
+@end itemize
+
+@geindex AI-0017 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0017 Freezing and incomplete types (0000-00-00)'
+
+So-called ‘Taft-amendment types’ (i.e., types that are completed in package
+bodies) are not frozen by the occurrence of bodies in the
+enclosing declarative part. GNAT always implemented this properly.
+
+RM References: 13.14 (3/1)
+@end itemize
+
+@geindex AI-0060 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0060 Extended definition of remote access types (0000-00-00)'
+
+This AI extends the definition of remote access types to include access
+to limited, synchronized, protected or task class-wide interface types.
+GNAT already implemented this extension.
+
+RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18)
+@end itemize
+
+@geindex AI-0114 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0114 Classification of letters (0000-00-00)'
+
+The code points 170 (@code{FEMININE ORDINAL INDICATOR}),
+181 (@code{MICRO SIGN}), and
+186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered
+lower case letters by Unicode.
+However, they are not allowed in identifiers, and they
+return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}.
+This behavior is consistent with that defined in Ada 95.
+
+RM References: A.03.02 (59) A.04.06 (7)
+@end itemize
+
+@geindex AI-0185 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)'
+
+Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide
+classification functions for @code{Wide_Character} and
+@code{Wide_Wide_Character}, as well as providing
+case folding routines for @code{Wide_[Wide_]Character} and
+@code{Wide_[Wide_]String}.
+
+RM References: A.03.05 (0) A.03.06 (0)
+@end itemize
+
+@geindex AI-0031 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0031 Add From parameter to Find_Token (2010-07-25)'
+
+A new version of @code{Find_Token} is added to all relevant string packages,
+with an extra parameter @code{From}. Instead of starting at the first
+character of the string, the search for a matching Token starts at the
+character indexed by the value of @code{From}.
+These procedures are available in all versions of Ada
+but if used in versions earlier than Ada 2012 they will generate a warning
+that an Ada 2012 subprogram is being used.
+
+RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51)
+A.04.05 (46)
+@end itemize
+
+@geindex AI-0056 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0056 Index on null string returns zero (0000-00-00)'
+
+The wording in the Ada 2005 RM implied an incompatible handling of the
+@code{Index} functions, resulting in raising an exception instead of
+returning zero in some situations.
+This was not intended and has been corrected.
+GNAT always returned zero, and is thus consistent with this AI.
+
+RM References: A.04.03 (56.2/2) A.04.03 (58.5/2)
+@end itemize
+
+@geindex AI-0137 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0137 String encoding package (2010-03-25)'
+
+The packages @code{Ada.Strings.UTF_Encoding}, together with its child
+packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings},
+and @code{Wide_Wide_Strings} have been
+implemented. These packages (whose documentation can be found in the spec
+files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads},
+@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of
+@code{String}, @code{Wide_String}, and @code{Wide_Wide_String}
+values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
+UTF-16), as well as conversions between the different UTF encodings. With
+the exception of @code{Wide_Wide_Strings}, these packages are available in
+Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
+The @code{Wide_Wide_Strings} package
+is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
+mode since it uses @code{Wide_Wide_Character}).
+
+RM References: A.04.11
+@end itemize
+
+@geindex AI-0038 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0038 Minor errors in Text_IO (0000-00-00)'
+
+These are minor errors in the description on three points. The intent on
+all these points has always been clear, and GNAT has always implemented the
+correct intended semantics.
+
+RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24)
+@end itemize
+
+@geindex AI-0044 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0044 Restrictions on container instantiations (0000-00-00)'
+
+This AI places restrictions on allowed instantiations of generic containers.
+These restrictions are not checked by the compiler, so there is nothing to
+change in the implementation. This affects only the RM documentation.
+
+RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2)
+@end itemize
+
+@geindex AI-0127 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0127 Adding Locale Capabilities (2010-09-29)'
+
+This package provides an interface for identifying the current locale.
+
+RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06
+A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13
+@end itemize
+
+@geindex AI-0002 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0002 Export C with unconstrained arrays (0000-00-00)'
+
+The compiler is not required to support exporting an Ada subprogram with
+convention C if there are parameters or a return type of an unconstrained
+array type (such as @code{String}). GNAT allows such declarations but
+generates warnings. It is possible, but complicated, to write the
+corresponding C code and certainly such code would be specific to GNAT and
+non-portable.
+
+RM References: B.01 (17) B.03 (62) B.03 (71.1/2)
+@end itemize
+
+@geindex AI05-0216 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)'
+
+It is clearly the intention that @code{No_Task_Hierarchy} is intended to
+forbid tasks declared locally within subprograms, or functions returning task
+objects, and that is the implementation that GNAT has always provided.
+However the language in the RM was not sufficiently clear on this point.
+Thus this is a documentation change in the RM only.
+
+RM References: D.07 (3/3)
+@end itemize
+
+@geindex AI-0211 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)'
+
+The restriction @code{No_Relative_Delays} forbids any calls to the subprogram
+@code{Ada.Real_Time.Timing_Events.Set_Handler}.
+
+RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2)
+@end itemize
+
+@geindex AI-0190 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0190 pragma Default_Storage_Pool (2010-09-15)'
+
+This AI introduces a new pragma @code{Default_Storage_Pool}, which can be
+used to control storage pools globally.
+In particular, you can force every access
+type that is used for allocation (`new') to have an explicit storage pool,
+or you can declare a pool globally to be used for all access types that lack
+an explicit one.
+
+RM References: D.07 (8)
+@end itemize
+
+@geindex AI-0189 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0189 No_Allocators_After_Elaboration (2010-01-23)'
+
+This AI introduces a new restriction @code{No_Allocators_After_Elaboration},
+which says that no dynamic allocation will occur once elaboration is
+completed.
+In general this requires a run-time check, which is not required, and which
+GNAT does not attempt. But the static cases of allocators in a task body or
+in the body of the main program are detected and flagged at compile or bind
+time.
+
+RM References: D.07 (19.1/2) H.04 (23.3/2)
+@end itemize
+
+@geindex AI-0171 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)'
+
+A new package @code{System.Multiprocessors} is added, together with the
+definition of pragma @code{CPU} for controlling task affinity. A new no
+dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains},
+is added to the Ravenscar profile.
+
+RM References: D.13.01 (4/2) D.16
+@end itemize
+
+@geindex AI-0210 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0210 Correct Timing_Events metric (0000-00-00)'
+
+This is a documentation only issue regarding wording of metric requirements,
+that does not affect the implementation of the compiler.
+
+RM References: D.15 (24/2)
+@end itemize
+
+@geindex AI-0206 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0206 Remote types packages and preelaborate (2010-07-24)'
+
+Remote types packages are now allowed to depend on preelaborated packages.
+This was formerly considered illegal.
+
+RM References: E.02.02 (6)
+@end itemize
+
+@geindex AI-0152 (Ada 2012 feature)
+
+
+@itemize *
+
+@item
+`AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)'
+
+Restriction @code{No_Anonymous_Allocators} prevents the use of allocators
+where the type of the returned value is an anonymous access type.
+
+RM References: H.04 (8/1)
+@end itemize
+
+@node Security Hardening Features,Obsolescent Features,Implementation of Ada 2012 Features,Top
+@anchor{gnat_rm/security_hardening_features doc}@anchor{42b}@anchor{gnat_rm/security_hardening_features id1}@anchor{42c}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15}
+@chapter Security Hardening Features
+
+
+This chapter describes Ada extensions aimed at security hardening that
+are provided by GNAT.
+
+The features in this chapter are currently experimental and subject to
+change.
+
+@c Register Scrubbing:
+
+@menu
+* Register Scrubbing::
+* Stack Scrubbing::
+* Hardened Conditionals::
+* Hardened Booleans::
+* Control Flow Redundancy::
+
+@end menu
+
+@node Register Scrubbing,Stack Scrubbing,,Security Hardening Features
+@anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{42d}
+@section Register Scrubbing
+
+
+GNAT can generate code to zero-out hardware registers before returning
+from a subprogram.
+
+It can be enabled with the @code{-fzero-call-used-regs=`choice'}
+command-line option, to affect all subprograms in a compilation, and
+with a @code{Machine_Attribute} pragma, to affect only specific
+subprograms.
+
+@example
+procedure Foo;
+pragma Machine_Attribute (Foo, "zero_call_used_regs", "used");
+-- Before returning, Foo scrubs only call-clobbered registers
+-- that it uses itself.
+
+function Bar return Integer;
+pragma Machine_Attribute (Bar, "zero_call_used_regs", "all");
+-- Before returning, Bar scrubs all call-clobbered registers.
+@end example
+
+For usage and more details on the command-line option, on the
+@code{zero_call_used_regs} attribute, and on their use with other
+programming languages, see @cite{Using the GNU Compiler Collection (GCC)}.
+
+@c Stack Scrubbing:
+
+@node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features
+@anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{42e}
+@section Stack Scrubbing
+
+
+GNAT can generate code to zero-out stack frames used by subprograms.
+
+It can be activated with the @code{Machine_Attribute} pragma, on
+specific subprograms and variables, or their types. (This attribute
+always applies to a type, even when it is associated with a subprogram
+or a variable.)
+
+@example
+function Foo returns Integer;
+pragma Machine_Attribute (Foo, "strub");
+-- Foo and its callers are modified so as to scrub the stack
+-- space used by Foo after it returns. Shorthand for:
+-- pragma Machine_Attribute (Foo, "strub", "at-calls");
+
+procedure Bar;
+pragma Machine_Attribute (Bar, "strub", "internal");
+-- Bar is turned into a wrapper for its original body,
+-- and they scrub the stack used by the original body.
+
+Var : Integer;
+pragma Machine_Attribute (Var, "strub");
+-- Reading from Var in a subprogram enables stack scrubbing
+-- of the stack space used by the subprogram. Furthermore, if
+-- Var is declared within a subprogram, this also enables
+-- scrubbing of the stack space used by that subprogram.
+@end example
+
+Given these declarations, Foo has its type and body modified as
+follows:
+
+@example
+function Foo (<WaterMark> : in out System.Address) returns Integer
+is
+ -- ...
+begin
+ <__strub_update> (<WaterMark>); -- Updates the stack WaterMark.
+ -- ...
+end;
+@end example
+
+whereas its callers are modified from:
+
+@example
+X := Foo;
+@end example
+
+to:
+
+@example
+declare
+ <WaterMark> : System.Address;
+begin
+ <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>.
+ X := Foo (<WaterMark>);
+ <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>.
+end;
+@end example
+
+As for Bar, because it is strubbed in internal mode, its callers are
+not modified. Its definition is modified roughly as follows:
+
+@example
+procedure Bar is
+ <WaterMark> : System.Address;
+ procedure Strubbed_Bar (<WaterMark> : in out System.Address) is
+ begin
+ <__strub_update> (<WaterMark>); -- Updates the stack WaterMark.
+ -- original Bar body.
+ end Strubbed_Bar;
+begin
+ <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>.
+ Strubbed_Bar (<WaterMark>);
+ <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>.
+end Bar;
+@end example
+
+There are also @code{-fstrub=`choice'} command-line options to
+control default settings. For usage and more details on the
+command-line options, on the @code{strub} attribute, and their use with
+other programming languages, see @cite{Using the GNU Compiler Collection (GCC)}.
+
+Note that Ada secondary stacks are not scrubbed. The restriction
+@code{No_Secondary_Stack} avoids their use, and thus their accidental
+preservation of data that should be scrubbed.
+
+Attributes @code{Access} and @code{Unconstrained_Access} of variables and
+constants with @code{strub} enabled require types with @code{strub} enabled;
+there is no way to express an access-to-strub type otherwise.
+@code{Unchecked_Access} bypasses this constraint, but the resulting
+access type designates a non-strub type.
+
+@example
+VI : aliased Integer;
+pragma Machine_Attribute (VI, "strub");
+XsVI : access Integer := VI'Access; -- Error.
+UXsVI : access Integer := VI'Unchecked_Access; -- OK,
+-- UXsVI does *not* enable strub in subprograms that
+-- dereference it to obtain the UXsVI.all value.
+
+type Strub_Int is new Integer;
+pragma Machine_Attribute (Strub_Int, "strub");
+VSI : aliased Strub_Int;
+XsVSI : access Strub_Int := VSI'Access; -- OK,
+-- VSI and XsVSI.all both enable strub in subprograms that
+-- read their values.
+@end example
+
+Every access-to-subprogram type, renaming, and overriding and
+overridden dispatching operations that may refer to a subprogram with
+an attribute-modified interface must be annotated with the same
+interface-modifying attribute. Access-to-subprogram types can be
+explicitly converted to different strub modes, as long as they are
+interface-compatible (i.e., adding or removing @code{at-calls} is not
+allowed). For example, a @code{strub}-@code{disabled} subprogram can be
+turned @code{callable} through such an explicit conversion:
+
+@example
+type TBar is access procedure;
+
+type TBar_Callable is access procedure;
+pragma Machine_Attribute (TBar_Callable, "strub", "callable");
+-- The attribute modifies the procedure type, rather than the
+-- access type, because of the extra argument after "strub",
+-- only applicable to subprogram types.
+
+Bar_Callable_Ptr : constant TBar_Callable
+ := TBar_Callable (TBar'(Bar'Access));
+
+procedure Bar_Callable renames Bar_Callable_Ptr.all;
+pragma Machine_Attribute (Bar_Callable, "strub", "callable");
+@end example
+
+Note that the renaming declaration is expanded to a full subprogram
+body, it won’t be just an alias. Only if it is inlined will it be as
+efficient as a call by dereferencing the access-to-subprogram constant
+Bar_Callable_Ptr.
+
+@c Hardened Conditionals:
+
+@node Hardened Conditionals,Hardened Booleans,Stack Scrubbing,Security Hardening Features
+@anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{42f}
+@section Hardened Conditionals
+
+
+GNAT can harden conditionals to protect against control-flow attacks.
+
+This is accomplished by two complementary transformations, each
+activated by a separate command-line option.
+
+The option @code{-fharden-compares} enables hardening of compares
+that compute results stored in variables, adding verification that the
+reversed compare yields the opposite result, turning:
+
+@example
+B := X = Y;
+@end example
+
+into:
+
+@example
+B := X = Y;
+declare
+ NotB : Boolean := X /= Y; -- Computed independently of B.
+begin
+ if B = NotB then
+ <__builtin_trap>;
+ end if;
+end;
+@end example
+
+The option @code{-fharden-conditional-branches} enables hardening
+of compares that guard conditional branches, adding verification of
+the reversed compare to both execution paths, turning:
+
+@example
+if X = Y then
+ X := Z + 1;
+else
+ Y := Z - 1;
+end if;
+@end example
+
+into:
+
+@example
+if X = Y then
+ if X /= Y then -- Computed independently of X = Y.
+ <__builtin_trap>;
+ end if;
+ X := Z + 1;
+else
+ if X /= Y then -- Computed independently of X = Y.
+ null;
+ else
+ <__builtin_trap>;
+ end if;
+ Y := Z - 1;
+end if;
+@end example
+
+These transformations are introduced late in the compilation pipeline,
+long after boolean expressions are decomposed into separate compares,
+each one turned into either a conditional branch or a compare whose
+result is stored in a boolean variable or temporary. Compiler
+optimizations, if enabled, may also turn conditional branches into
+stored compares, and vice-versa, or into operations with implied
+conditionals (e.g. MIN and MAX). Conditionals may also be optimized
+out entirely, if their value can be determined at compile time, and
+occasionally multiple compares can be combined into one.
+
+It is thus difficult to predict which of these two options will affect
+a specific compare operation expressed in source code. Using both
+options ensures that every compare that is neither optimized out nor
+optimized into implied conditionals will be hardened.
+
+The addition of reversed compares can be observed by enabling the dump
+files of the corresponding passes, through command-line options
+@code{-fdump-tree-hardcmp} and @code{-fdump-tree-hardcbr},
+respectively.
+
+They are separate options, however, because of the significantly
+different performance impact of the hardening transformations.
+
+For usage and more details on the command-line options, see
+@cite{Using the GNU Compiler Collection (GCC)}. These options can
+be used with other programming languages supported by GCC.
+
+@c Hardened Booleans:
+
+@node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features
+@anchor{gnat_rm/security_hardening_features hardened-booleans}@anchor{430}
+@section Hardened Booleans
+
+
+Ada has built-in support for introducing boolean types with
+alternative representations, using representation clauses:
+
+@example
+type HBool is new Boolean;
+for HBool use (16#5a#, 16#a5#);
+for HBool'Size use 8;
+@end example
+
+When validity checking is enabled, the compiler will check that
+variables of such types hold values corresponding to the selected
+representations.
+
+There are multiple strategies for where to introduce validity checking
+(see @code{-gnatV} options). Their goal is to guard against
+various kinds of programming errors, and GNAT strives to omit checks
+when program logic rules out an invalid value, and optimizers may
+further remove checks found to be redundant.
+
+For additional hardening, the @code{hardbool} @code{Machine_Attribute}
+pragma can be used to annotate boolean types with representation
+clauses, so that expressions of such types used as conditions are
+checked even when compiling with @code{-gnatVT}:
+
+@example
+pragma Machine_Attribute (HBool, "hardbool");
+
+function To_Boolean (X : HBool) returns Boolean is (Boolean (X));
+@end example
+
+is compiled roughly like:
+
+@example
+function To_Boolean (X : HBool) returns Boolean is
+begin
+ if X not in True | False then
+ raise Constraint_Error;
+ elsif X in True then
+ return True;
+ else
+ return False;
+ end if;
+end To_Boolean;
+@end example
+
+Note that @code{-gnatVn} will disable even @code{hardbool} testing.
+
+Analogous behavior is available as a GCC extension to the C and
+Objective C programming languages, through the @code{hardbool} attribute,
+with the difference that, instead of raising a Constraint_Error
+exception, when a hardened boolean variable is found to hold a value
+that stands for neither True nor False, the program traps. For usage
+and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
+
+@c Control Flow Redundancy:
+
+@node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features
+@anchor{gnat_rm/security_hardening_features control-flow-redundancy}@anchor{431}
+@section Control Flow Redundancy
+
+
+GNAT can guard against unexpected execution flows, such as branching
+into the middle of subprograms, as in Return Oriented Programming
+exploits.
+
+In units compiled with @code{-fharden-control-flow-redundancy},
+subprograms are instrumented so that, every time they are called,
+basic blocks take note as control flows through them, and, before
+returning, subprograms verify that the taken notes are consistent with
+the control-flow graph.
+
+Functions with too many basic blocks, or with multiple return points,
+call a run-time function to perform the verification. Other functions
+perform the verification inline before returning.
+
+Optimizing the inlined verification can be quite time consuming, so
+the default upper limit for the inline mode is set at 16 blocks.
+Command-line option @code{--param hardcfr-max-inline-blocks=} can
+override it.
+
+Even though typically sparse control-flow graphs exhibit run-time
+verification time nearly proportional to the block count of a
+subprogram, it may become very significant for generated subprograms
+with thousands of blocks. Command-line option
+@code{--param hardcfr-max-blocks=} can set an upper limit for
+instrumentation.
+
+For each block that is marked as visited, the mechanism checks that at
+least one of its predecessors, and at least one of its successors, are
+also marked as visited.
+
+Verification is performed just before returning. Subprogram
+executions that complete by raising or propagating an exception bypass
+verification-and-return points. A subprogram that can only complete
+by raising or propagating an exception may have instrumentation
+disabled altogether.
+
+The instrumentation for hardening with control flow redundancy can be
+observed in dump files generated by the command-line option
+@code{-fdump-tree-hardcfr}.
+
+For more details on the control flow redundancy command-line options,
+see @cite{Using the GNU Compiler Collection (GCC)}. These options
+can be used with other programming languages supported by GCC.
+
+@node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top
+@anchor{gnat_rm/obsolescent_features doc}@anchor{432}@anchor{gnat_rm/obsolescent_features id1}@anchor{433}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16}
+@chapter Obsolescent Features
+
+
+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::
+* pragma Task_Info::
+* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads.
+
+@end menu
+
+@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features
+@anchor{gnat_rm/obsolescent_features id2}@anchor{434}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{435}
+@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,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features
+@anchor{gnat_rm/obsolescent_features id3}@anchor{436}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{437}
+@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,pragma Task_Info,pragma Ravenscar,Obsolescent Features
+@anchor{gnat_rm/obsolescent_features id4}@anchor{438}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{439}
+@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.
+
+@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features
+@anchor{gnat_rm/obsolescent_features id5}@anchor{43a}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{43b}
+@section pragma Task_Info
+
+
+The functionality provided by pragma @code{Task_Info} is now part of the
+Ada language. The @code{CPU} aspect and the package
+@code{System.Multiprocessors} offer a less system-dependent way to specify
+task affinity or to query the number of processors.
+
+Syntax
+
+@example
+pragma Task_Info (EXPRESSION);
+@end example
+
+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 package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features
+@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{43c}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{43d}
+@section package System.Task_Info (@code{s-tasinf.ads})
+
+
+This package provides target dependent functionality that is used
+to support the @code{Task_Info} pragma. The predefined Ada package
+@code{System.Multiprocessors} and the @code{CPU} aspect now provide a
+standard replacement for GNAT’s @code{Task_Info} functionality.
+
+@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top
+@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{43e}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{43f}
+@chapter Compatibility and Porting Guide
+
+
+This chapter presents some guidelines for developing portable Ada code,
+describes the compatibility issues that may arise between
+GNAT and other Ada compilation systems (including those for Ada 83),
+and shows how GNAT can expedite porting
+applications developed in other Ada environments.
+
+@menu
+* Writing Portable Fixed-Point Declarations::
+* Compatibility with Ada 83::
+* Compatibility between Ada 95 and Ada 2005::
+* Implementation-dependent characteristics::
+* Compatibility with Other Ada Systems::
+* Representation Clauses::
+* Compatibility with HP Ada 83::
+
+@end menu
+
+@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide
+@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{440}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{441}
+@section Writing Portable Fixed-Point Declarations
+
+
+The Ada Reference Manual gives an implementation freedom to choose bounds
+that are narrower by @code{Small} from the given bounds.
+For example, if we write
+
+@example
+type F1 is delta 1.0 range -128.0 .. +128.0;
+@end example
+
+then the implementation is allowed to choose -128.0 .. +127.0 if it
+likes, but is not required to do so.
+
+This leads to possible portability problems, so let’s have a closer
+look at this, and figure out how to avoid these problems.
+
+First, why does this freedom exist, and why would an implementation
+take advantage of it? To answer this, take a closer look at the type
+declaration for @code{F1} above. If the compiler uses the given bounds,
+it would need 9 bits to hold the largest positive value (and typically
+that means 16 bits on all machines). But if the implementation chooses
+the +127.0 bound then it can fit values of the type in 8 bits.
+
+Why not make the user write +127.0 if that’s what is wanted?
+The rationale is that if you are thinking of fixed point
+as a kind of ‘poor man’s floating-point’, then you don’t want
+to be thinking about the scaled integers that are used in its
+representation. Let’s take another example:
+
+@example
+type F2 is delta 2.0**(-15) range -1.0 .. +1.0;
+@end example
+
+Looking at this declaration, it seems casually as though
+it should fit in 16 bits, but again that extra positive value
++1.0 has the scaled integer equivalent of 2**15 which is one too
+big for signed 16 bits. The implementation can treat this as:
+
+@example
+type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15));
+@end example
+
+and the Ada language design team felt that this was too annoying
+to require. We don’t need to debate this decision at this point,
+since it is well established (the rule about narrowing the ranges
+dates to Ada 83).
+
+But the important point is that an implementation is not required
+to do this narrowing, so we have a potential portability problem.
+We could imagine three types of implementation:
+
+
+@enumerate a
+
+@item
+those that narrow the range automatically if they can figure
+out that the narrower range will allow storage in a smaller machine unit,
+
+@item
+those that will narrow only if forced to by a @code{'Size} clause, and
+
+@item
+those that will never narrow.
+@end enumerate
+
+Now if we are language theoreticians, we can imagine a fourth
+approach: to narrow all the time, e.g. to treat
+
+@example
+type F3 is delta 1.0 range -10.0 .. +23.0;
+@end example
+
+as though it had been written:
+
+@example
+type F3 is delta 1.0 range -9.0 .. +22.0;
+@end example
+
+But although technically allowed, such a behavior would be hostile and silly,
+and no real compiler would do this. All real compilers will fall into one of
+the categories (a), (b) or (c) above.
+
+So, how do you get the compiler to do what you want? The answer is give the
+actual bounds you want, and then use a @code{'Small} clause and a
+@code{'Size} clause to absolutely pin down what the compiler does.
+E.g., for @code{F2} above, we will write:
+
+@example
+My_Small : constant := 2.0**(-15);
+My_First : constant := -1.0;
+My_Last : constant := +1.0 - My_Small;
+
+type F2 is delta My_Small range My_First .. My_Last;
+@end example
+
+and then add
+
+@example
+for F2'Small use my_Small;
+for F2'Size use 16;
+@end example
+
+In practice all compilers will do the same thing here and will give you
+what you want, so the above declarations are fully portable. If you really
+want to play language lawyer and guard against ludicrous behavior by the
+compiler you could add
+
+@example
+Test1 : constant := 1 / Boolean'Pos (F2'First = My_First);
+Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last);
+@end example
+
+One or other or both are allowed to be illegal if the compiler is
+behaving in a silly manner, but at least the silly compiler will not
+get away with silently messing with your (very clear) intentions.
+
+If you follow this scheme you will be guaranteed that your fixed-point
+types will be portable.
+
+@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{442}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{443}
+@section Compatibility with Ada 83
+
+
+@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012)
+
+Ada 95 and the subsequent revisions Ada 2005 and Ada 2012
+are highly upwards compatible with Ada 83. In
+particular, the design intention was that the difficulties associated
+with moving from Ada 83 to later versions of the standard should be no greater
+than those that occur when moving from one Ada 83 system to another.
+
+However, there are a number of points at which there are minor
+incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains
+full details of these issues as they relate to Ada 95,
+and should be consulted for a complete treatment.
+In practice the
+following subsections treat the most likely issues to be encountered.
+
+@menu
+* Legal Ada 83 programs that are illegal in Ada 95::
+* More deterministic semantics::
+* Changed semantics::
+* Other language compatibility issues::
+
+@end menu
+
+@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83
+@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{444}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{445}
+@subsection Legal Ada 83 programs that are illegal in Ada 95
+
+
+Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
+Ada 95 and later versions of the standard:
+
+
+@itemize *
+
+@item
+`Character literals'
+
+Some uses of character literals are ambiguous. Since Ada 95 has introduced
+@code{Wide_Character} as a new predefined character type, some uses of
+character literals that were legal in Ada 83 are illegal in Ada 95.
+For example:
+
+@example
+for Char in 'A' .. 'Z' loop ... end loop;
+@end example
+
+The problem is that ‘A’ and ‘Z’ could be from either
+@code{Character} or @code{Wide_Character}. The simplest correction
+is to make the type explicit; e.g.:
+
+@example
+for Char in Character range 'A' .. 'Z' loop ... end loop;
+@end example
+
+@item
+`New reserved words'
+
+The identifiers @code{abstract}, @code{aliased}, @code{protected},
+@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95.
+Existing Ada 83 code using any of these identifiers must be edited to
+use some alternative name.
+
+@item
+`Freezing rules'
+
+The rules in Ada 95 are slightly different with regard to the point at
+which entities are frozen, and representation pragmas and clauses are
+not permitted past the freeze point. This shows up most typically in
+the form of an error message complaining that a representation item
+appears too late, and the appropriate corrective action is to move
+the item nearer to the declaration of the entity to which it refers.
+
+A particular case is that representation pragmas
+cannot be applied to a subprogram body. If necessary, a separate subprogram
+declaration must be introduced to which the pragma can be applied.
+
+@item
+`Optional bodies for library packages'
+
+In Ada 83, a package that did not require a package body was nevertheless
+allowed to have one. This lead to certain surprises in compiling large
+systems (situations in which the body could be unexpectedly ignored by the
+binder). In Ada 95, if a package does not require a body then it is not
+permitted to have a body. To fix this problem, simply remove a redundant
+body if it is empty, or, if it is non-empty, introduce a dummy declaration
+into the spec that makes the body required. One approach is to add a private
+part to the package declaration (if necessary), and define a parameterless
+procedure called @code{Requires_Body}, which must then be given a dummy
+procedure body in the package body, which then becomes required.
+Another approach (assuming that this does not introduce elaboration
+circularities) is to add an @code{Elaborate_Body} pragma to the package spec,
+since one effect of this pragma is to require the presence of a package body.
+
+@item
+`Numeric_Error is the same exception as Constraint_Error'
+
+In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}.
+This means that it is illegal to have separate exception handlers for
+the two exceptions. The fix is simply to remove the handler for the
+@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise
+@code{Constraint_Error} in place of @code{Numeric_Error} in all cases).
+
+@item
+`Indefinite subtypes in generics'
+
+In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String})
+as the actual for a generic formal private type, but then the instantiation
+would be illegal if there were any instances of declarations of variables
+of this type in the generic body. In Ada 95, to avoid this clear violation
+of the methodological principle known as the ‘contract model’,
+the generic declaration explicitly indicates whether
+or not such instantiations are permitted. If a generic formal parameter
+has explicit unknown discriminants, indicated by using @code{(<>)} after the
+subtype name, then it can be instantiated with indefinite types, but no
+stand-alone variables can be declared of this type. Any attempt to declare
+such a variable will result in an illegality at the time the generic is
+declared. If the @code{(<>)} notation is not used, then it is illegal
+to instantiate the generic with an indefinite type.
+This is the potential incompatibility issue when porting Ada 83 code to Ada 95.
+It will show up as a compile time error, and
+the fix is usually simply to add the @code{(<>)} to the generic declaration.
+@end itemize
+
+@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83
+@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{447}
+@subsection More deterministic semantics
+
+
+
+@itemize *
+
+@item
+`Conversions'
+
+Conversions from real types to integer types round away from 0. In Ada 83
+the conversion Integer(2.5) could deliver either 2 or 3 as its value. This
+implementation freedom was intended to support unbiased rounding in
+statistical applications, but in practice it interfered with portability.
+In Ada 95 the conversion semantics are unambiguous, and rounding away from 0
+is required. Numeric code may be affected by this change in semantics.
+Note, though, that this issue is no worse than already existed in Ada 83
+when porting code from one vendor to another.
+
+@item
+`Tasking'
+
+The Real-Time Annex introduces a set of policies that define the behavior of
+features that were implementation dependent in Ada 83, such as the order in
+which open select branches are executed.
+@end itemize
+
+@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83
+@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{448}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{449}
+@subsection Changed semantics
+
+
+The worst kind of incompatibility is one where a program that is legal in
+Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not
+possible in Ada 83. Fortunately this is extremely rare, but the one
+situation that you should be alert to is the change in the predefined type
+@code{Character} from 7-bit ASCII to 8-bit Latin-1.
+
+@quotation
+
+@geindex Latin-1
+@end quotation
+
+
+@itemize *
+
+@item
+`Range of type `@w{`}Character`@w{`}'
+
+The range of @code{Standard.Character} is now the full 256 characters
+of Latin-1, whereas in most Ada 83 implementations it was restricted
+to 128 characters. Although some of the effects of
+this change will be manifest in compile-time rejection of legal
+Ada 83 programs it is possible for a working Ada 83 program to have
+a different effect in Ada 95, one that was not permitted in Ada 83.
+As an example, the expression
+@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now
+delivers @code{255} as its value.
+In general, you should look at the logic of any
+character-processing Ada 83 program and see whether it needs to be adapted
+to work correctly with Latin-1. Note that the predefined Ada 95 API has a
+character handling package that may be relevant if code needs to be adapted
+to account for the additional Latin-1 elements.
+The desirable fix is to
+modify the program to accommodate the full character set, but in some cases
+it may be convenient to define a subtype or derived type of Character that
+covers only the restricted range.
+@end itemize
+
+@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83
+@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{44a}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{44b}
+@subsection Other language compatibility issues
+
+
+
+@itemize *
+
+@item
+`-gnat83' switch
+
+All implementations of GNAT provide a switch that causes GNAT to operate
+in Ada 83 mode. In this mode, some but not all compatibility problems
+of the type described above are handled automatically. For example, the
+new reserved words introduced in Ada 95 and Ada 2005 are treated simply
+as identifiers as in Ada 83. However,
+in practice, it is usually advisable to make the necessary modifications
+to the program to remove the need for using this switch.
+See the @code{Compiling Different Versions of Ada} section in
+the @cite{GNAT User’s Guide}.
+
+@item
+Support for removed Ada 83 pragmas and attributes
+
+A number of pragmas and attributes from Ada 83 were removed from Ada 95,
+generally because they were replaced by other mechanisms. Ada 95 and Ada 2005
+compilers are allowed, but not required, to implement these missing
+elements. In contrast with some other compilers, GNAT implements all
+such pragmas and attributes, eliminating this compatibility concern. These
+include @code{pragma Interface} and the floating point type attributes
+(@code{Emax}, @code{Mantissa}, etc.), among other items.
+@end itemize
+
+@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{44d}
+@section Compatibility between Ada 95 and Ada 2005
+
+
+@geindex Compatibility between Ada 95 and Ada 2005
+
+Although Ada 2005 was designed to be upwards compatible with Ada 95, there are
+a number of incompatibilities. Several are enumerated below;
+for a complete description please see the
+@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in
+@cite{Rationale for Ada 2005}.
+
+
+@itemize *
+
+@item
+`New reserved words.'
+
+The words @code{interface}, @code{overriding} and @code{synchronized} are
+reserved in Ada 2005.
+A pre-Ada 2005 program that uses any of these as an identifier will be
+illegal.
+
+@item
+`New declarations in predefined packages.'
+
+A number of packages in the predefined environment contain new declarations:
+@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings},
+@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded},
+@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed},
+@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded},
+@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}.
+If an Ada 95 program does a @code{with} and @code{use} of any of these
+packages, the new declarations may cause name clashes.
+
+@item
+`Access parameters.'
+
+A nondispatching subprogram with an access parameter cannot be renamed
+as a dispatching operation. This was permitted in Ada 95.
+
+@item
+`Access types, discriminants, and constraints.'
+
+Rule changes in this area have led to some incompatibilities; for example,
+constrained subtypes of some access types are not permitted in Ada 2005.
+
+@item
+`Aggregates for limited types.'
+
+The allowance of aggregates for limited types in Ada 2005 raises the
+possibility of ambiguities in legal Ada 95 programs, since additional types
+now need to be considered in expression resolution.
+
+@item
+`Fixed-point multiplication and division.'
+
+Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which
+were legal in Ada 95 and invoked the predefined versions of these operations,
+are now ambiguous.
+The ambiguity may be resolved either by applying a type conversion to the
+expression, or by explicitly invoking the operation from package
+@code{Standard}.
+
+@item
+`Return-by-reference types.'
+
+The Ada 95 return-by-reference mechanism has been removed. Instead, the user
+can declare a function returning a value from an anonymous access type.
+@end itemize
+
+@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide
+@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{44f}
+@section Implementation-dependent characteristics
+
+
+Although the Ada language defines the semantics of each construct as
+precisely as practical, in some situations (for example for reasons of
+efficiency, or where the effect is heavily dependent on the host or target
+platform) the implementation is allowed some freedom. In porting Ada 83
+code to GNAT, you need to be aware of whether / how the existing code
+exercised such implementation dependencies. Such characteristics fall into
+several categories, and GNAT offers specific support in assisting the
+transition from certain Ada 83 compilers.
+
+@menu
+* Implementation-defined pragmas::
+* Implementation-defined attributes::
+* Libraries::
+* Elaboration order::
+* Target-specific aspects::
+
+@end menu
+
+@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics
+@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{451}
+@subsection Implementation-defined pragmas
+
+
+Ada compilers are allowed to supplement the language-defined pragmas, and
+these are a potential source of non-portability. All GNAT-defined pragmas
+are described in @ref{7,,Implementation Defined Pragmas},
+and these include several that are specifically
+intended to correspond to other vendors’ Ada 83 pragmas.
+For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
+For compatibility with HP Ada 83, GNAT supplies the pragmas
+@code{Extend_System}, @code{Ident}, @code{Inline_Generic},
+@code{Interface_Name}, @code{Passive}, @code{Suppress_All},
+and @code{Volatile}.
+Other relevant pragmas include @code{External} and @code{Link_With}.
+Some vendor-specific
+Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are
+recognized, thus
+avoiding compiler rejection of units that contain such pragmas; they are not
+relevant in a GNAT context and hence are not otherwise implemented.
+
+@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics
+@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{453}
+@subsection Implementation-defined attributes
+
+
+Analogous to pragmas, the set of attributes may be extended by an
+implementation. All GNAT-defined attributes are described in
+@ref{8,,Implementation Defined Attributes},
+and these include several that are specifically intended
+to correspond to other vendors’ Ada 83 attributes. For migrating from VADS,
+the attribute @code{VADS_Size} may be useful. For compatibility with HP
+Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
+@code{Type_Class}.
+
+@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics
+@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{455}
+@subsection Libraries
+
+
+Vendors may supply libraries to supplement the standard Ada API. If Ada 83
+code uses vendor-specific libraries then there are several ways to manage
+this in Ada 95 and later versions of the standard:
+
+
+@itemize *
+
+@item
+If the source code for the libraries (specs and bodies) are
+available, then the libraries can be migrated in the same way as the
+application.
+
+@item
+If the source code for the specs but not the bodies are
+available, then you can reimplement the bodies.
+
+@item
+Some features introduced by Ada 95 obviate the need for library support. For
+example most Ada 83 vendors supplied a package for unsigned integers. The
+Ada 95 modular type feature is the preferred way to handle this need, so
+instead of migrating or reimplementing the unsigned integer package it may
+be preferable to retrofit the application using modular types.
+@end itemize
+
+@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics
+@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{457}
+@subsection Elaboration order
+
+
+The implementation can choose any elaboration order consistent with the unit
+dependency relationship. This freedom means that some orders can result in
+Program_Error being raised due to an ‘Access Before Elaboration’: an attempt
+to invoke a subprogram before its body has been elaborated, or to instantiate
+a generic before the generic body has been elaborated. By default GNAT
+attempts to choose a safe order (one that will not encounter access before
+elaboration problems) by implicitly inserting @code{Elaborate} or
+@code{Elaborate_All} pragmas where
+needed. However, this can lead to the creation of elaboration circularities
+and a resulting rejection of the program by gnatbind. This issue is
+thoroughly described in the `Elaboration Order Handling in GNAT' appendix
+in the @cite{GNAT User’s Guide}.
+In brief, there are several
+ways to deal with this situation:
+
+
+@itemize *
+
+@item
+Modify the program to eliminate the circularities, e.g., by moving
+elaboration-time code into explicitly-invoked procedures
+
+@item
+Constrain the elaboration order by including explicit @code{Elaborate_Body} or
+@code{Elaborate} pragmas, and then inhibit the generation of implicit
+@code{Elaborate_All}
+pragmas either globally (as an effect of the `-gnatE' switch) or locally
+(by selectively suppressing elaboration checks via pragma
+@code{Suppress(Elaboration_Check)} when it is safe to do so).
+@end itemize
+
+@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics
+@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{459}
+@subsection Target-specific aspects
+
+
+Low-level applications need to deal with machine addresses, data
+representations, interfacing with assembler code, and similar issues. If
+such an Ada 83 application is being ported to different target hardware (for
+example where the byte endianness has changed) then you will need to
+carefully examine the program logic; the porting effort will heavily depend
+on the robustness of the original design. Moreover, Ada 95 (and thus
+Ada 2005 and Ada 2012) are sometimes
+incompatible with typical Ada 83 compiler practices regarding implicit
+packing, the meaning of the Size attribute, and the size of access values.
+GNAT’s approach to these issues is described in @ref{45a,,Representation Clauses}.
+
+@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{45b}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{45c}
+@section Compatibility with Other Ada Systems
+
+
+If programs avoid the use of implementation dependent and
+implementation defined features, as documented in the
+@cite{Ada Reference Manual}, there should be a high degree of portability between
+GNAT and other Ada systems. The following are specific items which
+have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95
+compilers, but do not affect porting code to GNAT.
+(As of January 2007, GNAT is the only compiler available for Ada 2005;
+the following issues may or may not arise for Ada 2005 programs
+when other compilers appear.)
+
+
+@itemize *
+
+@item
+`Ada 83 Pragmas and Attributes'
+
+Ada 95 compilers are allowed, but not required, to implement the missing
+Ada 83 pragmas and attributes that are no longer defined in Ada 95.
+GNAT implements all such pragmas and attributes, eliminating this as
+a compatibility concern, but some other Ada 95 compilers reject these
+pragmas and attributes.
+
+@item
+`Specialized Needs Annexes'
+
+GNAT implements the full set of special needs annexes. At the
+current time, it is the only Ada 95 compiler to do so. This means that
+programs making use of these features may not be portable to other Ada
+95 compilation systems.
+
+@item
+`Representation Clauses'
+
+Some other Ada 95 compilers implement only the minimal set of
+representation clauses required by the Ada 95 reference manual. GNAT goes
+far beyond this minimal set, as described in the next section.
+@end itemize
+
+@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide
+@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{45d}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{45a}
+@section Representation Clauses
+
+
+The Ada 83 reference manual was quite vague in describing both the minimal
+required implementation of representation clauses, and also their precise
+effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the
+minimal set of capabilities required is still quite limited.
+
+GNAT implements the full required set of capabilities in
+Ada 95 and Ada 2005, but also goes much further, and in particular
+an effort has been made to be compatible with existing Ada 83 usage to the
+greatest extent possible.
+
+A few cases exist in which Ada 83 compiler behavior is incompatible with
+the requirements in Ada 95 (and thus also Ada 2005). These are instances of
+intentional or accidental dependence on specific implementation dependent
+characteristics of these Ada 83 compilers. The following is a list of
+the cases most likely to arise in existing Ada 83 code.
+
+
+@itemize *
+
+@item
+`Implicit Packing'
+
+Some Ada 83 compilers allowed a Size specification to cause implicit
+packing of an array or record. This could cause expensive implicit
+conversions for change of representation in the presence of derived
+types, and the Ada design intends to avoid this possibility.
+Subsequent AI’s were issued to make it clear that such implicit
+change of representation in response to a Size clause is inadvisable,
+and this recommendation is represented explicitly in the Ada 95 (and Ada 2005)
+Reference Manuals as implementation advice that is followed by GNAT.
+The problem will show up as an error
+message rejecting the size clause. The fix is simply to provide
+the explicit pragma @code{Pack}, or for more fine tuned control, provide
+a Component_Size clause.
+
+@item
+`Meaning of Size Attribute'
+
+The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as
+the minimal number of bits required to hold values of the type. For example,
+on a 32-bit machine, the size of @code{Natural} will typically be 31 and not
+32 (since no sign bit is required). Some Ada 83 compilers gave 31, and
+some 32 in this situation. This problem will usually show up as a compile
+time error, but not always. It is a good idea to check all uses of the
+‘Size attribute when porting Ada 83 code. The GNAT specific attribute
+Object_Size can provide a useful way of duplicating the behavior of
+some Ada 83 compiler systems.
+
+@item
+`Size of Access Types'
+
+A common assumption in Ada 83 code is that an access type is in fact a pointer,
+and that therefore it will be the same size as a System.Address value. This
+assumption is true for GNAT in most cases with one exception. For the case of
+a pointer to an unconstrained array type (where the bounds may vary from one
+value of the access type to another), the default is to use a ‘fat pointer’,
+which is represented as two separate pointers, one to the bounds, and one to
+the array. This representation has a number of advantages, including improved
+efficiency. However, it may cause some difficulties in porting existing Ada 83
+code which makes the assumption that, for example, pointers fit in 32 bits on
+a machine with 32-bit addressing.
+
+To get around this problem, GNAT also permits the use of ‘thin pointers’ for
+access types in this case (where the designated type is an unconstrained array
+type). These thin pointers are indeed the same size as a System.Address value.
+To specify a thin pointer, use a size clause for the type, for example:
+
+@example
+type X is access all String;
+for X'Size use Standard'Address_Size;
+@end example
+
+which will cause the type X to be represented using a single pointer.
+When using this representation, the bounds are right behind the array.
+This representation is slightly less efficient, and does not allow quite
+such flexibility in the use of foreign pointers or in using the
+Unrestricted_Access attribute to create pointers to non-aliased objects.
+But for any standard portable use of the access type it will work in
+a functionally correct manner and allow porting of existing code.
+Note that another way of forcing a thin pointer representation
+is to use a component size clause for the element size in an array,
+or a record representation clause for an access field in a record.
+
+See the documentation of Unrestricted_Access in the GNAT RM for a
+full discussion of possible problems using this attribute in conjunction
+with thin pointers.
+@end itemize
+
+@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{45f}
+@section Compatibility with HP Ada 83
+
+
+All the HP Ada 83 pragmas and attributes are recognized, although only a subset
+of them can sensibly be implemented. The description of pragmas in
+@ref{7,,Implementation Defined Pragmas} indicates whether or not they are
+applicable to GNAT.
+
+
+@itemize *
+
+@item
+`Default floating-point representation'
+
+In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83,
+it is VMS format.
+
+@item
+`System'
+
+the package System in GNAT exactly corresponds to the definition in the
+Ada 95 reference manual, which means that it excludes many of the
+HP Ada 83 extensions. However, a separate package Aux_DEC is provided
+that contains the additional definitions, and a special pragma,
+Extend_System allows this package to be treated transparently as an
+extension of package System.
+@end itemize
+
+@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top
+@anchor{share/gnu_free_documentation_license doc}@anchor{460}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{461}
+@chapter GNU Free Documentation License
+
+
+Version 1.3, 3 November 2008
+
+Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc
+@indicateurl{https://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+`Preamble'
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document “free” in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of “copyleft”, which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+`1. APPLICABILITY AND DEFINITIONS'
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The `Document', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as “`you'”. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A “`Modified Version'” of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A “`Secondary Section'” is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document’s overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The “`Invariant Sections'” are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The “`Cover Texts'” are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A “`Transparent'” copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not “Transparent” is called `Opaque'.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The “`Title Page'” means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, “Title Page” means
+the text near the most prominent appearance of the work’s title,
+preceding the beginning of the body of the text.
+
+The “`publisher'” means any person or entity that distributes
+copies of the Document to the public.
+
+A section “`Entitled XYZ'” means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as “`Acknowledgements'”,
+“`Dedications'”, “`Endorsements'”, or “`History'”.)
+To “`Preserve the Title'”
+of such a section when you modify the Document means that it remains a
+section “Entitled XYZ” according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+`2. VERBATIM COPYING'
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+`3. COPYING IN QUANTITY'
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document’s license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+`4. MODIFICATIONS'
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+
+@enumerate A
+
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document’s license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled “History”, Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled “History” in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the “History” section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled “Acknowledgements” or “Dedications”,
+Preserve the Title of the section, and preserve in the section all
+the substance and tone of each of the contributor acknowledgements
+and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled “Endorsements”. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled “Endorsements”
+or to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version’s license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled “Endorsements”, provided it contains
+nothing but endorsements of your Modified Version by various
+parties—for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+`5. COMBINING DOCUMENTS'
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled “History”
+in the various original documents, forming one section Entitled
+“History”; likewise combine any sections Entitled “Acknowledgements”,
+and any sections Entitled “Dedications”. You must delete all sections
+Entitled “Endorsements”.
+
+`6. COLLECTIONS OF DOCUMENTS'
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+`7. AGGREGATION WITH INDEPENDENT WORKS'
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an “aggregate” if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation’s users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document’s Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+`8. TRANSLATION'
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled “Acknowledgements”,
+“Dedications”, or “History”, the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+`9. TERMINATION'
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+`10. FUTURE REVISIONS OF THIS LICENSE'
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@indicateurl{https://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License “or any later version” applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy’s public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+`11. RELICENSING'
+
+“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+“Massive Multiauthor Collaboration” (or “MMC”) contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+“Incorporate” means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is “eligible for relicensing” if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+`ADDENDUM: How to use this License for your documents'
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@quotation
+
+Copyright © YEAR YOUR NAME.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled “GNU
+Free Documentation License”.
+@end quotation
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the “with … Texts.” line with this:
+
+@quotation
+
+with the Invariant Sections being LIST THEIR TITLES, with the
+Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+@end quotation
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@node Index,,GNU Free Documentation License,Top
+@unnumbered Index
+
+
+@printindex ge
+
+
+@c %**end of body
+@bye
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename gnat_ugn.info
+@documentencoding UTF-8
+@ifinfo
+@*Generated by Sphinx 5.2.3.@*
+@end ifinfo
+@settitle GNAT User's Guide for Native Platforms
+@defindex ge
+@paragraphindent 0
+@exampleindent 4
+@finalout
+@dircategory GNU Ada Tools
+@direntry
+* gnat_ugn: (gnat_ugn.info). gnat_ugn
+@end direntry
+
+@c %**end of header
+
+@copying
+@quotation
+GNAT User's Guide for Native Platforms , Oct 27, 2022
+
+AdaCore
+
+Copyright @copyright{} 2008-2022, Free Software Foundation
+@end quotation
+
+@end copying
+
+@titlepage
+@title GNAT User's Guide for Native Platforms
+@insertcopying
+@end titlepage
+@contents
+
+@c %** start of user preamble
+
+@c %** end of user preamble
+
+@ifnottex
+@node Top
+@top GNAT User's Guide for Native Platforms
+@insertcopying
+@end ifnottex
+
+@c %**start of body
+@anchor{gnat_ugn doc}@anchor{0}
+`GNAT, The GNU Ada Development Environment'
+
+
+@include gcc-common.texi
+GCC version @value{version-GCC}@*
+AdaCore
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being
+“GNAT User’s Guide for Native Platforms”,
+and with no Back-Cover Texts. A copy of the license is
+included in the section entitled @ref{1,,GNU Free Documentation License}.
+
+@menu
+* About This Guide::
+* Getting Started with GNAT::
+* The GNAT Compilation Model::
+* Building Executable Programs with GNAT::
+* GNAT Utility Programs::
+* GNAT and Program Execution::
+* Platform-Specific Information::
+* Example of Binder Output File::
+* Elaboration Order Handling in GNAT::
+* Inline Assembler::
+* GNU Free Documentation License::
+* Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+About This Guide
+
+* What This Guide Contains::
+* What You Should Know before Reading This Guide::
+* Related Information::
+* Conventions::
+
+Getting Started with GNAT
+
+* System Requirements::
+* Running GNAT::
+* Running a Simple Ada Program::
+* Running a Program with Multiple Units::
+
+The GNAT Compilation Model
+
+* Source Representation::
+* Foreign Language Representation::
+* File Naming Topics and Utilities::
+* Configuration Pragmas::
+* Generating Object Files::
+* Source Dependencies::
+* The Ada Library Information Files::
+* Binding an Ada Program::
+* GNAT and Libraries::
+* Conditional Compilation::
+* Mixed Language Programming::
+* GNAT and Other Compilation Models::
+* Using GNAT Files with External Tools::
+
+Foreign Language Representation
+
+* Latin-1::
+* Other 8-Bit Codes::
+* Wide_Character Encodings::
+* Wide_Wide_Character Encodings::
+
+File Naming Topics and Utilities
+
+* File Naming Rules::
+* Using Other File Names::
+* Alternative File Naming Schemes::
+* Handling Arbitrary File Naming Conventions with gnatname::
+* File Name Krunching with gnatkr::
+* Renaming Files with gnatchop::
+
+Handling Arbitrary File Naming Conventions with gnatname
+
+* Arbitrary File Naming Conventions::
+* Running gnatname::
+* Switches for gnatname::
+* Examples of gnatname Usage::
+
+File Name Krunching with gnatkr
+
+* About gnatkr::
+* Using gnatkr::
+* Krunching Method::
+* Examples of gnatkr Usage::
+
+Renaming Files with gnatchop
+
+* Handling Files with Multiple Units::
+* Operating gnatchop in Compilation Mode::
+* Command Line for gnatchop::
+* Switches for gnatchop::
+* Examples of gnatchop Usage::
+
+Configuration Pragmas
+
+* Handling of Configuration Pragmas::
+* The Configuration Pragmas Files::
+
+GNAT and Libraries
+
+* Introduction to Libraries in GNAT::
+* General Ada Libraries::
+* Stand-alone Ada Libraries::
+* Rebuilding the GNAT Run-Time Library::
+
+General Ada Libraries
+
+* Building a library::
+* Installing a library::
+* Using a library::
+
+Stand-alone Ada Libraries
+
+* Introduction to Stand-alone Libraries::
+* Building a Stand-alone Library::
+* Creating a Stand-alone Library to be used in a non-Ada context::
+* Restrictions in Stand-alone Libraries::
+
+Conditional Compilation
+
+* Modeling Conditional Compilation in Ada::
+* Preprocessing with gnatprep::
+* Integrated Preprocessing::
+
+Modeling Conditional Compilation in Ada
+
+* Use of Boolean Constants::
+* Debugging - A Special Case::
+* Conditionalizing Declarations::
+* Use of Alternative Implementations::
+* Preprocessing::
+
+Preprocessing with gnatprep
+
+* Preprocessing Symbols::
+* Using gnatprep::
+* Switches for gnatprep::
+* Form of Definitions File::
+* Form of Input Text for gnatprep::
+
+Mixed Language Programming
+
+* Interfacing to C::
+* Calling Conventions::
+* Building Mixed Ada and C++ Programs::
+* Generating Ada Bindings for C and C++ headers::
+* Generating C Headers for Ada Specifications::
+
+Building Mixed Ada and C++ Programs
+
+* Interfacing to C++::
+* Linking a Mixed C++ & Ada Program::
+* A Simple Example::
+* Interfacing with C++ constructors::
+* Interfacing with C++ at the Class Level::
+
+Generating Ada Bindings for C and C++ headers
+
+* Running the Binding Generator::
+* Generating Bindings for C++ Headers::
+* Switches::
+
+Generating C Headers for Ada Specifications
+
+* Running the C Header Generator::
+
+GNAT and Other Compilation Models
+
+* Comparison between GNAT and C/C++ Compilation Models::
+* Comparison between GNAT and Conventional Ada Library Models::
+
+Using GNAT Files with External Tools
+
+* Using Other Utility Programs with GNAT::
+* The External Symbol Naming Scheme of GNAT::
+
+Building Executable Programs with GNAT
+
+* Building with gnatmake::
+* Compiling with gcc::
+* Compiler Switches::
+* Linker Switches::
+* Binding with gnatbind::
+* Linking with gnatlink::
+* Using the GNU make Utility::
+
+Building with gnatmake
+
+* Running gnatmake::
+* Switches for gnatmake::
+* Mode Switches for gnatmake::
+* Notes on the Command Line::
+* How gnatmake Works::
+* Examples of gnatmake Usage::
+
+Compiling with gcc
+
+* Compiling Programs::
+* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL.
+* Order of Compilation Issues::
+* Examples::
+
+Compiler Switches
+
+* Alphabetical List of All Switches::
+* Output and Error Message Control::
+* Warning Message Control::
+* Debugging and Assertion Control::
+* Validity Checking::
+* Style Checking::
+* Run-Time Checks::
+* Using gcc for Syntax Checking::
+* Using gcc for Semantic Checking::
+* Compiling Different Versions of Ada::
+* Character Set Control::
+* File Naming Control::
+* Subprogram Inlining Control::
+* Auxiliary Output Control::
+* Debugging Control::
+* Exception Handling Control::
+* Units to Sources Mapping Files::
+* Code Generation Control::
+
+Binding with gnatbind
+
+* Running gnatbind::
+* Switches for gnatbind::
+* Command-Line Access::
+* Search Paths for gnatbind::
+* Examples of gnatbind Usage::
+
+Switches for gnatbind
+
+* Consistency-Checking Modes::
+* Binder Error Message Control::
+* Elaboration Control::
+* Output Control::
+* Dynamic Allocation Control::
+* Binding with Non-Ada Main Programs::
+* Binding Programs with No Main Subprogram::
+
+Linking with gnatlink
+
+* Running gnatlink::
+* Switches for gnatlink::
+
+Using the GNU make Utility
+
+* Using gnatmake in a Makefile::
+* Automatically Creating a List of Directories::
+* Generating the Command Line Switches::
+* Overcoming Command Line Length Limits::
+
+GNAT Utility Programs
+
+* The File Cleanup Utility gnatclean::
+* The GNAT Library Browser gnatls::
+
+The File Cleanup Utility gnatclean
+
+* Running gnatclean::
+* Switches for gnatclean::
+
+The GNAT Library Browser gnatls
+
+* Running gnatls::
+* Switches for gnatls::
+* Example of gnatls Usage::
+
+GNAT and Program Execution
+
+* Running and Debugging Ada Programs::
+* Profiling::
+* Improving Performance::
+* Overflow Check Handling in GNAT::
+* Performing Dimensionality Analysis in GNAT::
+* Stack Related Facilities::
+* Memory Management Issues::
+
+Running and Debugging Ada Programs
+
+* The GNAT Debugger GDB::
+* Running GDB::
+* Introduction to GDB Commands::
+* Using Ada Expressions::
+* Calling User-Defined Subprograms::
+* Using the next Command in a Function::
+* Stopping When Ada Exceptions Are Raised::
+* Ada Tasks::
+* Debugging Generic Units::
+* Remote Debugging with gdbserver::
+* GNAT Abnormal Termination or Failure to Terminate::
+* Naming Conventions for GNAT Source Files::
+* Getting Internal Debugging Information::
+* Stack Traceback::
+* Pretty-Printers for the GNAT runtime::
+
+Stack Traceback
+
+* Non-Symbolic Traceback::
+* Symbolic Traceback::
+
+Profiling
+
+* Profiling an Ada Program with gprof::
+
+Profiling an Ada Program with gprof
+
+* Compilation for profiling::
+* Program execution::
+* Running gprof::
+* Interpretation of profiling results::
+
+Improving Performance
+
+* Performance Considerations::
+* Text_IO Suggestions::
+* Reducing Size of Executables with Unused Subprogram/Data Elimination::
+
+Performance Considerations
+
+* Controlling Run-Time Checks::
+* Use of Restrictions::
+* Optimization Levels::
+* Debugging Optimized Code::
+* Inlining of Subprograms::
+* Floating Point Operations::
+* Vectorization of loops::
+* Other Optimization Switches::
+* Optimization and Strict Aliasing::
+* Aliased Variables and Optimization::
+* Atomic Variables and Optimization::
+* Passive Task Optimization::
+
+Reducing Size of Executables with Unused Subprogram/Data Elimination
+
+* About unused subprogram/data elimination::
+* Compilation options::
+* Example of unused subprogram/data elimination::
+
+Overflow Check Handling in GNAT
+
+* Background::
+* Management of Overflows in GNAT::
+* Specifying the Desired Mode::
+* Default Settings::
+* Implementation Notes::
+
+Stack Related Facilities
+
+* Stack Overflow Checking::
+* Static Stack Usage Analysis::
+* Dynamic Stack Usage Analysis::
+
+Memory Management Issues
+
+* Some Useful Memory Pools::
+* The GNAT Debug Pool Facility::
+
+Platform-Specific Information
+
+* Run-Time Libraries::
+* Specifying a Run-Time Library::
+* GNU/Linux Topics::
+* Microsoft Windows Topics::
+* Mac OS Topics::
+
+Run-Time Libraries
+
+* Summary of Run-Time Configurations::
+
+Specifying a Run-Time Library
+
+* Choosing the Scheduling Policy::
+
+GNU/Linux Topics
+
+* Required Packages on GNU/Linux::
+* A GNU/Linux Debug Quirk::
+
+Microsoft Windows Topics
+
+* Using GNAT on Windows::
+* Using a network installation of GNAT::
+* CONSOLE and WINDOWS subsystems::
+* Temporary Files::
+* Disabling Command Line Argument Expansion::
+* Windows Socket Timeouts::
+* Mixed-Language Programming on Windows::
+* Windows Specific Add-Ons::
+
+Mixed-Language Programming on Windows
+
+* Windows Calling Conventions::
+* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs.
+* Using DLLs with GNAT::
+* Building DLLs with GNAT Project files::
+* Building DLLs with GNAT::
+* Building DLLs with gnatdll::
+* Ada DLLs and Finalization::
+* Creating a Spec for Ada DLLs::
+* GNAT and Windows Resources::
+* Using GNAT DLLs from Microsoft Visual Studio Applications::
+* Debugging a DLL::
+* Setting Stack Size from gnatlink::
+* Setting Heap Size from gnatlink::
+
+Windows Calling Conventions
+
+* C Calling Convention::
+* Stdcall Calling Convention::
+* Win32 Calling Convention::
+* DLL Calling Convention::
+
+Using DLLs with GNAT
+
+* Creating an Ada Spec for the DLL Services::
+* Creating an Import Library::
+
+Building DLLs with gnatdll
+
+* Limitations When Using Ada DLLs from Ada::
+* Exporting Ada Entities::
+* Ada DLLs and Elaboration::
+
+Creating a Spec for Ada DLLs
+
+* Creating the Definition File::
+* Using gnatdll::
+
+GNAT and Windows Resources
+
+* Building Resources::
+* Compiling Resources::
+* Using Resources::
+
+Debugging a DLL
+
+* Program and DLL Both Built with GCC/GNAT::
+* Program Built with Foreign Tools and DLL Built with GCC/GNAT::
+
+Windows Specific Add-Ons
+
+* Win32Ada::
+* wPOSIX::
+
+Mac OS Topics
+
+* Codesigning the Debugger::
+
+Elaboration Order Handling in GNAT
+
+* Elaboration Code::
+* Elaboration Order::
+* Checking the Elaboration Order::
+* Controlling the Elaboration Order in Ada::
+* Controlling the Elaboration Order in GNAT::
+* Mixing Elaboration Models::
+* ABE Diagnostics::
+* SPARK Diagnostics::
+* Elaboration Circularities::
+* Resolving Elaboration Circularities::
+* Elaboration-related Compiler Switches::
+* Summary of Procedures for Elaboration Control::
+* Inspecting the Chosen Elaboration Order::
+
+Inline Assembler
+
+* Basic Assembler Syntax::
+* A Simple Example of Inline Assembler::
+* Output Variables in Inline Assembler::
+* Input Variables in Inline Assembler::
+* Inlining Inline Assembler Code::
+* Other Asm Functionality::
+
+Other Asm Functionality
+
+* The Clobber Parameter::
+* The Volatile Parameter::
+
+@end detailmenu
+@end menu
+
+@node About This Guide,Getting Started with GNAT,Top,Top
+@anchor{gnat_ugn/about_this_guide doc}@anchor{2}@anchor{gnat_ugn/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_ugn/about_this_guide gnat-user-s-guide-for-native-platforms}@anchor{4}@anchor{gnat_ugn/about_this_guide id1}@anchor{5}
+@chapter About This Guide
+
+
+
+This guide describes the use of GNAT,
+a compiler and software development
+toolset for the full Ada programming language.
+It documents the features of the compiler and tools, and explains
+how to use them to build Ada applications.
+
+GNAT implements Ada 95, Ada 2005, Ada 2012, and Ada 202x, and it may also be
+invoked in Ada 83 compatibility mode.
+By default, GNAT assumes Ada 2012, but you can override with a
+compiler switch (@ref{6,,Compiling Different Versions of Ada})
+to explicitly specify the language version.
+Throughout this manual, references to ‘Ada’ without a year suffix
+apply to all Ada versions of the language, starting with Ada 95.
+
+@menu
+* What This Guide Contains::
+* What You Should Know before Reading This Guide::
+* Related Information::
+* Conventions::
+
+@end menu
+
+@node What This Guide Contains,What You Should Know before Reading This Guide,,About This Guide
+@anchor{gnat_ugn/about_this_guide what-this-guide-contains}@anchor{7}
+@section What This Guide Contains
+
+
+This guide contains the following chapters:
+
+
+@itemize *
+
+@item
+@ref{8,,Getting Started with GNAT} describes how to get started compiling
+and running Ada programs with the GNAT Ada programming environment.
+
+@item
+@ref{9,,The GNAT Compilation Model} describes the compilation model used
+by GNAT.
+
+@item
+@ref{a,,Building Executable Programs with GNAT} describes how to use the
+main GNAT tools to build executable programs, and it also gives examples of
+using the GNU make utility with GNAT.
+
+@item
+@ref{b,,GNAT Utility Programs} explains the various utility programs that
+are included in the GNAT environment
+
+@item
+@ref{c,,GNAT and Program Execution} covers a number of topics related to
+running, debugging, and tuning the performace of programs developed
+with GNAT
+@end itemize
+
+Appendices cover several additional topics:
+
+
+@itemize *
+
+@item
+@ref{d,,Platform-Specific Information} describes the different run-time
+library implementations and also presents information on how to use
+GNAT on several specific platforms
+
+@item
+@ref{e,,Example of Binder Output File} shows the source code for the binder
+output file for a sample program.
+
+@item
+@ref{f,,Elaboration Order Handling in GNAT} describes how GNAT helps
+you deal with elaboration order issues.
+
+@item
+@ref{10,,Inline Assembler} shows how to use the inline assembly facility
+in an Ada program.
+@end itemize
+
+@node What You Should Know before Reading This Guide,Related Information,What This Guide Contains,About This Guide
+@anchor{gnat_ugn/about_this_guide what-you-should-know-before-reading-this-guide}@anchor{11}
+@section What You Should Know before Reading This Guide
+
+
+@geindex Ada 95 Language Reference Manual
+
+@geindex Ada 2005 Language Reference Manual
+
+This guide assumes a basic familiarity with the Ada 95 language, as
+described in the International Standard ANSI/ISO/IEC-8652:1995, January
+1995.
+Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in
+the GNAT documentation package.
+
+@node Related Information,Conventions,What You Should Know before Reading This Guide,About This Guide
+@anchor{gnat_ugn/about_this_guide related-information}@anchor{12}
+@section Related Information
+
+
+For further information about Ada and related tools, please refer to the
+following documents:
+
+
+@itemize *
+
+@item
+@cite{Ada 95 Reference Manual}, @cite{Ada 2005 Reference Manual}, and
+@cite{Ada 2012 Reference Manual}, which contain reference
+material for the several revisions of the Ada language standard.
+
+@item
+@cite{GNAT Reference_Manual}, which contains all reference material for the GNAT
+implementation of Ada.
+
+@item
+@cite{Using GNAT Studio}, which describes the GNAT Studio
+Integrated Development Environment.
+
+@item
+@cite{GNAT Studio Tutorial}, which introduces the
+main GNAT Studio features through examples.
+
+@item
+@cite{Debugging with GDB},
+for all details on the use of the GNU source-level debugger.
+
+@item
+@cite{GNU Emacs Manual},
+for full information on the extensible editor and programming
+environment Emacs.
+@end itemize
+
+@node Conventions,,Related Information,About This Guide
+@anchor{gnat_ugn/about_this_guide conventions}@anchor{13}
+@section Conventions
+
+
+@geindex Conventions
+@geindex typographical
+
+@geindex Typographical conventions
+
+Following are examples of the typographical and graphic conventions used
+in this guide:
+
+
+@itemize *
+
+@item
+@code{Functions}, @code{utility program names}, @code{standard names},
+and @code{classes}.
+
+@item
+@code{Option flags}
+
+@item
+@code{File names}
+
+@item
+@code{Variables}
+
+@item
+`Emphasis'
+
+@item
+[optional information or parameters]
+
+@item
+Examples are described by text
+
+@example
+and then shown this way.
+@end example
+
+@item
+Commands that are entered by the user are shown as preceded by a prompt string
+comprising the @code{$} character followed by a space.
+
+@item
+Full file names are shown with the ‘/’ character
+as the directory separator; e.g., @code{parent-dir/subdir/myfile.adb}.
+If you are using GNAT on a Windows platform, please note that
+the ‘\’ character should be used instead.
+@end itemize
+
+@node Getting Started with GNAT,The GNAT Compilation Model,About This Guide,Top
+@anchor{gnat_ugn/getting_started_with_gnat doc}@anchor{14}@anchor{gnat_ugn/getting_started_with_gnat getting-started-with-gnat}@anchor{8}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{15}
+@chapter Getting Started with GNAT
+
+
+This chapter describes how to use GNAT’s command line interface to build
+executable Ada programs.
+On most platforms a visually oriented Integrated Development Environment
+is also available: GNAT Studio.
+GNAT Studio offers a graphical “look and feel”, support for development in
+other programming languages, comprehensive browsing features, and
+many other capabilities.
+For information on GNAT Studio please refer to the
+@cite{GNAT Studio documentation}.
+
+@menu
+* System Requirements::
+* Running GNAT::
+* Running a Simple Ada Program::
+* Running a Program with Multiple Units::
+
+@end menu
+
+@node System Requirements,Running GNAT,,Getting Started with GNAT
+@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{16}@anchor{gnat_ugn/getting_started_with_gnat system-requirements}@anchor{17}
+@section System Requirements
+
+
+Even though any machine can run the GNAT toolset and GNAT Studio IDE, in order
+to get the best experience, we recommend using a machine with as many cores
+as possible since all individual compilations can run in parallel.
+A comfortable setup for a compiler server is a machine with 24 physical cores
+or more, with at least 48 GB of memory (2 GB per core).
+
+For a desktop machine, a minimum of 4 cores is recommended (8 preferred),
+with at least 2GB per core (so 8 to 16GB).
+
+In addition, for running and navigating sources in GNAT Studio smoothly, we
+recommend at least 1.5 GB plus 3 GB of RAM per 1 million source line of code.
+In other words, we recommend at least 3 GB for for 500K lines of code and
+7.5 GB for 2 million lines of code.
+
+Note that using local and fast drives will also make a difference in terms of
+build and link time. Network drives such as NFS, SMB, or worse, configuration
+management filesystems (such as ClearCase dynamic views) should be avoided as
+much as possible and will produce very degraded performance (typically 2 to 3
+times slower than on local fast drives). If such slow drives cannot be avoided
+for accessing the source code, then you should at least configure your project
+file so that the result of the compilation is stored on a drive local to the
+machine performing the run. This can be achieved by setting the @code{Object_Dir}
+project file attribute.
+
+@node Running GNAT,Running a Simple Ada Program,System Requirements,Getting Started with GNAT
+@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{18}@anchor{gnat_ugn/getting_started_with_gnat running-gnat}@anchor{19}
+@section Running GNAT
+
+
+Three steps are needed to create an executable file from an Ada source
+file:
+
+
+@itemize *
+
+@item
+The source file(s) must be compiled.
+
+@item
+The file(s) must be bound using the GNAT binder.
+
+@item
+All appropriate object files must be linked to produce an executable.
+@end itemize
+
+All three steps are most commonly handled by using the @code{gnatmake}
+utility program that, given the name of the main program, automatically
+performs the necessary compilation, binding and linking steps.
+
+@node Running a Simple Ada Program,Running a Program with Multiple Units,Running GNAT,Getting Started with GNAT
+@anchor{gnat_ugn/getting_started_with_gnat id4}@anchor{1a}@anchor{gnat_ugn/getting_started_with_gnat running-a-simple-ada-program}@anchor{1b}
+@section Running a Simple Ada Program
+
+
+Any text editor may be used to prepare an Ada program.
+(If Emacs is used, the optional Ada mode may be helpful in laying out the
+program.)
+The program text is a normal text file. We will assume in our initial
+example that you have used your editor to prepare the following
+standard format text file:
+
+@example
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Hello is
+begin
+ Put_Line ("Hello WORLD!");
+end Hello;
+@end example
+
+This file should be named @code{hello.adb}.
+With the normal default file naming conventions, GNAT requires
+that each file
+contain a single compilation unit whose file name is the
+unit name,
+with periods replaced by hyphens; the
+extension is @code{ads} for a
+spec and @code{adb} for a body.
+You can override this default file naming convention by use of the
+special pragma @code{Source_File_Name} (for further information please
+see @ref{1c,,Using Other File Names}).
+Alternatively, if you want to rename your files according to this default
+convention, which is probably more convenient if you will be using GNAT
+for all your compilations, then the @code{gnatchop} utility
+can be used to generate correctly-named source files
+(see @ref{1d,,Renaming Files with gnatchop}).
+
+You can compile the program using the following command (@code{$} is used
+as the command prompt in the examples in this document):
+
+@example
+$ gcc -c hello.adb
+@end example
+
+@code{gcc} is the command used to run the compiler. This compiler is
+capable of compiling programs in several languages, including Ada and
+C. It assumes that you have given it an Ada program if the file extension is
+either @code{.ads} or @code{.adb}, and it will then call
+the GNAT compiler to compile the specified file.
+
+The @code{-c} switch is required. It tells @code{gcc} to only do a
+compilation. (For C programs, @code{gcc} can also do linking, but this
+capability is not used directly for Ada programs, so the @code{-c}
+switch must always be present.)
+
+This compile command generates a file
+@code{hello.o}, which is the object
+file corresponding to your Ada program. It also generates
+an ‘Ada Library Information’ file @code{hello.ali},
+which contains additional information used to check
+that an Ada program is consistent.
+
+To build an executable file, use either @code{gnatmake} or gprbuild with
+the name of the main file: these tools are builders that will take care of
+all the necessary build steps in the correct order.
+In particular, these builders automatically recompile any sources that have
+been modified since they were last compiled, or sources that depend
+on such modified sources, so that ‘version skew’ is avoided.
+
+@geindex Version skew (avoided by `@w{`}gnatmake`@w{`})
+
+@example
+$ gnatmake hello.adb
+@end example
+
+The result is an executable program called @code{hello}, which can be
+run by entering:
+
+@example
+$ hello
+@end example
+
+assuming that the current directory is on the search path
+for executable programs.
+
+and, if all has gone well, you will see:
+
+@example
+Hello WORLD!
+@end example
+
+appear in response to this command.
+
+@node Running a Program with Multiple Units,,Running a Simple Ada Program,Getting Started with GNAT
+@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{1e}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{1f}
+@section Running a Program with Multiple Units
+
+
+Consider a slightly more complicated example that has three files: a
+main program, and the spec and body of a package:
+
+@example
+package Greetings is
+ procedure Hello;
+ procedure Goodbye;
+end Greetings;
+
+with Ada.Text_IO; use Ada.Text_IO;
+package body Greetings is
+ procedure Hello is
+ begin
+ Put_Line ("Hello WORLD!");
+ end Hello;
+
+ procedure Goodbye is
+ begin
+ Put_Line ("Goodbye WORLD!");
+ end Goodbye;
+end Greetings;
+
+with Greetings;
+procedure Gmain is
+begin
+ Greetings.Hello;
+ Greetings.Goodbye;
+end Gmain;
+@end example
+
+Following the one-unit-per-file rule, place this program in the
+following three separate files:
+
+
+@table @asis
+
+@item `greetings.ads'
+
+spec of package @code{Greetings}
+
+@item `greetings.adb'
+
+body of package @code{Greetings}
+
+@item `gmain.adb'
+
+body of main program
+@end table
+
+Note that there is no required order of compilation when using GNAT.
+In particular it is perfectly fine to compile the main program first.
+Also, it is not necessary to compile package specs in the case where
+there is an accompanying body; you only need to compile the body. If you want
+to submit these files to the compiler for semantic checking and not code
+generation, then use the @code{-gnatc} switch:
+
+@example
+$ gcc -c greetings.ads -gnatc
+@end example
+
+Although the compilation can be done in separate steps, in practice it is
+almost always more convenient to use the @code{gnatmake} or @code{gprbuild} tools:
+
+@example
+$ gnatmake gmain.adb
+@end example
+
+@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
+
+@node The GNAT Compilation Model,Building Executable Programs with GNAT,Getting Started with GNAT,Top
+@anchor{gnat_ugn/the_gnat_compilation_model doc}@anchor{20}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{21}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9}
+@chapter The GNAT Compilation Model
+
+
+@geindex GNAT compilation model
+
+@geindex Compilation model
+
+This chapter describes the compilation model used by GNAT. Although
+similar to that used by other languages such as C and C++, this model
+is substantially different from the traditional Ada compilation models,
+which are based on a centralized program library. The chapter covers
+the following material:
+
+
+@itemize *
+
+@item
+Topics related to source file makeup and naming
+
+
+@itemize *
+
+@item
+@ref{22,,Source Representation}
+
+@item
+@ref{23,,Foreign Language Representation}
+
+@item
+@ref{24,,File Naming Topics and Utilities}
+@end itemize
+
+@item
+@ref{25,,Configuration Pragmas}
+
+@item
+@ref{26,,Generating Object Files}
+
+@item
+@ref{27,,Source Dependencies}
+
+@item
+@ref{28,,The Ada Library Information Files}
+
+@item
+@ref{29,,Binding an Ada Program}
+
+@item
+@ref{2a,,GNAT and Libraries}
+
+@item
+@ref{2b,,Conditional Compilation}
+
+@item
+@ref{2c,,Mixed Language Programming}
+
+@item
+@ref{2d,,GNAT and Other Compilation Models}
+
+@item
+@ref{2e,,Using GNAT Files with External Tools}
+@end itemize
+
+@menu
+* Source Representation::
+* Foreign Language Representation::
+* File Naming Topics and Utilities::
+* Configuration Pragmas::
+* Generating Object Files::
+* Source Dependencies::
+* The Ada Library Information Files::
+* Binding an Ada Program::
+* GNAT and Libraries::
+* Conditional Compilation::
+* Mixed Language Programming::
+* GNAT and Other Compilation Models::
+* Using GNAT Files with External Tools::
+
+@end menu
+
+@node Source Representation,Foreign Language Representation,,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{2f}@anchor{gnat_ugn/the_gnat_compilation_model source-representation}@anchor{22}
+@section Source Representation
+
+
+@geindex Latin-1
+
+@geindex VT
+@geindex HT
+@geindex CR
+@geindex LF
+@geindex FF
+
+Ada source programs are represented in standard text files, using
+Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar
+7-bit ASCII set, plus additional characters used for
+representing foreign languages (see @ref{23,,Foreign Language Representation}
+for support of non-USA character sets). The format effector characters
+are represented using their standard ASCII encodings, as follows:
+
+@quotation
+
+
+@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
+@item
+
+Character
+
+@tab
+
+Effect
+
+@tab
+
+Code
+
+@item
+
+@code{VT}
+
+@tab
+
+Vertical tab
+
+@tab
+
+@code{16#0B#}
+
+@item
+
+@code{HT}
+
+@tab
+
+Horizontal tab
+
+@tab
+
+@code{16#09#}
+
+@item
+
+@code{CR}
+
+@tab
+
+Carriage return
+
+@tab
+
+@code{16#0D#}
+
+@item
+
+@code{LF}
+
+@tab
+
+Line feed
+
+@tab
+
+@code{16#0A#}
+
+@item
+
+@code{FF}
+
+@tab
+
+Form feed
+
+@tab
+
+@code{16#0C#}
+
+@end multitable
+
+@end quotation
+
+Source files are in standard text file format. In addition, GNAT will
+recognize a wide variety of stream formats, in which the end of
+physical lines is marked by any of the following sequences:
+@code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful
+in accommodating files that are imported from other operating systems.
+
+@geindex End of source file; Source file@comma{} end
+
+@geindex SUB (control character)
+
+The end of a source file is normally represented by the physical end of
+file. However, the control character @code{16#1A#} (@code{SUB}) is also
+recognized as signalling the end of the source file. Again, this is
+provided for compatibility with other operating systems where this
+code is used to represent the end of file.
+
+@geindex spec (definition)
+@geindex compilation (definition)
+
+Each file contains a single Ada compilation unit, including any pragmas
+associated with the unit. For example, this means you must place a
+package declaration (a package `spec') and the corresponding body in
+separate files. An Ada `compilation' (which is a sequence of
+compilation units) is represented using a sequence of files. Similarly,
+you will place each subunit or child unit in a separate file.
+
+@node Foreign Language Representation,File Naming Topics and Utilities,Source Representation,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model foreign-language-representation}@anchor{23}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{30}
+@section Foreign Language Representation
+
+
+GNAT supports the standard character sets defined in Ada as well as
+several other non-standard character sets for use in localized versions
+of the compiler (@ref{31,,Character Set Control}).
+
+@menu
+* Latin-1::
+* Other 8-Bit Codes::
+* Wide_Character Encodings::
+* Wide_Wide_Character Encodings::
+
+@end menu
+
+@node Latin-1,Other 8-Bit Codes,,Foreign Language Representation
+@anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{32}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{33}
+@subsection Latin-1
+
+
+@geindex Latin-1
+
+The basic character set is Latin-1. This character set is defined by ISO
+standard 8859, part 1. The lower half (character codes @code{16#00#}
+… @code{16#7F#)} is identical to standard ASCII coding, but the upper
+half is used to represent additional characters. These include extended letters
+used by European languages, such as French accents, the vowels with umlauts
+used in German, and the extra letter A-ring used in Swedish.
+
+@geindex Ada.Characters.Latin_1
+
+For a complete list of Latin-1 codes and their encodings, see the source
+file of library unit @code{Ada.Characters.Latin_1} in file
+@code{a-chlat1.ads}.
+You may use any of these extended characters freely in character or
+string literals. In addition, the extended characters that represent
+letters can be used in identifiers.
+
+@node Other 8-Bit Codes,Wide_Character Encodings,Latin-1,Foreign Language Representation
+@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{34}@anchor{gnat_ugn/the_gnat_compilation_model other-8-bit-codes}@anchor{35}
+@subsection Other 8-Bit Codes
+
+
+GNAT also supports several other 8-bit coding schemes:
+
+@geindex Latin-2
+
+@geindex ISO 8859-2
+
+
+@table @asis
+
+@item `ISO 8859-2 (Latin-2)'
+
+Latin-2 letters allowed in identifiers, with uppercase and lowercase
+equivalence.
+@end table
+
+@geindex Latin-3
+
+@geindex ISO 8859-3
+
+
+@table @asis
+
+@item `ISO 8859-3 (Latin-3)'
+
+Latin-3 letters allowed in identifiers, with uppercase and lowercase
+equivalence.
+@end table
+
+@geindex Latin-4
+
+@geindex ISO 8859-4
+
+
+@table @asis
+
+@item `ISO 8859-4 (Latin-4)'
+
+Latin-4 letters allowed in identifiers, with uppercase and lowercase
+equivalence.
+@end table
+
+@geindex ISO 8859-5
+
+@geindex Cyrillic
+
+
+@table @asis
+
+@item `ISO 8859-5 (Cyrillic)'
+
+ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and
+lowercase equivalence.
+@end table
+
+@geindex ISO 8859-15
+
+@geindex Latin-9
+
+
+@table @asis
+
+@item `ISO 8859-15 (Latin-9)'
+
+ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and
+lowercase equivalence
+@end table
+
+@geindex code page 437 (IBM PC)
+
+
+@table @asis
+
+@item `IBM PC (code page 437)'
+
+This code page is the normal default for PCs in the U.S. It corresponds
+to the original IBM PC character set. This set has some, but not all, of
+the extended Latin-1 letters, but these letters do not have the same
+encoding as Latin-1. In this mode, these letters are allowed in
+identifiers with uppercase and lowercase equivalence.
+@end table
+
+@geindex code page 850 (IBM PC)
+
+
+@table @asis
+
+@item `IBM PC (code page 850)'
+
+This code page is a modification of 437 extended to include all the
+Latin-1 letters, but still not with the usual Latin-1 encoding. In this
+mode, all these letters are allowed in identifiers with uppercase and
+lowercase equivalence.
+
+@item `Full Upper 8-bit'
+
+Any character in the range 80-FF allowed in identifiers, and all are
+considered distinct. In other words, there are no uppercase and lowercase
+equivalences in this range. This is useful in conjunction with
+certain encoding schemes used for some foreign character sets (e.g.,
+the typical method of representing Chinese characters on the PC).
+
+@item `No Upper-Half'
+
+No upper-half characters in the range 80-FF are allowed in identifiers.
+This gives Ada 83 compatibility for identifier names.
+@end table
+
+For precise data on the encodings permitted, and the uppercase and lowercase
+equivalences that are recognized, see the file @code{csets.adb} in
+the GNAT compiler sources. You will need to obtain a full source release
+of GNAT to obtain this file.
+
+@node Wide_Character Encodings,Wide_Wide_Character Encodings,Other 8-Bit Codes,Foreign Language Representation
+@anchor{gnat_ugn/the_gnat_compilation_model id6}@anchor{36}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{37}
+@subsection Wide_Character Encodings
+
+
+GNAT allows wide character codes to appear in character and string
+literals, and also optionally in identifiers, by means of the following
+possible encoding schemes:
+
+
+@table @asis
+
+@item `Hex Coding'
+
+In this encoding, a wide character is represented by the following five
+character sequence:
+
+@example
+ESC a b c d
+@end example
+
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
+characters (using uppercase letters) of the wide character code. For
+example, ESC 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.
+
+@item `Upper-Half Coding'
+
+@geindex Upper-Half Coding
+
+The wide character with encoding @code{16#abcd#} where the upper bit is on
+(in other words, ‘a’ is in the range 8-F) is represented as two bytes,
+@code{16#ab#} and @code{16#cd#}. The second byte cannot 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'
+
+@geindex Shift JIS Coding
+
+A wide character is represented by a two-character sequence,
+@code{16#ab#} and
+@code{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'
+
+@geindex EUC Coding
+
+A wide character is represented by a two-character sequence
+@code{16#ab#} and
+@code{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:
+
+@example
+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 example
+
+where the @code{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, and in the following section on wide wide
+characters, the use of these sequences is documented).
+
+@item `Brackets Coding'
+
+In this encoding, a wide character is represented by the following eight
+character sequence:
+
+@example
+[ " a b c d " ]
+@end example
+
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
+characters (using uppercase letters) of the wide character code. For
+example, [‘A345’] is used to represent the wide character with code
+@code{16#A345#}. It is also possible (though not required) to use the
+Brackets coding for upper half characters. For example, the code
+@code{16#A3#} can be represented as @code{['A3']}.
+
+This scheme is compatible with use of the full Wide_Character set,
+and is also the method used for wide character encoding in some standard
+ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
+@end table
+
+@cartouche
+@quotation Note
+Some of these coding schemes do not permit the full use of the
+Ada character set. For example, neither Shift JIS nor EUC allow the
+use of the upper half of the Latin-1 set.
+@end quotation
+@end cartouche
+
+@node Wide_Wide_Character Encodings,,Wide_Character Encodings,Foreign Language Representation
+@anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{38}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{39}
+@subsection Wide_Wide_Character Encodings
+
+
+GNAT allows wide wide character codes to appear in character and string
+literals, and also optionally in identifiers, by means of the following
+possible encoding schemes:
+
+
+@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
+of character codes with values greater than 16#FFFF# is a
+is a four, five, or six byte sequence:
+
+@example
+16#01_0000#-16#10_FFFF#: 11110xxx 10xxxxxx 10xxxxxx
+ 10xxxxxx
+16#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx
+ 10xxxxxx 10xxxxxx
+16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx
+ 10xxxxxx 10xxxxxx 10xxxxxx
+@end example
+
+where the @code{xxx} bits correspond to the left-padded bits of the
+32-bit character value.
+
+@item `Brackets Coding'
+
+In this encoding, a wide wide character is represented by the following ten or
+twelve byte character sequence:
+
+@example
+[ " a b c d e f " ]
+[ " a b c d e f g h " ]
+@end example
+
+where @code{a-h} are the six or eight hexadecimal
+characters (using uppercase letters) of the wide wide character code. For
+example, [“1F4567”] is used to represent the wide wide character with code
+@code{16#001F_4567#}.
+
+This scheme is compatible with use of the full Wide_Wide_Character set,
+and is also the method used for wide wide character encoding in some standard
+ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
+@end table
+
+@node File Naming Topics and Utilities,Configuration Pragmas,Foreign Language Representation,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{24}@anchor{gnat_ugn/the_gnat_compilation_model id8}@anchor{3a}
+@section File Naming Topics and Utilities
+
+
+GNAT has a default file naming scheme and also provides the user with
+a high degree of control over how the names and extensions of the
+source files correspond to the Ada compilation units that they contain.
+
+@menu
+* File Naming Rules::
+* Using Other File Names::
+* Alternative File Naming Schemes::
+* Handling Arbitrary File Naming Conventions with gnatname::
+* File Name Krunching with gnatkr::
+* Renaming Files with gnatchop::
+
+@end menu
+
+@node File Naming Rules,Using Other File Names,,File Naming Topics and Utilities
+@anchor{gnat_ugn/the_gnat_compilation_model file-naming-rules}@anchor{3b}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{3c}
+@subsection File Naming Rules
+
+
+The default file name is determined by the name of the unit that the
+file contains. The name is formed by taking the full expanded name of
+the unit and replacing the separating dots with hyphens and using
+lowercase for all letters.
+
+An exception arises if the file name generated by the above rules starts
+with one of the characters
+@code{a}, @code{g}, @code{i}, or @code{s}, and the second character is a
+minus. In this case, the character tilde is used in place
+of the minus. The reason for this special rule is to avoid clashes with
+the standard names for child units of the packages System, Ada,
+Interfaces, and GNAT, which use the prefixes
+@code{s-}, @code{a-}, @code{i-}, and @code{g-},
+respectively.
+
+The file extension is @code{.ads} for a spec and
+@code{.adb} for a body. The following table shows some
+examples of these rules.
+
+@quotation
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+Source File
+
+@tab
+
+Ada Compilation Unit
+
+@item
+
+@code{main.ads}
+
+@tab
+
+Main (spec)
+
+@item
+
+@code{main.adb}
+
+@tab
+
+Main (body)
+
+@item
+
+@code{arith_functions.ads}
+
+@tab
+
+Arith_Functions (package spec)
+
+@item
+
+@code{arith_functions.adb}
+
+@tab
+
+Arith_Functions (package body)
+
+@item
+
+@code{func-spec.ads}
+
+@tab
+
+Func.Spec (child package spec)
+
+@item
+
+@code{func-spec.adb}
+
+@tab
+
+Func.Spec (child package body)
+
+@item
+
+@code{main-sub.adb}
+
+@tab
+
+Sub (subunit of Main)
+
+@item
+
+@code{a~bad.adb}
+
+@tab
+
+A.Bad (child package body)
+
+@end multitable
+
+@end quotation
+
+Following these rules can result in excessively long
+file names if corresponding
+unit names are long (for example, if child units or subunits are
+heavily nested). An option is available to shorten such long file names
+(called file name ‘krunching’). This may be particularly useful when
+programs being developed with GNAT are to be used on operating systems
+with limited file name lengths. @ref{3d,,Using gnatkr}.
+
+Of course, no file shortening algorithm can guarantee uniqueness over
+all possible unit names; if file name krunching is used, it is your
+responsibility to ensure no name clashes occur. Alternatively you
+can specify the exact file names that you want used, as described
+in the next section. Finally, if your Ada programs are migrating from a
+compiler with a different naming convention, you can use the gnatchop
+utility to produce source files that follow the GNAT naming conventions.
+(For details see @ref{1d,,Renaming Files with gnatchop}.)
+
+Note: in the case of Windows or Mac OS operating systems, case is not
+significant. So for example on Windows if the canonical name is
+@code{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead.
+However, case is significant for other operating systems, so for example,
+if you want to use other than canonically cased file names on a Unix system,
+you need to follow the procedures described in the next section.
+
+@node Using Other File Names,Alternative File Naming Schemes,File Naming Rules,File Naming Topics and Utilities
+@anchor{gnat_ugn/the_gnat_compilation_model id10}@anchor{3e}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{1c}
+@subsection Using Other File Names
+
+
+@geindex File names
+
+In the previous section, we have described the default rules used by
+GNAT to determine the file name in which a given unit resides. It is
+often convenient to follow these default rules, and if you follow them,
+the compiler knows without being explicitly told where to find all
+the files it needs.
+
+@geindex Source_File_Name pragma
+
+However, in some cases, particularly when a program is imported from
+another Ada compiler environment, it may be more convenient for the
+programmer to specify which file names contain which units. GNAT allows
+arbitrary file names to be used by means of the Source_File_Name pragma.
+The form of this pragma is as shown in the following examples:
+
+@example
+pragma Source_File_Name (My_Utilities.Stacks,
+ Spec_File_Name => "myutilst_a.ada");
+pragma Source_File_name (My_Utilities.Stacks,
+ Body_File_Name => "myutilst.ada");
+@end example
+
+As shown in this example, the first argument for the pragma is the unit
+name (in this example a child unit). The second argument has the form
+of a named association. The identifier
+indicates whether the file name is for a spec or a body;
+the file name itself is given by a string literal.
+
+The source file name pragma is a configuration pragma, which means that
+normally it will be placed in the @code{gnat.adc}
+file used to hold configuration
+pragmas that apply to a complete compilation environment.
+For more details on how the @code{gnat.adc} file is created and used
+see @ref{3f,,Handling of Configuration Pragmas}.
+
+@geindex gnat.adc
+
+GNAT allows completely arbitrary file names to be specified using the
+source file name pragma. However, if the file name specified has an
+extension other than @code{.ads} or @code{.adb} it is necessary to use
+a special syntax when compiling the file. The name in this case must be
+preceded by the special sequence @code{-x} followed by a space and the name
+of the language, here @code{ada}, as in:
+
+@example
+$ gcc -c -x ada peculiar_file_name.sim
+@end example
+
+@code{gnatmake} handles non-standard file names in the usual manner (the
+non-standard file name for the main program is simply used as the
+argument to gnatmake). Note that if the extension is also non-standard,
+then it must be included in the @code{gnatmake} command, it may not
+be omitted.
+
+@node Alternative File Naming Schemes,Handling Arbitrary File Naming Conventions with gnatname,Using Other File Names,File Naming Topics and Utilities
+@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{40}@anchor{gnat_ugn/the_gnat_compilation_model id11}@anchor{41}
+@subsection Alternative File Naming Schemes
+
+
+@geindex File naming schemes
+@geindex alternative
+
+@geindex File names
+
+The previous section described the use of the @code{Source_File_Name}
+pragma to allow arbitrary names to be assigned to individual source files.
+However, this approach requires one pragma for each file, and especially in
+large systems can result in very long @code{gnat.adc} files, and also create
+a maintenance problem.
+
+@geindex Source_File_Name pragma
+
+GNAT also provides a facility for specifying systematic file naming schemes
+other than the standard default naming scheme previously described. An
+alternative scheme for naming is specified by the use of
+@code{Source_File_Name} pragmas having the following format:
+
+@example
+pragma Source_File_Name (
+ Spec_File_Name => FILE_NAME_PATTERN
+ [ , Casing => CASING_SPEC]
+ [ , Dot_Replacement => STRING_LITERAL ] );
+
+pragma Source_File_Name (
+ Body_File_Name => FILE_NAME_PATTERN
+ [ , Casing => CASING_SPEC ]
+ [ , Dot_Replacement => STRING_LITERAL ] ) ;
+
+pragma Source_File_Name (
+ Subunit_File_Name => FILE_NAME_PATTERN
+ [ , Casing => CASING_SPEC ]
+ [ , Dot_Replacement => STRING_LITERAL ] ) ;
+
+FILE_NAME_PATTERN ::= STRING_LITERAL
+CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
+@end example
+
+The @code{FILE_NAME_PATTERN} string shows how the file name is constructed.
+It contains a single asterisk character, and the unit name is substituted
+systematically for this asterisk. The optional parameter
+@code{Casing} indicates
+whether the unit name is to be all upper-case letters, all lower-case letters,
+or mixed-case. If no
+@code{Casing} parameter is used, then the default is all
+lower-case.
+
+The optional @code{Dot_Replacement} string is used to replace any periods
+that occur in subunit or child unit names. If no @code{Dot_Replacement}
+argument is used then separating dots appear unchanged in the resulting
+file name.
+Although the above syntax indicates that the
+@code{Casing} argument must appear
+before the @code{Dot_Replacement} argument, but it
+is also permissible to write these arguments in the opposite order.
+
+As indicated, it is possible to specify different naming schemes for
+bodies, specs, and subunits. Quite often the rule for subunits is the
+same as the rule for bodies, in which case, there is no need to give
+a separate @code{Subunit_File_Name} rule, and in this case the
+@code{Body_File_name} rule is used for subunits as well.
+
+The separate rule for subunits can also be used to implement the rather
+unusual case of a compilation environment (e.g., a single directory) which
+contains a subunit and a child unit with the same unit name. Although
+both units cannot appear in the same partition, the Ada Reference Manual
+allows (but does not require) the possibility of the two units coexisting
+in the same environment.
+
+The file name translation works in the following steps:
+
+
+@itemize *
+
+@item
+If there is a specific @code{Source_File_Name} pragma for the given unit,
+then this is always used, and any general pattern rules are ignored.
+
+@item
+If there is a pattern type @code{Source_File_Name} pragma that applies to
+the unit, then the resulting file name will be used if the file exists. If
+more than one pattern matches, the latest one will be tried first, and the
+first attempt resulting in a reference to a file that exists will be used.
+
+@item
+If no pattern type @code{Source_File_Name} pragma that applies to the unit
+for which the corresponding file exists, then the standard GNAT default
+naming rules are used.
+@end itemize
+
+As an example of the use of this mechanism, consider a commonly used scheme
+in which file names are all lower case, with separating periods copied
+unchanged to the resulting file name, and specs end with @code{.1.ada}, and
+bodies end with @code{.2.ada}. GNAT will follow this scheme if the following
+two pragmas appear:
+
+@example
+pragma Source_File_Name
+ (Spec_File_Name => ".1.ada");
+pragma Source_File_Name
+ (Body_File_Name => ".2.ada");
+@end example
+
+The default GNAT scheme is actually implemented by providing the following
+default pragmas internally:
+
+@example
+pragma Source_File_Name
+ (Spec_File_Name => ".ads", Dot_Replacement => "-");
+pragma Source_File_Name
+ (Body_File_Name => ".adb", Dot_Replacement => "-");
+@end example
+
+Our final example implements a scheme typically used with one of the
+Ada 83 compilers, where the separator character for subunits was ‘__’
+(two underscores), specs were identified by adding @code{_.ADA}, bodies
+by adding @code{.ADA}, and subunits by
+adding @code{.SEP}. All file names were
+upper case. Child units were not present of course since this was an
+Ada 83 compiler, but it seems reasonable to extend this scheme to use
+the same double underscore separator for child units.
+
+@example
+pragma Source_File_Name
+ (Spec_File_Name => "_.ADA",
+ Dot_Replacement => "__",
+ Casing = Uppercase);
+pragma Source_File_Name
+ (Body_File_Name => ".ADA",
+ Dot_Replacement => "__",
+ Casing = Uppercase);
+pragma Source_File_Name
+ (Subunit_File_Name => ".SEP",
+ Dot_Replacement => "__",
+ Casing = Uppercase);
+@end example
+
+@geindex gnatname
+
+@node Handling Arbitrary File Naming Conventions with gnatname,File Name Krunching with gnatkr,Alternative File Naming Schemes,File Naming Topics and Utilities
+@anchor{gnat_ugn/the_gnat_compilation_model handling-arbitrary-file-naming-conventions-with-gnatname}@anchor{42}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{43}
+@subsection Handling Arbitrary File Naming Conventions with @code{gnatname}
+
+
+@geindex File Naming Conventions
+
+@menu
+* Arbitrary File Naming Conventions::
+* Running gnatname::
+* Switches for gnatname::
+* Examples of gnatname Usage::
+
+@end menu
+
+@node Arbitrary File Naming Conventions,Running gnatname,,Handling Arbitrary File Naming Conventions with gnatname
+@anchor{gnat_ugn/the_gnat_compilation_model arbitrary-file-naming-conventions}@anchor{44}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{45}
+@subsubsection Arbitrary File Naming Conventions
+
+
+The GNAT compiler must be able to know the source file name of a compilation
+unit. When using the standard GNAT default file naming conventions
+(@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler
+does not need additional information.
+
+When the source file names do not follow the standard GNAT default file naming
+conventions, the GNAT compiler must be given additional information through
+a configuration pragmas file (@ref{25,,Configuration Pragmas})
+or a project file.
+When the non-standard file naming conventions are well-defined,
+a small number of pragmas @code{Source_File_Name} specifying a naming pattern
+(@ref{40,,Alternative File Naming Schemes}) may be sufficient. However,
+if the file naming conventions are irregular or arbitrary, a number
+of pragma @code{Source_File_Name} for individual compilation units
+must be defined.
+To help maintain the correspondence between compilation unit names and
+source file names within the compiler,
+GNAT provides a tool @code{gnatname} to generate the required pragmas for a
+set of files.
+
+@node Running gnatname,Switches for gnatname,Arbitrary File Naming Conventions,Handling Arbitrary File Naming Conventions with gnatname
+@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{46}@anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{47}
+@subsubsection Running @code{gnatname}
+
+
+The usual form of the @code{gnatname} command is:
+
+@example
+$ gnatname [ switches ] naming_pattern [ naming_patterns ]
+ [--and [ switches ] naming_pattern [ naming_patterns ]]
+@end example
+
+All of the arguments are optional. If invoked without any argument,
+@code{gnatname} will display its usage.
+
+When used with at least one naming pattern, @code{gnatname} will attempt to
+find all the compilation units in files that follow at least one of the
+naming patterns. To find these compilation units,
+@code{gnatname} will use the GNAT compiler in syntax-check-only mode on all
+regular files.
+
+One or several Naming Patterns may be given as arguments to @code{gnatname}.
+Each Naming Pattern is enclosed between double quotes (or single
+quotes on Windows).
+A Naming Pattern is a regular expression similar to the wildcard patterns
+used in file names by the Unix shells or the DOS prompt.
+
+@code{gnatname} may be called with several sections of directories/patterns.
+Sections are separated by the switch @code{--and}. In each section, there must be
+at least one pattern. If no directory is specified in a section, the current
+directory (or the project directory if @code{-P} is used) is implied.
+The options other that the directory switches and the patterns apply globally
+even if they are in different sections.
+
+Examples of Naming Patterns are:
+
+@example
+"*.[12].ada"
+"*.ad[sb]*"
+"body_*" "spec_*"
+@end example
+
+For a more complete description of the syntax of Naming Patterns,
+see the second kind of regular expressions described in @code{g-regexp.ads}
+(the ‘Glob’ regular expressions).
+
+When invoked without the switch @code{-P}, @code{gnatname} will create a
+configuration pragmas file @code{gnat.adc} in the current working directory,
+with pragmas @code{Source_File_Name} for each file that contains a valid Ada
+unit.
+
+@node Switches for gnatname,Examples of gnatname Usage,Running gnatname,Handling Arbitrary File Naming Conventions with gnatname
+@anchor{gnat_ugn/the_gnat_compilation_model id15}@anchor{48}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{49}
+@subsubsection Switches for @code{gnatname}
+
+
+Switches for @code{gnatname} must precede any specified Naming Pattern.
+
+You may specify any of the following switches to @code{gnatname}:
+
+@geindex --version (gnatname)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display Copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatname)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+
+@item @code{--subdirs=`dir'}
+
+Real object, library or exec directories are subdirectories <dir> of the
+specified ones.
+
+@item @code{--no-backup}
+
+Do not create a backup copy of an existing project file.
+
+@item @code{--and}
+
+Start another section of directories/patterns.
+@end table
+
+@geindex -c (gnatname)
+
+
+@table @asis
+
+@item @code{-c`filename'}
+
+Create a configuration pragmas file @code{filename} (instead of the default
+@code{gnat.adc}).
+There may be zero, one or more space between @code{-c} and
+@code{filename}.
+@code{filename} may include directory information. @code{filename} must be
+writable. There may be only one switch @code{-c}.
+When a switch @code{-c} is
+specified, no switch @code{-P} may be specified (see below).
+@end table
+
+@geindex -d (gnatname)
+
+
+@table @asis
+
+@item @code{-d`dir'}
+
+Look for source files in directory @code{dir}. There may be zero, one or more
+spaces between @code{-d} and @code{dir}.
+@code{dir} may end with @code{/**}, that is it may be of the form
+@code{root_dir/**}. In this case, the directory @code{root_dir} and all of its
+subdirectories, recursively, have to be searched for sources.
+When a switch @code{-d}
+is specified, the current working directory will not be searched for source
+files, unless it is explicitly specified with a @code{-d}
+or @code{-D} switch.
+Several switches @code{-d} may be specified.
+If @code{dir} is a relative path, it is relative to the directory of
+the configuration pragmas file specified with switch
+@code{-c},
+or to the directory of the project file specified with switch
+@code{-P} or,
+if neither switch @code{-c}
+nor switch @code{-P} are specified, it is relative to the
+current working directory. The directory
+specified with switch @code{-d} must exist and be readable.
+@end table
+
+@geindex -D (gnatname)
+
+
+@table @asis
+
+@item @code{-D`filename'}
+
+Look for source files in all directories listed in text file @code{filename}.
+There may be zero, one or more spaces between @code{-D}
+and @code{filename}.
+@code{filename} must be an existing, readable text file.
+Each nonempty line in @code{filename} must be a directory.
+Specifying switch @code{-D} is equivalent to specifying as many
+switches @code{-d} as there are nonempty lines in
+@code{file}.
+
+@item @code{-eL}
+
+Follow symbolic links when processing project files.
+
+@geindex -f (gnatname)
+
+@item @code{-f`pattern'}
+
+Foreign patterns. Using this switch, it is possible to add sources of languages
+other than Ada to the list of sources of a project file.
+It is only useful if a -P switch is used.
+For example,
+
+@example
+gnatname -Pprj -f"*.c" "*.ada"
+@end example
+
+will look for Ada units in all files with the @code{.ada} extension,
+and will add to the list of file for project @code{prj.gpr} the C files
+with extension @code{.c}.
+
+@geindex -h (gnatname)
+
+@item @code{-h}
+
+Output usage (help) information. The output is written to @code{stdout}.
+
+@geindex -P (gnatname)
+
+@item @code{-P`proj'}
+
+Create or update project file @code{proj}. There may be zero, one or more space
+between @code{-P} and @code{proj}. @code{proj} may include directory
+information. @code{proj} must be writable.
+There may be only one switch @code{-P}.
+When a switch @code{-P} is specified,
+no switch @code{-c} may be specified.
+On all platforms, except on VMS, when @code{gnatname} is invoked for an
+existing project file <proj>.gpr, a backup copy of the project file is created
+in the project directory with file name <proj>.gpr.saved_x. ‘x’ is the first
+non negative number that makes this backup copy a new file.
+
+@geindex -v (gnatname)
+
+@item @code{-v}
+
+Verbose mode. Output detailed explanation of behavior to @code{stdout}.
+This includes name of the file written, the name of the directories to search
+and, for each file in those directories whose name matches at least one of
+the Naming Patterns, an indication of whether the file contains a unit,
+and if so the name of the unit.
+@end table
+
+@geindex -v -v (gnatname)
+
+
+@table @asis
+
+@item @code{-v -v}
+
+Very Verbose mode. In addition to the output produced in verbose mode,
+for each file in the searched directories whose name matches none of
+the Naming Patterns, an indication is given that there is no match.
+
+@geindex -x (gnatname)
+
+@item @code{-x`pattern'}
+
+Excluded patterns. Using this switch, it is possible to exclude some files
+that would match the name patterns. For example,
+
+@example
+gnatname -x "*_nt.ada" "*.ada"
+@end example
+
+will look for Ada units in all files with the @code{.ada} extension,
+except those whose names end with @code{_nt.ada}.
+@end table
+
+@node Examples of gnatname Usage,,Switches for gnatname,Handling Arbitrary File Naming Conventions with gnatname
+@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatname-usage}@anchor{4a}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{4b}
+@subsubsection Examples of @code{gnatname} Usage
+
+
+@example
+$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
+@end example
+
+In this example, the directory @code{/home/me} must already exist
+and be writable. In addition, the directory
+@code{/home/me/sources} (specified by
+@code{-d sources}) must exist and be readable.
+
+Note the optional spaces after @code{-c} and @code{-d}.
+
+@example
+$ gnatname -P/home/me/proj -x "*_nt_body.ada"
+-dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
+@end example
+
+Note that several switches @code{-d} may be used,
+even in conjunction with one or several switches
+@code{-D}. Several Naming Patterns and one excluded pattern
+are used in this example.
+
+@node File Name Krunching with gnatkr,Renaming Files with gnatchop,Handling Arbitrary File Naming Conventions with gnatname,File Naming Topics and Utilities
+@anchor{gnat_ugn/the_gnat_compilation_model file-name-krunching-with-gnatkr}@anchor{4c}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{4d}
+@subsection File Name Krunching with @code{gnatkr}
+
+
+@geindex gnatkr
+
+This section discusses the method used by the compiler to shorten
+the default file names chosen for Ada units so that they do not
+exceed the maximum length permitted. It also describes the
+@code{gnatkr} utility that can be used to determine the result of
+applying this shortening.
+
+@menu
+* About gnatkr::
+* Using gnatkr::
+* Krunching Method::
+* Examples of gnatkr Usage::
+
+@end menu
+
+@node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr
+@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{4e}@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{4f}
+@subsubsection About @code{gnatkr}
+
+
+The default file naming rule in GNAT
+is that the file name must be derived from
+the unit name. The exact default rule is as follows:
+
+
+@itemize *
+
+@item
+Take the unit name and replace all dots by hyphens.
+
+@item
+If such a replacement occurs in the
+second character position of a name, and the first character is
+@code{a}, @code{g}, @code{s}, or @code{i},
+then replace the dot by the character
+@code{~} (tilde)
+instead of a minus.
+
+The reason for this exception is to avoid clashes
+with the standard names for children of System, Ada, Interfaces,
+and GNAT, which use the prefixes
+@code{s-}, @code{a-}, @code{i-}, and @code{g-},
+respectively.
+@end itemize
+
+The @code{-gnatk`nn'}
+switch of the compiler activates a ‘krunching’
+circuit that limits file names to nn characters (where nn is a decimal
+integer).
+
+The @code{gnatkr} utility can be used to determine the krunched name for
+a given file, when krunched to a specified maximum length.
+
+@node Using gnatkr,Krunching Method,About gnatkr,File Name Krunching with gnatkr
+@anchor{gnat_ugn/the_gnat_compilation_model id19}@anchor{50}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{3d}
+@subsubsection Using @code{gnatkr}
+
+
+The @code{gnatkr} command has the form:
+
+@example
+$ gnatkr name [ length ]
+@end example
+
+@code{name} is the uncrunched file name, derived from the name of the unit
+in the standard manner described in the previous section (i.e., in particular
+all dots are replaced by hyphens). The file name may or may not have an
+extension (defined as a suffix of the form period followed by arbitrary
+characters other than period). If an extension is present then it will
+be preserved in the output. For example, when krunching @code{hellofile.ads}
+to eight characters, the result will be hellofil.ads.
+
+Note: for compatibility with previous versions of @code{gnatkr} dots may
+appear in the name instead of hyphens, but the last dot will always be
+taken as the start of an extension. So if @code{gnatkr} is given an argument
+such as @code{Hello.World.adb} it will be treated exactly as if the first
+period had been a hyphen, and for example krunching to eight characters
+gives the result @code{hellworl.adb}.
+
+Note that the result is always all lower case.
+Characters of the other case are folded as required.
+
+@code{length} represents the length of the krunched name. The default
+when no argument is given is 8 characters. A length of zero stands for
+unlimited, in other words do not chop except for system files where the
+implied crunching length is always eight characters.
+
+The output is the krunched name. The output has an extension only if the
+original argument was a file name with an extension.
+
+@node Krunching Method,Examples of gnatkr Usage,Using gnatkr,File Name Krunching with gnatkr
+@anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{52}
+@subsubsection Krunching Method
+
+
+The initial file name is determined by the name of the unit that the file
+contains. The name is formed by taking the full expanded name of the
+unit and replacing the separating dots with hyphens and
+using lowercase
+for all letters, except that a hyphen in the second character position is
+replaced by a tilde if the first character is
+@code{a}, @code{i}, @code{g}, or @code{s}.
+The extension is @code{.ads} for a
+spec and @code{.adb} for a body.
+Krunching does not affect the extension, but the file name is shortened to
+the specified length by following these rules:
+
+
+@itemize *
+
+@item
+The name is divided into segments separated by hyphens, tildes or
+underscores and all hyphens, tildes, and underscores are
+eliminated. If this leaves the name short enough, we are done.
+
+@item
+If the name is too long, the longest segment is located (left-most
+if there are two of equal length), and shortened by dropping
+its last character. This is repeated until the name is short enough.
+
+As an example, consider the krunching of @code{our-strings-wide_fixed.adb}
+to fit the name into 8 characters as required by some operating systems:
+
+@example
+our-strings-wide_fixed 22
+our strings wide fixed 19
+our string wide fixed 18
+our strin wide fixed 17
+our stri wide fixed 16
+our stri wide fixe 15
+our str wide fixe 14
+our str wid fixe 13
+our str wid fix 12
+ou str wid fix 11
+ou st wid fix 10
+ou st wi fix 9
+ou st wi fi 8
+Final file name: oustwifi.adb
+@end example
+
+@item
+The file names for all predefined units are always krunched to eight
+characters. The krunching of these predefined units uses the following
+special prefix replacements:
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx}
+@item
+
+Prefix
+
+@tab
+
+Replacement
+
+@item
+
+@code{ada-}
+
+@tab
+
+@code{a-}
+
+@item
+
+@code{gnat-}
+
+@tab
+
+@code{g-}
+
+@item
+
+@code{interfac es-}
+
+@tab
+
+@code{i-}
+
+@item
+
+@code{system-}
+
+@tab
+
+@code{s-}
+
+@end multitable
+
+
+These system files have a hyphen in the second character position. That
+is why normal user files replace such a character with a
+tilde, to avoid confusion with system file names.
+
+As an example of this special rule, consider
+@code{ada-strings-wide_fixed.adb}, which gets krunched as follows:
+
+@example
+ada-strings-wide_fixed 22
+a- strings wide fixed 18
+a- string wide fixed 17
+a- strin wide fixed 16
+a- stri wide fixed 15
+a- stri wide fixe 14
+a- str wide fixe 13
+a- str wid fixe 12
+a- str wid fix 11
+a- st wid fix 10
+a- st wi fix 9
+a- st wi fi 8
+Final file name: a-stwifi.adb
+@end example
+@end itemize
+
+Of course no file shortening algorithm can guarantee uniqueness over all
+possible unit names, and if file name krunching is used then it is your
+responsibility to ensure that no name clashes occur. The utility
+program @code{gnatkr} is supplied for conveniently determining the
+krunched name of a file.
+
+@node Examples of gnatkr Usage,,Krunching Method,File Name Krunching with gnatkr
+@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{53}@anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{54}
+@subsubsection Examples of @code{gnatkr} Usage
+
+
+@example
+$ gnatkr very_long_unit_name.ads --> velounna.ads
+$ gnatkr grandparent-parent-child.ads --> grparchi.ads
+$ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
+$ gnatkr grandparent-parent-child --> grparchi
+$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
+$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
+@end example
+
+@node Renaming Files with gnatchop,,File Name Krunching with gnatkr,File Naming Topics and Utilities
+@anchor{gnat_ugn/the_gnat_compilation_model id22}@anchor{55}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{1d}
+@subsection Renaming Files with @code{gnatchop}
+
+
+@geindex gnatchop
+
+This section discusses how to handle files with multiple units by using
+the @code{gnatchop} utility. This utility is also useful in renaming
+files to meet the standard GNAT default file naming conventions.
+
+@menu
+* Handling Files with Multiple Units::
+* Operating gnatchop in Compilation Mode::
+* Command Line for gnatchop::
+* Switches for gnatchop::
+* Examples of gnatchop Usage::
+
+@end menu
+
+@node Handling Files with Multiple Units,Operating gnatchop in Compilation Mode,,Renaming Files with gnatchop
+@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{56}@anchor{gnat_ugn/the_gnat_compilation_model id23}@anchor{57}
+@subsubsection Handling Files with Multiple Units
+
+
+The basic compilation model of GNAT requires that a file submitted to the
+compiler have only one unit and there be a strict correspondence
+between the file name and the unit name.
+
+If you want to keep your files with multiple units,
+perhaps to maintain compatibility with some other Ada compilation system,
+you can use @code{gnatname} to generate or update your project files.
+Generated or modified project files can be processed by GNAT.
+
+See @ref{42,,Handling Arbitrary File Naming Conventions with gnatname}
+for more details on how to use @cite{gnatname}.
+
+Alternatively, if you want to permanently restructure a set of ‘foreign’
+files so that they match the GNAT rules, and do the remaining development
+using the GNAT structure, you can simply use @code{gnatchop} once, generate the
+new set of files and work with them from that point on.
+
+Note that if your file containing multiple units starts with a byte order
+mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
+will each start with a copy of this BOM, meaning that they can be compiled
+automatically in UTF-8 mode without needing to specify an explicit encoding.
+
+@node Operating gnatchop in Compilation Mode,Command Line for gnatchop,Handling Files with Multiple Units,Renaming Files with gnatchop
+@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{58}@anchor{gnat_ugn/the_gnat_compilation_model operating-gnatchop-in-compilation-mode}@anchor{59}
+@subsubsection Operating gnatchop in Compilation Mode
+
+
+The basic function of @code{gnatchop} is to take a file with multiple units
+and split it into separate files. The boundary between files is reasonably
+clear, except for the issue of comments and pragmas. In default mode, the
+rule is that any pragmas between units belong to the previous unit, except
+that configuration pragmas always belong to the following unit. Any comments
+belong to the following unit. These rules
+almost always result in the right choice of
+the split point without needing to mark it explicitly and most users will
+find this default to be what they want. In this default mode it is incorrect to
+submit a file containing only configuration pragmas, or one that ends in
+configuration pragmas, to @code{gnatchop}.
+
+However, using a special option to activate ‘compilation mode’,
+@code{gnatchop}
+can perform another function, which is to provide exactly the semantics
+required by the RM for handling of configuration pragmas in a compilation.
+In the absence of configuration pragmas (at the main file level), this
+option has no effect, but it causes such configuration pragmas to be handled
+in a quite different manner.
+
+First, in compilation mode, if @code{gnatchop} is given a file that consists of
+only configuration pragmas, then this file is appended to the
+@code{gnat.adc} file in the current directory. This behavior provides
+the required behavior described in the RM for the actions to be taken
+on submitting such a file to the compiler, namely that these pragmas
+should apply to all subsequent compilations in the same compilation
+environment. Using GNAT, the current directory, possibly containing a
+@code{gnat.adc} file is the representation
+of a compilation environment. For more information on the
+@code{gnat.adc} file, see @ref{3f,,Handling of Configuration Pragmas}.
+
+Second, in compilation mode, if @code{gnatchop}
+is given a file that starts with
+configuration pragmas, and contains one or more units, then these
+configuration pragmas are prepended to each of the chopped files. This
+behavior provides the required behavior described in the RM for the
+actions to be taken on compiling such a file, namely that the pragmas
+apply to all units in the compilation, but not to subsequently compiled
+units.
+
+Finally, if configuration pragmas appear between units, they are appended
+to the previous unit. This results in the previous unit being illegal,
+since the compiler does not accept configuration pragmas that follow
+a unit. This provides the required RM behavior that forbids configuration
+pragmas other than those preceding the first compilation unit of a
+compilation.
+
+For most purposes, @code{gnatchop} will be used in default mode. The
+compilation mode described above is used only if you need exactly
+accurate behavior with respect to compilations, and you have files
+that contain multiple units and configuration pragmas. In this
+circumstance the use of @code{gnatchop} with the compilation mode
+switch provides the required behavior, and is for example the mode
+in which GNAT processes the ACVC tests.
+
+@node Command Line for gnatchop,Switches for gnatchop,Operating gnatchop in Compilation Mode,Renaming Files with gnatchop
+@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{5a}@anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{5b}
+@subsubsection Command Line for @code{gnatchop}
+
+
+The @code{gnatchop} command has the form:
+
+@example
+$ gnatchop switches file_name [file_name ...]
+ [directory]
+@end example
+
+The only required argument is the file name of the file to be chopped.
+There are no restrictions on the form of this file name. The file itself
+contains one or more Ada units, in normal GNAT format, concatenated
+together. As shown, more than one file may be presented to be chopped.
+
+When run in default mode, @code{gnatchop} generates one output file in
+the current directory for each unit in each of the files.
+
+@code{directory}, if specified, gives the name of the directory to which
+the output files will be written. If it is not specified, all files are
+written to the current directory.
+
+For example, given a
+file called @code{hellofiles} containing
+
+@example
+procedure Hello;
+
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Hello is
+begin
+ Put_Line ("Hello");
+end Hello;
+@end example
+
+the command
+
+@example
+$ gnatchop hellofiles
+@end example
+
+generates two files in the current directory, one called
+@code{hello.ads} containing the single line that is the procedure spec,
+and the other called @code{hello.adb} containing the remaining text. The
+original file is not affected. The generated files can be compiled in
+the normal manner.
+
+When gnatchop is invoked on a file that is empty or that contains only empty
+lines and/or comments, gnatchop will not fail, but will not produce any
+new sources.
+
+For example, given a
+file called @code{toto.txt} containing
+
+@example
+-- Just a comment
+@end example
+
+the command
+
+@example
+$ gnatchop toto.txt
+@end example
+
+will not produce any new file and will result in the following warnings:
+
+@example
+toto.txt:1:01: warning: empty file, contains no compilation units
+no compilation units found
+no source files written
+@end example
+
+@node Switches for gnatchop,Examples of gnatchop Usage,Command Line for gnatchop,Renaming Files with gnatchop
+@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{5c}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{5d}
+@subsubsection Switches for @code{gnatchop}
+
+
+@code{gnatchop} recognizes the following switches:
+
+@geindex --version (gnatchop)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display Copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatchop)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+@end table
+
+@geindex -c (gnatchop)
+
+
+@table @asis
+
+@item @code{-c}
+
+Causes @code{gnatchop} to operate in compilation mode, in which
+configuration pragmas are handled according to strict RM rules. See
+previous section for a full description of this mode.
+
+@item @code{-gnat`xxx'}
+
+This passes the given @code{-gnat`xxx'} switch to @code{gnat} which is
+used to parse the given file. Not all `xxx' options make sense,
+but for example, the use of @code{-gnati2} allows @code{gnatchop} to
+process a source file that uses Latin-2 coding for identifiers.
+
+@item @code{-h}
+
+Causes @code{gnatchop} to generate a brief help summary to the standard
+output file showing usage information.
+@end table
+
+@geindex -k (gnatchop)
+
+
+@table @asis
+
+@item @code{-k`mm'}
+
+Limit generated file names to the specified number @code{mm}
+of characters.
+This is useful if the
+resulting set of files is required to be interoperable with systems
+which limit the length of file names.
+No space is allowed between the @code{-k} and the numeric value. The numeric
+value may be omitted in which case a default of @code{-k8},
+suitable for use
+with DOS-like file systems, is used. If no @code{-k} switch
+is present then
+there is no limit on the length of file names.
+@end table
+
+@geindex -p (gnatchop)
+
+
+@table @asis
+
+@item @code{-p}
+
+Causes the file modification time stamp of the input file to be
+preserved and used for the time stamp of the output file(s). This may be
+useful for preserving coherency of time stamps in an environment where
+@code{gnatchop} is used as part of a standard build process.
+@end table
+
+@geindex -q (gnatchop)
+
+
+@table @asis
+
+@item @code{-q}
+
+Causes output of informational messages indicating the set of generated
+files to be suppressed. Warnings and error messages are unaffected.
+@end table
+
+@geindex -r (gnatchop)
+
+@geindex Source_Reference pragmas
+
+
+@table @asis
+
+@item @code{-r}
+
+Generate @code{Source_Reference} pragmas. Use this switch if the output
+files are regarded as temporary and development is to be done in terms
+of the original unchopped file. This switch causes
+@code{Source_Reference} pragmas to be inserted into each of the
+generated files to refers back to the original file name and line number.
+The result is that all error messages refer back to the original
+unchopped file.
+In addition, the debugging information placed into the object file (when
+the @code{-g} switch of @code{gcc} or @code{gnatmake} is
+specified)
+also refers back to this original file so that tools like profilers and
+debuggers will give information in terms of the original unchopped file.
+
+If the original file to be chopped itself contains
+a @code{Source_Reference}
+pragma referencing a third file, then gnatchop respects
+this pragma, and the generated @code{Source_Reference} pragmas
+in the chopped file refer to the original file, with appropriate
+line numbers. This is particularly useful when @code{gnatchop}
+is used in conjunction with @code{gnatprep} to compile files that
+contain preprocessing statements and multiple units.
+@end table
+
+@geindex -v (gnatchop)
+
+
+@table @asis
+
+@item @code{-v}
+
+Causes @code{gnatchop} to operate in verbose mode. The version
+number and copyright notice are output, as well as exact copies of
+the gnat1 commands spawned to obtain the chop control information.
+@end table
+
+@geindex -w (gnatchop)
+
+
+@table @asis
+
+@item @code{-w}
+
+Overwrite existing file names. Normally @code{gnatchop} regards it as a
+fatal error if there is already a file with the same name as a
+file it would otherwise output, in other words if the files to be
+chopped contain duplicated units. This switch bypasses this
+check, and causes all but the last instance of such duplicated
+units to be skipped.
+@end table
+
+@geindex --GCC= (gnatchop)
+
+
+@table @asis
+
+@item @code{--GCC=`xxxx'}
+
+Specify the path of the GNAT parser to be used. When this switch is used,
+no attempt is made to add the prefix to the GNAT parser executable.
+@end table
+
+@node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop
+@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{5e}@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{5f}
+@subsubsection Examples of @code{gnatchop} Usage
+
+
+@example
+$ gnatchop -w hello_s.ada prerelease/files
+@end example
+
+Chops the source file @code{hello_s.ada}. The output files will be
+placed in the directory @code{prerelease/files},
+overwriting any
+files with matching names in that directory (no files in the current
+directory are modified).
+
+@example
+$ gnatchop archive
+@end example
+
+Chops the source file @code{archive}
+into the current directory. One
+useful application of @code{gnatchop} is in sending sets of sources
+around, for example in email messages. The required sources are simply
+concatenated (for example, using a Unix @code{cat}
+command), and then
+@code{gnatchop} is used at the other end to reconstitute the original
+file names.
+
+@example
+$ gnatchop file1 file2 file3 direc
+@end example
+
+Chops all units in files @code{file1}, @code{file2}, @code{file3}, placing
+the resulting files in the directory @code{direc}. Note that if any units
+occur more than once anywhere within this set of files, an error message
+is generated, and no files are written. To override this check, use the
+@code{-w} switch,
+in which case the last occurrence in the last file will
+be the one that is output, and earlier duplicate occurrences for a given
+unit will be skipped.
+
+@node Configuration Pragmas,Generating Object Files,File Naming Topics and Utilities,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{25}@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{60}
+@section Configuration Pragmas
+
+
+@geindex Configuration pragmas
+
+@geindex Pragmas
+@geindex configuration
+
+Configuration pragmas include those pragmas described as
+such in the Ada Reference Manual, as well as
+implementation-dependent pragmas that are configuration pragmas.
+See the @code{Implementation_Defined_Pragmas} chapter in the
+@cite{GNAT_Reference_Manual} for details on these
+additional GNAT-specific configuration pragmas.
+Most notably, the pragma @code{Source_File_Name}, which allows
+specifying non-default names for source files, is a configuration
+pragma. The following is a complete list of configuration pragmas
+recognized by GNAT:
+
+@example
+Ada_83
+Ada_95
+Ada_05
+Ada_2005
+Ada_12
+Ada_2012
+Ada_2022
+Aggregate_Individually_Assign
+Allow_Integer_Address
+Annotate
+Assertion_Policy
+Assume_No_Invalid_Values
+C_Pass_By_Copy
+Check_Float_Overflow
+Check_Name
+Check_Policy
+Component_Alignment
+Convention_Identifier
+Debug_Policy
+Default_Scalar_Storage_Order
+Default_Storage_Pool
+Detect_Blocking
+Disable_Atomic_Synchronization
+Discard_Names
+Elaboration_Checks
+Eliminate
+Enable_Atomic_Synchronization
+Extend_System
+Extensions_Allowed
+External_Name_Casing
+Fast_Math
+Favor_Top_Level
+Ignore_Pragma
+Implicit_Packing
+Initialize_Scalars
+Interrupt_State
+License
+Locking_Policy
+No_Component_Reordering
+No_Heap_Finalization
+No_Strict_Aliasing
+Normalize_Scalars
+Optimize_Alignment
+Overflow_Mode
+Overriding_Renamings
+Partition_Elaboration_Policy
+Persistent_BSS
+Prefix_Exception_Messages
+Priority_Specific_Dispatching
+Profile
+Profile_Warnings
+Queuing_Policy
+Rename_Pragma
+Restrictions
+Restriction_Warnings
+Reviewable
+Short_Circuit_And_Or
+Source_File_Name
+Source_File_Name_Project
+SPARK_Mode
+Style_Checks
+Suppress
+Suppress_Exception_Locations
+Task_Dispatching_Policy
+Unevaluated_Use_Of_Old
+Unsuppress
+Use_VADS_Size
+Validity_Checks
+Warning_As_Error
+Warnings
+Wide_Character_Encoding
+@end example
+
+@menu
+* Handling of Configuration Pragmas::
+* The Configuration Pragmas Files::
+
+@end menu
+
+@node Handling of Configuration Pragmas,The Configuration Pragmas Files,,Configuration Pragmas
+@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{3f}@anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{61}
+@subsection Handling of Configuration Pragmas
+
+
+Configuration pragmas may either appear at the start of a compilation
+unit, or they can appear in a configuration pragma file to apply to
+all compilations performed in a given compilation environment.
+
+GNAT also provides the @code{gnatchop} utility to provide an automatic
+way to handle configuration pragmas following the semantics for
+compilations (that is, files with multiple units), described in the RM.
+See @ref{59,,Operating gnatchop in Compilation Mode} for details.
+However, for most purposes, it will be more convenient to edit the
+@code{gnat.adc} file that contains configuration pragmas directly,
+as described in the following section.
+
+In the case of @code{Restrictions} pragmas appearing as configuration
+pragmas in individual compilation units, the exact handling depends on
+the type of restriction.
+
+Restrictions that require partition-wide consistency (like
+@code{No_Tasking}) are
+recognized wherever they appear
+and can be freely inherited, e.g. from a `with'ed unit to the `with'ing
+unit. This makes sense since the binder will in any case insist on seeing
+consistent use, so any unit not conforming to any restrictions that are
+anywhere in the partition will be rejected, and you might as well find
+that out at compile time rather than at bind time.
+
+For restrictions that do not require partition-wide consistency, e.g.
+SPARK or No_Implementation_Attributes, in general the restriction applies
+only to the unit in which the pragma appears, and not to any other units.
+
+The exception is No_Elaboration_Code which always applies to the entire
+object file from a compilation, i.e. to the body, spec, and all subunits.
+This restriction can be specified in a configuration pragma file, or it
+can be on the body and/or the spec (in either case it applies to all the
+relevant units). It can appear on a subunit only if it has previously
+appeared in the body of spec.
+
+@node The Configuration Pragmas Files,,Handling of Configuration Pragmas,Configuration Pragmas
+@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{62}@anchor{gnat_ugn/the_gnat_compilation_model the-configuration-pragmas-files}@anchor{63}
+@subsection The Configuration Pragmas Files
+
+
+@geindex gnat.adc
+
+In GNAT a compilation environment is defined by the current
+directory at the time that a compile command is given. This current
+directory is searched for a file whose name is @code{gnat.adc}. If
+this file is present, it is expected to contain one or more
+configuration pragmas that will be applied to the current compilation.
+However, if the switch @code{-gnatA} is used, @code{gnat.adc} is not
+considered. When taken into account, @code{gnat.adc} is added to the
+dependencies, so that if @code{gnat.adc} is modified later, an invocation of
+@code{gnatmake} will recompile the source.
+
+Configuration pragmas may be entered into the @code{gnat.adc} file
+either by running @code{gnatchop} on a source file that consists only of
+configuration pragmas, or more conveniently by direct editing of the
+@code{gnat.adc} file, which is a standard format source file.
+
+Besides @code{gnat.adc}, additional files containing configuration
+pragmas may be applied to the current compilation using the switch
+@code{-gnatec=`path'} where @code{path} must designate an existing file that
+contains only configuration pragmas. These configuration pragmas are
+in addition to those found in @code{gnat.adc} (provided @code{gnat.adc}
+is present and switch @code{-gnatA} is not used).
+
+It is allowable to specify several switches @code{-gnatec=}, all of which
+will be taken into account.
+
+Files containing configuration pragmas specified with switches
+@code{-gnatec=} are added to the dependencies, unless they are
+temporary files. A file is considered temporary if its name ends in
+@code{.tmp} or @code{.TMP}. Certain tools follow this naming
+convention because they pass information to @code{gcc} via
+temporary files that are immediately deleted; it doesn’t make sense to
+depend on a file that no longer exists. Such tools include
+@code{gprbuild}, @code{gnatmake}, and @code{gnatcheck}.
+
+By default, configuration pragma files are stored by their absolute paths in
+ALI files. You can use the @code{-gnateb} switch in order to store them by
+their basename instead.
+
+If you are using project file, a separate mechanism is provided using
+project attributes.
+
+@c --Comment
+@c See :ref:`Specifying_Configuration_Pragmas` for more details.
+
+@node Generating Object Files,Source Dependencies,Configuration Pragmas,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model generating-object-files}@anchor{26}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{64}
+@section Generating Object Files
+
+
+An Ada program consists of a set of source files, and the first step in
+compiling the program is to generate the corresponding object files.
+These are generated by compiling a subset of these source files.
+The files you need to compile are the following:
+
+
+@itemize *
+
+@item
+If a package spec has no body, compile the package spec to produce the
+object file for the package.
+
+@item
+If a package has both a spec and a body, compile the body to produce the
+object file for the package. The source file for the package spec need
+not be compiled in this case because there is only one object file, which
+contains the code for both the spec and body of the package.
+
+@item
+For a subprogram, compile the subprogram body to produce the object file
+for the subprogram. The spec, if one is present, is as usual in a
+separate file, and need not be compiled.
+@end itemize
+
+@geindex Subunits
+
+
+@itemize *
+
+@item
+In the case of subunits, only compile the parent unit. A single object
+file is generated for the entire subunit tree, which includes all the
+subunits.
+
+@item
+Compile child units independently of their parent units
+(though, of course, the spec of all the ancestor unit must be present in order
+to compile a child unit).
+
+@geindex Generics
+
+@item
+Compile generic units in the same manner as any other units. The object
+files in this case are small dummy files that contain at most the
+flag used for elaboration checking. This is because GNAT always handles generic
+instantiation by means of macro expansion. However, it is still necessary to
+compile generic units, for dependency checking and elaboration purposes.
+@end itemize
+
+The preceding rules describe the set of files that must be compiled to
+generate the object files for a program. Each object file has the same
+name as the corresponding source file, except that the extension is
+@code{.o} as usual.
+
+You may wish to compile other files for the purpose of checking their
+syntactic and semantic correctness. For example, in the case where a
+package has a separate spec and body, you would not normally compile the
+spec. However, it is convenient in practice to compile the spec to make
+sure it is error-free before compiling clients of this spec, because such
+compilations will fail if there is an error in the spec.
+
+GNAT provides an option for compiling such files purely for the
+purposes of checking correctness; such compilations are not required as
+part of the process of building a program. To compile a file in this
+checking mode, use the @code{-gnatc} switch.
+
+@node Source Dependencies,The Ada Library Information Files,Generating Object Files,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{27}
+@section Source Dependencies
+
+
+A given object file clearly depends on the source file which is compiled
+to produce it. Here we are using “depends” in the sense of a typical
+@code{make} utility; in other words, an object file depends on a source
+file if changes to the source file require the object file to be
+recompiled.
+In addition to this basic dependency, a given object may depend on
+additional source files as follows:
+
+
+@itemize *
+
+@item
+If a file being compiled `with's a unit @code{X}, the object file
+depends on the file containing the spec of unit @code{X}. This includes
+files that are `with'ed implicitly either because they are parents
+of `with'ed child units or they are run-time units required by the
+language constructs used in a particular unit.
+
+@item
+If a file being compiled instantiates a library level generic unit, the
+object file depends on both the spec and body files for this generic
+unit.
+
+@item
+If a file being compiled instantiates a generic unit defined within a
+package, the object file depends on the body file for the package as
+well as the spec file.
+@end itemize
+
+@geindex Inline
+
+@geindex -gnatn switch
+
+
+@itemize *
+
+@item
+If a file being compiled contains a call to a subprogram for which
+pragma @code{Inline} applies and inlining is activated with the
+@code{-gnatn} switch, the object file depends on the file containing the
+body of this subprogram as well as on the file containing the spec. Note
+that for inlining to actually occur as a result of the use of this switch,
+it is necessary to compile in optimizing mode.
+
+@geindex -gnatN switch
+
+The use of @code{-gnatN} activates inlining optimization
+that is performed by the front end of the compiler. This inlining does
+not require that the code generation be optimized. Like @code{-gnatn},
+the use of this switch generates additional dependencies.
+
+When using a gcc-based back end, then the use of
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
+
+@item
+If an object file @code{O} depends on the proper body of a subunit through
+inlining or instantiation, it depends on the parent unit of the subunit.
+This means that any modification of the parent unit or one of its subunits
+affects the compilation of @code{O}.
+
+@item
+The object file for a parent unit depends on all its subunit body files.
+
+@item
+The previous two rules meant that for purposes of computing dependencies and
+recompilation, a body and all its subunits are treated as an indivisible whole.
+
+These rules are applied transitively: if unit @code{A} `with's
+unit @code{B}, whose elaboration calls an inlined procedure in package
+@code{C}, the object file for unit @code{A} will depend on the body of
+@code{C}, in file @code{c.adb}.
+
+The set of dependent files described by these rules includes all the
+files on which the unit is semantically dependent, as dictated by the
+Ada language standard. However, it is a superset of what the
+standard describes, because it includes generic, inline, and subunit
+dependencies.
+
+An object file must be recreated by recompiling the corresponding source
+file if any of the source files on which it depends are modified. For
+example, if the @code{make} utility is used to control compilation,
+the rule for an Ada object file must mention all the source files on
+which the object file depends, according to the above definition.
+The determination of the necessary
+recompilations is done automatically when one uses @code{gnatmake}.
+@end itemize
+
+@node The Ada Library Information Files,Binding an Ada Program,Source Dependencies,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model id33}@anchor{66}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{28}
+@section The Ada Library Information Files
+
+
+@geindex Ada Library Information files
+
+@geindex ALI files
+
+Each compilation actually generates two output files. The first of these
+is the normal object file that has a @code{.o} extension. The second is a
+text file containing full dependency information. It has the same
+name as the source file, but an @code{.ali} extension.
+This file is known as the Ada Library Information (@code{ALI}) file.
+The following information is contained in the @code{ALI} file.
+
+
+@itemize *
+
+@item
+Version information (indicates which version of GNAT was used to compile
+the unit(s) in question)
+
+@item
+Main program information (including priority and time slice settings,
+as well as the wide character encoding used during compilation).
+
+@item
+List of arguments used in the @code{gcc} command for the compilation
+
+@item
+Attributes of the unit, including configuration pragmas used, an indication
+of whether the compilation was successful, exception model used etc.
+
+@item
+A list of relevant restrictions applying to the unit (used for consistency)
+checking.
+
+@item
+Categorization information (e.g., use of pragma @code{Pure}).
+
+@item
+Information on all `with'ed units, including presence of
+@code{Elaborate} or @code{Elaborate_All} pragmas.
+
+@item
+Information from any @code{Linker_Options} pragmas used in the unit
+
+@item
+Information on the use of @code{Body_Version} or @code{Version}
+attributes in the unit.
+
+@item
+Dependency information. This is a list of files, together with
+time stamp and checksum information. These are files on which
+the unit depends in the sense that recompilation is required
+if any of these units are modified.
+
+@item
+Cross-reference data. Contains information on all entities referenced
+in the unit. Used by some tools to provide cross-reference information.
+@end itemize
+
+For a full detailed description of the format of the @code{ALI} file,
+see the source of the body of unit @code{Lib.Writ}, contained in file
+@code{lib-writ.adb} in the GNAT compiler sources.
+
+@node Binding an Ada Program,GNAT and Libraries,The Ada Library Information Files,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{29}@anchor{gnat_ugn/the_gnat_compilation_model id34}@anchor{67}
+@section Binding an Ada Program
+
+
+When using languages such as C and C++, once the source files have been
+compiled the only remaining step in building an executable program
+is linking the object modules together. This means that it is possible to
+link an inconsistent version of a program, in which two units have
+included different versions of the same header.
+
+The rules of Ada do not permit such an inconsistent program to be built.
+For example, if two clients have different versions of the same package,
+it is illegal to build a program containing these two clients.
+These rules are enforced by the GNAT binder, which also determines an
+elaboration order consistent with the Ada rules.
+
+The GNAT binder is run after all the object files for a program have
+been created. It is given the name of the main program unit, and from
+this it determines the set of units required by the program, by reading the
+corresponding ALI files. It generates error messages if the program is
+inconsistent or if no valid order of elaboration exists.
+
+If no errors are detected, the binder produces a main program, in Ada by
+default, that contains calls to the elaboration procedures of those
+compilation unit that require them, followed by
+a call to the main program. This Ada program is compiled to generate the
+object file for the main program. The name of
+the Ada file is @code{b~xxx}.adb` (with the corresponding spec
+@code{b~xxx}.ads`) where @code{xxx} is the name of the
+main program unit.
+
+Finally, the linker is used to build the resulting executable program,
+using the object from the main program from the bind step as well as the
+object files for the Ada units of the program.
+
+@node GNAT and Libraries,Conditional Compilation,Binding an Ada Program,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-libraries}@anchor{2a}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{68}
+@section GNAT and Libraries
+
+
+@geindex Library building and using
+
+This section describes how to build and use libraries with GNAT, and also shows
+how to recompile the GNAT run-time library. You should be familiar with the
+Project Manager facility (see the `GNAT_Project_Manager' chapter of the
+`GPRbuild User’s Guide') before reading this chapter.
+
+@menu
+* Introduction to Libraries in GNAT::
+* General Ada Libraries::
+* Stand-alone Ada Libraries::
+* Rebuilding the GNAT Run-Time Library::
+
+@end menu
+
+@node Introduction to Libraries in GNAT,General Ada Libraries,,GNAT and Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{69}@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-libraries-in-gnat}@anchor{6a}
+@subsection Introduction to Libraries in GNAT
+
+
+A library is, conceptually, a collection of objects which does not have its
+own main thread of execution, but rather provides certain services to the
+applications that use it. A library can be either statically linked with the
+application, in which case its code is directly included in the application,
+or, on platforms that support it, be dynamically linked, in which case
+its code is shared by all applications making use of this library.
+
+GNAT supports both types of libraries.
+In the static case, the compiled code can be provided in different ways. The
+simplest approach is to provide directly the set of objects resulting from
+compilation of the library source files. Alternatively, you can group the
+objects into an archive using whatever commands are provided by the operating
+system. For the latter case, the objects are grouped into a shared library.
+
+In the GNAT environment, a library has three types of components:
+
+
+@itemize *
+
+@item
+Source files,
+
+@item
+@code{ALI} files (see @ref{28,,The Ada Library Information Files}), and
+
+@item
+Object files, an archive or a shared library.
+@end itemize
+
+A GNAT library may expose all its source files, which is useful for
+documentation purposes. Alternatively, it may expose only the units needed by
+an external user to make use of the library. That is to say, the specs
+reflecting the library services along with all the units needed to compile
+those specs, which can include generic bodies or any body implementing an
+inlined routine. In the case of `stand-alone libraries' those exposed
+units are called `interface units' (@ref{6b,,Stand-alone Ada Libraries}).
+
+All compilation units comprising an application, including those in a library,
+need to be elaborated in an order partially defined by Ada’s semantics. GNAT
+computes the elaboration order from the @code{ALI} files and this is why they
+constitute a mandatory part of GNAT libraries.
+`Stand-alone libraries' are the exception to this rule because a specific
+library elaboration routine is produced independently of the application(s)
+using the library.
+
+@node General Ada Libraries,Stand-alone Ada Libraries,Introduction to Libraries in GNAT,GNAT and Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model general-ada-libraries}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{6d}
+@subsection General Ada Libraries
+
+
+@menu
+* Building a library::
+* Installing a library::
+* Using a library::
+
+@end menu
+
+@node Building a library,Installing a library,,General Ada Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model building-a-library}@anchor{6e}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{6f}
+@subsubsection Building a library
+
+
+The easiest way to build a library is to use the Project Manager,
+which supports a special type of project called a `Library Project'
+(see the `Library Projects' section in the `GNAT Project Manager'
+chapter of the `GPRbuild User’s Guide').
+
+A project is considered a library project, when two project-level attributes
+are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to
+control different aspects of library configuration, additional optional
+project-level attributes can be specified:
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item @code{Library_Kind}
+
+This attribute controls whether the library is to be static or dynamic
+@end table
+
+@item
+
+@table @asis
+
+@item @code{Library_Version}
+
+This attribute specifies the library version; this value is used
+during dynamic linking of shared libraries to determine if the currently
+installed versions of the binaries are compatible.
+@end table
+
+@item
+@code{Library_Options}
+
+@item
+
+@table @asis
+
+@item @code{Library_GCC}
+
+These attributes specify additional low-level options to be used during
+library generation, and redefine the actual application used to generate
+library.
+@end table
+@end itemize
+
+The GNAT Project Manager takes full care of the library maintenance task,
+including recompilation of the source files for which objects do not exist
+or are not up to date, assembly of the library archive, and installation of
+the library (i.e., copying associated source, object and @code{ALI} files
+to the specified location).
+
+Here is a simple library project file:
+
+@example
+project My_Lib is
+ for Source_Dirs use ("src1", "src2");
+ for Object_Dir use "obj";
+ for Library_Name use "mylib";
+ for Library_Dir use "lib";
+ for Library_Kind use "dynamic";
+end My_lib;
+@end example
+
+and the compilation command to build and install the library:
+
+@example
+$ gnatmake -Pmy_lib
+@end example
+
+It is not entirely trivial to perform manually all the steps required to
+produce a library. We recommend that you use the GNAT Project Manager
+for this task. In special cases where this is not desired, the necessary
+steps are discussed below.
+
+There are various possibilities for compiling the units that make up the
+library: for example with a Makefile (@ref{70,,Using the GNU make Utility}) or
+with a conventional script. For simple libraries, it is also possible to create
+a dummy main program which depends upon all the packages that comprise the
+interface of the library. This dummy main program can then be given to
+@code{gnatmake}, which will ensure that all necessary objects are built.
+
+After this task is accomplished, you should follow the standard procedure
+of the underlying operating system to produce the static or shared library.
+
+Here is an example of such a dummy program:
+
+@example
+with My_Lib.Service1;
+with My_Lib.Service2;
+with My_Lib.Service3;
+procedure My_Lib_Dummy is
+begin
+ null;
+end;
+@end example
+
+Here are the generic commands that will build an archive or a shared library.
+
+@example
+# compiling the library
+$ gnatmake -c my_lib_dummy.adb
+
+# we don't need the dummy object itself
+$ rm my_lib_dummy.o my_lib_dummy.ali
+
+# create an archive with the remaining objects
+$ ar rc libmy_lib.a *.o
+# some systems may require "ranlib" to be run as well
+
+# or create a shared library
+$ gcc -shared -o libmy_lib.so *.o
+# some systems may require the code to have been compiled with -fPIC
+
+# remove the object files that are now in the library
+$ rm *.o
+
+# Make the ALI files read-only so that gnatmake will not try to
+# regenerate the objects that are in the library
+$ chmod -w *.ali
+@end example
+
+Please note that the library must have a name of the form @code{lib`xxx'.a}
+or @code{lib`xxx'.so} (or @code{lib`xxx'.dll} on Windows) in order to
+be accessed by the directive @code{-l`xxx'} at link time.
+
+@node Installing a library,Using a library,Building a library,General Ada Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model installing-a-library}@anchor{72}
+@subsubsection Installing a library
+
+
+@geindex ADA_PROJECT_PATH
+
+@geindex GPR_PROJECT_PATH
+
+If you use project files, library installation is part of the library build
+process (see the `Installing a Library with Project Files' section of the
+`GNAT Project Manager' chapter of the `GPRbuild User’s Guide').
+
+When project files are not an option, it is also possible, but not recommended,
+to install the library so that the sources needed to use the library are on the
+Ada source path and the ALI files & libraries be on the Ada Object path (see
+@ref{73,,Search Paths and the Run-Time Library (RTL)}. Alternatively, the system
+administrator can place general-purpose libraries in the default compiler
+paths, by specifying the libraries’ location in the configuration files
+@code{ada_source_path} and @code{ada_object_path}. These configuration files
+must be located in the GNAT installation tree at the same place as the gcc spec
+file. The location of the gcc spec file can be determined as follows:
+
+@example
+$ gcc -v
+@end example
+
+The configuration files mentioned above have a simple format: each line
+must contain one unique directory name.
+Those names are added to the corresponding path
+in their order of appearance in the file. The names can be either absolute
+or relative; in the latter case, they are relative to where theses files
+are located.
+
+The files @code{ada_source_path} and @code{ada_object_path} might not be
+present in a
+GNAT installation, in which case, GNAT will look for its run-time library in
+the directories @code{adainclude} (for the sources) and @code{adalib} (for the
+objects and @code{ALI} files). When the files exist, the compiler does not
+look in @code{adainclude} and @code{adalib}, and thus the
+@code{ada_source_path} file
+must contain the location for the GNAT run-time sources (which can simply
+be @code{adainclude}). In the same way, the @code{ada_object_path} file must
+contain the location for the GNAT run-time objects (which can simply
+be @code{adalib}).
+
+You can also specify a new default path to the run-time library at compilation
+time with the switch @code{--RTS=rts-path}. You can thus choose / change
+the run-time library you want your program to be compiled with. This switch is
+recognized by @code{gcc}, @code{gnatmake}, @code{gnatbind}, @code{gnatls}, and all
+project aware tools.
+
+It is possible to install a library before or after the standard GNAT
+library, by reordering the lines in the configuration files. In general, a
+library must be installed before the GNAT library if it redefines
+any part of it.
+
+@node Using a library,,Installing a library,General Ada Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{74}@anchor{gnat_ugn/the_gnat_compilation_model using-a-library}@anchor{75}
+@subsubsection Using a library
+
+
+Once again, the project facility greatly simplifies the use of
+libraries. In this context, using a library is just a matter of adding a
+`with' clause in the user project. For instance, to make use of the
+library @code{My_Lib} shown in examples in earlier sections, you can
+write:
+
+@example
+with "my_lib";
+project My_Proj is
+ ...
+end My_Proj;
+@end example
+
+Even if you have a third-party, non-Ada library, you can still use GNAT’s
+Project Manager facility to provide a wrapper for it. For example, the
+following project, when `with'ed by your main project, will link with the
+third-party library @code{liba.a}:
+
+@example
+project Liba is
+ for Externally_Built use "true";
+ for Source_Files use ();
+ for Library_Dir use "lib";
+ for Library_Name use "a";
+ for Library_Kind use "static";
+end Liba;
+@end example
+
+This is an alternative to the use of @code{pragma Linker_Options}. It is
+especially interesting in the context of systems with several interdependent
+static libraries where finding a proper linker order is not easy and best be
+left to the tools having visibility over project dependence information.
+
+In order to use an Ada library manually, you need to make sure that this
+library is on both your source and object path
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}
+and @ref{76,,Search Paths for gnatbind}). Furthermore, when the objects are grouped
+in an archive or a shared library, you need to specify the desired
+library at link time.
+
+For example, you can use the library @code{mylib} installed in
+@code{/dir/my_lib_src} and @code{/dir/my_lib_obj} with the following commands:
+
+@example
+$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\
+ -largs -lmy_lib
+@end example
+
+This can be expressed more simply:
+
+@example
+$ gnatmake my_appl
+@end example
+
+when the following conditions are met:
+
+
+@itemize *
+
+@item
+@code{/dir/my_lib_src} has been added by the user to the environment
+variable
+@geindex ADA_INCLUDE_PATH
+@geindex environment variable; ADA_INCLUDE_PATH
+@code{ADA_INCLUDE_PATH}, or by the administrator to the file
+@code{ada_source_path}
+
+@item
+@code{/dir/my_lib_obj} has been added by the user to the environment
+variable
+@geindex ADA_OBJECTS_PATH
+@geindex environment variable; ADA_OBJECTS_PATH
+@code{ADA_OBJECTS_PATH}, or by the administrator to the file
+@code{ada_object_path}
+
+@item
+a pragma @code{Linker_Options} has been added to one of the sources.
+For example:
+
+@example
+pragma Linker_Options ("-lmy_lib");
+@end example
+@end itemize
+
+Note that you may also load a library dynamically at
+run time given its filename, as illustrated in the GNAT @code{plugins} example
+in the directory @code{share/examples/gnat/plugins} within the GNAT
+install area.
+
+@node Stand-alone Ada Libraries,Rebuilding the GNAT Run-Time Library,General Ada Libraries,GNAT and Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{77}@anchor{gnat_ugn/the_gnat_compilation_model stand-alone-ada-libraries}@anchor{6b}
+@subsection Stand-alone Ada Libraries
+
+
+@geindex Stand-alone libraries
+
+@menu
+* Introduction to Stand-alone Libraries::
+* Building a Stand-alone Library::
+* Creating a Stand-alone Library to be used in a non-Ada context::
+* Restrictions in Stand-alone Libraries::
+
+@end menu
+
+@node Introduction to Stand-alone Libraries,Building a Stand-alone Library,,Stand-alone Ada Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{78}@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-stand-alone-libraries}@anchor{79}
+@subsubsection Introduction to Stand-alone Libraries
+
+
+A Stand-alone Library (abbreviated ‘SAL’) is a library that contains the
+necessary code to
+elaborate the Ada units that are included in the library. In contrast with
+an ordinary library, which consists of all sources, objects and @code{ALI}
+files of the
+library, a SAL may specify a restricted subset of compilation units
+to serve as a library interface. In this case, the fully
+self-sufficient set of files will normally consist of an objects
+archive, the sources of interface units’ specs, and the @code{ALI}
+files of interface units.
+If an interface spec contains a generic unit or an inlined subprogram,
+the body’s
+source must also be provided; if the units that must be provided in the source
+form depend on other units, the source and @code{ALI} files of those must
+also be provided.
+
+The main purpose of a SAL is to minimize the recompilation overhead of client
+applications when a new version of the library is installed. Specifically,
+if the interface sources have not changed, client applications do not need to
+be recompiled. If, furthermore, a SAL is provided in the shared form and its
+version, controlled by @code{Library_Version} attribute, is not changed,
+then the clients do not need to be relinked.
+
+SALs also allow the library providers to minimize the amount of library source
+text exposed to the clients. Such ‘information hiding’ might be useful or
+necessary for various reasons.
+
+Stand-alone libraries are also well suited to be used in an executable whose
+main routine is not written in Ada.
+
+@node Building a Stand-alone Library,Creating a Stand-alone Library to be used in a non-Ada context,Introduction to Stand-alone Libraries,Stand-alone Ada Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{7a}@anchor{gnat_ugn/the_gnat_compilation_model id43}@anchor{7b}
+@subsubsection Building a Stand-alone Library
+
+
+GNAT’s Project facility provides a simple way of building and installing
+stand-alone libraries; see the `Stand-alone Library Projects' section
+in the `GNAT Project Manager' chapter of the `GPRbuild User’s Guide'.
+To be a Stand-alone Library Project, in addition to the two attributes
+that make a project a Library Project (@code{Library_Name} and
+@code{Library_Dir}; see the `Library Projects' section in the
+`GNAT Project Manager' chapter of the `GPRbuild User’s Guide'),
+the attribute @code{Library_Interface} must be defined. For example:
+
+@example
+for Library_Dir use "lib_dir";
+for Library_Name use "dummy";
+for Library_Interface use ("int1", "int1.child");
+@end example
+
+Attribute @code{Library_Interface} has a non-empty string list value,
+each string in the list designating a unit contained in an immediate source
+of the project file.
+
+When a Stand-alone Library is built, first the binder is invoked to build
+a package whose name depends on the library name
+(@code{b~dummy.ads/b} in the example above).
+This binder-generated package includes initialization and
+finalization procedures whose
+names depend on the library name (@code{dummyinit} and @code{dummyfinal}
+in the example
+above). The object corresponding to this package is included in the library.
+
+You must ensure timely (e.g., prior to any use of interfaces in the SAL)
+calling of these procedures if a static SAL is built, or if a shared SAL
+is built
+with the project-level attribute @code{Library_Auto_Init} set to
+@code{"false"}.
+
+For a Stand-Alone Library, only the @code{ALI} files of the Interface Units
+(those that are listed in attribute @code{Library_Interface}) are copied to
+the Library Directory. As a consequence, only the Interface Units may be
+imported from Ada units outside of the library. If other units are imported,
+the binding phase will fail.
+
+It is also possible to build an encapsulated library where not only
+the code to elaborate and finalize the library is embedded but also
+ensuring that the library is linked only against static
+libraries. So an encapsulated library only depends on system
+libraries, all other code, including the GNAT runtime, is embedded. To
+build an encapsulated library the attribute
+@code{Library_Standalone} must be set to @code{encapsulated}:
+
+@example
+for Library_Dir use "lib_dir";
+for Library_Name use "dummy";
+for Library_Kind use "dynamic";
+for Library_Interface use ("int1", "int1.child");
+for Library_Standalone use "encapsulated";
+@end example
+
+The default value for this attribute is @code{standard} in which case
+a stand-alone library is built.
+
+The attribute @code{Library_Src_Dir} may be specified for a
+Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
+single string value. Its value must be the path (absolute or relative to the
+project directory) of an existing directory. This directory cannot be the
+object directory or one of the source directories, but it can be the same as
+the library directory. The sources of the Interface
+Units of the library that are needed by an Ada client of the library will be
+copied to the designated directory, called the Interface Copy directory.
+These sources include the specs of the Interface Units, but they may also
+include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
+are used, or when there is a generic unit in the spec. Before the sources
+are copied to the Interface Copy directory, an attempt is made to delete all
+files in the Interface Copy directory.
+
+Building stand-alone libraries by hand is somewhat tedious, but for those
+occasions when it is necessary here are the steps that you need to perform:
+
+
+@itemize *
+
+@item
+Compile all library sources.
+
+@item
+Invoke the binder with the switch @code{-n} (No Ada main program),
+with all the @code{ALI} files of the interfaces, and
+with the switch @code{-L} to give specific names to the @code{init}
+and @code{final} procedures. For example:
+
+@example
+$ gnatbind -n int1.ali int2.ali -Lsal1
+@end example
+
+@item
+Compile the binder generated file:
+
+@example
+$ gcc -c b~int2.adb
+@end example
+
+@item
+Link the dynamic library with all the necessary object files,
+indicating to the linker the names of the @code{init} (and possibly
+@code{final}) procedures for automatic initialization (and finalization).
+The built library should be placed in a directory different from
+the object directory.
+
+@item
+Copy the @code{ALI} files of the interface to the library directory,
+add in this copy an indication that it is an interface to a SAL
+(i.e., add a word @code{SL} on the line in the @code{ALI} file that starts
+with letter ‘P’) and make the modified copy of the @code{ALI} file
+read-only.
+@end itemize
+
+Using SALs is not different from using other libraries
+(see @ref{75,,Using a library}).
+
+@node Creating a Stand-alone Library to be used in a non-Ada context,Restrictions in Stand-alone Libraries,Building a Stand-alone Library,Stand-alone Ada Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model creating-a-stand-alone-library-to-be-used-in-a-non-ada-context}@anchor{7c}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{7d}
+@subsubsection Creating a Stand-alone Library to be used in a non-Ada context
+
+
+It is easy to adapt the SAL build procedure discussed above for use of a SAL in
+a non-Ada context.
+
+The only extra step required is to ensure that library interface subprograms
+are compatible with the main program, by means of @code{pragma Export}
+or @code{pragma Convention}.
+
+Here is an example of simple library interface for use with C main program:
+
+@example
+package My_Package is
+
+ procedure Do_Something;
+ pragma Export (C, Do_Something, "do_something");
+
+ procedure Do_Something_Else;
+ pragma Export (C, Do_Something_Else, "do_something_else");
+
+end My_Package;
+@end example
+
+On the foreign language side, you must provide a ‘foreign’ view of the
+library interface; remember that it should contain elaboration routines in
+addition to interface subprograms.
+
+The example below shows the content of @code{mylib_interface.h} (note
+that there is no rule for the naming of this file, any name can be used)
+
+@example
+/* the library elaboration procedure */
+extern void mylibinit (void);
+
+/* the library finalization procedure */
+extern void mylibfinal (void);
+
+/* the interface exported by the library */
+extern void do_something (void);
+extern void do_something_else (void);
+@end example
+
+Libraries built as explained above can be used from any program, provided
+that the elaboration procedures (named @code{mylibinit} in the previous
+example) are called before the library services are used. Any number of
+libraries can be used simultaneously, as long as the elaboration
+procedure of each library is called.
+
+Below is an example of a C program that uses the @code{mylib} library.
+
+@example
+#include "mylib_interface.h"
+
+int
+main (void)
+@{
+ /* First, elaborate the library before using it */
+ mylibinit ();
+
+ /* Main program, using the library exported entities */
+ do_something ();
+ do_something_else ();
+
+ /* Library finalization at the end of the program */
+ mylibfinal ();
+ return 0;
+@}
+@end example
+
+Note that invoking any library finalization procedure generated by
+@code{gnatbind} shuts down the Ada run-time environment.
+Consequently, the
+finalization of all Ada libraries must be performed at the end of the program.
+No call to these libraries or to the Ada run-time library should be made
+after the finalization phase.
+
+Note also that special care must be taken with multi-tasks
+applications. The initialization and finalization routines are not
+protected against concurrent access. If such requirement is needed it
+must be ensured at the application level using a specific operating
+system services like a mutex or a critical-section.
+
+@node Restrictions in Stand-alone Libraries,,Creating a Stand-alone Library to be used in a non-Ada context,Stand-alone Ada Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model id45}@anchor{7e}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{7f}
+@subsubsection Restrictions in Stand-alone Libraries
+
+
+The pragmas listed below should be used with caution inside libraries,
+as they can create incompatibilities with other Ada libraries:
+
+
+@itemize *
+
+@item
+pragma @code{Locking_Policy}
+
+@item
+pragma @code{Partition_Elaboration_Policy}
+
+@item
+pragma @code{Queuing_Policy}
+
+@item
+pragma @code{Task_Dispatching_Policy}
+
+@item
+pragma @code{Unreserve_All_Interrupts}
+@end itemize
+
+When using a library that contains such pragmas, the user must make sure
+that all libraries use the same pragmas with the same values. Otherwise,
+@code{Program_Error} will
+be raised during the elaboration of the conflicting
+libraries. The usage of these pragmas and its consequences for the user
+should therefore be well documented.
+
+Similarly, the traceback in the exception occurrence mechanism should be
+enabled or disabled in a consistent manner across all libraries.
+Otherwise, Program_Error will be raised during the elaboration of the
+conflicting libraries.
+
+If the @code{Version} or @code{Body_Version}
+attributes are used inside a library, then you need to
+perform a @code{gnatbind} step that specifies all @code{ALI} files in all
+libraries, so that version identifiers can be properly computed.
+In practice these attributes are rarely used, so this is unlikely
+to be a consideration.
+
+@node Rebuilding the GNAT Run-Time Library,,Stand-alone Ada Libraries,GNAT and Libraries
+@anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{80}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{81}
+@subsection Rebuilding the GNAT Run-Time Library
+
+
+@geindex GNAT Run-Time Library
+@geindex rebuilding
+
+@geindex Building the GNAT Run-Time Library
+
+@geindex Rebuilding the GNAT Run-Time Library
+
+@geindex Run-Time Library
+@geindex rebuilding
+
+It may be useful to recompile the GNAT library in various debugging or
+experimentation contexts. A project file called
+@code{libada.gpr} is provided to that effect and can be found in
+the directory containing the GNAT library. The location of this
+directory depends on the way the GNAT environment has been installed and can
+be determined by means of the command:
+
+@example
+$ gnatls -v
+@end example
+
+The last entry in the source search path usually contains the
+gnat library (the @code{adainclude} directory). This project file contains its
+own documentation and in particular the set of instructions needed to rebuild a
+new library and to use it.
+
+Note that rebuilding the GNAT Run-Time is only recommended for temporary
+experiments or debugging, and is not supported.
+
+@geindex Conditional compilation
+
+@node Conditional Compilation,Mixed Language Programming,GNAT and Libraries,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{2b}@anchor{gnat_ugn/the_gnat_compilation_model id47}@anchor{82}
+@section Conditional Compilation
+
+
+This section presents some guidelines for modeling conditional compilation in Ada and describes the
+gnatprep preprocessor utility.
+
+@geindex Conditional compilation
+
+@menu
+* Modeling Conditional Compilation in Ada::
+* Preprocessing with gnatprep::
+* Integrated Preprocessing::
+
+@end menu
+
+@node Modeling Conditional Compilation in Ada,Preprocessing with gnatprep,,Conditional Compilation
+@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{83}@anchor{gnat_ugn/the_gnat_compilation_model modeling-conditional-compilation-in-ada}@anchor{84}
+@subsection Modeling Conditional Compilation in Ada
+
+
+It is often necessary to arrange for a single source program
+to serve multiple purposes, where it is compiled in different
+ways to achieve these different goals. Some examples of the
+need for this feature are
+
+
+@itemize *
+
+@item
+Adapting a program to a different hardware environment
+
+@item
+Adapting a program to a different target architecture
+
+@item
+Turning debugging features on and off
+
+@item
+Arranging for a program to compile with different compilers
+@end itemize
+
+In C, or C++, the typical approach would be to use the preprocessor
+that is defined as part of the language. The Ada language does not
+contain such a feature. This is not an oversight, but rather a very
+deliberate design decision, based on the experience that overuse of
+the preprocessing features in C and C++ can result in programs that
+are extremely difficult to maintain. For example, if we have ten
+switches that can be on or off, this means that there are a thousand
+separate programs, any one of which might not even be syntactically
+correct, and even if syntactically correct, the resulting program
+might not work correctly. Testing all combinations can quickly become
+impossible.
+
+Nevertheless, the need to tailor programs certainly exists, and in
+this section we will discuss how this can
+be achieved using Ada in general, and GNAT in particular.
+
+@menu
+* Use of Boolean Constants::
+* Debugging - A Special Case::
+* Conditionalizing Declarations::
+* Use of Alternative Implementations::
+* Preprocessing::
+
+@end menu
+
+@node Use of Boolean Constants,Debugging - A Special Case,,Modeling Conditional Compilation in Ada
+@anchor{gnat_ugn/the_gnat_compilation_model id49}@anchor{85}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{86}
+@subsubsection Use of Boolean Constants
+
+
+In the case where the difference is simply which code
+sequence is executed, the cleanest solution is to use Boolean
+constants to control which code is executed.
+
+@example
+FP_Initialize_Required : constant Boolean := True;
+...
+if FP_Initialize_Required then
+...
+end if;
+@end example
+
+Not only will the code inside the @code{if} statement not be executed if
+the constant Boolean is @code{False}, but it will also be completely
+deleted from the program.
+However, the code is only deleted after the @code{if} statement
+has been checked for syntactic and semantic correctness.
+(In contrast, with preprocessors the code is deleted before the
+compiler ever gets to see it, so it is not checked until the switch
+is turned on.)
+
+@geindex Preprocessors (contrasted with conditional compilation)
+
+Typically the Boolean constants will be in a separate package,
+something like:
+
+@example
+package Config is
+ FP_Initialize_Required : constant Boolean := True;
+ Reset_Available : constant Boolean := False;
+ ...
+end Config;
+@end example
+
+The @code{Config} package exists in multiple forms for the various targets,
+with an appropriate script selecting the version of @code{Config} needed.
+Then any other unit requiring conditional compilation can do a `with'
+of @code{Config} to make the constants visible.
+
+@node Debugging - A Special Case,Conditionalizing Declarations,Use of Boolean Constants,Modeling Conditional Compilation in Ada
+@anchor{gnat_ugn/the_gnat_compilation_model debugging-a-special-case}@anchor{87}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{88}
+@subsubsection Debugging - A Special Case
+
+
+A common use of conditional code is to execute statements (for example
+dynamic checks, or output of intermediate results) under control of a
+debug switch, so that the debugging behavior can be turned on and off.
+This can be done using a Boolean constant to control whether the code
+is active:
+
+@example
+if Debugging then
+ Put_Line ("got to the first stage!");
+end if;
+@end example
+
+or
+
+@example
+if Debugging and then Temperature > 999.0 then
+ raise Temperature_Crazy;
+end if;
+@end example
+
+@geindex pragma Assert
+
+Since this is a common case, there are special features to deal with
+this in a convenient manner. For the case of tests, Ada 2005 has added
+a pragma @code{Assert} that can be used for such tests. This pragma is modeled
+on the @code{Assert} pragma that has always been available in GNAT, so this
+feature may be used with GNAT even if you are not using Ada 2005 features.
+The use of pragma @code{Assert} is described in the
+@cite{GNAT_Reference_Manual}, but as an
+example, the last test could be written:
+
+@example
+pragma Assert (Temperature <= 999.0, "Temperature Crazy");
+@end example
+
+or simply
+
+@example
+pragma Assert (Temperature <= 999.0);
+@end example
+
+In both cases, if assertions are active and the temperature is excessive,
+the exception @code{Assert_Failure} will be raised, with the given string in
+the first case or a string indicating the location of the pragma in the second
+case used as the exception message.
+
+@geindex pragma Assertion_Policy
+
+You can turn assertions on and off by using the @code{Assertion_Policy}
+pragma.
+
+@geindex -gnata switch
+
+This is an Ada 2005 pragma which is implemented in all modes by
+GNAT. Alternatively, you can use the @code{-gnata} switch
+to enable assertions from the command line, which applies to
+all versions of Ada.
+
+@geindex pragma Debug
+
+For the example above with the @code{Put_Line}, the GNAT-specific pragma
+@code{Debug} can be used:
+
+@example
+pragma Debug (Put_Line ("got to the first stage!"));
+@end example
+
+If debug pragmas are enabled, the argument, which must be of the form of
+a procedure call, is executed (in this case, @code{Put_Line} will be called).
+Only one call can be present, but of course a special debugging procedure
+containing any code you like can be included in the program and then
+called in a pragma @code{Debug} argument as needed.
+
+One advantage of pragma @code{Debug} over the @code{if Debugging then}
+construct is that pragma @code{Debug} can appear in declarative contexts,
+such as at the very beginning of a procedure, before local declarations have
+been elaborated.
+
+@geindex pragma Debug_Policy
+
+Debug pragmas are enabled using either the @code{-gnata} switch that also
+controls assertions, or with a separate Debug_Policy pragma.
+
+The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used
+in Ada 95 and Ada 83 programs as well), and is analogous to
+pragma @code{Assertion_Policy} to control assertions.
+
+@code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas,
+and thus they can appear in @code{gnat.adc} if you are not using a
+project file, or in the file designated to contain configuration pragmas
+in a project file.
+They then apply to all subsequent compilations. In practice the use of
+the @code{-gnata} switch is often the most convenient method of controlling
+the status of these pragmas.
+
+Note that a pragma is not a statement, so in contexts where a statement
+sequence is required, you can’t just write a pragma on its own. You have
+to add a @code{null} statement.
+
+@example
+if ... then
+ ... -- some statements
+else
+ pragma Assert (Num_Cases < 10);
+ null;
+end if;
+@end example
+
+@node Conditionalizing Declarations,Use of Alternative Implementations,Debugging - A Special Case,Modeling Conditional Compilation in Ada
+@anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{89}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{8a}
+@subsubsection Conditionalizing Declarations
+
+
+In some cases it may be necessary to conditionalize declarations to meet
+different requirements. For example we might want a bit string whose length
+is set to meet some hardware message requirement.
+
+This may be possible using declare blocks controlled
+by conditional constants:
+
+@example
+if Small_Machine then
+ declare
+ X : Bit_String (1 .. 10);
+ begin
+ ...
+ end;
+else
+ declare
+ X : Large_Bit_String (1 .. 1000);
+ begin
+ ...
+ end;
+end if;
+@end example
+
+Note that in this approach, both declarations are analyzed by the
+compiler so this can only be used where both declarations are legal,
+even though one of them will not be used.
+
+Another approach is to define integer constants, e.g., @code{Bits_Per_Word},
+or Boolean constants, e.g., @code{Little_Endian}, and then write declarations
+that are parameterized by these constants. For example
+
+@example
+for Rec use
+ Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word;
+end record;
+@end example
+
+If @code{Bits_Per_Word} is set to 32, this generates either
+
+@example
+for Rec use
+ Field1 at 0 range 0 .. 32;
+end record;
+@end example
+
+for the big endian case, or
+
+@example
+for Rec use record
+ Field1 at 0 range 10 .. 32;
+end record;
+@end example
+
+for the little endian case. Since a powerful subset of Ada expression
+notation is usable for creating static constants, clever use of this
+feature can often solve quite difficult problems in conditionalizing
+compilation (note incidentally that in Ada 95, the little endian
+constant was introduced as @code{System.Default_Bit_Order}, so you do not
+need to define this one yourself).
+
+@node Use of Alternative Implementations,Preprocessing,Conditionalizing Declarations,Modeling Conditional Compilation in Ada
+@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{8b}@anchor{gnat_ugn/the_gnat_compilation_model use-of-alternative-implementations}@anchor{8c}
+@subsubsection Use of Alternative Implementations
+
+
+In some cases, none of the approaches described above are adequate. This
+can occur for example if the set of declarations required is radically
+different for two different configurations.
+
+In this situation, the official Ada way of dealing with conditionalizing
+such code is to write separate units for the different cases. As long as
+this does not result in excessive duplication of code, this can be done
+without creating maintenance problems. The approach is to share common
+code as far as possible, and then isolate the code and declarations
+that are different. Subunits are often a convenient method for breaking
+out a piece of a unit that is to be conditionalized, with separate files
+for different versions of the subunit for different targets, where the
+build script selects the right one to give to the compiler.
+
+@geindex Subunits (and conditional compilation)
+
+As an example, consider a situation where a new feature in Ada 2005
+allows something to be done in a really nice way. But your code must be able
+to compile with an Ada 95 compiler. Conceptually you want to say:
+
+@example
+if Ada_2005 then
+ ... neat Ada 2005 code
+else
+ ... not quite as neat Ada 95 code
+end if;
+@end example
+
+where @code{Ada_2005} is a Boolean constant.
+
+But this won’t work when @code{Ada_2005} is set to @code{False},
+since the @code{then} clause will be illegal for an Ada 95 compiler.
+(Recall that although such unreachable code would eventually be deleted
+by the compiler, it still needs to be legal. If it uses features
+introduced in Ada 2005, it will be illegal in Ada 95.)
+
+So instead we write
+
+@example
+procedure Insert is separate;
+@end example
+
+Then we have two files for the subunit @code{Insert}, with the two sets of
+code.
+If the package containing this is called @code{File_Queries}, then we might
+have two files
+
+
+@itemize *
+
+@item
+@code{file_queries-insert-2005.adb}
+
+@item
+@code{file_queries-insert-95.adb}
+@end itemize
+
+and the build script renames the appropriate file to @code{file_queries-insert.adb} and then carries out the compilation.
+
+This can also be done with project files’ naming schemes. For example:
+
+@example
+for body ("File_Queries.Insert") use "file_queries-insert-2005.ada";
+@end example
+
+Note also that with project files it is desirable to use a different extension
+than @code{ads} / @code{adb} for alternative versions. Otherwise a naming
+conflict may arise through another commonly used feature: to declare as part
+of the project a set of directories containing all the sources obeying the
+default naming scheme.
+
+The use of alternative units is certainly feasible in all situations,
+and for example the Ada part of the GNAT run-time is conditionalized
+based on the target architecture using this approach. As a specific example,
+consider the implementation of the AST feature in VMS. There is one
+spec: @code{s-asthan.ads} which is the same for all architectures, and three
+bodies:
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item @code{s-asthan.adb}
+
+used for all non-VMS operating systems
+@end table
+
+@item
+
+@table @asis
+
+@item @code{s-asthan-vms-alpha.adb}
+
+used for VMS on the Alpha
+@end table
+
+@item
+
+@table @asis
+
+@item @code{s-asthan-vms-ia64.adb}
+
+used for VMS on the ia64
+@end table
+@end itemize
+
+The dummy version @code{s-asthan.adb} simply raises exceptions noting that
+this operating system feature is not available, and the two remaining
+versions interface with the corresponding versions of VMS to provide
+VMS-compatible AST handling. The GNAT build script knows the architecture
+and operating system, and automatically selects the right version,
+renaming it if necessary to @code{s-asthan.adb} before the run-time build.
+
+Another style for arranging alternative implementations is through Ada’s
+access-to-subprogram facility.
+In case some functionality is to be conditionally included,
+you can declare an access-to-procedure variable @code{Ref} that is initialized
+to designate a ‘do nothing’ procedure, and then invoke @code{Ref.all}
+when appropriate.
+In some library package, set @code{Ref} to @code{Proc'Access} for some
+procedure @code{Proc} that performs the relevant processing.
+The initialization only occurs if the library package is included in the
+program.
+The same idea can also be implemented using tagged types and dispatching
+calls.
+
+@node Preprocessing,,Use of Alternative Implementations,Modeling Conditional Compilation in Ada
+@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{8d}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{8e}
+@subsubsection Preprocessing
+
+
+@geindex Preprocessing
+
+Although it is quite possible to conditionalize code without the use of
+C-style preprocessing, as described earlier in this section, it is
+nevertheless convenient in some cases to use the C approach. Moreover,
+older Ada compilers have often provided some preprocessing capability,
+so legacy code may depend on this approach, even though it is not
+standard.
+
+To accommodate such use, GNAT provides a preprocessor (modeled to a large
+extent on the various preprocessors that have been used
+with legacy code on other compilers, to enable easier transition).
+
+@geindex gnatprep
+
+The preprocessor may be used in two separate modes. It can be used quite
+separately from the compiler, to generate a separate output source file
+that is then fed to the compiler as a separate step. This is the
+@code{gnatprep} utility, whose use is fully described in
+@ref{8f,,Preprocessing with gnatprep}.
+
+The preprocessing language allows such constructs as
+
+@example
+#if DEBUG or else (PRIORITY > 4) then
+ sequence of declarations
+#else
+ completely different sequence of declarations
+#end if;
+@end example
+
+The values of the symbols @code{DEBUG} and @code{PRIORITY} can be
+defined either on the command line or in a separate file.
+
+The other way of running the preprocessor is even closer to the C style and
+often more convenient. In this approach the preprocessing is integrated into
+the compilation process. The compiler is given the preprocessor input which
+includes @code{#if} lines etc, and then the compiler carries out the
+preprocessing internally and processes the resulting output.
+For more details on this approach, see @ref{90,,Integrated Preprocessing}.
+
+@node Preprocessing with gnatprep,Integrated Preprocessing,Modeling Conditional Compilation in Ada,Conditional Compilation
+@anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{91}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{8f}
+@subsection Preprocessing with @code{gnatprep}
+
+
+@geindex gnatprep
+
+@geindex Preprocessing (gnatprep)
+
+This section discusses how to use GNAT’s @code{gnatprep} utility for simple
+preprocessing.
+Although designed for use with GNAT, @code{gnatprep} does not depend on any
+special GNAT features.
+For further discussion of conditional compilation in general, see
+@ref{2b,,Conditional Compilation}.
+
+@menu
+* Preprocessing Symbols::
+* Using gnatprep::
+* Switches for gnatprep::
+* Form of Definitions File::
+* Form of Input Text for gnatprep::
+
+@end menu
+
+@node Preprocessing Symbols,Using gnatprep,,Preprocessing with gnatprep
+@anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{92}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{93}
+@subsubsection Preprocessing Symbols
+
+
+Preprocessing symbols are defined in `definition files' and referenced in the
+sources to be preprocessed. A preprocessing symbol is an identifier, following
+normal Ada (case-insensitive) rules for its syntax, with the restriction that
+all characters need to be in the ASCII set (no accented letters).
+
+@node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep
+@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{94}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{95}
+@subsubsection Using @code{gnatprep}
+
+
+To call @code{gnatprep} use:
+
+@example
+$ gnatprep [ switches ] infile outfile [ deffile ]
+@end example
+
+where
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item `switches'
+
+is an optional sequence of switches as described in the next section.
+@end table
+
+@item
+
+@table @asis
+
+@item `infile'
+
+is the full name of the input file, which is an Ada source
+file containing preprocessor directives.
+@end table
+
+@item
+
+@table @asis
+
+@item `outfile'
+
+is the full name of the output file, which is an Ada source
+in standard Ada form. When used with GNAT, this file name will
+normally have an @code{ads} or @code{adb} suffix.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{deffile}
+
+is the full name of a text file containing definitions of
+preprocessing symbols to be referenced by the preprocessor. This argument is
+optional, and can be replaced by the use of the @code{-D} switch.
+@end table
+@end itemize
+
+@node Switches for gnatprep,Form of Definitions File,Using gnatprep,Preprocessing with gnatprep
+@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{96}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{97}
+@subsubsection Switches for @code{gnatprep}
+
+
+@geindex --version (gnatprep)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display Copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatprep)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage and then exit disregarding
+all other options.
+@end table
+
+@geindex -b (gnatprep)
+
+
+@table @asis
+
+@item @code{-b}
+
+Causes both preprocessor lines and the lines deleted by
+preprocessing to be replaced by blank lines in the output source file,
+preserving line numbers in the output file.
+@end table
+
+@geindex -c (gnatprep)
+
+
+@table @asis
+
+@item @code{-c}
+
+Causes both preprocessor lines and the lines deleted
+by preprocessing to be retained in the output source as comments marked
+with the special string @code{"--! "}. This option will result in line numbers
+being preserved in the output file.
+@end table
+
+@geindex -C (gnatprep)
+
+
+@table @asis
+
+@item @code{-C}
+
+Causes comments to be scanned. Normally comments are ignored by gnatprep.
+If this option is specified, then comments are scanned and any $symbol
+substitutions performed as in program text. This is particularly useful
+when structured comments are used (e.g., for programs written in a
+pre-2014 version of the SPARK Ada subset). Note that this switch is not
+available when doing integrated preprocessing (it would be useless in
+this context since comments are ignored by the compiler in any case).
+@end table
+
+@geindex -D (gnatprep)
+
+
+@table @asis
+
+@item @code{-D`symbol'[=`value']}
+
+Defines a new preprocessing symbol with the specified value. If no value is given
+on the command line, then symbol is considered to be @code{True}. This switch
+can be used in place of a definition file.
+@end table
+
+@geindex -r (gnatprep)
+
+
+@table @asis
+
+@item @code{-r}
+
+Causes a @code{Source_Reference} pragma to be generated that
+references the original input file, so that error messages will use
+the file name of this original file. The use of this switch implies
+that preprocessor lines are not to be removed from the file, so its
+use will force @code{-b} mode if @code{-c}
+has not been specified explicitly.
+
+Note that if the file to be preprocessed contains multiple units, then
+it will be necessary to @code{gnatchop} the output file from
+@code{gnatprep}. If a @code{Source_Reference} pragma is present
+in the preprocessed file, it will be respected by
+@code{gnatchop -r}
+so that the final chopped files will correctly refer to the original
+input source file for @code{gnatprep}.
+@end table
+
+@geindex -s (gnatprep)
+
+
+@table @asis
+
+@item @code{-s}
+
+Causes a sorted list of symbol names and values to be
+listed on the standard output file.
+@end table
+
+@geindex -T (gnatprep)
+
+
+@table @asis
+
+@item @code{-T}
+
+Use LF as line terminators when writing files. By default the line terminator
+of the host (LF under unix, CR/LF under Windows) is used.
+@end table
+
+@geindex -u (gnatprep)
+
+
+@table @asis
+
+@item @code{-u}
+
+Causes undefined symbols to be treated as having the value FALSE in the context
+of a preprocessor test. In the absence of this option, an undefined symbol in
+a @code{#if} or @code{#elsif} test will be treated as an error.
+@end table
+
+@geindex -v (gnatprep)
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose mode: generates more output about work done.
+@end table
+
+Note: if neither @code{-b} nor @code{-c} is present,
+then preprocessor lines and
+deleted lines are completely removed from the output, unless -r is
+specified, in which case -b is assumed.
+
+@node Form of Definitions File,Form of Input Text for gnatprep,Switches for gnatprep,Preprocessing with gnatprep
+@anchor{gnat_ugn/the_gnat_compilation_model form-of-definitions-file}@anchor{98}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{99}
+@subsubsection Form of Definitions File
+
+
+The definitions file contains lines of the form:
+
+@example
+symbol := value
+@end example
+
+where @code{symbol} is a preprocessing symbol, and @code{value} is one of the following:
+
+
+@itemize *
+
+@item
+Empty, corresponding to a null substitution,
+
+@item
+A string literal using normal Ada syntax, or
+
+@item
+Any sequence of characters from the set @{letters, digits, period, underline@}.
+@end itemize
+
+Comment lines may also appear in the definitions file, starting with
+the usual @code{--},
+and comments may be added to the definitions lines.
+
+@node Form of Input Text for gnatprep,,Form of Definitions File,Preprocessing with gnatprep
+@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{9a}@anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{9b}
+@subsubsection Form of Input Text for @code{gnatprep}
+
+
+The input text may contain preprocessor conditional inclusion lines,
+as well as general symbol substitution sequences.
+
+The preprocessor conditional inclusion commands have the form:
+
+@example
+#if <expression> [then]
+ lines
+#elsif <expression> [then]
+ lines
+#elsif <expression> [then]
+ lines
+...
+#else
+ lines
+#end if;
+@end example
+
+In this example, <expression> is defined by the following grammar:
+
+@example
+<expression> ::= <symbol>
+<expression> ::= <symbol> = "<value>"
+<expression> ::= <symbol> = <symbol>
+<expression> ::= <symbol> = <integer>
+<expression> ::= <symbol> > <integer>
+<expression> ::= <symbol> >= <integer>
+<expression> ::= <symbol> < <integer>
+<expression> ::= <symbol> <= <integer>
+<expression> ::= <symbol> 'Defined
+<expression> ::= not <expression>
+<expression> ::= <expression> and <expression>
+<expression> ::= <expression> or <expression>
+<expression> ::= <expression> and then <expression>
+<expression> ::= <expression> or else <expression>
+<expression> ::= ( <expression> )
+@end example
+
+Note the following restriction: it is not allowed to have “and” or “or”
+following “not” in the same expression without parentheses. For example, this
+is not allowed:
+
+@example
+not X or Y
+@end example
+
+This can be expressed instead as one of the following forms:
+
+@example
+(not X) or Y
+not (X or Y)
+@end example
+
+For the first test (<expression> ::= <symbol>) the symbol must have
+either the value true or false, that is to say the right-hand of the
+symbol definition must be one of the (case-insensitive) literals
+@code{True} or @code{False}. If the value is true, then the
+corresponding lines are included, and if the value is false, they are
+excluded.
+
+When comparing a symbol to an integer, the integer is any non negative
+literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or
+2#11#. The symbol value must also be a non negative integer. Integer values
+in the range 0 .. 2**31-1 are supported.
+
+The test (<expression> ::= <symbol>’Defined) is true only if
+the symbol has been defined in the definition file or by a @code{-D}
+switch on the command line. Otherwise, the test is false.
+
+The equality tests are case insensitive, as are all the preprocessor lines.
+
+If the symbol referenced is not defined in the symbol definitions file,
+then the effect depends on whether or not switch @code{-u}
+is specified. If so, then the symbol is treated as if it had the value
+false and the test fails. If this switch is not specified, then
+it is an error to reference an undefined symbol. It is also an error to
+reference a symbol that is defined with a value other than @code{True}
+or @code{False}.
+
+The use of the @code{not} operator inverts the sense of this logical test.
+The @code{not} operator cannot be combined with the @code{or} or @code{and}
+operators, without parentheses. For example, “if not X or Y then” is not
+allowed, but “if (not X) or Y then” and “if not (X or Y) then” are.
+
+The @code{then} keyword is optional as shown
+
+The @code{#} must be the first non-blank character on a line, but
+otherwise the format is free form. Spaces or tabs may appear between
+the @code{#} and the keyword. The keywords and the symbols are case
+insensitive as in normal Ada code. Comments may be used on a
+preprocessor line, but other than that, no other tokens may appear on a
+preprocessor line. Any number of @code{elsif} clauses can be present,
+including none at all. The @code{else} is optional, as in Ada.
+
+The @code{#} marking the start of a preprocessor line must be the first
+non-blank character on the line, i.e., it must be preceded only by
+spaces or horizontal tabs.
+
+Symbol substitution outside of preprocessor lines is obtained by using
+the sequence:
+
+@example
+$symbol
+@end example
+
+anywhere within a source line, except in a comment or within a
+string literal. The identifier
+following the @code{$} must match one of the symbols defined in the symbol
+definition file, and the result is to substitute the value of the
+symbol in place of @code{$symbol} in the output file.
+
+Note that although the substitution of strings within a string literal
+is not possible, it is possible to have a symbol whose defined value is
+a string literal. So instead of setting XYZ to @code{hello} and writing:
+
+@example
+Header : String := "$XYZ";
+@end example
+
+you should set XYZ to @code{"hello"} and write:
+
+@example
+Header : String := $XYZ;
+@end example
+
+and then the substitution will occur as desired.
+
+@node Integrated Preprocessing,,Preprocessing with gnatprep,Conditional Compilation
+@anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{90}
+@subsection Integrated Preprocessing
+
+
+As noted above, a file to be preprocessed consists of Ada source code
+in which preprocessing lines have been inserted. However,
+instead of using @code{gnatprep} to explicitly preprocess a file as a separate
+step before compilation, you can carry out the preprocessing implicitly
+as part of compilation. Such `integrated preprocessing', which is the common
+style with C, is performed when either or both of the following switches
+are passed to the compiler:
+
+@quotation
+
+
+@itemize *
+
+@item
+@code{-gnatep}, which specifies the `preprocessor data file'.
+This file dictates how the source files will be preprocessed (e.g., which
+symbol definition files apply to which sources).
+
+@item
+@code{-gnateD}, which defines values for preprocessing symbols.
+@end itemize
+@end quotation
+
+Integrated preprocessing applies only to Ada source files, it is
+not available for configuration pragma files.
+
+With integrated preprocessing, the output from the preprocessor is not,
+by default, written to any external file. Instead it is passed
+internally to the compiler. To preserve the result of
+preprocessing in a file, either run @code{gnatprep}
+in standalone mode or else supply the @code{-gnateG} switch
+(described below) to the compiler.
+
+When using project files:
+
+@quotation
+
+
+@itemize *
+
+@item
+the builder switch @code{-x} should be used if any Ada source is
+compiled with @code{gnatep=}, so that the compiler finds the
+`preprocessor data file'.
+
+@item
+the preprocessing data file and the symbol definition files should be
+located in the source directories of the project.
+@end itemize
+@end quotation
+
+Note that the @code{gnatmake} switch @code{-m} will almost
+always trigger recompilation for sources that are preprocessed,
+because @code{gnatmake} cannot compute the checksum of the source after
+preprocessing.
+
+The actual preprocessing function is described in detail in
+@ref{8f,,Preprocessing with gnatprep}. This section explains the switches
+that relate to integrated preprocessing.
+
+@geindex -gnatep (gcc)
+
+
+@table @asis
+
+@item @code{-gnatep=`preprocessor_data_file'}
+
+This switch specifies the file name (without directory
+information) of the preprocessor data file. Either place this file
+in one of the source directories, or, when using project
+files, reference the project file’s directory via the
+@code{project_name'Project_Dir} project attribute; e.g:
+
+@quotation
+
+@example
+project Prj is
+ package Compiler is
+ for Switches ("Ada") use
+ ("-gnatep=" & Prj'Project_Dir & "prep.def");
+ end Compiler;
+end Prj;
+@end example
+@end quotation
+
+A preprocessor data file is a text file that contains `preprocessor
+control lines'. A preprocessor control line directs the preprocessing of
+either a particular source file, or, analogous to @code{others} in Ada,
+all sources not specified elsewhere in the preprocessor data file.
+A preprocessor control line
+can optionally identify a `definition file' that assigns values to
+preprocessor symbols, as well as a list of switches that relate to
+preprocessing.
+Empty lines and comments (using Ada syntax) are also permitted, with no
+semantic effect.
+
+Here’s an example of a preprocessor data file:
+
+@quotation
+
+@example
+"toto.adb" "prep.def" -u
+-- Preprocess toto.adb, using definition file prep.def
+-- Undefined symbols are treated as False
+
+* -c -DVERSION=V101
+-- Preprocess all other sources without using a definition file
+-- Suppressed lined are commented
+-- Symbol VERSION has the value V101
+
+"tata.adb" "prep2.def" -s
+-- Preprocess tata.adb, using definition file prep2.def
+-- List all symbols with their values
+@end example
+@end quotation
+
+A preprocessor control line has the following syntax:
+
+@quotation
+
+@example
+<preprocessor_control_line> ::=
+ <preprocessor_input> [ <definition_file_name> ] @{ <switch> @}
+
+<preprocessor_input> ::= <source_file_name> | '*'
+
+<definition_file_name> ::= <string_literal>
+
+<source_file_name> := <string_literal>
+
+<switch> := (See below for list)
+@end example
+@end quotation
+
+Thus each preprocessor control line starts with either a literal string or
+the character ‘*’:
+
+
+@itemize *
+
+@item
+A literal string is the file name (without directory information) of the source
+file that will be input to the preprocessor.
+
+@item
+The character ‘*’ is a wild-card indicator; the additional parameters on the line
+indicate the preprocessing for all the sources
+that are not specified explicitly on other lines (the order of the lines is not
+significant).
+@end itemize
+
+It is an error to have two lines with the same file name or two
+lines starting with the character ‘*’.
+
+After the file name or ‘*’, an optional literal string specifies the name of
+the definition file to be used for preprocessing
+(@ref{98,,Form of Definitions File}). The definition files are found by the
+compiler in one of the source directories. In some cases, when compiling
+a source in a directory other than the current directory, if the definition
+file is in the current directory, it may be necessary to add the current
+directory as a source directory through the @code{-I} switch; otherwise
+the compiler would not find the definition file.
+
+Finally, switches similar to those of @code{gnatprep} may optionally appear:
+
+
+@table @asis
+
+@item @code{-b}
+
+Causes both preprocessor lines and the lines deleted by
+preprocessing to be replaced by blank lines, preserving the line number.
+This switch is always implied; however, if specified after @code{-c}
+it cancels the effect of @code{-c}.
+
+@item @code{-c}
+
+Causes both preprocessor lines and the lines deleted
+by preprocessing to be retained as comments marked
+with the special string ‘@cite{–!}’.
+
+@item @code{-D`symbol'=`new_value'}
+
+Define or redefine @code{symbol} to have @code{new_value} as its value.
+The permitted form for @code{symbol} is either an Ada identifier, or any Ada reserved word
+aside from @code{if},
+@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
+The permitted form for @code{new_value} is a literal string, an Ada identifier or any Ada reserved
+word. A symbol declared with this switch replaces a symbol with the
+same name defined in a definition file.
+
+@item @code{-s}
+
+Causes a sorted list of symbol names and values to be
+listed on the standard output file.
+
+@item @code{-u}
+
+Causes undefined symbols to be treated as having the value @code{FALSE}
+in the context
+of a preprocessor test. In the absence of this option, an undefined symbol in
+a @code{#if} or @code{#elsif} test will be treated as an error.
+@end table
+@end table
+
+@geindex -gnateD (gcc)
+
+
+@table @asis
+
+@item @code{-gnateD`symbol'[=`new_value']}
+
+Define or redefine @code{symbol} to have @code{new_value} as its value. If no value
+is supplied, then the value of @code{symbol} is @code{True}.
+The form of @code{symbol} is an identifier, following normal Ada (case-insensitive)
+rules for its syntax, and @code{new_value} is either an arbitrary string between double
+quotes or any sequence (including an empty sequence) of characters from the
+set (letters, digits, period, underline).
+Ada reserved words may be used as symbols, with the exceptions of @code{if},
+@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
+
+Examples:
+
+@quotation
+
+@example
+-gnateDToto=Tata
+-gnateDFoo
+-gnateDFoo=\"Foo-Bar\"
+@end example
+@end quotation
+
+A symbol declared with this switch on the command line replaces a
+symbol with the same name either in a definition file or specified with a
+switch @code{-D} in the preprocessor data file.
+
+This switch is similar to switch @code{-D} of @code{gnatprep}.
+
+@item @code{-gnateG}
+
+When integrated preprocessing is performed on source file @code{filename.extension},
+create or overwrite @code{filename.extension.prep} to contain
+the result of the preprocessing.
+For example if the source file is @code{foo.adb} then
+the output file will be @code{foo.adb.prep}.
+@end table
+
+@node Mixed Language Programming,GNAT and Other Compilation Models,Conditional Compilation,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{9d}@anchor{gnat_ugn/the_gnat_compilation_model mixed-language-programming}@anchor{2c}
+@section Mixed Language Programming
+
+
+@geindex Mixed Language Programming
+
+This section describes how to develop a mixed-language program,
+with a focus on combining Ada with C or C++.
+
+@menu
+* Interfacing to C::
+* Calling Conventions::
+* Building Mixed Ada and C++ Programs::
+* Generating Ada Bindings for C and C++ headers::
+* Generating C Headers for Ada Specifications::
+
+@end menu
+
+@node Interfacing to C,Calling Conventions,,Mixed Language Programming
+@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{9e}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{9f}
+@subsection Interfacing to C
+
+
+Interfacing Ada with a foreign language such as C involves using
+compiler directives to import and/or export entity definitions in each
+language – using @code{extern} statements in C, for instance, and the
+@code{Import}, @code{Export}, and @code{Convention} pragmas in Ada.
+A full treatment of these topics is provided in Appendix B, section 1
+of the Ada Reference Manual.
+
+There are two ways to build a program using GNAT that contains some Ada
+sources and some foreign language sources, depending on whether or not
+the main subprogram is written in Ada. Here is a source example with
+the main subprogram in Ada:
+
+@example
+/* file1.c */
+#include <stdio.h>
+
+void print_num (int num)
+@{
+ printf ("num is %d.\\n", num);
+ return;
+@}
+@end example
+
+@example
+/* file2.c */
+
+/* num_from_Ada is declared in my_main.adb */
+extern int num_from_Ada;
+
+int get_num (void)
+@{
+ return num_from_Ada;
+@}
+@end example
+
+@example
+-- my_main.adb
+procedure My_Main is
+
+ -- Declare then export an Integer entity called num_from_Ada
+ My_Num : Integer := 10;
+ pragma Export (C, My_Num, "num_from_Ada");
+
+ -- Declare an Ada function spec for Get_Num, then use
+ -- C function get_num for the implementation.
+ function Get_Num return Integer;
+ pragma Import (C, Get_Num, "get_num");
+
+ -- Declare an Ada procedure spec for Print_Num, then use
+ -- C function print_num for the implementation.
+ procedure Print_Num (Num : Integer);
+ pragma Import (C, Print_Num, "print_num");
+
+begin
+ Print_Num (Get_Num);
+end My_Main;
+@end example
+
+To build this example:
+
+
+@itemize *
+
+@item
+First compile the foreign language files to
+generate object files:
+
+@example
+$ gcc -c file1.c
+$ gcc -c file2.c
+@end example
+
+@item
+Then, compile the Ada units to produce a set of object files and ALI
+files:
+
+@example
+$ gnatmake -c my_main.adb
+@end example
+
+@item
+Run the Ada binder on the Ada main program:
+
+@example
+$ gnatbind my_main.ali
+@end example
+
+@item
+Link the Ada main program, the Ada objects and the other language
+objects:
+
+@example
+$ gnatlink my_main.ali file1.o file2.o
+@end example
+@end itemize
+
+The last three steps can be grouped in a single command:
+
+@example
+$ gnatmake my_main.adb -largs file1.o file2.o
+@end example
+
+@geindex Binder output file
+
+If the main program is in a language other than Ada, then you may have
+more than one entry point into the Ada subsystem. You must use a special
+binder option to generate callable routines that initialize and
+finalize the Ada units (@ref{a0,,Binding with Non-Ada Main Programs}).
+Calls to the initialization and finalization routines must be inserted
+in the main program, or some other appropriate point in the code. The
+call to initialize the Ada units must occur before the first Ada
+subprogram is called, and the call to finalize the Ada units must occur
+after the last Ada subprogram returns. The binder will place the
+initialization and finalization subprograms into the
+@code{b~xxx.adb} file where they can be accessed by your C
+sources. To illustrate, we have the following example:
+
+@example
+/* main.c */
+extern void adainit (void);
+extern void adafinal (void);
+extern int add (int, int);
+extern int sub (int, int);
+
+int main (int argc, char *argv[])
+@{
+ int a = 21, b = 7;
+
+ adainit();
+
+ /* Should print "21 + 7 = 28" */
+ printf ("%d + %d = %d\\n", a, b, add (a, b));
+
+ /* Should print "21 - 7 = 14" */
+ printf ("%d - %d = %d\\n", a, b, sub (a, b));
+
+ adafinal();
+@}
+@end example
+
+@example
+-- unit1.ads
+package Unit1 is
+ function Add (A, B : Integer) return Integer;
+ pragma Export (C, Add, "add");
+end Unit1;
+@end example
+
+@example
+-- unit1.adb
+package body Unit1 is
+ function Add (A, B : Integer) return Integer is
+ begin
+ return A + B;
+ end Add;
+end Unit1;
+@end example
+
+@example
+-- unit2.ads
+package Unit2 is
+ function Sub (A, B : Integer) return Integer;
+ pragma Export (C, Sub, "sub");
+end Unit2;
+@end example
+
+@example
+-- unit2.adb
+package body Unit2 is
+ function Sub (A, B : Integer) return Integer is
+ begin
+ return A - B;
+ end Sub;
+end Unit2;
+@end example
+
+The build procedure for this application is similar to the last
+example’s:
+
+
+@itemize *
+
+@item
+First, compile the foreign language files to generate object files:
+
+@example
+$ gcc -c main.c
+@end example
+
+@item
+Next, compile the Ada units to produce a set of object files and ALI
+files:
+
+@example
+$ gnatmake -c unit1.adb
+$ gnatmake -c unit2.adb
+@end example
+
+@item
+Run the Ada binder on every generated ALI file. Make sure to use the
+@code{-n} option to specify a foreign main program:
+
+@example
+$ gnatbind -n unit1.ali unit2.ali
+@end example
+
+@item
+Link the Ada main program, the Ada objects and the foreign language
+objects. You need only list the last ALI file here:
+
+@example
+$ gnatlink unit2.ali main.o -o exec_file
+@end example
+
+This procedure yields a binary executable called @code{exec_file}.
+@end itemize
+
+Depending on the circumstances (for example when your non-Ada main object
+does not provide symbol @code{main}), you may also need to instruct the
+GNAT linker not to include the standard startup objects by passing the
+@code{-nostartfiles} switch to @code{gnatlink}.
+
+@node Calling Conventions,Building Mixed Ada and C++ Programs,Interfacing to C,Mixed Language Programming
+@anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{a1}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{a2}
+@subsection Calling Conventions
+
+
+@geindex Foreign Languages
+
+@geindex Calling Conventions
+
+GNAT follows standard calling sequence conventions and will thus interface
+to any other language that also follows these conventions. The following
+Convention identifiers are recognized by GNAT:
+
+@geindex Interfacing to Ada
+
+@geindex Other Ada compilers
+
+@geindex Convention Ada
+
+
+@table @asis
+
+@item @code{Ada}
+
+This indicates that the standard Ada calling sequence will be
+used and all Ada data items may be passed without any limitations in the
+case where GNAT is used to generate both the caller and callee. It is also
+possible to mix GNAT generated code and code generated by another Ada
+compiler. In this case, the data types should be restricted to simple
+cases, including primitive types. Whether complex data types can be passed
+depends on the situation. Probably it is safe to pass simple arrays, such
+as arrays of integers or floats. Records may or may not work, depending
+on whether both compilers lay them out identically. Complex structures
+involving variant records, access parameters, tasks, or protected types,
+are unlikely to be able to be passed.
+
+Note that in the case of GNAT running
+on a platform that supports HP Ada 83, a higher degree of compatibility
+can be guaranteed, and in particular records are laid out in an identical
+manner in the two compilers. Note also that if output from two different
+compilers is mixed, the program is responsible for dealing with elaboration
+issues. Probably the safest approach is to write the main program in the
+version of Ada other than GNAT, so that it takes care of its own elaboration
+requirements, and then call the GNAT-generated adainit procedure to ensure
+elaboration of the GNAT components. Consult the documentation of the other
+Ada compiler for further details on elaboration.
+
+However, it is not possible to mix the tasking run time of GNAT and
+HP Ada 83, All the tasking operations must either be entirely within
+GNAT compiled sections of the program, or entirely within HP Ada 83
+compiled sections of the program.
+@end table
+
+@geindex Interfacing to Assembly
+
+@geindex Convention Assembler
+
+
+@table @asis
+
+@item @code{Assembler}
+
+Specifies assembler as the convention. In practice this has the
+same effect as convention Ada (but is not equivalent in the sense of being
+considered the same convention).
+@end table
+
+@geindex Convention Asm
+
+@geindex Asm
+
+
+@table @asis
+
+@item @code{Asm}
+
+Equivalent to Assembler.
+
+@geindex Interfacing to COBOL
+
+@geindex Convention COBOL
+@end table
+
+@geindex COBOL
+
+
+@table @asis
+
+@item @code{COBOL}
+
+Data will be passed according to the conventions described
+in section B.4 of the Ada Reference Manual.
+@end table
+
+@geindex C
+
+@geindex Interfacing to C
+
+@geindex Convention C
+
+
+@table @asis
+
+@item @code{C}
+
+Data will be passed according to the conventions described
+in section B.3 of the Ada Reference Manual.
+
+A note on interfacing to a C ‘varargs’ function:
+
+@quotation
+
+@geindex C varargs function
+
+@geindex Interfacing to C varargs function
+
+@geindex varargs function interfaces
+
+In C, @code{varargs} allows a function to take a variable number of
+arguments. There is no direct equivalent in this to Ada. One
+approach that can be used is to create a C wrapper for each
+different profile and then interface to this C wrapper. For
+example, to print an @code{int} value using @code{printf},
+create a C function @code{printfi} that takes two arguments, a
+pointer to a string and an int, and calls @code{printf}.
+Then in the Ada program, use pragma @code{Import} to
+interface to @code{printfi}.
+
+It may work on some platforms to directly interface to
+a @code{varargs} function by providing a specific Ada profile
+for a particular call. However, this does not work on
+all platforms, since there is no guarantee that the
+calling sequence for a two argument normal C function
+is the same as for calling a @code{varargs} C function with
+the same two arguments.
+@end quotation
+@end table
+
+@geindex Convention Default
+
+@geindex Default
+
+
+@table @asis
+
+@item @code{Default}
+
+Equivalent to C.
+@end table
+
+@geindex Convention External
+
+@geindex External
+
+
+@table @asis
+
+@item @code{External}
+
+Equivalent to C.
+@end table
+
+@geindex C++
+
+@geindex Interfacing to C++
+
+@geindex Convention C++
+
+
+@table @asis
+
+@item @code{C_Plus_Plus} (or @code{CPP})
+
+This stands for C++. For most purposes this is identical to C.
+See the separate description of the specialized GNAT pragmas relating to
+C++ interfacing for further details.
+@end table
+
+@geindex Fortran
+
+@geindex Interfacing to Fortran
+
+@geindex Convention Fortran
+
+
+@table @asis
+
+@item @code{Fortran}
+
+Data will be passed according to the conventions described
+in section B.5 of the Ada Reference Manual.
+
+@item @code{Intrinsic}
+
+This applies to an intrinsic operation, as defined in the Ada
+Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
+this means that the body of the subprogram is provided by the compiler itself,
+usually by means of an efficient code sequence, and that the user does not
+supply an explicit body for it. In an application program, the pragma may
+be applied to the following sets of names:
+
+
+@itemize *
+
+@item
+Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_Arithmetic.
+The corresponding subprogram declaration must have
+two formal parameters. The
+first one must be a signed integer type or a modular type with a binary
+modulus, and the second parameter must be of type Natural.
+The return type must be the same as the type of the first argument. The size
+of this type can only be 8, 16, 32, or 64.
+
+@item
+Binary arithmetic operators: ‘+’, ‘-’, ‘*’, ‘/’.
+The corresponding operator declaration must have parameters and result type
+that have the same root numeric type (for example, all three are long_float
+types). This simplifies the definition of operations that use type checking
+to perform dimensional checks:
+@end itemize
+
+@example
+ type Distance is new Long_Float;
+ type Time is new Long_Float;
+ type Velocity is new Long_Float;
+ function "/" (D : Distance; T : Time)
+ return Velocity;
+ pragma Import (Intrinsic, "/");
+
+This common idiom is often programmed with a generic definition and an
+explicit body. The pragma makes it simpler to introduce such declarations.
+It incurs no overhead in compilation time or code size, because it is
+implemented as a single machine instruction.
+@end example
+
+
+@itemize *
+
+@item
+General subprogram entities. This is used to bind an Ada subprogram
+declaration to
+a compiler builtin by name with back-ends where such interfaces are
+available. A typical example is the set of @code{__builtin} functions
+exposed by the GCC back-end, as in the following example:
+
+@example
+function builtin_sqrt (F : Float) return Float;
+pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf");
+@end example
+
+Most of the GCC builtins are accessible this way, and as for other
+import conventions (e.g. C), it is the user’s responsibility to ensure
+that the Ada subprogram profile matches the underlying builtin
+expectations.
+@end itemize
+@end table
+
+@geindex Stdcall
+
+@geindex Convention Stdcall
+
+
+@table @asis
+
+@item @code{Stdcall}
+
+This is relevant only to Windows implementations of GNAT,
+and specifies that the @code{Stdcall} calling sequence will be used,
+as defined by the NT API. Nevertheless, to ease building
+cross-platform bindings this convention will be handled as a @code{C} calling
+convention on non-Windows platforms.
+@end table
+
+@geindex DLL
+
+@geindex Convention DLL
+
+
+@table @asis
+
+@item @code{DLL}
+
+This is equivalent to @code{Stdcall}.
+@end table
+
+@geindex Win32
+
+@geindex Convention Win32
+
+
+@table @asis
+
+@item @code{Win32}
+
+This is equivalent to @code{Stdcall}.
+@end table
+
+@geindex Stubbed
+
+@geindex Convention Stubbed
+
+
+@table @asis
+
+@item @code{Stubbed}
+
+This is a special convention that indicates that the compiler
+should provide a stub body that raises @code{Program_Error}.
+@end table
+
+GNAT additionally provides a useful pragma @code{Convention_Identifier}
+that can be used to parameterize conventions and allow additional synonyms
+to be specified. For example if you have legacy code in which the convention
+identifier Fortran77 was used for Fortran, you can use the configuration
+pragma:
+
+@example
+pragma Convention_Identifier (Fortran77, Fortran);
+@end example
+
+And from now on the identifier Fortran77 may be used as a convention
+identifier (for example in an @code{Import} pragma) with the same
+meaning as Fortran.
+
+@node Building Mixed Ada and C++ Programs,Generating Ada Bindings for C and C++ headers,Calling Conventions,Mixed Language Programming
+@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{a3}@anchor{gnat_ugn/the_gnat_compilation_model id64}@anchor{a4}
+@subsection Building Mixed Ada and C++ Programs
+
+
+A programmer inexperienced with mixed-language development may find that
+building an application containing both Ada and C++ code can be a
+challenge. This section gives a few hints that should make this task easier.
+
+@menu
+* Interfacing to C++::
+* Linking a Mixed C++ & Ada Program::
+* A Simple Example::
+* Interfacing with C++ constructors::
+* Interfacing with C++ at the Class Level::
+
+@end menu
+
+@node Interfacing to C++,Linking a Mixed C++ & Ada Program,,Building Mixed Ada and C++ Programs
+@anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{a6}
+@subsubsection Interfacing to C++
+
+
+GNAT supports interfacing with the G++ compiler (or any C++ compiler
+generating code that is compatible with the G++ Application Binary
+Interface —see @indicateurl{http://itanium-cxx-abi.github.io/cxx-abi/abi.html}).
+
+Interfacing can be done at 3 levels: simple data, subprograms, and
+classes. In the first two cases, GNAT offers a specific @code{Convention C_Plus_Plus}
+(or @code{CPP}) that behaves exactly like @code{Convention C}.
+Usually, C++ mangles the names of subprograms. To generate proper mangled
+names automatically, see @ref{a7,,Generating Ada Bindings for C and C++ headers}).
+This problem can also be addressed manually in two ways:
+
+
+@itemize *
+
+@item
+by modifying the C++ code in order to force a C convention using
+the @code{extern "C"} syntax.
+
+@item
+by figuring out the mangled name (using e.g. @code{nm}) and using it as the
+Link_Name argument of the pragma import.
+@end itemize
+
+Interfacing at the class level can be achieved by using the GNAT specific
+pragmas such as @code{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information.
+
+@node Linking a Mixed C++ & Ada Program,A Simple Example,Interfacing to C++,Building Mixed Ada and C++ Programs
+@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-ada-program}@anchor{a8}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{a9}
+@subsubsection Linking a Mixed C++ & Ada Program
+
+
+Usually the linker of the C++ development system must be used to link
+mixed applications because most C++ systems will resolve elaboration
+issues (such as calling constructors on global class instances)
+transparently during the link phase. GNAT has been adapted to ease the
+use of a foreign linker for the last phase. Three cases can be
+considered:
+
+
+@itemize *
+
+@item
+Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
+The C++ linker can simply be called by using the C++ specific driver
+called @code{g++}.
+
+Note that if the C++ code uses inline functions, you will need to
+compile your C++ code with the @code{-fkeep-inline-functions} switch in
+order to provide an existing function implementation that the Ada code can
+link with.
+
+@example
+$ g++ -c -fkeep-inline-functions file1.C
+$ g++ -c -fkeep-inline-functions file2.C
+$ gnatmake ada_unit -largs file1.o file2.o --LINK=g++
+@end example
+
+@item
+Using GNAT and G++ from two different GCC installations: If both
+compilers are on the :envvar`PATH`, the previous method may be used. It is
+important to note that environment variables such as
+@geindex C_INCLUDE_PATH
+@geindex environment variable; C_INCLUDE_PATH
+@code{C_INCLUDE_PATH},
+@geindex GCC_EXEC_PREFIX
+@geindex environment variable; GCC_EXEC_PREFIX
+@code{GCC_EXEC_PREFIX},
+@geindex BINUTILS_ROOT
+@geindex environment variable; BINUTILS_ROOT
+@code{BINUTILS_ROOT}, and
+@geindex GCC_ROOT
+@geindex environment variable; GCC_ROOT
+@code{GCC_ROOT} will affect both compilers
+at the same time and may make one of the two compilers operate
+improperly if set during invocation of the wrong compiler. It is also
+very important that the linker uses the proper @code{libgcc.a} GCC
+library – that is, the one from the C++ compiler installation. The
+implicit link command as suggested in the @code{gnatmake} command
+from the former example can be replaced by an explicit link command with
+the full-verbosity option in order to verify which library is used:
+
+@example
+$ gnatbind ada_unit
+$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
+@end example
+
+If there is a problem due to interfering environment variables, it can
+be worked around by using an intermediate script. The following example
+shows the proper script to use when GNAT has not been installed at its
+default location and g++ has been installed at its default location:
+
+@example
+$ cat ./my_script
+#!/bin/sh
+unset BINUTILS_ROOT
+unset GCC_ROOT
+c++ $*
+$ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script
+@end example
+
+@item
+Using a non-GNU C++ compiler: The commands previously described can be
+used to insure that the C++ linker is used. Nonetheless, you need to add
+a few more parameters to the link command line, depending on the exception
+mechanism used.
+
+If the @code{setjmp} / @code{longjmp} exception mechanism is used, only the paths
+to the @code{libgcc} libraries are required:
+
+@example
+$ cat ./my_script
+#!/bin/sh
+CC $* gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a
+$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
+@end example
+
+where CC is the name of the non-GNU C++ compiler.
+
+If the “zero cost” exception mechanism is used, and the platform
+supports automatic registration of exception tables (e.g., Solaris),
+paths to more objects are required:
+
+@example
+$ cat ./my_script
+#!/bin/sh
+CC gcc -print-file-name=crtbegin.o $* \\
+gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a \\
+gcc -print-file-name=crtend.o
+$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
+@end example
+
+If the “zero cost exception” mechanism is used, and the platform
+doesn’t support automatic registration of exception tables (e.g., HP-UX
+or AIX), the simple approach described above will not work and
+a pre-linking phase using GNAT will be necessary.
+@end itemize
+
+Another alternative is to use the @code{gprbuild} multi-language builder
+which has a large knowledge base and knows how to link Ada and C++ code
+together automatically in most cases.
+
+@node A Simple Example,Interfacing with C++ constructors,Linking a Mixed C++ & Ada Program,Building Mixed Ada and C++ Programs
+@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{aa}@anchor{gnat_ugn/the_gnat_compilation_model id67}@anchor{ab}
+@subsubsection A Simple Example
+
+
+The following example, provided as part of the GNAT examples, shows how
+to achieve procedural interfacing between Ada and C++ in both
+directions. The C++ class A has two methods. The first method is exported
+to Ada by the means of an extern C wrapper function. The second method
+calls an Ada subprogram. On the Ada side, the C++ calls are modelled by
+a limited record with a layout comparable to the C++ class. The Ada
+subprogram, in turn, calls the C++ method. So, starting from the C++
+main program, the process passes back and forth between the two
+languages.
+
+Here are the compilation commands:
+
+@example
+$ gnatmake -c simple_cpp_interface
+$ g++ -c cpp_main.C
+$ g++ -c ex7.C
+$ gnatbind -n simple_cpp_interface
+$ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o
+@end example
+
+Here are the corresponding sources:
+
+@example
+//cpp_main.C
+
+#include "ex7.h"
+
+extern "C" @{
+ void adainit (void);
+ void adafinal (void);
+ void method1 (A *t);
+@}
+
+void method1 (A *t)
+@{
+ t->method1 ();
+@}
+
+int main ()
+@{
+ A obj;
+ adainit ();
+ obj.method2 (3030);
+ adafinal ();
+@}
+@end example
+
+@example
+//ex7.h
+
+class Origin @{
+ public:
+ int o_value;
+@};
+class A : public Origin @{
+ public:
+ void method1 (void);
+ void method2 (int v);
+ A();
+ int a_value;
+@};
+@end example
+
+@example
+//ex7.C
+
+#include "ex7.h"
+#include <stdio.h>
+
+extern "C" @{ void ada_method2 (A *t, int v);@}
+
+void A::method1 (void)
+@{
+ a_value = 2020;
+ printf ("in A::method1, a_value = %d \\n",a_value);
+@}
+
+void A::method2 (int v)
+@{
+ ada_method2 (this, v);
+ printf ("in A::method2, a_value = %d \\n",a_value);
+@}
+
+A::A(void)
+@{
+ a_value = 1010;
+ printf ("in A::A, a_value = %d \\n",a_value);
+@}
+@end example
+
+@example
+-- simple_cpp_interface.ads
+with System;
+package Simple_Cpp_Interface is
+ type A is limited
+ record
+ Vptr : System.Address;
+ O_Value : Integer;
+ A_Value : Integer;
+ end record;
+ pragma Convention (C, A);
+
+ procedure Method1 (This : in out A);
+ pragma Import (C, Method1);
+
+ procedure Ada_Method2 (This : in out A; V : Integer);
+ pragma Export (C, Ada_Method2);
+
+end Simple_Cpp_Interface;
+@end example
+
+@example
+-- simple_cpp_interface.adb
+package body Simple_Cpp_Interface is
+
+ procedure Ada_Method2 (This : in out A; V : Integer) is
+ begin
+ Method1 (This);
+ This.A_Value := V;
+ end Ada_Method2;
+
+end Simple_Cpp_Interface;
+@end example
+
+@node Interfacing with C++ constructors,Interfacing with C++ at the Class Level,A Simple Example,Building Mixed Ada and C++ Programs
+@anchor{gnat_ugn/the_gnat_compilation_model id68}@anchor{ac}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{ad}
+@subsubsection Interfacing with C++ constructors
+
+
+In order to interface with C++ constructors GNAT provides the
+@code{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual}
+for additional information).
+In this section we present some common uses of C++ constructors
+in mixed-languages programs in GNAT.
+
+Let us assume that we need to interface with the following
+C++ class:
+
+@example
+class Root @{
+public:
+ int a_value;
+ int b_value;
+ virtual int Get_Value ();
+ Root(); // Default constructor
+ Root(int v); // 1st non-default constructor
+ Root(int v, int w); // 2nd non-default constructor
+@};
+@end example
+
+For this purpose we can write the following package spec (further
+information on how to build this spec is available in
+@ref{ae,,Interfacing with C++ at the Class Level} and
+@ref{a7,,Generating Ada Bindings for C and C++ headers}).
+
+@example
+with Interfaces.C; use Interfaces.C;
+package Pkg_Root is
+ type Root is tagged limited record
+ A_Value : int;
+ B_Value : int;
+ end record;
+ pragma Import (CPP, Root);
+
+ function Get_Value (Obj : Root) return int;
+ pragma Import (CPP, Get_Value);
+
+ function Constructor return Root;
+ pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev");
+
+ function Constructor (v : Integer) return Root;
+ pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei");
+
+ function Constructor (v, w : Integer) return Root;
+ pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii");
+end Pkg_Root;
+@end example
+
+On the Ada side the constructor is represented by a function (whose
+name is arbitrary) that returns the classwide type corresponding to
+the imported C++ class. Although the constructor is described as a
+function, 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.
+
+Constructors can only appear in the following contexts:
+
+
+@itemize *
+
+@item
+On the right side of an initialization of an object of type @code{T}.
+
+@item
+On the right side of an initialization of a record component of type @code{T}.
+
+@item
+In an Ada 2005 limited aggregate.
+
+@item
+In an Ada 2005 nested limited aggregate.
+
+@item
+In an Ada 2005 limited aggregate that initializes an object built in
+place by an extended return statement.
+@end itemize
+
+In a declaration of an object whose type is a class imported from C++,
+either the default C++ constructor is implicitly called by GNAT, or
+else the required C++ constructor must be explicitly called in the
+expression that initializes the object. For example:
+
+@example
+Obj1 : Root;
+Obj2 : Root := Constructor;
+Obj3 : Root := Constructor (v => 10);
+Obj4 : Root := Constructor (30, 40);
+@end example
+
+The first two declarations are equivalent: in both cases the default C++
+constructor is invoked (in the former case the call to the constructor is
+implicit, and in the latter case the call is explicit in the object
+declaration). @code{Obj3} is initialized by the C++ non-default constructor
+that takes an integer argument, and @code{Obj4} is initialized by the
+non-default C++ constructor that takes two integers.
+
+Let us derive the imported C++ class in the Ada side. For example:
+
+@example
+type DT is new Root with record
+ C_Value : Natural := 2009;
+end record;
+@end example
+
+In this case the components DT inherited from the C++ side must be
+initialized by a C++ constructor, and the additional Ada components
+of type DT are initialized by GNAT. The initialization of such an
+object is done either by default, or by means of a function returning
+an aggregate of type DT, or by means of an extension aggregate.
+
+@example
+Obj5 : DT;
+Obj6 : DT := Function_Returning_DT (50);
+Obj7 : DT := (Constructor (30,40) with C_Value => 50);
+@end example
+
+The declaration of @code{Obj5} invokes the default constructors: the
+C++ default constructor of the parent type takes care of the initialization
+of the components inherited from Root, and GNAT takes care of the default
+initialization of the additional Ada components of type DT (that is,
+@code{C_Value} is initialized to value 2009). The order of invocation of
+the constructors is consistent with the order of elaboration required by
+Ada and C++. That is, the constructor of the parent type is always called
+before the constructor of the derived type.
+
+Let us now consider a record that has components whose type is imported
+from C++. For example:
+
+@example
+type Rec1 is limited record
+ Data1 : Root := Constructor (10);
+ Value : Natural := 1000;
+end record;
+
+type Rec2 (D : Integer := 20) is limited record
+ Rec : Rec1;
+ Data2 : Root := Constructor (D, 30);
+end record;
+@end example
+
+The initialization of an object of type @code{Rec2} will call the
+non-default C++ constructors specified for the imported components.
+For example:
+
+@example
+Obj8 : Rec2 (40);
+@end example
+
+Using Ada 2005 we can use limited aggregates to initialize an object
+invoking C++ constructors that differ from those specified in the type
+declarations. For example:
+
+@example
+Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16),
+ others => <>),
+ others => <>);
+@end example
+
+The above declaration uses an Ada 2005 limited aggregate to
+initialize @code{Obj9}, and the C++ constructor that has two integer
+arguments is invoked to initialize the @code{Data1} component instead
+of the constructor specified in the declaration of type @code{Rec1}. In
+Ada 2005 the box in the aggregate indicates that unspecified components
+are initialized using the expression (if any) available in the component
+declaration. That is, in this case discriminant @code{D} is initialized
+to value @code{20}, @code{Value} is initialized to value 1000, and the
+non-default C++ constructor that handles two integers takes care of
+initializing component @code{Data2} with values @code{20,30}.
+
+In Ada 2005 we can use the extended return statement to build the Ada
+equivalent to C++ non-default constructors. For example:
+
+@example
+function Constructor (V : Integer) return Rec2 is
+begin
+ return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20),
+ others => <>),
+ others => <>) do
+ -- Further actions required for construction of
+ -- objects of type Rec2
+ ...
+ end record;
+end Constructor;
+@end example
+
+In this example the extended return statement construct is used to
+build in place the returned object whose components are initialized
+by means of a limited aggregate. Any further action associated with
+the constructor can be placed inside the construct.
+
+@node Interfacing with C++ at the Class Level,,Interfacing with C++ constructors,Building Mixed Ada and C++ Programs
+@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{af}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-at-the-class-level}@anchor{ae}
+@subsubsection Interfacing with C++ at the Class Level
+
+
+In this section we demonstrate the GNAT features for interfacing with
+C++ by means of an example making use of Ada 2005 abstract interface
+types. This example consists of a classification of animals; classes
+have been used to model our main classification of animals, and
+interfaces provide support for the management of secondary
+classifications. We first demonstrate a case in which the types and
+constructors are defined on the C++ side and imported from the Ada
+side, and latter the reverse case.
+
+The root of our derivation will be the @code{Animal} class, with a
+single private attribute (the @code{Age} of the animal), a constructor,
+and two public primitives to set and get the value of this attribute.
+
+@example
+class Animal @{
+ public:
+ virtual void Set_Age (int New_Age);
+ virtual int Age ();
+ Animal() @{Age_Count = 0;@};
+ private:
+ int Age_Count;
+@};
+@end example
+
+Abstract interface types are defined in C++ by means of classes with pure
+virtual functions and no data members. In our example we will use two
+interfaces that provide support for the common management of @code{Carnivore}
+and @code{Domestic} animals:
+
+@example
+class Carnivore @{
+public:
+ virtual int Number_Of_Teeth () = 0;
+@};
+
+class Domestic @{
+public:
+ virtual void Set_Owner (char* Name) = 0;
+@};
+@end example
+
+Using these declarations, we can now say that a @code{Dog} is an animal that is
+both Carnivore and Domestic, that is:
+
+@example
+class Dog : Animal, Carnivore, Domestic @{
+ public:
+ virtual int Number_Of_Teeth ();
+ virtual void Set_Owner (char* Name);
+
+ Dog(); // Constructor
+ private:
+ int Tooth_Count;
+ char *Owner;
+@};
+@end example
+
+In the following examples we will assume that the previous declarations are
+located in a file named @code{animals.h}. The following package demonstrates
+how to import these C++ declarations from the Ada side:
+
+@example
+with Interfaces.C.Strings; use Interfaces.C.Strings;
+package Animals is
+ type Carnivore is limited interface;
+ pragma Convention (C_Plus_Plus, Carnivore);
+ function Number_Of_Teeth (X : Carnivore)
+ return Natural is abstract;
+
+ type Domestic is limited interface;
+ pragma Convention (C_Plus_Plus, Domestic);
+ procedure Set_Owner
+ (X : in out Domestic;
+ Name : Chars_Ptr) is abstract;
+
+ type Animal is tagged limited record
+ Age : Natural;
+ end record;
+ pragma Import (C_Plus_Plus, Animal);
+
+ procedure Set_Age (X : in out Animal; Age : Integer);
+ pragma Import (C_Plus_Plus, Set_Age);
+
+ function Age (X : Animal) return Integer;
+ pragma Import (C_Plus_Plus, Age);
+
+ function New_Animal return Animal;
+ pragma CPP_Constructor (New_Animal);
+ pragma Import (CPP, New_Animal, "_ZN6AnimalC1Ev");
+
+ type Dog is new Animal and Carnivore and Domestic with record
+ Tooth_Count : Natural;
+ Owner : Chars_Ptr;
+ end record;
+ pragma Import (C_Plus_Plus, Dog);
+
+ function Number_Of_Teeth (A : Dog) return Natural;
+ pragma Import (C_Plus_Plus, Number_Of_Teeth);
+
+ procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
+ pragma Import (C_Plus_Plus, Set_Owner);
+
+ function New_Dog return Dog;
+ pragma CPP_Constructor (New_Dog);
+ pragma Import (CPP, New_Dog, "_ZN3DogC2Ev");
+end Animals;
+@end example
+
+Thanks to the compatibility between GNAT run-time structures and the C++ ABI,
+interfacing with these C++ classes is easy. The only requirement is that all
+the primitives and components must be declared exactly in the same order in
+the two languages.
+
+Regarding the abstract interfaces, we must indicate to the GNAT compiler by
+means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass
+the arguments to the called primitives will be the same as for C++. For the
+imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus}
+to indicate that they have been defined on the C++ side; this is required
+because the dispatch table associated with these tagged types will be built
+in the C++ side and therefore will not contain the predefined Ada primitives
+which Ada would otherwise expect.
+
+As the reader can see there is no need to indicate the C++ mangled names
+associated with each subprogram because it is assumed that all the calls to
+these primitives will be dispatching calls. The only exception is the
+constructor, which must be registered with the compiler by means of
+@code{pragma CPP_Constructor} and needs to provide its associated C++
+mangled name because the Ada compiler generates direct calls to it.
+
+With the above packages we can now declare objects of type Dog on the Ada side
+and dispatch calls to the corresponding subprograms on the C++ side. We can
+also extend the tagged type Dog with further fields and primitives, and
+override some of its C++ primitives on the Ada side. For example, here we have
+a type derivation defined on the Ada side that inherits all the dispatching
+primitives of the ancestor from the C++ side.
+
+@example
+with Animals; use Animals;
+package Vaccinated_Animals is
+ type Vaccinated_Dog is new Dog with null record;
+ function Vaccination_Expired (A : Vaccinated_Dog) return Boolean;
+end Vaccinated_Animals;
+@end example
+
+It is important to note that, because of the ABI compatibility, the programmer
+does not need to add any further information to indicate either the object
+layout or the dispatch table entry associated with each dispatching operation.
+
+Now let us define all the types and constructors on the Ada side and export
+them to C++, using the same hierarchy of our previous example:
+
+@example
+with Interfaces.C.Strings;
+use Interfaces.C.Strings;
+package Animals is
+ type Carnivore is limited interface;
+ pragma Convention (C_Plus_Plus, Carnivore);
+ function Number_Of_Teeth (X : Carnivore)
+ return Natural is abstract;
+
+ type Domestic is limited interface;
+ pragma Convention (C_Plus_Plus, Domestic);
+ procedure Set_Owner
+ (X : in out Domestic;
+ Name : Chars_Ptr) is abstract;
+
+ type Animal is tagged record
+ Age : Natural;
+ end record;
+ pragma Convention (C_Plus_Plus, Animal);
+
+ procedure Set_Age (X : in out Animal; Age : Integer);
+ pragma Export (C_Plus_Plus, Set_Age);
+
+ function Age (X : Animal) return Integer;
+ pragma Export (C_Plus_Plus, Age);
+
+ function New_Animal return Animal'Class;
+ pragma Export (C_Plus_Plus, New_Animal);
+
+ type Dog is new Animal and Carnivore and Domestic with record
+ Tooth_Count : Natural;
+ Owner : String (1 .. 30);
+ end record;
+ pragma Convention (C_Plus_Plus, Dog);
+
+ function Number_Of_Teeth (A : Dog) return Natural;
+ pragma Export (C_Plus_Plus, Number_Of_Teeth);
+
+ procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
+ pragma Export (C_Plus_Plus, Set_Owner);
+
+ function New_Dog return Dog'Class;
+ pragma Export (C_Plus_Plus, New_Dog);
+end Animals;
+@end example
+
+Compared with our previous example the only differences are the use of
+@code{pragma Convention} (instead of @code{pragma Import}), and the use of
+@code{pragma Export} to indicate to the GNAT compiler that the primitives will
+be available to C++. Thanks to the ABI compatibility, on the C++ side there is
+nothing else to be done; as explained above, the only requirement is that all
+the primitives and components are declared in exactly the same order.
+
+For completeness, let us see a brief C++ main program that uses the
+declarations available in @code{animals.h} (presented in our first example) to
+import and use the declarations from the Ada side, properly initializing and
+finalizing the Ada run-time system along the way:
+
+@example
+#include "animals.h"
+#include <iostream>
+using namespace std;
+
+void Check_Carnivore (Carnivore *obj) @{...@}
+void Check_Domestic (Domestic *obj) @{...@}
+void Check_Animal (Animal *obj) @{...@}
+void Check_Dog (Dog *obj) @{...@}
+
+extern "C" @{
+ void adainit (void);
+ void adafinal (void);
+ Dog* new_dog ();
+@}
+
+void test ()
+@{
+ Dog *obj = new_dog(); // Ada constructor
+ Check_Carnivore (obj); // Check secondary DT
+ Check_Domestic (obj); // Check secondary DT
+ Check_Animal (obj); // Check primary DT
+ Check_Dog (obj); // Check primary DT
+@}
+
+int main ()
+@{
+ adainit (); test(); adafinal ();
+ return 0;
+@}
+@end example
+
+@node Generating Ada Bindings for C and C++ headers,Generating C Headers for Ada Specifications,Building Mixed Ada and C++ Programs,Mixed Language Programming
+@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{a7}@anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{b0}
+@subsection Generating Ada Bindings for C and C++ headers
+
+
+@geindex Binding generation (for C and C++ headers)
+
+@geindex C headers (binding generation)
+
+@geindex C++ headers (binding generation)
+
+GNAT includes a binding generator for C and C++ headers which is
+intended to do 95% of the tedious work of generating Ada specs from C
+or C++ header files.
+
+Note that this capability is not intended to generate 100% correct Ada specs,
+and will is some cases require manual adjustments, although it can often
+be used out of the box in practice.
+
+Some of the known limitations include:
+
+
+@itemize *
+
+@item
+only very simple character constant macros are translated into Ada
+constants. Function macros (macros with arguments) are partially translated
+as comments, to be completed manually if needed.
+
+@item
+some extensions (e.g. vector types) are not supported
+
+@item
+pointers to pointers are mapped to System.Address
+
+@item
+identifiers with identical name (except casing) may generate compilation
+errors (e.g. @code{shm_get} vs @code{SHM_GET}).
+@end itemize
+
+The code is generated using Ada 2012 syntax, which makes it easier to interface
+with other languages. In most cases you can still use the generated binding
+even if your code is compiled using earlier versions of Ada (e.g. @code{-gnat95}).
+
+@menu
+* Running the Binding Generator::
+* Generating Bindings for C++ Headers::
+* Switches::
+
+@end menu
+
+@node Running the Binding Generator,Generating Bindings for C++ Headers,,Generating Ada Bindings for C and C++ headers
+@anchor{gnat_ugn/the_gnat_compilation_model id71}@anchor{b1}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{b2}
+@subsubsection Running the Binding Generator
+
+
+The binding generator is part of the @code{gcc} compiler and can be
+invoked via the @code{-fdump-ada-spec} switch, which will generate Ada
+spec files for the header files specified on the command line, and all
+header files needed by these files transitively. For example:
+
+@example
+$ gcc -c -fdump-ada-spec -C /usr/include/time.h
+$ gcc -c *.ads
+@end example
+
+will generate, under GNU/Linux, the following files: @code{time_h.ads},
+@code{bits_time_h.ads}, @code{stddef_h.ads}, @code{bits_types_h.ads} which
+correspond to the files @code{/usr/include/time.h},
+@code{/usr/include/bits/time.h}, etc…, and then compile these Ada specs.
+That is to say, the name of the Ada specs is in keeping with the relative path
+under @code{/usr/include/} of the header files. This behavior is specific to
+paths ending with @code{/include/}; in all the other cases, the name of the
+Ada specs is derived from the simple name of the header files instead.
+
+The @code{-C} switch tells @code{gcc} to extract comments from headers,
+and will attempt to generate corresponding Ada comments.
+
+If you want to generate a single Ada file and not the transitive closure, you
+can use instead the @code{-fdump-ada-spec-slim} switch.
+
+You can optionally specify a parent unit, of which all generated units will
+be children, using @code{-fada-spec-parent=`unit'}.
+
+The simple @code{gcc}-based command works only for C headers. For C++ headers
+you need to use either the @code{g++} command or the combination @code{gcc -x c++}.
+
+In some cases, the generated bindings will be more complete or more meaningful
+when defining some macros, which you can do via the @code{-D} switch. This
+is for example the case with @code{Xlib.h} under GNU/Linux:
+
+@example
+$ gcc -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
+@end example
+
+The above will generate more complete bindings than a straight call without
+the @code{-DXLIB_ILLEGAL_ACCESS} switch.
+
+In other cases, it is not possible to parse a header file in a stand-alone
+manner, because other include files need to be included first. In this
+case, the solution is to create a small header file including the needed
+@code{#include} and possible @code{#define} directives. For example, to
+generate Ada bindings for @code{readline/readline.h}, you need to first
+include @code{stdio.h}, so you can create a file with the following two
+lines in e.g. @code{readline1.h}:
+
+@example
+#include <stdio.h>
+#include <readline/readline.h>
+@end example
+
+and then generate Ada bindings from this file:
+
+@example
+$ gcc -c -fdump-ada-spec readline1.h
+@end example
+
+@node Generating Bindings for C++ Headers,Switches,Running the Binding Generator,Generating Ada Bindings for C and C++ headers
+@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{b3}@anchor{gnat_ugn/the_gnat_compilation_model id72}@anchor{b4}
+@subsubsection Generating Bindings for C++ Headers
+
+
+Generating bindings for C++ headers is done using the same options, always
+with the `g++' compiler. Note that generating Ada spec from C++ headers is a
+much more complex job and support for C++ headers is much more limited that
+support for C headers. As a result, you will need to modify the resulting
+bindings by hand more extensively when using C++ headers.
+
+In this mode, C++ classes will be mapped to Ada tagged types, constructors
+will be mapped using the @code{CPP_Constructor} pragma, and when possible,
+multiple inheritance of abstract classes will be mapped to Ada interfaces
+(see the `Interfacing to C++' section in the @cite{GNAT Reference Manual}
+for additional information on interfacing to C++).
+
+For example, given the following C++ header file:
+
+@example
+class Carnivore @{
+public:
+ virtual int Number_Of_Teeth () = 0;
+@};
+
+class Domestic @{
+public:
+ virtual void Set_Owner (char* Name) = 0;
+@};
+
+class Animal @{
+public:
+ int Age_Count;
+ virtual void Set_Age (int New_Age);
+@};
+
+class Dog : Animal, Carnivore, Domestic @{
+ public:
+ int Tooth_Count;
+ char *Owner;
+
+ virtual int Number_Of_Teeth ();
+ virtual void Set_Owner (char* Name);
+
+ Dog();
+@};
+@end example
+
+The corresponding Ada code is generated:
+
+@example
+package Class_Carnivore is
+ type Carnivore is limited interface;
+ pragma Import (CPP, Carnivore);
+
+ function Number_Of_Teeth (this : access Carnivore) return int is abstract;
+end;
+use Class_Carnivore;
+
+package Class_Domestic is
+ type Domestic is limited interface;
+ pragma Import (CPP, Domestic);
+
+ procedure Set_Owner
+ (this : access Domestic;
+ Name : Interfaces.C.Strings.chars_ptr) is abstract;
+end;
+use Class_Domestic;
+
+package Class_Animal is
+ type Animal is tagged limited record
+ Age_Count : aliased int;
+ end record;
+ pragma Import (CPP, Animal);
+
+ procedure Set_Age (this : access Animal; New_Age : int);
+ pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
+end;
+use Class_Animal;
+
+package Class_Dog is
+ type Dog is new Animal and Carnivore and Domestic with record
+ Tooth_Count : aliased int;
+ Owner : Interfaces.C.Strings.chars_ptr;
+ end record;
+ pragma Import (CPP, Dog);
+
+ function Number_Of_Teeth (this : access Dog) return int;
+ pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");
+
+ procedure Set_Owner
+ (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
+ pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
+
+ function New_Dog return Dog;
+ pragma CPP_Constructor (New_Dog);
+ pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
+end;
+use Class_Dog;
+@end example
+
+@node Switches,,Generating Bindings for C++ Headers,Generating Ada Bindings for C and C++ headers
+@anchor{gnat_ugn/the_gnat_compilation_model switches}@anchor{b5}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{b6}
+@subsubsection Switches
+
+
+@geindex -fdump-ada-spec (gcc)
+
+
+@table @asis
+
+@item @code{-fdump-ada-spec}
+
+Generate Ada spec files for the given header files transitively (including
+all header files that these headers depend upon).
+@end table
+
+@geindex -fdump-ada-spec-slim (gcc)
+
+
+@table @asis
+
+@item @code{-fdump-ada-spec-slim}
+
+Generate Ada spec files for the header files specified on the command line
+only.
+@end table
+
+@geindex -fada-spec-parent (gcc)
+
+
+@table @asis
+
+@item @code{-fada-spec-parent=`unit'}
+
+Specifies that all files generated by @code{-fdump-ada-spec} are
+to be child units of the specified parent unit.
+@end table
+
+@geindex -C (gcc)
+
+
+@table @asis
+
+@item @code{-C}
+
+Extract comments from headers and generate Ada comments in the Ada spec files.
+@end table
+
+@node Generating C Headers for Ada Specifications,,Generating Ada Bindings for C and C++ headers,Mixed Language Programming
+@anchor{gnat_ugn/the_gnat_compilation_model generating-c-headers-for-ada-specifications}@anchor{b7}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{b8}
+@subsection Generating C Headers for Ada Specifications
+
+
+@geindex Binding generation (for Ada specs)
+
+@geindex C headers (binding generation)
+
+GNAT includes a C header generator for Ada specifications which supports
+Ada types that have a direct mapping to C types. This includes in particular
+support for:
+
+
+@itemize *
+
+@item
+Scalar types
+
+@item
+Constrained arrays
+
+@item
+Records (untagged)
+
+@item
+Composition of the above types
+
+@item
+Constant declarations
+
+@item
+Object declarations
+
+@item
+Subprogram declarations
+@end itemize
+
+@menu
+* Running the C Header Generator::
+
+@end menu
+
+@node Running the C Header Generator,,,Generating C Headers for Ada Specifications
+@anchor{gnat_ugn/the_gnat_compilation_model running-the-c-header-generator}@anchor{b9}
+@subsubsection Running the C Header Generator
+
+
+The C header generator is part of the GNAT compiler and can be invoked via
+the @code{-gnatceg} combination of switches, which will generate a @code{.h}
+file corresponding to the given input file (Ada spec or body). Note that
+only spec files are processed in any case, so giving a spec or a body file
+as input is equivalent. For example:
+
+@example
+$ gcc -c -gnatceg pack1.ads
+@end example
+
+will generate a self-contained file called @code{pack1.h} including
+common definitions from the Ada Standard package, followed by the
+definitions included in @code{pack1.ads}, as well as all the other units
+withed by this file.
+
+For instance, given the following Ada files:
+
+@example
+package Pack2 is
+ type Int is range 1 .. 10;
+end Pack2;
+@end example
+
+@example
+with Pack2;
+
+package Pack1 is
+ type Rec is record
+ Field1, Field2 : Pack2.Int;
+ end record;
+
+ Global : Rec := (1, 2);
+
+ procedure Proc1 (R : Rec);
+ procedure Proc2 (R : in out Rec);
+end Pack1;
+@end example
+
+The above @code{gcc} command will generate the following @code{pack1.h} file:
+
+@example
+/* Standard definitions skipped */
+#ifndef PACK2_ADS
+#define PACK2_ADS
+typedef short_short_integer pack2__TintB;
+typedef pack2__TintB pack2__int;
+#endif /* PACK2_ADS */
+
+#ifndef PACK1_ADS
+#define PACK1_ADS
+typedef struct _pack1__rec @{
+ pack2__int field1;
+ pack2__int field2;
+@} pack1__rec;
+extern pack1__rec pack1__global;
+extern void pack1__proc1(const pack1__rec r);
+extern void pack1__proc2(pack1__rec *r);
+#endif /* PACK1_ADS */
+@end example
+
+You can then @code{include} @code{pack1.h} from a C source file and use the types,
+call subprograms, reference objects, and constants.
+
+@node GNAT and Other Compilation Models,Using GNAT Files with External Tools,Mixed Language Programming,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{2d}@anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{ba}
+@section GNAT and Other Compilation Models
+
+
+This section compares the GNAT model with the approaches taken in
+other environments, first the C/C++ model and then the mechanism that
+has been used in other Ada systems, in particular those traditionally
+used for Ada 83.
+
+@menu
+* Comparison between GNAT and C/C++ Compilation Models::
+* Comparison between GNAT and Conventional Ada Library Models::
+
+@end menu
+
+@node Comparison between GNAT and C/C++ Compilation Models,Comparison between GNAT and Conventional Ada Library Models,,GNAT and Other Compilation Models
+@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-c-c-compilation-models}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{bc}
+@subsection Comparison between GNAT and C/C++ Compilation Models
+
+
+The GNAT model of compilation is close to the C and C++ models. You can
+think of Ada specs as corresponding to header files in C. As in C, you
+don’t need to compile specs; they are compiled when they are used. The
+Ada `with' is similar in effect to the @code{#include} of a C
+header.
+
+One notable difference is that, in Ada, you may compile specs separately
+to check them for semantic and syntactic accuracy. This is not always
+possible with C headers because they are fragments of programs that have
+less specific syntactic or semantic rules.
+
+The other major difference is the requirement for running the binder,
+which performs two important functions. First, it checks for
+consistency. In C or C++, the only defense against assembling
+inconsistent programs lies outside the compiler, in a makefile, for
+example. The binder satisfies the Ada requirement that it be impossible
+to construct an inconsistent program when the compiler is used in normal
+mode.
+
+@geindex Elaboration order control
+
+The other important function of the binder is to deal with elaboration
+issues. There are also elaboration issues in C++ that are handled
+automatically. This automatic handling has the advantage of being
+simpler to use, but the C++ programmer has no control over elaboration.
+Where @code{gnatbind} might complain there was no valid order of
+elaboration, a C++ compiler would simply construct a program that
+malfunctioned at run time.
+
+@node Comparison between GNAT and Conventional Ada Library Models,,Comparison between GNAT and C/C++ Compilation Models,GNAT and Other Compilation Models
+@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-conventional-ada-library-models}@anchor{bd}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{be}
+@subsection Comparison between GNAT and Conventional Ada Library Models
+
+
+This section is intended for Ada programmers who have
+used an Ada compiler implementing the traditional Ada library
+model, as described in the Ada Reference Manual.
+
+@geindex GNAT library
+
+In GNAT, there is no ‘library’ in the normal sense. Instead, the set of
+source files themselves acts as the library. Compiling Ada programs does
+not generate any centralized information, but rather an object file and
+a ALI file, which are of interest only to the binder and linker.
+In a traditional system, the compiler reads information not only from
+the source file being compiled, but also from the centralized library.
+This means that the effect of a compilation depends on what has been
+previously compiled. In particular:
+
+
+@itemize *
+
+@item
+When a unit is `with'ed, the unit seen by the compiler corresponds
+to the version of the unit most recently compiled into the library.
+
+@item
+Inlining is effective only if the necessary body has already been
+compiled into the library.
+
+@item
+Compiling a unit may obsolete other units in the library.
+@end itemize
+
+In GNAT, compiling one unit never affects the compilation of any other
+units because the compiler reads only source files. Only changes to source
+files can affect the results of a compilation. In particular:
+
+
+@itemize *
+
+@item
+When a unit is `with'ed, the unit seen by the compiler corresponds
+to the source version of the unit that is currently accessible to the
+compiler.
+
+@geindex Inlining
+
+@item
+Inlining requires the appropriate source files for the package or
+subprogram bodies to be available to the compiler. Inlining is always
+effective, independent of the order in which units are compiled.
+
+@item
+Compiling a unit never affects any other compilations. The editing of
+sources may cause previous compilations to be out of date if they
+depended on the source file being modified.
+@end itemize
+
+The most important result of these differences is that order of compilation
+is never significant in GNAT. There is no situation in which one is
+required to do one compilation before another. What shows up as order of
+compilation requirements in the traditional Ada library becomes, in
+GNAT, simple source dependencies; in other words, there is only a set
+of rules saying what source files must be present when a file is
+compiled.
+
+@node Using GNAT Files with External Tools,,GNAT and Other Compilation Models,The GNAT Compilation Model
+@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{bf}@anchor{gnat_ugn/the_gnat_compilation_model using-gnat-files-with-external-tools}@anchor{2e}
+@section Using GNAT Files with External Tools
+
+
+This section explains how files that are produced by GNAT may be
+used with tools designed for other languages.
+
+@menu
+* Using Other Utility Programs with GNAT::
+* The External Symbol Naming Scheme of GNAT::
+
+@end menu
+
+@node Using Other Utility Programs with GNAT,The External Symbol Naming Scheme of GNAT,,Using GNAT Files with External Tools
+@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{c0}@anchor{gnat_ugn/the_gnat_compilation_model using-other-utility-programs-with-gnat}@anchor{c1}
+@subsection Using Other Utility Programs with GNAT
+
+
+The object files generated by GNAT are in standard system format and in
+particular the debugging information uses this format. This means
+programs generated by GNAT can be used with existing utilities that
+depend on these formats.
+
+In general, any utility program that works with C will also often work with
+Ada programs generated by GNAT. This includes software utilities such as
+gprof (a profiling program), gdb (the FSF debugger), and utilities such
+as Purify.
+
+@node The External Symbol Naming Scheme of GNAT,,Using Other Utility Programs with GNAT,Using GNAT Files with External Tools
+@anchor{gnat_ugn/the_gnat_compilation_model id79}@anchor{c2}@anchor{gnat_ugn/the_gnat_compilation_model the-external-symbol-naming-scheme-of-gnat}@anchor{c3}
+@subsection The External Symbol Naming Scheme of GNAT
+
+
+In order to interpret the output from GNAT, when using tools that are
+originally intended for use with other languages, it is useful to
+understand the conventions used to generate link names from the Ada
+entity names.
+
+All link names are in all lowercase letters. With the exception of library
+procedure names, the mechanism used is simply to use the full expanded
+Ada name with dots replaced by double underscores. For example, suppose
+we have the following package spec:
+
+@example
+package QRS is
+ MN : Integer;
+end QRS;
+@end example
+
+@geindex pragma Export
+
+The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so
+the corresponding link name is @code{qrs__mn}.
+Of course if a @code{pragma Export} is used this may be overridden:
+
+@example
+package Exports is
+ Var1 : Integer;
+ pragma Export (Var1, C, External_Name => "var1_name");
+ Var2 : Integer;
+ pragma Export (Var2, C, Link_Name => "var2_link_name");
+end Exports;
+@end example
+
+In this case, the link name for @code{Var1} is whatever link name the
+C compiler would assign for the C function @code{var1_name}. This typically
+would be either @code{var1_name} or @code{_var1_name}, depending on operating
+system conventions, but other possibilities exist. The link name for
+@code{Var2} is @code{var2_link_name}, and this is not operating system
+dependent.
+
+One exception occurs for library level procedures. A potential ambiguity
+arises between the required name @code{_main} for the C main program,
+and the name we would otherwise assign to an Ada library level procedure
+called @code{Main} (which might well not be the main program).
+
+To avoid this ambiguity, we attach the prefix @code{_ada_} to such
+names. So if we have a library level procedure such as:
+
+@example
+procedure Hello (S : String);
+@end example
+
+the external name of this procedure will be @code{_ada_hello}.
+
+@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
+
+@node Building Executable Programs with GNAT,GNAT Utility Programs,The GNAT Compilation Model,Top
+@anchor{gnat_ugn/building_executable_programs_with_gnat doc}@anchor{c4}@anchor{gnat_ugn/building_executable_programs_with_gnat building-executable-programs-with-gnat}@anchor{a}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{c5}
+@chapter Building Executable Programs with GNAT
+
+
+This chapter describes first the gnatmake tool
+(@ref{c6,,Building with gnatmake}),
+which automatically determines the set of sources
+needed by an Ada compilation unit and executes the necessary
+(re)compilations, binding and linking.
+It also explains how to use each tool individually: the
+compiler (gcc, see @ref{c7,,Compiling with gcc}),
+binder (gnatbind, see @ref{c8,,Binding with gnatbind}),
+and linker (gnatlink, see @ref{c9,,Linking with gnatlink})
+to build executable programs.
+Finally, this chapter provides examples of
+how to make use of the general GNU make mechanism
+in a GNAT context (see @ref{70,,Using the GNU make Utility}).
+
+
+@menu
+* Building with gnatmake::
+* Compiling with gcc::
+* Compiler Switches::
+* Linker Switches::
+* Binding with gnatbind::
+* Linking with gnatlink::
+* Using the GNU make Utility::
+
+@end menu
+
+@node Building with gnatmake,Compiling with gcc,,Building Executable Programs with GNAT
+@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{ca}@anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{c6}
+@section Building with @code{gnatmake}
+
+
+@geindex gnatmake
+
+A typical development cycle when working on an Ada program consists of
+the following steps:
+
+
+@enumerate
+
+@item
+Edit some sources to fix bugs;
+
+@item
+Add enhancements;
+
+@item
+Compile all sources affected;
+
+@item
+Rebind and relink; and
+
+@item
+Test.
+@end enumerate
+
+@geindex Dependency rules (compilation)
+
+The third step in particular can be tricky, because not only do the modified
+files have to be compiled, but any files depending on these files must also be
+recompiled. The dependency rules in Ada can be quite complex, especially
+in the presence of overloading, @code{use} clauses, generics and inlined
+subprograms.
+
+@code{gnatmake} automatically takes care of the third and fourth steps
+of this process. It determines which sources need to be compiled,
+compiles them, and binds and links the resulting object files.
+
+Unlike some other Ada make programs, the dependencies are always
+accurately recomputed from the new sources. The source based approach of
+the GNAT compilation model makes this possible. This means that if
+changes to the source program cause corresponding changes in
+dependencies, they will always be tracked exactly correctly by
+@code{gnatmake}.
+
+Note that for advanced forms of project structure, we recommend creating
+a project file as explained in the `GNAT_Project_Manager' chapter in the
+`GPRbuild User’s Guide', and using the
+@code{gprbuild} tool which supports building with project files and works similarly
+to @code{gnatmake}.
+
+@menu
+* Running gnatmake::
+* Switches for gnatmake::
+* Mode Switches for gnatmake::
+* Notes on the Command Line::
+* How gnatmake Works::
+* Examples of gnatmake Usage::
+
+@end menu
+
+@node Running gnatmake,Switches for gnatmake,,Building with gnatmake
+@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{cb}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{cc}
+@subsection Running @code{gnatmake}
+
+
+The usual form of the @code{gnatmake} command is
+
+@example
+$ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
+@end example
+
+The only required argument is one @code{file_name}, which specifies
+a compilation unit that is a main program. Several @code{file_names} can be
+specified: this will result in several executables being built.
+If @code{switches} are present, they can be placed before the first
+@code{file_name}, between @code{file_names} or after the last @code{file_name}.
+If @code{mode_switches} are present, they must always be placed after
+the last @code{file_name} and all @code{switches}.
+
+If you are using standard file extensions (@code{.adb} and
+@code{.ads}), then the
+extension may be omitted from the @code{file_name} arguments. However, if
+you are using non-standard extensions, then it is required that the
+extension be given. A relative or absolute directory path can be
+specified in a @code{file_name}, in which case, the input source file will
+be searched for in the specified directory only. Otherwise, the input
+source file will first be searched in the directory where
+@code{gnatmake} was invoked and if it is not found, it will be search on
+the source path of the compiler as described in
+@ref{73,,Search Paths and the Run-Time Library (RTL)}.
+
+All @code{gnatmake} output (except when you specify @code{-M}) is sent to
+@code{stderr}. The output produced by the
+@code{-M} switch is sent to @code{stdout}.
+
+@node Switches for gnatmake,Mode Switches for gnatmake,Running gnatmake,Building with gnatmake
+@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{cd}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{ce}
+@subsection Switches for @code{gnatmake}
+
+
+You may specify any of the following switches to @code{gnatmake}:
+
+@geindex --version (gnatmake)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display Copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatmake)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+@end table
+
+@geindex -P (gnatmake)
+
+
+@table @asis
+
+@item @code{-P`project'}
+
+Build GNAT project file @code{project} using GPRbuild. When this switch is
+present, all other command-line switches are treated as GPRbuild switches
+and not @code{gnatmake} switches.
+@end table
+
+@c -- Comment:
+@c :ref:`gnatmake_and_Project_Files`.
+
+@geindex --GCC=compiler_name (gnatmake)
+
+
+@table @asis
+
+@item @code{--GCC=`compiler_name'}
+
+Program used for compiling. The default is @code{gcc}. You need to use
+quotes around @code{compiler_name} if @code{compiler_name} contains
+spaces or other separator characters.
+As an example @code{--GCC="foo -x -y"}
+will instruct @code{gnatmake} to use @code{foo -x -y} as your
+compiler. A limitation of this syntax is that the name and path name of
+the executable itself must not include any embedded spaces. Note that
+switch @code{-c} is always inserted after your command name. Thus in the
+above example the compiler command that will be used by @code{gnatmake}
+will be @code{foo -c -x -y}. If several @code{--GCC=compiler_name} are
+used, only the last @code{compiler_name} is taken into account. However,
+all the additional switches are also taken into account. Thus,
+@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
+@code{--GCC="bar -x -y -z -t"}.
+@end table
+
+@geindex --GNATBIND=binder_name (gnatmake)
+
+
+@table @asis
+
+@item @code{--GNATBIND=`binder_name'}
+
+Program used for binding. The default is @code{gnatbind}. You need to
+use quotes around @code{binder_name} if @code{binder_name} contains spaces
+or other separator characters.
+As an example @code{--GNATBIND="bar -x -y"}
+will instruct @code{gnatmake} to use @code{bar -x -y} as your
+binder. Binder switches that are normally appended by @code{gnatmake}
+to @code{gnatbind} are now appended to the end of @code{bar -x -y}.
+A limitation of this syntax is that the name and path name of the executable
+itself must not include any embedded spaces.
+@end table
+
+@geindex --GNATLINK=linker_name (gnatmake)
+
+
+@table @asis
+
+@item @code{--GNATLINK=`linker_name'}
+
+Program used for linking. The default is @code{gnatlink}. You need to
+use quotes around @code{linker_name} if @code{linker_name} contains spaces
+or other separator characters.
+As an example @code{--GNATLINK="lan -x -y"}
+will instruct @code{gnatmake} to use @code{lan -x -y} as your
+linker. Linker switches that are normally appended by @code{gnatmake} to
+@code{gnatlink} are now appended to the end of @code{lan -x -y}.
+A limitation of this syntax is that the name and path name of the executable
+itself must not include any embedded spaces.
+
+@item @code{--create-map-file}
+
+When linking an executable, create a map file. The name of the map file
+has the same name as the executable with extension “.map”.
+
+@item @code{--create-map-file=`mapfile'}
+
+When linking an executable, create a map file with the specified name.
+@end table
+
+@geindex --create-missing-dirs (gnatmake)
+
+
+@table @asis
+
+@item @code{--create-missing-dirs}
+
+When using project files (@code{-P`project'}), automatically create
+missing object directories, library directories and exec
+directories.
+
+@item @code{--single-compile-per-obj-dir}
+
+Disallow simultaneous compilations in the same object directory when
+project files are used.
+
+@item @code{--subdirs=`subdir'}
+
+Actual object directory of each project file is the subdirectory subdir of the
+object directory specified or defaulted in the project file.
+
+@item @code{--unchecked-shared-lib-imports}
+
+By default, shared library projects are not allowed to import static library
+projects. When this switch is used on the command line, this restriction is
+relaxed.
+
+@item @code{--source-info=`source info file'}
+
+Specify a source info file. This switch is active only when project files
+are used. If the source info file is specified as a relative path, then it is
+relative to the object directory of the main project. If the source info file
+does not exist, then after the Project Manager has successfully parsed and
+processed the project files and found the sources, it creates the source info
+file. If the source info file already exists and can be read successfully,
+then the Project Manager will get all the needed information about the sources
+from the source info file and will not look for them. This reduces the time
+to process the project files, especially when looking for sources that take a
+long time. If the source info file exists but cannot be parsed successfully,
+the Project Manager will attempt to recreate it. If the Project Manager fails
+to create the source info file, a message is issued, but gnatmake does not
+fail. @code{gnatmake} “trusts” the source info file. This means that
+if the source files have changed (addition, deletion, moving to a different
+source directory), then the source info file need to be deleted and recreated.
+@end table
+
+@geindex -a (gnatmake)
+
+
+@table @asis
+
+@item @code{-a}
+
+Consider all files in the make process, even the GNAT internal system
+files (for example, the predefined Ada library files), as well as any
+locked files. Locked files are files whose ALI file is write-protected.
+By default,
+@code{gnatmake} does not check these files,
+because the assumption is that the GNAT internal files are properly up
+to date, and also that any write protected ALI files have been properly
+installed. Note that if there is an installation problem, such that one
+of these files is not up to date, it will be properly caught by the
+binder.
+You may have to specify this switch if you are working on GNAT
+itself. The switch @code{-a} is also useful
+in conjunction with @code{-f}
+if you need to recompile an entire application,
+including run-time files, using special configuration pragmas,
+such as a @code{Normalize_Scalars} pragma.
+
+By default
+@code{gnatmake -a} compiles all GNAT
+internal files with
+@code{gcc -c -gnatpg} rather than @code{gcc -c}.
+@end table
+
+@geindex -b (gnatmake)
+
+
+@table @asis
+
+@item @code{-b}
+
+Bind only. Can be combined with @code{-c} to do
+compilation and binding, but no link.
+Can be combined with @code{-l}
+to do binding and linking. When not combined with
+@code{-c}
+all the units in the closure of the main program must have been previously
+compiled and must be up to date. The root unit specified by @code{file_name}
+may be given without extension, with the source extension or, if no GNAT
+Project File is specified, with the ALI file extension.
+@end table
+
+@geindex -c (gnatmake)
+
+
+@table @asis
+
+@item @code{-c}
+
+Compile only. Do not perform binding, except when @code{-b}
+is also specified. Do not perform linking, except if both
+@code{-b} and
+@code{-l} are also specified.
+If the root unit specified by @code{file_name} is not a main unit, this is the
+default. Otherwise @code{gnatmake} will attempt binding and linking
+unless all objects are up to date and the executable is more recent than
+the objects.
+@end table
+
+@geindex -C (gnatmake)
+
+
+@table @asis
+
+@item @code{-C}
+
+Use a temporary mapping file. A mapping file is a way to communicate
+to the compiler two mappings: from unit names to file names (without
+any directory information) and from file names to path names (with
+full directory information). A mapping file can make the compiler’s
+file searches faster, especially if there are many source directories,
+or the sources are read over a slow network connection. If
+@code{-P} is used, a mapping file is always used, so
+@code{-C} is unnecessary; in this case the mapping file
+is initially populated based on the project file. If
+@code{-C} is used without
+@code{-P},
+the mapping file is initially empty. Each invocation of the compiler
+will add any newly accessed sources to the mapping file.
+@end table
+
+@geindex -C= (gnatmake)
+
+
+@table @asis
+
+@item @code{-C=`file'}
+
+Use a specific mapping file. The file, specified as a path name (absolute or
+relative) by this switch, should already exist, otherwise the switch is
+ineffective. The specified mapping file will be communicated to the compiler.
+This switch is not compatible with a project file
+(-P`file`) or with multiple compiling processes
+(-jnnn, when nnn is greater than 1).
+@end table
+
+@geindex -d (gnatmake)
+
+
+@table @asis
+
+@item @code{-d}
+
+Display progress for each source, up to date or not, as a single line:
+
+@example
+completed x out of y (zz%)
+@end example
+
+If the file needs to be compiled this is displayed after the invocation of
+the compiler. These lines are displayed even in quiet output mode.
+@end table
+
+@geindex -D (gnatmake)
+
+
+@table @asis
+
+@item @code{-D `dir'}
+
+Put all object files and ALI file in directory @code{dir}.
+If the @code{-D} switch is not used, all object files
+and ALI files go in the current working directory.
+
+This switch cannot be used when using a project file.
+@end table
+
+@geindex -eI (gnatmake)
+
+
+@table @asis
+
+@item @code{-eI`nnn'}
+
+Indicates that the main source is a multi-unit source and the rank of the unit
+in the source file is nnn. nnn needs to be a positive number and a valid
+index in the source. This switch cannot be used when @code{gnatmake} is
+invoked for several mains.
+@end table
+
+@geindex -eL (gnatmake)
+
+@geindex symbolic links
+
+
+@table @asis
+
+@item @code{-eL}
+
+Follow all symbolic links when processing project files.
+This should be used if your project uses symbolic links for files or
+directories, but is not needed in other cases.
+
+@geindex naming scheme
+
+This also assumes that no directory matches the naming scheme for files (for
+instance that you do not have a directory called “sources.ads” when using the
+default GNAT naming scheme).
+
+When you do not have to use this switch (i.e., by default), gnatmake is able to
+save a lot of system calls (several per source file and object file), which
+can result in a significant speed up to load and manipulate a project file,
+especially when using source files from a remote system.
+@end table
+
+@geindex -eS (gnatmake)
+
+
+@table @asis
+
+@item @code{-eS}
+
+Output the commands for the compiler, the binder and the linker
+on standard output,
+instead of standard error.
+@end table
+
+@geindex -f (gnatmake)
+
+
+@table @asis
+
+@item @code{-f}
+
+Force recompilations. Recompile all sources, even though some object
+files may be up to date, but don’t recompile predefined or GNAT internal
+files or locked files (files with a write-protected ALI file),
+unless the @code{-a} switch is also specified.
+@end table
+
+@geindex -F (gnatmake)
+
+
+@table @asis
+
+@item @code{-F}
+
+When using project files, if some errors or warnings are detected during
+parsing and verbose mode is not in effect (no use of switch
+-v), then error lines start with the full path name of the project
+file, rather than its simple file name.
+@end table
+
+@geindex -g (gnatmake)
+
+
+@table @asis
+
+@item @code{-g}
+
+Enable debugging. This switch is simply passed to the compiler and to the
+linker.
+@end table
+
+@geindex -i (gnatmake)
+
+
+@table @asis
+
+@item @code{-i}
+
+In normal mode, @code{gnatmake} compiles all object files and ALI files
+into the current directory. If the @code{-i} switch is used,
+then instead object files and ALI files that already exist are overwritten
+in place. This means that once a large project is organized into separate
+directories in the desired manner, then @code{gnatmake} will automatically
+maintain and update this organization. If no ALI files are found on the
+Ada object path (see @ref{73,,Search Paths and the Run-Time Library (RTL)}),
+the new object and ALI files are created in the
+directory containing the source being compiled. If another organization
+is desired, where objects and sources are kept in different directories,
+a useful technique is to create dummy ALI files in the desired directories.
+When detecting such a dummy file, @code{gnatmake} will be forced to
+recompile the corresponding source file, and it will be put the resulting
+object and ALI files in the directory where it found the dummy file.
+@end table
+
+@geindex -j (gnatmake)
+
+@geindex Parallel make
+
+
+@table @asis
+
+@item @code{-j`n'}
+
+Use @code{n} processes to carry out the (re)compilations. On a multiprocessor
+machine compilations will occur in parallel. If @code{n} is 0, then the
+maximum number of parallel compilations is the number of core processors
+on the platform. In the event of compilation errors, messages from various
+compilations might get interspersed (but @code{gnatmake} will give you the
+full ordered list of failing compiles at the end). If this is problematic,
+rerun the make process with n set to 1 to get a clean list of messages.
+@end table
+
+@geindex -k (gnatmake)
+
+
+@table @asis
+
+@item @code{-k}
+
+Keep going. Continue as much as possible after a compilation error. To
+ease the programmer’s task in case of compilation errors, the list of
+sources for which the compile fails is given when @code{gnatmake}
+terminates.
+
+If @code{gnatmake} is invoked with several @code{file_names} and with this
+switch, if there are compilation errors when building an executable,
+@code{gnatmake} will not attempt to build the following executables.
+@end table
+
+@geindex -l (gnatmake)
+
+
+@table @asis
+
+@item @code{-l}
+
+Link only. Can be combined with @code{-b} to binding
+and linking. Linking will not be performed if combined with
+@code{-c}
+but not with @code{-b}.
+When not combined with @code{-b}
+all the units in the closure of the main program must have been previously
+compiled and must be up to date, and the main program needs to have been bound.
+The root unit specified by @code{file_name}
+may be given without extension, with the source extension or, if no GNAT
+Project File is specified, with the ALI file extension.
+@end table
+
+@geindex -m (gnatmake)
+
+
+@table @asis
+
+@item @code{-m}
+
+Specify that the minimum necessary amount of recompilations
+be performed. In this mode @code{gnatmake} ignores time
+stamp differences when the only
+modifications to a source file consist in adding/removing comments,
+empty lines, spaces or tabs. This means that if you have changed the
+comments in a source file or have simply reformatted it, using this
+switch will tell @code{gnatmake} not to recompile files that depend on it
+(provided other sources on which these files depend have undergone no
+semantic modifications). Note that the debugging information may be
+out of date with respect to the sources if the @code{-m} switch causes
+a compilation to be switched, so the use of this switch represents a
+trade-off between compilation time and accurate debugging information.
+@end table
+
+@geindex Dependencies
+@geindex producing list
+
+@geindex -M (gnatmake)
+
+
+@table @asis
+
+@item @code{-M}
+
+Check if all objects are up to date. If they are, output the object
+dependences to @code{stdout} in a form that can be directly exploited in
+a @code{Makefile}. By default, each source file is prefixed with its
+(relative or absolute) directory name. This name is whatever you
+specified in the various @code{-aI}
+and @code{-I} switches. If you use
+@code{gnatmake -M} @code{-q}
+(see below), only the source file names,
+without relative paths, are output. If you just specify the @code{-M}
+switch, dependencies of the GNAT internal system files are omitted. This
+is typically what you want. If you also specify
+the @code{-a} switch,
+dependencies of the GNAT internal files are also listed. Note that
+dependencies of the objects in external Ada libraries (see
+switch @code{-aL`dir'} in the following list)
+are never reported.
+@end table
+
+@geindex -n (gnatmake)
+
+
+@table @asis
+
+@item @code{-n}
+
+Don’t compile, bind, or link. Checks if all objects are up to date.
+If they are not, the full name of the first file that needs to be
+recompiled is printed.
+Repeated use of this option, followed by compiling the indicated source
+file, will eventually result in recompiling all required units.
+@end table
+
+@geindex -o (gnatmake)
+
+
+@table @asis
+
+@item @code{-o `exec_name'}
+
+Output executable name. The name of the final executable program will be
+@code{exec_name}. If the @code{-o} switch is omitted the default
+name for the executable will be the name of the input file in appropriate form
+for an executable file on the host system.
+
+This switch cannot be used when invoking @code{gnatmake} with several
+@code{file_names}.
+@end table
+
+@geindex -p (gnatmake)
+
+
+@table @asis
+
+@item @code{-p}
+
+Same as @code{--create-missing-dirs}
+@end table
+
+@geindex -q (gnatmake)
+
+
+@table @asis
+
+@item @code{-q}
+
+Quiet. When this flag is not set, the commands carried out by
+@code{gnatmake} are displayed.
+@end table
+
+@geindex -s (gnatmake)
+
+
+@table @asis
+
+@item @code{-s}
+
+Recompile if compiler switches have changed since last compilation.
+All compiler switches but -I and -o are taken into account in the
+following way:
+orders between different ‘first letter’ switches are ignored, but
+orders between same switches are taken into account. For example,
+@code{-O -O2} is different than @code{-O2 -O}, but @code{-g -O}
+is equivalent to @code{-O -g}.
+
+This switch is recommended when Integrated Preprocessing is used.
+@end table
+
+@geindex -u (gnatmake)
+
+
+@table @asis
+
+@item @code{-u}
+
+Unique. Recompile at most the main files. It implies -c. Combined with
+-f, it is equivalent to calling the compiler directly. Note that using
+-u with a project file and no main has a special meaning.
+@end table
+
+@c --Comment
+@c (See :ref:`Project_Files_and_Main_Subprograms`.)
+
+@geindex -U (gnatmake)
+
+
+@table @asis
+
+@item @code{-U}
+
+When used without a project file or with one or several mains on the command
+line, is equivalent to -u. When used with a project file and no main
+on the command line, all sources of all project files are checked and compiled
+if not up to date, and libraries are rebuilt, if necessary.
+@end table
+
+@geindex -v (gnatmake)
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose. Display the reason for all recompilations @code{gnatmake}
+decides are necessary, with the highest verbosity level.
+@end table
+
+@geindex -vl (gnatmake)
+
+
+@table @asis
+
+@item @code{-vl}
+
+Verbosity level Low. Display fewer lines than in verbosity Medium.
+@end table
+
+@geindex -vm (gnatmake)
+
+
+@table @asis
+
+@item @code{-vm}
+
+Verbosity level Medium. Potentially display fewer lines than in verbosity High.
+@end table
+
+@geindex -vm (gnatmake)
+
+
+@table @asis
+
+@item @code{-vh}
+
+Verbosity level High. Equivalent to -v.
+
+@item @code{-vP`x'}
+
+Indicate the verbosity of the parsing of GNAT project files.
+See @ref{cf,,Switches Related to Project Files}.
+@end table
+
+@geindex -x (gnatmake)
+
+
+@table @asis
+
+@item @code{-x}
+
+Indicate that sources that are not part of any Project File may be compiled.
+Normally, when using Project Files, only sources that are part of a Project
+File may be compile. When this switch is used, a source outside of all Project
+Files may be compiled. The ALI file and the object file will be put in the
+object directory of the main Project. The compilation switches used will only
+be those specified on the command line. Even when
+@code{-x} is used, mains specified on the
+command line need to be sources of a project file.
+
+@item @code{-X`name'=`value'}
+
+Indicate that external variable @code{name} has the value @code{value}.
+The Project Manager will use this value for occurrences of
+@code{external(name)} when parsing the project file.
+@ref{cf,,Switches Related to Project Files}.
+@end table
+
+@geindex -z (gnatmake)
+
+
+@table @asis
+
+@item @code{-z}
+
+No main subprogram. Bind and link the program even if the unit name
+given on the command line is a package name. The resulting executable
+will execute the elaboration routines of the package and its closure,
+then the finalization routines.
+@end table
+
+@subsubheading GCC switches
+
+
+Any uppercase or multi-character switch that is not a @code{gnatmake} switch
+is passed to @code{gcc} (e.g., @code{-O}, @code{-gnato,} etc.)
+
+@subsubheading Source and library search path switches
+
+
+@geindex -aI (gnatmake)
+
+
+@table @asis
+
+@item @code{-aI`dir'}
+
+When looking for source files also look in directory @code{dir}.
+The order in which source files search is undertaken is
+described in @ref{73,,Search Paths and the Run-Time Library (RTL)}.
+@end table
+
+@geindex -aL (gnatmake)
+
+
+@table @asis
+
+@item @code{-aL`dir'}
+
+Consider @code{dir} as being an externally provided Ada library.
+Instructs @code{gnatmake} to skip compilation units whose @code{.ALI}
+files have been located in directory @code{dir}. This allows you to have
+missing bodies for the units in @code{dir} and to ignore out of date bodies
+for the same units. You still need to specify
+the location of the specs for these units by using the switches
+@code{-aI`dir'} or @code{-I`dir'}.
+Note: this switch is provided for compatibility with previous versions
+of @code{gnatmake}. The easier method of causing standard libraries
+to be excluded from consideration is to write-protect the corresponding
+ALI files.
+@end table
+
+@geindex -aO (gnatmake)
+
+
+@table @asis
+
+@item @code{-aO`dir'}
+
+When searching for library and object files, look in directory
+@code{dir}. The order in which library files are searched is described in
+@ref{76,,Search Paths for gnatbind}.
+@end table
+
+@geindex Search paths
+@geindex for gnatmake
+
+@geindex -A (gnatmake)
+
+
+@table @asis
+
+@item @code{-A`dir'}
+
+Equivalent to @code{-aL`dir'} @code{-aI`dir'}.
+
+@geindex -I (gnatmake)
+
+@item @code{-I`dir'}
+
+Equivalent to @code{-aO`dir' -aI`dir'}.
+@end table
+
+@geindex -I- (gnatmake)
+
+@geindex Source files
+@geindex suppressing search
+
+
+@table @asis
+
+@item @code{-I-}
+
+Do not look for source files in the directory containing the source
+file named in the command line.
+Do not look for ALI or object files in the directory
+where @code{gnatmake} was invoked.
+@end table
+
+@geindex -L (gnatmake)
+
+@geindex Linker libraries
+
+
+@table @asis
+
+@item @code{-L`dir'}
+
+Add directory @code{dir} to the list of directories in which the linker
+will search for libraries. This is equivalent to
+@code{-largs} @code{-L`dir'}.
+Furthermore, under Windows, the sources pointed to by the libraries path
+set in the registry are not searched for.
+@end table
+
+@geindex -nostdinc (gnatmake)
+
+
+@table @asis
+
+@item @code{-nostdinc}
+
+Do not look for source files in the system default directory.
+@end table
+
+@geindex -nostdlib (gnatmake)
+
+
+@table @asis
+
+@item @code{-nostdlib}
+
+Do not look for library files in the system default directory.
+@end table
+
+@geindex --RTS (gnatmake)
+
+
+@table @asis
+
+@item @code{--RTS=`rts-path'}
+
+Specifies the default location of the run-time library. GNAT looks for the
+run-time
+in the following directories, and stops as soon as a valid run-time is found
+(@code{adainclude} or @code{ada_source_path}, and @code{adalib} or
+@code{ada_object_path} present):
+
+
+@itemize *
+
+@item
+`<current directory>/$rts_path'
+
+@item
+`<default-search-dir>/$rts_path'
+
+@item
+`<default-search-dir>/rts-$rts_path'
+
+@item
+The selected path is handled like a normal RTS path.
+@end itemize
+@end table
+
+@node Mode Switches for gnatmake,Notes on the Command Line,Switches for gnatmake,Building with gnatmake
+@anchor{gnat_ugn/building_executable_programs_with_gnat id4}@anchor{d0}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{d1}
+@subsection Mode Switches for @code{gnatmake}
+
+
+The mode switches (referred to as @code{mode_switches}) allow the
+inclusion of switches that are to be passed to the compiler itself, the
+binder or the linker. The effect of a mode switch is to cause all
+subsequent switches up to the end of the switch list, or up to the next
+mode switch, to be interpreted as switches to be passed on to the
+designated component of GNAT.
+
+@geindex -cargs (gnatmake)
+
+
+@table @asis
+
+@item @code{-cargs `switches'}
+
+Compiler switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gcc}. They will be passed on to
+all compile steps performed by @code{gnatmake}.
+@end table
+
+@geindex -bargs (gnatmake)
+
+
+@table @asis
+
+@item @code{-bargs `switches'}
+
+Binder switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gnatbind}. They will be passed on to
+all bind steps performed by @code{gnatmake}.
+@end table
+
+@geindex -largs (gnatmake)
+
+
+@table @asis
+
+@item @code{-largs `switches'}
+
+Linker switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gnatlink}. They will be passed on to
+all link steps performed by @code{gnatmake}.
+@end table
+
+@geindex -margs (gnatmake)
+
+
+@table @asis
+
+@item @code{-margs `switches'}
+
+Make switches. The switches are directly interpreted by @code{gnatmake},
+regardless of any previous occurrence of @code{-cargs}, @code{-bargs}
+or @code{-largs}.
+@end table
+
+@node Notes on the Command Line,How gnatmake Works,Mode Switches for gnatmake,Building with gnatmake
+@anchor{gnat_ugn/building_executable_programs_with_gnat id5}@anchor{d2}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{d3}
+@subsection Notes on the Command Line
+
+
+This section contains some additional useful notes on the operation
+of the @code{gnatmake} command.
+
+@geindex Recompilation (by gnatmake)
+
+
+@itemize *
+
+@item
+If @code{gnatmake} finds no ALI files, it recompiles the main program
+and all other units required by the main program.
+This means that @code{gnatmake}
+can be used for the initial compile, as well as during subsequent steps of
+the development cycle.
+
+@item
+If you enter @code{gnatmake foo.adb}, where @code{foo}
+is a subunit or body of a generic unit, @code{gnatmake} recompiles
+@code{foo.adb} (because it finds no ALI) and stops, issuing a
+warning.
+
+@item
+In @code{gnatmake} the switch @code{-I}
+is used to specify both source and
+library file paths. Use @code{-aI}
+instead if you just want to specify
+source paths only and @code{-aO}
+if you want to specify library paths
+only.
+
+@item
+@code{gnatmake} will ignore any files whose ALI file is write-protected.
+This may conveniently be used to exclude standard libraries from
+consideration and in particular it means that the use of the
+@code{-f} switch will not recompile these files
+unless @code{-a} is also specified.
+
+@item
+@code{gnatmake} has been designed to make the use of Ada libraries
+particularly convenient. Assume you have an Ada library organized
+as follows: `obj-dir' contains the objects and ALI files for
+of your Ada compilation units,
+whereas `include-dir' contains the
+specs of these units, but no bodies. Then to compile a unit
+stored in @code{main.adb}, which uses this Ada library you would just type:
+
+@example
+$ gnatmake -aI`include-dir` -aL`obj-dir` main
+@end example
+
+@item
+Using @code{gnatmake} along with the @code{-m (minimal recompilation)}
+switch provides a mechanism for avoiding unnecessary recompilations. Using
+this switch,
+you can update the comments/format of your
+source files without having to recompile everything. Note, however, that
+adding or deleting lines in a source files may render its debugging
+info obsolete. If the file in question is a spec, the impact is rather
+limited, as that debugging info will only be useful during the
+elaboration phase of your program. For bodies the impact can be more
+significant. In all events, your debugger will warn you if a source file
+is more recent than the corresponding object, and alert you to the fact
+that the debugging information may be out of date.
+@end itemize
+
+@node How gnatmake Works,Examples of gnatmake Usage,Notes on the Command Line,Building with gnatmake
+@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{d4}@anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{d5}
+@subsection How @code{gnatmake} Works
+
+
+Generally @code{gnatmake} automatically performs all necessary
+recompilations and you don’t need to worry about how it works. However,
+it may be useful to have some basic understanding of the @code{gnatmake}
+approach and in particular to understand how it uses the results of
+previous compilations without incorrectly depending on them.
+
+First a definition: an object file is considered `up to date' if the
+corresponding ALI file exists and if all the source files listed in the
+dependency section of this ALI file have time stamps matching those in
+the ALI file. This means that neither the source file itself nor any
+files that it depends on have been modified, and hence there is no need
+to recompile this file.
+
+@code{gnatmake} works by first checking if the specified main unit is up
+to date. If so, no compilations are required for the main unit. If not,
+@code{gnatmake} compiles the main program to build a new ALI file that
+reflects the latest sources. Then the ALI file of the main unit is
+examined to find all the source files on which the main program depends,
+and @code{gnatmake} recursively applies the above procedure on all these
+files.
+
+This process ensures that @code{gnatmake} only trusts the dependencies
+in an existing ALI file if they are known to be correct. Otherwise it
+always recompiles to determine a new, guaranteed accurate set of
+dependencies. As a result the program is compiled ‘upside down’ from what may
+be more familiar as the required order of compilation in some other Ada
+systems. In particular, clients are compiled before the units on which
+they depend. The ability of GNAT to compile in any order is critical in
+allowing an order of compilation to be chosen that guarantees that
+@code{gnatmake} will recompute a correct set of new dependencies if
+necessary.
+
+When invoking @code{gnatmake} with several @code{file_names}, if a unit is
+imported by several of the executables, it will be recompiled at most once.
+
+Note: when using non-standard naming conventions
+(@ref{1c,,Using Other File Names}), changing through a configuration pragmas
+file the version of a source and invoking @code{gnatmake} to recompile may
+have no effect, if the previous version of the source is still accessible
+by @code{gnatmake}. It may be necessary to use the switch
+-f.
+
+@node Examples of gnatmake Usage,,How gnatmake Works,Building with gnatmake
+@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatmake-usage}@anchor{d6}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{d7}
+@subsection Examples of @code{gnatmake} Usage
+
+
+
+@table @asis
+
+@item `gnatmake hello.adb'
+
+Compile all files necessary to bind and link the main program
+@code{hello.adb} (containing unit @code{Hello}) and bind and link the
+resulting object files to generate an executable file @code{hello}.
+
+@item `gnatmake main1 main2 main3'
+
+Compile all files necessary to bind and link the main programs
+@code{main1.adb} (containing unit @code{Main1}), @code{main2.adb}
+(containing unit @code{Main2}) and @code{main3.adb}
+(containing unit @code{Main3}) and bind and link the resulting object files
+to generate three executable files @code{main1},
+@code{main2} and @code{main3}.
+
+@item `gnatmake -q Main_Unit -cargs -O2 -bargs -l'
+
+Compile all files necessary to bind and link the main program unit
+@code{Main_Unit} (from file @code{main_unit.adb}). All compilations will
+be done with optimization level 2 and the order of elaboration will be
+listed by the binder. @code{gnatmake} will operate in quiet mode, not
+displaying commands it is executing.
+@end table
+
+@node Compiling with gcc,Compiler Switches,Building with gnatmake,Building Executable Programs with GNAT
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-with-gcc}@anchor{c7}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{d8}
+@section Compiling with @code{gcc}
+
+
+This section discusses how to compile Ada programs using the @code{gcc}
+command. It also describes the set of switches
+that can be used to control the behavior of the compiler.
+
+@menu
+* Compiling Programs::
+* Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL.
+* Order of Compilation Issues::
+* Examples::
+
+@end menu
+
+@node Compiling Programs,Search Paths and the Run-Time Library RTL,,Compiling with gcc
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-programs}@anchor{d9}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{da}
+@subsection Compiling Programs
+
+
+The first step in creating an executable program is to compile the units
+of the program using the @code{gcc} command. You must compile the
+following files:
+
+
+@itemize *
+
+@item
+the body file (@code{.adb}) for a library level subprogram or generic
+subprogram
+
+@item
+the spec file (@code{.ads}) for a library level package or generic
+package that has no body
+
+@item
+the body file (@code{.adb}) for a library level package
+or generic package that has a body
+@end itemize
+
+You need `not' compile the following files
+
+
+@itemize *
+
+@item
+the spec of a library unit which has a body
+
+@item
+subunits
+@end itemize
+
+because they are compiled as part of compiling related units. GNAT
+package specs
+when the corresponding body is compiled, and subunits when the parent is
+compiled.
+
+@geindex cannot generate code
+
+If you attempt to compile any of these files, you will get one of the
+following error messages (where @code{fff} is the name of the file you
+compiled):
+
+@quotation
+
+@example
+cannot generate code for file `@w{`}fff`@w{`} (package spec)
+to check package spec, use -gnatc
+
+cannot generate code for file `@w{`}fff`@w{`} (missing subunits)
+to check parent unit, use -gnatc
+
+cannot generate code for file `@w{`}fff`@w{`} (subprogram spec)
+to check subprogram spec, use -gnatc
+
+cannot generate code for file `@w{`}fff`@w{`} (subunit)
+to check subunit, use -gnatc
+@end example
+@end quotation
+
+As indicated by the above error messages, if you want to submit
+one of these files to the compiler to check for correct semantics
+without generating code, then use the @code{-gnatc} switch.
+
+The basic command for compiling a file containing an Ada unit is:
+
+@example
+$ gcc -c [switches] <file name>
+@end example
+
+where @code{file name} is the name of the Ada file (usually
+having an extension @code{.ads} for a spec or @code{.adb} for a body).
+You specify the
+@code{-c} switch to tell @code{gcc} to compile, but not link, the file.
+The result of a successful compilation is an object file, which has the
+same name as the source file but an extension of @code{.o} and an Ada
+Library Information (ALI) file, which also has the same name as the
+source file, but with @code{.ali} as the extension. GNAT creates these
+two output files in the current directory, but you may specify a source
+file in any directory using an absolute or relative path specification
+containing the directory information.
+
+TESTING: the @code{--foobar`NN'} switch
+
+@geindex gnat1
+
+@code{gcc} is actually a driver program that looks at the extensions of
+the file arguments and loads the appropriate compiler. For example, the
+GNU C compiler is @code{cc1}, and the Ada compiler is @code{gnat1}.
+These programs are in directories known to the driver program (in some
+configurations via environment variables you set), but need not be in
+your path. The @code{gcc} driver also calls the assembler and any other
+utilities needed to complete the generation of the required object
+files.
+
+It is possible to supply several file names on the same @code{gcc}
+command. This causes @code{gcc} to call the appropriate compiler for
+each file. For example, the following command lists two separate
+files to be compiled:
+
+@example
+$ gcc -c x.adb y.adb
+@end example
+
+calls @code{gnat1} (the Ada compiler) twice to compile @code{x.adb} and
+@code{y.adb}.
+The compiler generates two object files @code{x.o} and @code{y.o}
+and the two ALI files @code{x.ali} and @code{y.ali}.
+
+Any switches apply to all the files listed, see @ref{db,,Compiler Switches} for a
+list of available @code{gcc} switches.
+
+@node Search Paths and the Run-Time Library RTL,Order of Compilation Issues,Compiling Programs,Compiling with gcc
+@anchor{gnat_ugn/building_executable_programs_with_gnat id10}@anchor{dc}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{73}
+@subsection Search Paths and the Run-Time Library (RTL)
+
+
+With the GNAT source-based library system, the compiler must be able to
+find source files for units that are needed by the unit being compiled.
+Search paths are used to guide this process.
+
+The compiler compiles one source file whose name must be given
+explicitly on the command line. In other words, no searching is done
+for this file. To find all other source files that are needed (the most
+common being the specs of units), the compiler examines the following
+directories, in the following order:
+
+
+@itemize *
+
+@item
+The directory containing the source file of the main unit being compiled
+(the file name on the command line).
+
+@item
+Each directory named by an @code{-I} switch given on the @code{gcc}
+command line, in the order given.
+
+@geindex ADA_PRJ_INCLUDE_FILE
+
+@item
+Each of the directories listed in the text file whose name is given
+by the
+@geindex ADA_PRJ_INCLUDE_FILE
+@geindex environment variable; ADA_PRJ_INCLUDE_FILE
+@code{ADA_PRJ_INCLUDE_FILE} environment variable.
+@geindex ADA_PRJ_INCLUDE_FILE
+@geindex environment variable; ADA_PRJ_INCLUDE_FILE
+@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the gnat
+driver when project files are used. It should not normally be set
+by other means.
+
+@geindex ADA_INCLUDE_PATH
+
+@item
+Each of the directories listed in the value of the
+@geindex ADA_INCLUDE_PATH
+@geindex environment variable; ADA_INCLUDE_PATH
+@code{ADA_INCLUDE_PATH} environment variable.
+Construct this value
+exactly as the
+@geindex PATH
+@geindex environment variable; PATH
+@code{PATH} environment variable: a list of directory
+names separated by colons (semicolons when working with the NT version).
+
+@item
+The content of the @code{ada_source_path} file which is part of the GNAT
+installation tree and is used to store standard libraries such as the
+GNAT Run Time Library (RTL) source files.
+@ref{72,,Installing a library}
+@end itemize
+
+Specifying the switch @code{-I-}
+inhibits the use of the directory
+containing the source file named in the command line. You can still
+have this directory on your search path, but in this case it must be
+explicitly requested with a @code{-I} switch.
+
+Specifying the switch @code{-nostdinc}
+inhibits the search of the default location for the GNAT Run Time
+Library (RTL) source files.
+
+The compiler outputs its object files and ALI files in the current
+working directory.
+Caution: The object file can be redirected with the @code{-o} switch;
+however, @code{gcc} and @code{gnat1} have not been coordinated on this
+so the @code{ALI} file will not go to the right place. Therefore, you should
+avoid using the @code{-o} switch.
+
+@geindex System.IO
+
+The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
+children make up the GNAT RTL, together with the simple @code{System.IO}
+package used in the @code{"Hello World"} example. The sources for these units
+are needed by the compiler and are kept together in one directory. Not
+all of the bodies are needed, but all of the sources are kept together
+anyway. In a normal installation, you need not specify these directory
+names when compiling or binding. Either the environment variables or
+the built-in defaults cause these files to be found.
+
+In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
+@code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
+consisting of child units of @code{GNAT}. This is a collection of generally
+useful types, subprograms, etc. See the @cite{GNAT_Reference_Manual}
+for further details.
+
+Besides simplifying access to the RTL, a major use of search paths is
+in compiling sources from multiple directories. This can make
+development environments much more flexible.
+
+@node Order of Compilation Issues,Examples,Search Paths and the Run-Time Library RTL,Compiling with gcc
+@anchor{gnat_ugn/building_executable_programs_with_gnat id11}@anchor{dd}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{de}
+@subsection Order of Compilation Issues
+
+
+If, in our earlier example, there was a spec for the @code{hello}
+procedure, it would be contained in the file @code{hello.ads}; yet this
+file would not have to be explicitly compiled. This is the result of the
+model we chose to implement library management. Some of the consequences
+of this model are as follows:
+
+
+@itemize *
+
+@item
+There is no point in compiling specs (except for package
+specs with no bodies) because these are compiled as needed by clients. If
+you attempt a useless compilation, you will receive an error message.
+It is also useless to compile subunits because they are compiled as needed
+by the parent.
+
+@item
+There are no order of compilation requirements: performing a
+compilation never obsoletes anything. The only way you can obsolete
+something and require recompilations is to modify one of the
+source files on which it depends.
+
+@item
+There is no library as such, apart from the ALI files
+(@ref{28,,The Ada Library Information Files}, for information on the format
+of these files). For now we find it convenient to create separate ALI files,
+but eventually the information therein may be incorporated into the object
+file directly.
+
+@item
+When you compile a unit, the source files for the specs of all units
+that it `with's, all its subunits, and the bodies of any generics it
+instantiates must be available (reachable by the search-paths mechanism
+described above), or you will receive a fatal error message.
+@end itemize
+
+@node Examples,,Order of Compilation Issues,Compiling with gcc
+@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{e0}
+@subsection Examples
+
+
+The following are some typical Ada compilation command line examples:
+
+@example
+$ gcc -c xyz.adb
+@end example
+
+Compile body in file @code{xyz.adb} with all default options.
+
+@example
+$ gcc -c -O2 -gnata xyz-def.adb
+@end example
+
+Compile the child unit package in file @code{xyz-def.adb} with extensive
+optimizations, and pragma @code{Assert}/@cite{Debug} statements
+enabled.
+
+@example
+$ gcc -c -gnatc abc-def.adb
+@end example
+
+Compile the subunit in file @code{abc-def.adb} in semantic-checking-only
+mode.
+
+@node Compiler Switches,Linker Switches,Compiling with gcc,Building Executable Programs with GNAT
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{e1}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{db}
+@section Compiler Switches
+
+
+The @code{gcc} command accepts switches that control the
+compilation process. These switches are fully described in this section:
+first an alphabetical listing of all switches with a brief description,
+and then functionally grouped sets of switches with more detailed
+information.
+
+More switches exist for GCC than those documented here, especially
+for specific targets. However, their use is not recommended as
+they may change code generation in ways that are incompatible with
+the Ada run-time library, or can cause inconsistencies between
+compilation units.
+
+@menu
+* Alphabetical List of All Switches::
+* Output and Error Message Control::
+* Warning Message Control::
+* Debugging and Assertion Control::
+* Validity Checking::
+* Style Checking::
+* Run-Time Checks::
+* Using gcc for Syntax Checking::
+* Using gcc for Semantic Checking::
+* Compiling Different Versions of Ada::
+* Character Set Control::
+* File Naming Control::
+* Subprogram Inlining Control::
+* Auxiliary Output Control::
+* Debugging Control::
+* Exception Handling Control::
+* Units to Sources Mapping Files::
+* Code Generation Control::
+
+@end menu
+
+@node Alphabetical List of All Switches,Output and Error Message Control,,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{e2}@anchor{gnat_ugn/building_executable_programs_with_gnat id13}@anchor{e3}
+@subsection Alphabetical List of All Switches
+
+
+@geindex -b (gcc)
+
+
+@table @asis
+
+@item @code{-b `target'}
+
+Compile your program to run on @code{target}, which is the name of a
+system configuration. You must have a GNAT cross-compiler built if
+@code{target} is not the same as your host system.
+@end table
+
+@geindex -B (gcc)
+
+
+@table @asis
+
+@item @code{-B`dir'}
+
+Load compiler executables (for example, @code{gnat1}, the Ada compiler)
+from @code{dir} instead of the default location. Only use this switch
+when multiple versions of the GNAT compiler are available.
+See the “Options for Directory Search” section in the
+@cite{Using the GNU Compiler Collection (GCC)} manual for further details.
+You would normally use the @code{-b} or @code{-V} switch instead.
+@end table
+
+@geindex -c (gcc)
+
+
+@table @asis
+
+@item @code{-c}
+
+Compile. Always use this switch when compiling Ada programs.
+
+Note: for some other languages when using @code{gcc}, notably in
+the case of C and C++, it is possible to use
+use @code{gcc} without a @code{-c} switch to
+compile and link in one step. In the case of GNAT, you
+cannot use this approach, because the binder must be run
+and @code{gcc} cannot be used to run the GNAT binder.
+@end table
+
+@geindex -fcallgraph-info (gcc)
+
+
+@table @asis
+
+@item @code{-fcallgraph-info[=su,da]}
+
+Makes the compiler output callgraph information for the program, on a
+per-file basis. The information is generated in the VCG format. It can
+be decorated with additional, per-node and/or per-edge information, if a
+list of comma-separated markers is additionally specified. When the
+@code{su} marker is specified, the callgraph is decorated with stack usage
+information; it is equivalent to @code{-fstack-usage}. When the @code{da}
+marker is specified, the callgraph is decorated with information about
+dynamically allocated objects.
+@end table
+
+@geindex -fdiagnostics-format (gcc)
+
+
+@table @asis
+
+@item @code{-fdiagnostics-format=json}
+
+Makes GNAT emit warning and error messages as JSON. Inhibits printing of
+text warning and errors messages except if @code{-gnatv} or
+@code{-gnatl} are present. Uses absolute file paths when used along
+@code{-gnatef}.
+@end table
+
+@geindex -fdump-scos (gcc)
+
+
+@table @asis
+
+@item @code{-fdump-scos}
+
+Generates SCO (Source Coverage Obligation) information in the ALI file.
+This information is used by advanced coverage tools. See unit @code{SCOs}
+in the compiler sources for details in files @code{scos.ads} and
+@code{scos.adb}.
+@end table
+
+@geindex -fgnat-encodings (gcc)
+
+
+@table @asis
+
+@item @code{-fgnat-encodings=[all|gdb|minimal]}
+
+This switch controls the balance between GNAT encodings and standard DWARF
+emitted in the debug information.
+@end table
+
+@geindex -flto (gcc)
+
+
+@table @asis
+
+@item @code{-flto[=`n']}
+
+Enables Link Time Optimization. This switch must be used in conjunction
+with the @code{-Ox} switches (but not with the @code{-gnatn} switch
+since it is a full replacement for the latter) and instructs the compiler
+to defer most optimizations until the link stage. The advantage of this
+approach is that the compiler can do a whole-program analysis and choose
+the best interprocedural optimization strategy based on a complete view
+of the program, instead of a fragmentary view with the usual approach.
+This can also speed up the compilation of big programs and reduce the
+size of the executable, compared with a traditional per-unit compilation
+with inlining across units enabled by the @code{-gnatn} switch.
+The drawback of this approach is that it may require more memory and that
+the debugging information generated by -g with it might be hardly usable.
+The switch, as well as the accompanying @code{-Ox} switches, must be
+specified both for the compilation and the link phases.
+If the @code{n} parameter is specified, the optimization and final code
+generation at link time are executed using @code{n} parallel jobs by
+means of an installed @code{make} program.
+@end table
+
+@geindex -fno-inline (gcc)
+
+
+@table @asis
+
+@item @code{-fno-inline}
+
+Suppresses all inlining, unless requested with pragma @code{Inline_Always}. The
+effect is enforced regardless of other optimization or inlining switches.
+Note that inlining can also be suppressed on a finer-grained basis with
+pragma @code{No_Inline}.
+@end table
+
+@geindex -fno-inline-functions (gcc)
+
+
+@table @asis
+
+@item @code{-fno-inline-functions}
+
+Suppresses automatic inlining of subprograms, which is enabled
+if @code{-O3} is used.
+@end table
+
+@geindex -fno-inline-small-functions (gcc)
+
+
+@table @asis
+
+@item @code{-fno-inline-small-functions}
+
+Suppresses automatic inlining of small subprograms, which is enabled
+if @code{-O2} is used.
+@end table
+
+@geindex -fno-inline-functions-called-once (gcc)
+
+
+@table @asis
+
+@item @code{-fno-inline-functions-called-once}
+
+Suppresses inlining of subprograms local to the unit and called once
+from within it, which is enabled if @code{-O1} is used.
+@end table
+
+@geindex -fno-ivopts (gcc)
+
+
+@table @asis
+
+@item @code{-fno-ivopts}
+
+Suppresses high-level loop induction variable optimizations, which are
+enabled if @code{-O1} is used. These optimizations are generally
+profitable but, for some specific cases of loops with numerous uses
+of the iteration variable that follow a common pattern, they may end
+up destroying the regularity that could be exploited at a lower level
+and thus producing inferior code.
+@end table
+
+@geindex -fno-strict-aliasing (gcc)
+
+
+@table @asis
+
+@item @code{-fno-strict-aliasing}
+
+Causes the compiler to avoid assumptions regarding non-aliasing
+of objects of different types. See
+@ref{e4,,Optimization and Strict Aliasing} for details.
+@end table
+
+@geindex -fno-strict-overflow (gcc)
+
+
+@table @asis
+
+@item @code{-fno-strict-overflow}
+
+Causes the compiler to avoid assumptions regarding the rules of signed
+integer overflow. These rules specify that signed integer overflow will
+result in a Constraint_Error exception at run time and are enforced in
+default mode by the compiler, so this switch should not be necessary in
+normal operating mode. It might be useful in conjunction with @code{-gnato0}
+for very peculiar cases of low-level programming.
+@end table
+
+@geindex -fstack-check (gcc)
+
+
+@table @asis
+
+@item @code{-fstack-check}
+
+Activates stack checking.
+See @ref{e5,,Stack Overflow Checking} for details.
+@end table
+
+@geindex -fstack-usage (gcc)
+
+
+@table @asis
+
+@item @code{-fstack-usage}
+
+Makes the compiler output stack usage information for the program, on a
+per-subprogram basis. See @ref{e6,,Static Stack Usage Analysis} for details.
+@end table
+
+@geindex -g (gcc)
+
+
+@table @asis
+
+@item @code{-g}
+
+Generate debugging information. This information is stored in the object
+file and copied from there to the final executable file by the linker,
+where it can be read by the debugger. You must use the
+@code{-g} switch if you plan on using the debugger.
+@end table
+
+@geindex -gnat05 (gcc)
+
+
+@table @asis
+
+@item @code{-gnat05}
+
+Allow full Ada 2005 features.
+@end table
+
+@geindex -gnat12 (gcc)
+
+
+@table @asis
+
+@item @code{-gnat12}
+
+Allow full Ada 2012 features.
+@end table
+
+@geindex -gnat83 (gcc)
+
+@geindex -gnat2005 (gcc)
+
+
+@table @asis
+
+@item @code{-gnat2005}
+
+Allow full Ada 2005 features (same as @code{-gnat05})
+@end table
+
+@geindex -gnat2012 (gcc)
+
+
+@table @asis
+
+@item @code{-gnat2012}
+
+Allow full Ada 2012 features (same as @code{-gnat12})
+@end table
+
+@geindex -gnat2022 (gcc)
+
+
+@table @asis
+
+@item @code{-gnat2022}
+
+Allow full Ada 2022 features
+
+@item @code{-gnat83}
+
+Enforce Ada 83 restrictions.
+@end table
+
+@geindex -gnat95 (gcc)
+
+
+@table @asis
+
+@item @code{-gnat95}
+
+Enforce Ada 95 restrictions.
+
+Note: for compatibility with some Ada 95 compilers which support only
+the @code{overriding} keyword of Ada 2005, the @code{-gnatd.D} switch can
+be used along with @code{-gnat95} to achieve a similar effect with GNAT.
+
+@code{-gnatd.D} instructs GNAT to consider @code{overriding} as a keyword
+and handle its associated semantic checks, even in Ada 95 mode.
+@end table
+
+@geindex -gnata (gcc)
+
+
+@table @asis
+
+@item @code{-gnata}
+
+Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
+activated. Note that these pragmas can also be controlled using the
+configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
+It also activates pragmas @code{Check}, @code{Precondition}, and
+@code{Postcondition}. Note that these pragmas can also be controlled
+using the configuration pragma @code{Check_Policy}. In Ada 2012, it
+also activates all assertions defined in the RM as aspects: preconditions,
+postconditions, type invariants and (sub)type predicates. In all Ada modes,
+corresponding pragmas for type invariants and (sub)type predicates are
+also activated. The default is that all these assertions are disabled,
+and have no effect, other than being checked for syntactic validity, and
+in the case of subtype predicates, constructions such as membership tests
+still test predicates even if assertions are turned off.
+@end table
+
+@geindex -gnatA (gcc)
+
+
+@table @asis
+
+@item @code{-gnatA}
+
+Avoid processing @code{gnat.adc}. If a @code{gnat.adc} file is present,
+it will be ignored.
+@end table
+
+@geindex -gnatb (gcc)
+
+
+@table @asis
+
+@item @code{-gnatb}
+
+Generate brief messages to @code{stderr} even if verbose mode set.
+@end table
+
+@geindex -gnatB (gcc)
+
+
+@table @asis
+
+@item @code{-gnatB}
+
+Assume no invalid (bad) values except for ‘Valid attribute use
+(@ref{e7,,Validity Checking}).
+@end table
+
+@geindex -gnatc (gcc)
+
+
+@table @asis
+
+@item @code{-gnatc}
+
+Check syntax and semantics only (no code generation attempted). When the
+compiler is invoked by @code{gnatmake}, if the switch @code{-gnatc} is
+only given to the compiler (after @code{-cargs} or in package Compiler of
+the project file), @code{gnatmake} will fail because it will not find the
+object file after compilation. If @code{gnatmake} is called with
+@code{-gnatc} as a builder switch (before @code{-cargs} or in package
+Builder of the project file) then @code{gnatmake} will not fail because
+it will not look for the object files after compilation, and it will not try
+to build and link.
+@end table
+
+@geindex -gnatC (gcc)
+
+
+@table @asis
+
+@item @code{-gnatC}
+
+Generate CodePeer intermediate format (no code generation attempted).
+This switch will generate an intermediate representation suitable for
+use by CodePeer (@code{.scil} files). This switch is not compatible with
+code generation (it will, among other things, disable some switches such
+as -gnatn, and enable others such as -gnata).
+@end table
+
+@geindex -gnatd (gcc)
+
+
+@table @asis
+
+@item @code{-gnatd}
+
+Specify debug options for the compiler. The string of characters after
+the @code{-gnatd} specifies the specific debug options. The possible
+characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore.
+See compiler source file @code{debug.adb} for details of the implemented
+debug options. Certain debug options are relevant to applications
+programmers, and these are documented at appropriate points in this
+users guide.
+@end table
+
+@geindex -gnatD[nn] (gcc)
+
+
+@table @asis
+
+@item @code{-gnatD}
+
+Create expanded source files for source level debugging. This switch
+also suppresses generation of cross-reference information
+(see @code{-gnatx}). Note that this switch is not allowed if a previous
+-gnatR switch has been given, since these two switches are not compatible.
+@end table
+
+@geindex -gnateA (gcc)
+
+
+@table @asis
+
+@item @code{-gnateA}
+
+Check that the actual parameters of a subprogram call are not aliases of one
+another. To qualify as aliasing, their memory locations must be identical or
+overlapping, at least one of the corresponding formal parameters must be of
+mode OUT or IN OUT, and at least one of the corresponding formal parameters
+must have its parameter passing mechanism not specified.
+
+@example
+type Rec_Typ is record
+ Data : Integer := 0;
+end record;
+
+function Self (Val : Rec_Typ) return Rec_Typ is
+begin
+ return Val;
+end Self;
+
+procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is
+begin
+ null;
+end Detect_Aliasing;
+
+Obj : Rec_Typ;
+
+Detect_Aliasing (Obj, Obj);
+Detect_Aliasing (Obj, Self (Obj));
+@end example
+
+In the example above, the first call to @code{Detect_Aliasing} fails with a
+@code{Program_Error} at run time because the actuals for @code{Val_1} and
+@code{Val_2} denote the same object. The second call executes without raising
+an exception because @code{Self(Obj)} produces an anonymous object which does
+not share the memory location of @code{Obj}.
+@end table
+
+@geindex -gnateb (gcc)
+
+
+@table @asis
+
+@item @code{-gnateb}
+
+Store configuration files by their basename in ALI files. This switch is
+used for instance by gprbuild for distributed builds in order to prevent
+issues where machine-specific absolute paths could end up being stored in
+ALI files.
+@end table
+
+@geindex -gnatec (gcc)
+
+
+@table @asis
+
+@item @code{-gnatec=`path'}
+
+Specify a configuration pragma file
+(the equal sign is optional)
+(@ref{63,,The Configuration Pragmas Files}).
+@end table
+
+@geindex -gnateC (gcc)
+
+
+@table @asis
+
+@item @code{-gnateC}
+
+Generate CodePeer messages in a compiler-like format. This switch is only
+effective if @code{-gnatcC} is also specified and requires an installation
+of CodePeer.
+@end table
+
+@geindex -gnated (gcc)
+
+
+@table @asis
+
+@item @code{-gnated}
+
+Disable atomic synchronization
+@end table
+
+@geindex -gnateD (gcc)
+
+
+@table @asis
+
+@item @code{-gnateDsymbol[=`value']}
+
+Defines a symbol, associated with @code{value}, for preprocessing.
+(@ref{90,,Integrated Preprocessing}).
+@end table
+
+@geindex -gnateE (gcc)
+
+
+@table @asis
+
+@item @code{-gnateE}
+
+Generate extra information in exception messages. In particular, display
+extra column information and the value and range associated with index and
+range check failures, and extra column information for access checks.
+In cases where the compiler is able to determine at compile time that
+a check will fail, it gives a warning, and the extra information is not
+produced at run time.
+@end table
+
+@geindex -gnatef (gcc)
+
+
+@table @asis
+
+@item @code{-gnatef}
+
+Display full source path name in brief error messages and absolute paths in
+@code{-fdiagnostics-format=json}’s output.
+@end table
+
+@geindex -gnateF (gcc)
+
+
+@table @asis
+
+@item @code{-gnateF}
+
+Check for overflow on all floating-point operations, including those
+for unconstrained predefined types. See description of pragma
+@code{Check_Float_Overflow} in GNAT RM.
+@end table
+
+@geindex -gnateg (gcc)
+
+@code{-gnateg}
+@code{-gnatceg}
+
+@quotation
+
+The @code{-gnatc} switch must always be specified before this switch, e.g.
+@code{-gnatceg}. Generate a C header from the Ada input file. See
+@ref{b7,,Generating C Headers for Ada Specifications} for more
+information.
+@end quotation
+
+@geindex -gnateG (gcc)
+
+
+@table @asis
+
+@item @code{-gnateG}
+
+Save result of preprocessing in a text file.
+@end table
+
+@geindex -gnatei (gcc)
+
+
+@table @asis
+
+@item @code{-gnatei`nnn'}
+
+Set maximum number of instantiations during compilation of a single unit to
+@code{nnn}. This may be useful in increasing the default maximum of 8000 for
+the rare case when a single unit legitimately exceeds this limit.
+@end table
+
+@geindex -gnateI (gcc)
+
+
+@table @asis
+
+@item @code{-gnateI`nnn'}
+
+Indicates that the source is a multi-unit source and that the index of the
+unit to compile is @code{nnn}. @code{nnn} needs to be a positive number and need
+to be a valid index in the multi-unit source.
+@end table
+
+@geindex -gnatel (gcc)
+
+
+@table @asis
+
+@item @code{-gnatel}
+
+This switch can be used with the static elaboration model to issue info
+messages showing
+where implicit @code{pragma Elaborate} and @code{pragma Elaborate_All}
+are generated. This is useful in diagnosing elaboration circularities
+caused by these implicit pragmas when using the static elaboration
+model. See See the section in this guide on elaboration checking for
+further details. These messages are not generated by default, and are
+intended only for temporary use when debugging circularity problems.
+@end table
+
+@geindex -gnatel (gcc)
+
+
+@table @asis
+
+@item @code{-gnateL}
+
+This switch turns off the info messages about implicit elaboration pragmas.
+@end table
+
+@geindex -gnatem (gcc)
+
+
+@table @asis
+
+@item @code{-gnatem=`path'}
+
+Specify a mapping file
+(the equal sign is optional)
+(@ref{e8,,Units to Sources Mapping Files}).
+@end table
+
+@geindex -gnatep (gcc)
+
+
+@table @asis
+
+@item @code{-gnatep=`file'}
+
+Specify a preprocessing data file
+(the equal sign is optional)
+(@ref{90,,Integrated Preprocessing}).
+@end table
+
+@geindex -gnateP (gcc)
+
+
+@table @asis
+
+@item @code{-gnateP}
+
+Turn categorization dependency errors into warnings.
+Ada requires that units that WITH one another have compatible categories, for
+example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
+these errors become warnings (which can be ignored, or suppressed in the usual
+manner). This can be useful in some specialized circumstances such as the
+temporary use of special test software.
+@end table
+
+@geindex -gnateS (gcc)
+
+
+@table @asis
+
+@item @code{-gnateS}
+
+Synonym of @code{-fdump-scos}, kept for backwards compatibility.
+@end table
+
+@geindex -gnatet=file (gcc)
+
+
+@table @asis
+
+@item @code{-gnatet=`path'}
+
+Generate target dependent information. The format of the output file is
+described in the section about switch @code{-gnateT}.
+@end table
+
+@geindex -gnateT (gcc)
+
+
+@table @asis
+
+@item @code{-gnateT=`path'}
+
+Read target dependent information, such as endianness or sizes and alignments
+of base type. If this switch is passed, the default target dependent
+information of the compiler is replaced by the one read from the input file.
+This is used by tools other than the compiler, e.g. to do
+semantic analysis of programs that will run on some other target than
+the machine on which the tool is run.
+
+The following target dependent values should be defined,
+where @code{Nat} denotes a natural integer value, @code{Pos} denotes a
+positive integer value, and fields marked with a question mark are
+boolean fields, where a value of 0 is False, and a value of 1 is True:
+
+@example
+Bits_BE : Nat; -- Bits stored big-endian?
+Bits_Per_Unit : Pos; -- Bits in a storage unit
+Bits_Per_Word : Pos; -- Bits in a word
+Bytes_BE : Nat; -- Bytes stored big-endian?
+Char_Size : Pos; -- Standard.Character'Size
+Double_Float_Alignment : Nat; -- Alignment of double float
+Double_Scalar_Alignment : Nat; -- Alignment of double length scalar
+Double_Size : Pos; -- Standard.Long_Float'Size
+Float_Size : Pos; -- Standard.Float'Size
+Float_Words_BE : Nat; -- Float words stored big-endian?
+Int_Size : Pos; -- Standard.Integer'Size
+Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size
+Long_Long_Long_Size : Pos; -- Standard.Long_Long_Long_Integer'Size
+Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size
+Long_Size : Pos; -- Standard.Long_Integer'Size
+Maximum_Alignment : Pos; -- Maximum permitted alignment
+Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field
+Pointer_Size : Pos; -- System.Address'Size
+Short_Enums : Nat; -- Foreign enums use short size?
+Short_Size : Pos; -- Standard.Short_Integer'Size
+Strict_Alignment : Nat; -- Strict alignment?
+System_Allocator_Alignment : Nat; -- Alignment for malloc calls
+Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size
+Words_BE : Nat; -- Words stored big-endian?
+@end example
+
+@code{Bits_Per_Unit} is the number of bits in a storage unit, the equivalent of
+GCC macro @code{BITS_PER_UNIT} documented as follows: @cite{Define this macro to be the number of bits in an addressable storage unit (byte); normally 8.}
+
+@code{Bits_Per_Word} is the number of bits in a machine word, the equivalent of
+GCC macro @code{BITS_PER_WORD} documented as follows: @cite{Number of bits in a word; normally 32.}
+
+@code{Double_Float_Alignment}, if not zero, is the maximum alignment that the
+compiler can choose by default for a 64-bit floating-point type or object.
+
+@code{Double_Scalar_Alignment}, if not zero, is the maximum alignment that the
+compiler can choose by default for a 64-bit or larger scalar type or object.
+
+@code{Maximum_Alignment} is the maximum alignment that the compiler can choose
+by default for a type or object, which is also the maximum alignment that can
+be specified in GNAT. It is computed for GCC backends as @code{BIGGEST_ALIGNMENT
+/ BITS_PER_UNIT} where GCC macro @code{BIGGEST_ALIGNMENT} is documented as
+follows: @cite{Biggest alignment that any data type can require on this machine@comma{} in bits.}
+
+@code{Max_Unaligned_Field} is the maximum size for unaligned bit field, which is
+64 for the majority of GCC targets (but can be different on some targets).
+
+@code{Strict_Alignment} is the equivalent of GCC macro @code{STRICT_ALIGNMENT}
+documented as follows: @cite{Define this macro to be the value 1 if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case@comma{} define this macro as 0.}
+
+@code{System_Allocator_Alignment} is the guaranteed alignment of data returned
+by calls to @code{malloc}.
+
+The format of the input file is as follows. First come the values of
+the variables defined above, with one line per value:
+
+@example
+name value
+@end example
+
+where @code{name} is the name of the parameter, spelled out in full,
+and cased as in the above list, and @code{value} is an unsigned decimal
+integer. Two or more blanks separates the name from the value.
+
+All the variables must be present, in alphabetical order (i.e. the
+same order as the list above).
+
+Then there is a blank line to separate the two parts of the file. Then
+come the lines showing the floating-point types to be registered, with
+one line per registered mode:
+
+@example
+name digs float_rep size alignment
+@end example
+
+where @code{name} is the string name of the type (which can have
+single spaces embedded in the name, e.g. long double), @code{digs} is
+the number of digits for the floating-point type, @code{float_rep} is
+the float representation (I for IEEE-754-Binary, which is
+the only one supported at this time),
+@code{size} is the size in bits, @code{alignment} is the
+alignment in bits. The name is followed by at least two blanks, fields
+are separated by at least one blank, and a LF character immediately
+follows the alignment field.
+
+Here is an example of a target parameterization file:
+
+@example
+Bits_BE 0
+Bits_Per_Unit 8
+Bits_Per_Word 64
+Bytes_BE 0
+Char_Size 8
+Double_Float_Alignment 0
+Double_Scalar_Alignment 0
+Double_Size 64
+Float_Size 32
+Float_Words_BE 0
+Int_Size 64
+Long_Double_Size 128
+Long_Long_Long_Size 128
+Long_Long_Size 64
+Long_Size 64
+Maximum_Alignment 16
+Max_Unaligned_Field 64
+Pointer_Size 64
+Short_Size 16
+Strict_Alignment 0
+System_Allocator_Alignment 16
+Wchar_T_Size 32
+Words_BE 0
+
+float 15 I 64 64
+double 15 I 64 64
+long double 18 I 80 128
+TF 33 I 128 128
+@end example
+@end table
+
+@geindex -gnateu (gcc)
+
+
+@table @asis
+
+@item @code{-gnateu}
+
+Ignore unrecognized validity, warning, and style switches that
+appear after this switch is given. This may be useful when
+compiling sources developed on a later version of the compiler
+with an earlier version. Of course the earlier version must
+support this switch.
+@end table
+
+@geindex -gnateV (gcc)
+
+
+@table @asis
+
+@item @code{-gnateV}
+
+Check that all actual parameters of a subprogram call are valid according to
+the rules of validity checking (@ref{e7,,Validity Checking}).
+@end table
+
+@geindex -gnateY (gcc)
+
+
+@table @asis
+
+@item @code{-gnateY}
+
+Ignore all STYLE_CHECKS pragmas. Full legality checks
+are still carried out, but the pragmas have no effect
+on what style checks are active. This allows all style
+checking options to be controlled from the command line.
+@end table
+
+@geindex -gnatE (gcc)
+
+
+@table @asis
+
+@item @code{-gnatE}
+
+Dynamic elaboration checking mode enabled. For further details see
+@ref{f,,Elaboration Order Handling in GNAT}.
+@end table
+
+@geindex -gnatf (gcc)
+
+
+@table @asis
+
+@item @code{-gnatf}
+
+Full errors. Multiple errors per line, all undefined references, do not
+attempt to suppress cascaded errors.
+@end table
+
+@geindex -gnatF (gcc)
+
+
+@table @asis
+
+@item @code{-gnatF}
+
+Externals names are folded to all uppercase.
+@end table
+
+@geindex -gnatg (gcc)
+
+
+@table @asis
+
+@item @code{-gnatg}
+
+Internal GNAT implementation mode. This should not be used for applications
+programs, it is intended only for use by the compiler and its run-time
+library. For documentation, see the GNAT sources. Note that @code{-gnatg}
+implies @code{-gnatw.ge} and @code{-gnatyg} so that all standard
+warnings and all standard style options are turned on. All warnings and style
+messages are treated as errors.
+@end table
+
+@geindex -gnatG[nn] (gcc)
+
+
+@table @asis
+
+@item @code{-gnatG=nn}
+
+List generated expanded code in source form.
+@end table
+
+@geindex -gnath (gcc)
+
+
+@table @asis
+
+@item @code{-gnath}
+
+Output usage information. The output is written to @code{stdout}.
+@end table
+
+@geindex -gnatH (gcc)
+
+
+@table @asis
+
+@item @code{-gnatH}
+
+Legacy elaboration-checking mode enabled. When this switch is in effect,
+the pre-18.x access-before-elaboration model becomes the de facto model.
+For further details see @ref{f,,Elaboration Order Handling in GNAT}.
+@end table
+
+@geindex -gnati (gcc)
+
+
+@table @asis
+
+@item @code{-gnati`c'}
+
+Identifier character set (@code{c} = 1/2/3/4/5/9/p/8/f/n/w).
+For details of the possible selections for @code{c},
+see @ref{31,,Character Set Control}.
+@end table
+
+@geindex -gnatI (gcc)
+
+
+@table @asis
+
+@item @code{-gnatI}
+
+Ignore representation clauses. When this switch is used,
+representation clauses are treated as comments. This is useful
+when initially porting code where you want to ignore rep clause
+problems, and also for compiling foreign code (particularly
+for use with ASIS). The representation clauses that are ignored
+are: enumeration_representation_clause, record_representation_clause,
+and attribute_definition_clause for the following attributes:
+Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
+Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
+and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
+Note that this option should be used only for compiling – the
+code is likely to malfunction at run time.
+@end table
+
+@geindex -gnatjnn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatj`nn'}
+
+Reformat error messages to fit on @code{nn} character lines
+@end table
+
+@geindex -gnatJ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatJ}
+
+Permissive elaboration-checking mode enabled. When this switch is in effect,
+the post-18.x access-before-elaboration model ignores potential issues with:
+
+
+@itemize -
+
+@item
+Accept statements
+
+@item
+Activations of tasks defined in instances
+
+@item
+Assertion pragmas
+
+@item
+Calls from within an instance to its enclosing context
+
+@item
+Calls through generic formal parameters
+
+@item
+Calls to subprograms defined in instances
+
+@item
+Entry calls
+
+@item
+Indirect calls using ‘Access
+
+@item
+Requeue statements
+
+@item
+Select statements
+
+@item
+Synchronous task suspension
+@end itemize
+
+and does not emit compile-time diagnostics or run-time checks. For further
+details see @ref{f,,Elaboration Order Handling in GNAT}.
+@end table
+
+@geindex -gnatk (gcc)
+
+
+@table @asis
+
+@item @code{-gnatk=`n'}
+
+Limit file names to @code{n} (1-999) characters (@code{k} = krunch).
+@end table
+
+@geindex -gnatl (gcc)
+
+
+@table @asis
+
+@item @code{-gnatl}
+
+Output full source listing with embedded error messages.
+@end table
+
+@geindex -gnatL (gcc)
+
+
+@table @asis
+
+@item @code{-gnatL}
+
+Used in conjunction with -gnatG or -gnatD to intersperse original
+source lines (as comment lines with line numbers) in the expanded
+source output.
+@end table
+
+@geindex -gnatm (gcc)
+
+
+@table @asis
+
+@item @code{-gnatm=`n'}
+
+Limit number of detected error or warning messages to @code{n}
+where @code{n} is in the range 1..999999. The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. The equal sign here is optional. A value of zero
+means that no limit applies.
+@end table
+
+@geindex -gnatn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatn[12]}
+
+Activate inlining across units for subprograms for which pragma @code{Inline}
+is specified. This inlining is performed by the GCC back-end. An optional
+digit sets the inlining level: 1 for moderate inlining across units
+or 2 for full inlining across units. If no inlining level is specified,
+the compiler will pick it based on the optimization level.
+@end table
+
+@geindex -gnatN (gcc)
+
+
+@table @asis
+
+@item @code{-gnatN}
+
+Activate front end inlining for subprograms for which
+pragma @code{Inline} is specified. This inlining is performed
+by the front end and will be visible in the
+@code{-gnatG} output.
+
+When using a gcc-based back end, then the use of
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
+@end table
+
+@geindex -gnato0 (gcc)
+
+
+@table @asis
+
+@item @code{-gnato0}
+
+Suppresses overflow checking. This causes the behavior of the compiler to
+match the default for older versions where overflow checking was suppressed
+by default. This is equivalent to having
+@code{pragma Suppress (Overflow_Check)} in a configuration pragma file.
+@end table
+
+@geindex -gnato?? (gcc)
+
+
+@table @asis
+
+@item @code{-gnato??}
+
+Set default mode for handling generation of code to avoid intermediate
+arithmetic overflow. Here @code{??} is two digits, a
+single digit, or nothing. Each digit is one of the digits @code{1}
+through @code{3}:
+
+
+@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+Digit
+
+@tab
+
+Interpretation
+
+@item
+
+`1'
+
+@tab
+
+All intermediate overflows checked against base type (@code{STRICT})
+
+@item
+
+`2'
+
+@tab
+
+Minimize intermediate overflows (@code{MINIMIZED})
+
+@item
+
+`3'
+
+@tab
+
+Eliminate intermediate overflows (@code{ELIMINATED})
+
+@end multitable
+
+
+If only one digit appears, then it applies to all
+cases; if two digits are given, then the first applies outside
+assertions, pre/postconditions, and type invariants, and the second
+applies within assertions, pre/postconditions, and type invariants.
+
+If no digits follow the @code{-gnato}, then it is equivalent to
+@code{-gnato11},
+causing all intermediate overflows to be handled in strict
+mode.
+
+This switch also causes arithmetic overflow checking to be performed
+(as though @code{pragma Unsuppress (Overflow_Check)} had been specified).
+
+The default if no option @code{-gnato} is given is that overflow handling
+is in @code{STRICT} mode (computations done using the base type), and that
+overflow checking is enabled.
+
+Note that division by zero is a separate check that is not
+controlled by this switch (divide-by-zero checking is on by default).
+
+See also @ref{e9,,Specifying the Desired Mode}.
+@end table
+
+@geindex -gnatp (gcc)
+
+
+@table @asis
+
+@item @code{-gnatp}
+
+Suppress all checks. See @ref{ea,,Run-Time Checks} for details. This switch
+has no effect if cancelled by a subsequent @code{-gnat-p} switch.
+@end table
+
+@geindex -gnat-p (gcc)
+
+
+@table @asis
+
+@item @code{-gnat-p}
+
+Cancel effect of previous @code{-gnatp} switch.
+@end table
+
+@geindex -gnatq (gcc)
+
+
+@table @asis
+
+@item @code{-gnatq}
+
+Don’t quit. Try semantics, even if parse errors.
+@end table
+
+@geindex -gnatQ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatQ}
+
+Don’t quit. Generate @code{ALI} and tree files even if illegalities.
+Note that code generation is still suppressed in the presence of any
+errors, so even with @code{-gnatQ} no object file is generated.
+@end table
+
+@geindex -gnatr (gcc)
+
+
+@table @asis
+
+@item @code{-gnatr}
+
+Treat pragma Restrictions as Restriction_Warnings.
+@end table
+
+@geindex -gnatR (gcc)
+
+
+@table @asis
+
+@item @code{-gnatR[0|1|2|3|4][e][j][m][s]}
+
+Output representation information for declared types, objects and
+subprograms. Note that this switch is not allowed if a previous
+@code{-gnatD} switch has been given, since these two switches
+are not compatible.
+@end table
+
+@geindex -gnats (gcc)
+
+
+@table @asis
+
+@item @code{-gnats}
+
+Syntax check only.
+@end table
+
+@geindex -gnatS (gcc)
+
+
+@table @asis
+
+@item @code{-gnatS}
+
+Print package Standard.
+@end table
+
+@geindex -gnatT (gcc)
+
+
+@table @asis
+
+@item @code{-gnatT`nnn'}
+
+All compiler tables start at @code{nnn} times usual starting size.
+@end table
+
+@geindex -gnatu (gcc)
+
+
+@table @asis
+
+@item @code{-gnatu}
+
+List units for this compilation.
+@end table
+
+@geindex -gnatU (gcc)
+
+
+@table @asis
+
+@item @code{-gnatU}
+
+Tag all error messages with the unique string ‘error:’
+@end table
+
+@geindex -gnatv (gcc)
+
+
+@table @asis
+
+@item @code{-gnatv}
+
+Verbose mode. Full error output with source lines to @code{stdout}.
+@end table
+
+@geindex -gnatV (gcc)
+
+
+@table @asis
+
+@item @code{-gnatV}
+
+Control level of validity checking (@ref{e7,,Validity Checking}).
+@end table
+
+@geindex -gnatw (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw`xxx'}
+
+Warning mode where
+@code{xxx} is a string of option letters that denotes
+the exact warnings that
+are enabled or disabled (@ref{eb,,Warning Message Control}).
+@end table
+
+@geindex -gnatW (gcc)
+
+
+@table @asis
+
+@item @code{-gnatW`e'}
+
+Wide character encoding method
+(@code{e}=n/h/u/s/e/8).
+@end table
+
+@geindex -gnatx (gcc)
+
+
+@table @asis
+
+@item @code{-gnatx}
+
+Suppress generation of cross-reference information.
+@end table
+
+@geindex -gnatX (gcc)
+
+
+@table @asis
+
+@item @code{-gnatX}
+
+Enable core GNAT implementation extensions and latest Ada version.
+@end table
+
+@geindex -gnatX0 (gcc)
+
+
+@table @asis
+
+@item @code{-gnatX0}
+
+Enable all GNAT implementation extensions and latest Ada version.
+@end table
+
+@geindex -gnaty (gcc)
+
+
+@table @asis
+
+@item @code{-gnaty}
+
+Enable built-in style checks (@ref{ec,,Style Checking}).
+@end table
+
+@geindex -gnatz (gcc)
+
+
+@table @asis
+
+@item @code{-gnatz`m'}
+
+Distribution stub generation and compilation
+(@code{m}=r/c for receiver/caller stubs).
+@end table
+
+@geindex -I (gcc)
+
+
+@table @asis
+
+@item @code{-I`dir'}
+
+@geindex RTL
+
+Direct GNAT to search the @code{dir} directory for source files needed by
+the current compilation
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
+@end table
+
+@geindex -I- (gcc)
+
+
+@table @asis
+
+@item @code{-I-}
+
+@geindex RTL
+
+Except for the source file named in the command line, do not look for source
+files in the directory containing the source file named in the command line
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
+@end table
+
+@geindex -o (gcc)
+
+
+@table @asis
+
+@item @code{-o `file'}
+
+This switch is used in @code{gcc} to redirect the generated object file
+and its associated ALI file. Beware of this switch with GNAT, because it may
+cause the object file and ALI file to have different names which in turn
+may confuse the binder and the linker.
+@end table
+
+@geindex -nostdinc (gcc)
+
+
+@table @asis
+
+@item @code{-nostdinc}
+
+Inhibit the search of the default location for the GNAT Run Time
+Library (RTL) source files.
+@end table
+
+@geindex -nostdlib (gcc)
+
+
+@table @asis
+
+@item @code{-nostdlib}
+
+Inhibit the search of the default location for the GNAT Run Time
+Library (RTL) ALI files.
+@end table
+
+@geindex -O (gcc)
+
+
+@table @asis
+
+@item @code{-O[`n']}
+
+@code{n} controls the optimization level:
+
+
+@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+`n'
+
+@tab
+
+Effect
+
+@item
+
+`0'
+
+@tab
+
+No optimization, the default setting if no @code{-O} appears
+
+@item
+
+`1'
+
+@tab
+
+Normal optimization, the default if you specify @code{-O} without an
+operand. A good compromise between code quality and compilation
+time.
+
+@item
+
+`2'
+
+@tab
+
+Extensive optimization, may improve execution time, possibly at
+the cost of substantially increased compilation time.
+
+@item
+
+`3'
+
+@tab
+
+Same as @code{-O2}, and also includes inline expansion for small
+subprograms in the same unit.
+
+@item
+
+`s'
+
+@tab
+
+Optimize space usage
+
+@end multitable
+
+
+See also @ref{ed,,Optimization Levels}.
+@end table
+
+@geindex -pass-exit-codes (gcc)
+
+
+@table @asis
+
+@item @code{-pass-exit-codes}
+
+Catch exit codes from the compiler and use the most meaningful as
+exit status.
+@end table
+
+@geindex --RTS (gcc)
+
+
+@table @asis
+
+@item @code{--RTS=`rts-path'}
+
+Specifies the default location of the run-time library. Same meaning as the
+equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}).
+@end table
+
+@geindex -S (gcc)
+
+
+@table @asis
+
+@item @code{-S}
+
+Used in place of @code{-c} to
+cause the assembler source file to be
+generated, using @code{.s} as the extension,
+instead of the object file.
+This may be useful if you need to examine the generated assembly code.
+@end table
+
+@geindex -fverbose-asm (gcc)
+
+
+@table @asis
+
+@item @code{-fverbose-asm}
+
+Used in conjunction with @code{-S}
+to cause the generated assembly code file to be annotated with variable
+names, making it significantly easier to follow.
+@end table
+
+@geindex -v (gcc)
+
+
+@table @asis
+
+@item @code{-v}
+
+Show commands generated by the @code{gcc} driver. Normally used only for
+debugging purposes or if you need to be sure what version of the
+compiler you are executing.
+@end table
+
+@geindex -V (gcc)
+
+
+@table @asis
+
+@item @code{-V `ver'}
+
+Execute @code{ver} version of the compiler. This is the @code{gcc}
+version, not the GNAT version.
+@end table
+
+@geindex -w (gcc)
+
+
+@table @asis
+
+@item @code{-w}
+
+Turn off warnings generated by the back end of the compiler. Use of
+this switch also causes the default for front end warnings to be set
+to suppress (as though @code{-gnatws} had appeared at the start of
+the options).
+@end table
+
+@geindex Combining GNAT switches
+
+You may combine a sequence of GNAT switches into a single switch. For
+example, the combined switch
+
+@quotation
+
+@example
+-gnatofi3
+@end example
+@end quotation
+
+is equivalent to specifying the following sequence of switches:
+
+@quotation
+
+@example
+-gnato -gnatf -gnati3
+@end example
+@end quotation
+
+The following restrictions apply to the combination of switches
+in this manner:
+
+
+@itemize *
+
+@item
+The switch @code{-gnatc} if combined with other switches must come
+first in the string.
+
+@item
+The switch @code{-gnats} if combined with other switches must come
+first in the string.
+
+@item
+The switches
+@code{-gnatzc} and @code{-gnatzr} may not be combined with any other
+switches, and only one of them may appear in the command line.
+
+@item
+The switch @code{-gnat-p} may not be combined with any other switch.
+
+@item
+Once a ‘y’ appears in the string (that is a use of the @code{-gnaty}
+switch), then all further characters in the switch are interpreted
+as style modifiers (see description of @code{-gnaty}).
+
+@item
+Once a ‘d’ appears in the string (that is a use of the @code{-gnatd}
+switch), then all further characters in the switch are interpreted
+as debug flags (see description of @code{-gnatd}).
+
+@item
+Once a ‘w’ appears in the string (that is a use of the @code{-gnatw}
+switch), then all further characters in the switch are interpreted
+as warning mode modifiers (see description of @code{-gnatw}).
+
+@item
+Once a ‘V’ appears in the string (that is a use of the @code{-gnatV}
+switch), then all further characters in the switch are interpreted
+as validity checking options (@ref{e7,,Validity Checking}).
+
+@item
+Option ‘em’, ‘ec’, ‘ep’, ‘l=’ and ‘R’ must be the last options in
+a combined list of options.
+@end itemize
+
+@node Output and Error Message Control,Warning Message Control,Alphabetical List of All Switches,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id14}@anchor{ee}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{ef}
+@subsection Output and Error Message Control
+
+
+@geindex stderr
+
+The standard default format for error messages is called ‘brief format’.
+Brief format messages are written to @code{stderr} (the standard error
+file) and have the following form:
+
+@example
+e.adb:3:04: Incorrect spelling of keyword "function"
+e.adb:4:20: ";" should be "is"
+@end example
+
+The first integer after the file name is the line number in the file,
+and the second integer is the column number within the line.
+@code{GNAT Studio} can parse the error messages
+and point to the referenced character.
+The following switches provide control over the error message
+format:
+
+@geindex -gnatv (gcc)
+
+
+@table @asis
+
+@item @code{-gnatv}
+
+The @code{v} stands for verbose.
+The effect of this setting is to write long-format error
+messages to @code{stdout} (the standard output file).
+The same program compiled with the
+@code{-gnatv} switch would generate:
+
+@example
+3. funcion X (Q : Integer)
+ |
+>>> Incorrect spelling of keyword "function"
+4. return Integer;
+ |
+>>> ";" should be "is"
+@end example
+
+The vertical bar indicates the location of the error, and the @code{>>>}
+prefix can be used to search for error messages. When this switch is
+used the only source lines output are those with errors.
+@end table
+
+@geindex -gnatl (gcc)
+
+
+@table @asis
+
+@item @code{-gnatl}
+
+The @code{l} stands for list.
+This switch causes a full listing of
+the file to be generated. In the case where a body is
+compiled, the corresponding spec is also listed, along
+with any subunits. Typical output from compiling a package
+body @code{p.adb} might look like:
+
+@example
+Compiling: p.adb
+
+ 1. package body p is
+ 2. procedure a;
+ 3. procedure a is separate;
+ 4. begin
+ 5. null
+ |
+ >>> missing ";"
+
+ 6. end;
+
+Compiling: p.ads
+
+ 1. package p is
+ 2. pragma Elaborate_Body
+ |
+ >>> missing ";"
+
+ 3. end p;
+
+Compiling: p-a.adb
+
+ 1. separate p
+ |
+ >>> missing "("
+
+ 2. procedure a is
+ 3. begin
+ 4. null
+ |
+ >>> missing ";"
+
+ 5. end;
+@end example
+
+When you specify the @code{-gnatv} or @code{-gnatl} switches and
+standard output is redirected, a brief summary is written to
+@code{stderr} (standard error) giving the number of error messages and
+warning messages generated.
+@end table
+
+@geindex -gnatl=fname (gcc)
+
+
+@table @asis
+
+@item @code{-gnatl=`fname'}
+
+This has the same effect as @code{-gnatl} except that the output is
+written to a file instead of to standard output. If the given name
+@code{fname} does not start with a period, then it is the full name
+of the file to be written. If @code{fname} is an extension, it is
+appended to the name of the file being compiled. For example, if
+file @code{xyz.adb} is compiled with @code{-gnatl=.lst},
+then the output is written to file xyz.adb.lst.
+@end table
+
+@geindex -gnatU (gcc)
+
+
+@table @asis
+
+@item @code{-gnatU}
+
+This switch forces all error messages to be preceded by the unique
+string ‘error:’. This means that error messages take a few more
+characters in space, but allows easy searching for and identification
+of error messages.
+@end table
+
+@geindex -gnatb (gcc)
+
+
+@table @asis
+
+@item @code{-gnatb}
+
+The @code{b} stands for brief.
+This switch causes GNAT to generate the
+brief format error messages to @code{stderr} (the standard error
+file) as well as the verbose
+format message or full listing (which as usual is written to
+@code{stdout}, the standard output file).
+@end table
+
+@geindex -gnatm (gcc)
+
+
+@table @asis
+
+@item @code{-gnatm=`n'}
+
+The @code{m} stands for maximum.
+@code{n} is a decimal integer in the
+range of 1 to 999999 and limits the number of error or warning
+messages to be generated. For example, using
+@code{-gnatm2} might yield
+
+@example
+e.adb:3:04: Incorrect spelling of keyword "function"
+e.adb:5:35: missing ".."
+fatal error: maximum number of errors detected
+compilation abandoned
+@end example
+
+The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. A value of zero means that no limit applies.
+
+Note that the equal sign is optional, so the switches
+@code{-gnatm2} and @code{-gnatm=2} are equivalent.
+@end table
+
+@geindex -gnatf (gcc)
+
+
+@table @asis
+
+@item @code{-gnatf}
+
+@geindex Error messages
+@geindex suppressing
+
+The @code{f} stands for full.
+Normally, the compiler suppresses error messages that are likely to be
+redundant. This switch causes all error
+messages to be generated. In particular, in the case of
+references to undefined variables. If a given variable is referenced
+several times, the normal format of messages is
+
+@example
+e.adb:7:07: "V" is undefined (more references follow)
+@end example
+
+where the parenthetical comment warns that there are additional
+references to the variable @code{V}. Compiling the same program with the
+@code{-gnatf} switch yields
+
+@example
+e.adb:7:07: "V" is undefined
+e.adb:8:07: "V" is undefined
+e.adb:8:12: "V" is undefined
+e.adb:8:16: "V" is undefined
+e.adb:9:07: "V" is undefined
+e.adb:9:12: "V" is undefined
+@end example
+
+The @code{-gnatf} switch also generates additional information for
+some error messages. Some examples are:
+
+
+@itemize *
+
+@item
+Details on possibly non-portable unchecked conversion
+
+@item
+List possible interpretations for ambiguous calls
+
+@item
+Additional details on incorrect parameters
+@end itemize
+@end table
+
+@geindex -gnatjnn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatjnn}
+
+In normal operation mode (or if @code{-gnatj0} is used), then error messages
+with continuation lines are treated as though the continuation lines were
+separate messages (and so a warning with two continuation lines counts as
+three warnings, and is listed as three separate messages).
+
+If the @code{-gnatjnn} switch is used with a positive value for nn, then
+messages are output in a different manner. A message and all its continuation
+lines are treated as a unit, and count as only one warning or message in the
+statistics totals. Furthermore, the message is reformatted so that no line
+is longer than nn characters.
+@end table
+
+@geindex -gnatq (gcc)
+
+
+@table @asis
+
+@item @code{-gnatq}
+
+The @code{q} stands for quit (really ‘don’t quit’).
+In normal operation mode, the compiler first parses the program and
+determines if there are any syntax errors. If there are, appropriate
+error messages are generated and compilation is immediately terminated.
+This switch tells
+GNAT to continue with semantic analysis even if syntax errors have been
+found. This may enable the detection of more errors in a single run. On
+the other hand, the semantic analyzer is more likely to encounter some
+internal fatal error when given a syntactically invalid tree.
+@end table
+
+@geindex -gnatQ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatQ}
+
+In normal operation mode, the @code{ALI} file is not generated if any
+illegalities are detected in the program. The use of @code{-gnatQ} forces
+generation of the @code{ALI} file. This file is marked as being in
+error, so it cannot be used for binding purposes, but it does contain
+reasonably complete cross-reference information, and thus may be useful
+for use by tools (e.g., semantic browsing tools or integrated development
+environments) that are driven from the @code{ALI} file. This switch
+implies @code{-gnatq}, since the semantic phase must be run to get a
+meaningful ALI file.
+
+When @code{-gnatQ} is used and the generated @code{ALI} file is marked as
+being in error, @code{gnatmake} will attempt to recompile the source when it
+finds such an @code{ALI} file, including with switch @code{-gnatc}.
+
+Note that @code{-gnatQ} has no effect if @code{-gnats} is specified,
+since ALI files are never generated if @code{-gnats} is set.
+@end table
+
+@node Warning Message Control,Debugging and Assertion Control,Output and Error Message Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{f0}@anchor{gnat_ugn/building_executable_programs_with_gnat warning-message-control}@anchor{eb}
+@subsection Warning Message Control
+
+
+@geindex Warning messages
+
+In addition to error messages, which correspond to illegalities as defined
+in the Ada Reference Manual, the compiler detects two kinds of warning
+situations.
+
+First, the compiler considers some constructs suspicious and generates a
+warning message to alert you to a possible error. Second, if the
+compiler detects a situation that is sure to raise an exception at
+run time, it generates a warning message. The following shows an example
+of warning messages:
+
+@example
+e.adb:4:24: warning: creation of object may raise Storage_Error
+e.adb:10:17: warning: static value out of range
+e.adb:10:17: warning: "Constraint_Error" will be raised at run time
+@end example
+
+GNAT considers a large number of situations as appropriate
+for the generation of warning messages. As always, warnings are not
+definite indications of errors. For example, if you do an out-of-range
+assignment with the deliberate intention of raising a
+@code{Constraint_Error} exception, then the warning that may be
+issued does not indicate an error. Some of the situations for which GNAT
+issues warnings (at least some of the time) are given in the following
+list. This list is not complete, and new warnings are often added to
+subsequent versions of GNAT. The list is intended to give a general idea
+of the kinds of warnings that are generated.
+
+
+@itemize *
+
+@item
+Possible infinitely recursive calls
+
+@item
+Out-of-range values being assigned
+
+@item
+Possible order of elaboration problems
+
+@item
+Size not a multiple of alignment for a record type
+
+@item
+Assertions (pragma Assert) that are sure to fail
+
+@item
+Unreachable code
+
+@item
+Address clauses with possibly unaligned values, or where an attempt is
+made to overlay a smaller variable with a larger one.
+
+@item
+Fixed-point type declarations with a null range
+
+@item
+Direct_IO or Sequential_IO instantiated with a type that has access values
+
+@item
+Variables that are never assigned a value
+
+@item
+Variables that are referenced before being initialized
+
+@item
+Task entries with no corresponding @code{accept} statement
+
+@item
+Duplicate accepts for the same task entry in a @code{select}
+
+@item
+Objects that take too much storage
+
+@item
+Unchecked conversion between types of differing sizes
+
+@item
+Missing @code{return} statement along some execution path in a function
+
+@item
+Incorrect (unrecognized) pragmas
+
+@item
+Incorrect external names
+
+@item
+Allocation from empty storage pool
+
+@item
+Potentially blocking operation in protected type
+
+@item
+Suspicious parenthesization of expressions
+
+@item
+Mismatching bounds in an aggregate
+
+@item
+Attempt to return local value by reference
+
+@item
+Premature instantiation of a generic body
+
+@item
+Attempt to pack aliased components
+
+@item
+Out of bounds array subscripts
+
+@item
+Wrong length on string assignment
+
+@item
+Violations of style rules if style checking is enabled
+
+@item
+Unused `with' clauses
+
+@item
+@code{Bit_Order} usage that does not have any effect
+
+@item
+@code{Standard.Duration} used to resolve universal fixed expression
+
+@item
+Dereference of possibly null value
+
+@item
+Declaration that is likely to cause storage error
+
+@item
+Internal GNAT unit `with'ed by application unit
+
+@item
+Values known to be out of range at compile time
+
+@item
+Unreferenced or unmodified variables. Note that a special
+exemption applies to variables which contain any of the substrings
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED}, in any casing. Such variables
+are considered likely to be intentionally used in a situation where
+otherwise a warning would be given, so warnings of this kind are
+always suppressed for such variables.
+
+@item
+Address overlays that could clobber memory
+
+@item
+Unexpected initialization when address clause present
+
+@item
+Bad alignment for address clause
+
+@item
+Useless type conversions
+
+@item
+Redundant assignment statements and other redundant constructs
+
+@item
+Useless exception handlers
+
+@item
+Accidental hiding of name by child unit
+
+@item
+Access before elaboration detected at compile time
+
+@item
+A range in a @code{for} loop that is known to be null or might be null
+@end itemize
+
+The following section lists compiler switches that are available
+to control the handling of warning messages. It is also possible
+to exercise much finer control over what warnings are issued and
+suppressed using the GNAT pragma Warnings (see the description
+of the pragma in the @cite{GNAT_Reference_manual}).
+
+@geindex -gnatwa (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwa}
+
+`Activate most optional warnings.'
+
+This switch activates most optional warning messages. See the remaining list
+in this section for details on optional warning messages that can be
+individually controlled. The warnings that are not turned on by this
+switch are:
+
+
+@itemize *
+
+@item
+@code{-gnatwd} (implicit dereferencing)
+
+@item
+@code{-gnatw.d} (tag warnings with -gnatw switch)
+
+@item
+@code{-gnatwh} (hiding)
+
+@item
+@code{-gnatw.h} (holes in record layouts)
+
+@item
+@code{-gnatw.j} (late primitives of tagged types)
+
+@item
+@code{-gnatw.k} (redefinition of names in standard)
+
+@item
+@code{-gnatwl} (elaboration warnings)
+
+@item
+@code{-gnatw.l} (inherited aspects)
+
+@item
+@code{-gnatw.n} (atomic synchronization)
+
+@item
+@code{-gnatwo} (address clause overlay)
+
+@item
+@code{-gnatw.o} (values set by out parameters ignored)
+
+@item
+@code{-gnatw.q} (questionable layout of record types)
+
+@item
+@code{-gnatw_q} (ignored equality)
+
+@item
+@code{-gnatw_r} (out-of-order record representation clauses)
+
+@item
+@code{-gnatw.s} (overridden size clause)
+
+@item
+@code{-gnatwt} (tracking of deleted conditional code)
+
+@item
+@code{-gnatw.u} (unordered enumeration)
+
+@item
+@code{-gnatw.w} (use of Warnings Off)
+
+@item
+@code{-gnatw.y} (reasons for package needing body)
+@end itemize
+
+All other optional warnings are turned on.
+@end table
+
+@geindex -gnatwA (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwA}
+
+`Suppress all optional errors.'
+
+This switch suppresses all optional warning messages, see remaining list
+in this section for details on optional warning messages that can be
+individually controlled. Note that unlike switch @code{-gnatws}, the
+use of switch @code{-gnatwA} does not suppress warnings that are
+normally given unconditionally and cannot be individually controlled
+(for example, the warning about a missing exit path in a function).
+Also, again unlike switch @code{-gnatws}, warnings suppressed by
+the use of switch @code{-gnatwA} can be individually turned back
+on. For example the use of switch @code{-gnatwA} followed by
+switch @code{-gnatwd} will suppress all optional warnings except
+the warnings for implicit dereferencing.
+@end table
+
+@geindex -gnatw.a (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.a}
+
+`Activate warnings on failing assertions.'
+
+@geindex Assert failures
+
+This switch activates warnings for assertions where the compiler can tell at
+compile time that the assertion will fail. Note that this warning is given
+even if assertions are disabled. The default is that such warnings are
+generated.
+@end table
+
+@geindex -gnatw.A (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.A}
+
+`Suppress warnings on failing assertions.'
+
+@geindex Assert failures
+
+This switch suppresses warnings for assertions where the compiler can tell at
+compile time that the assertion will fail.
+@end table
+
+@geindex -gnatw_a
+
+
+@table @asis
+
+@item @code{-gnatw_a}
+
+`Activate warnings on anonymous allocators.'
+
+@geindex Anonymous allocators
+
+This switch activates warnings for allocators of anonymous access types,
+which can involve run-time accessibility checks and lead to unexpected
+accessibility violations. For more details on the rules involved, see
+RM 3.10.2 (14).
+@end table
+
+@geindex -gnatw_A
+
+
+@table @asis
+
+@item @code{-gnatw_A}
+
+`Supress warnings on anonymous allocators.'
+
+@geindex Anonymous allocators
+
+This switch suppresses warnings for anonymous access type allocators.
+@end table
+
+@geindex -gnatwb (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwb}
+
+`Activate warnings on bad fixed values.'
+
+@geindex Bad fixed values
+
+@geindex Fixed-point Small value
+
+@geindex Small value
+
+This switch activates warnings for static fixed-point expressions whose
+value is not an exact multiple of Small. Such values are implementation
+dependent, since an implementation is free to choose either of the multiples
+that surround the value. GNAT always chooses the closer one, but this is not
+required behavior, and it is better to specify a value that is an exact
+multiple, ensuring predictable execution. The default is that such warnings
+are not generated.
+@end table
+
+@geindex -gnatwB (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwB}
+
+`Suppress warnings on bad fixed values.'
+
+This switch suppresses warnings for static fixed-point expressions whose
+value is not an exact multiple of Small.
+@end table
+
+@geindex -gnatw.b (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.b}
+
+`Activate warnings on biased representation.'
+
+@geindex Biased representation
+
+This switch activates warnings when a size clause, value size clause, component
+clause, or component size clause forces the use of biased representation for an
+integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
+to represent 10/11). The default is that such warnings are generated.
+@end table
+
+@geindex -gnatwB (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.B}
+
+`Suppress warnings on biased representation.'
+
+This switch suppresses warnings for representation clauses that force the use
+of biased representation.
+@end table
+
+@geindex -gnatwc (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwc}
+
+`Activate warnings on conditionals.'
+
+@geindex Conditionals
+@geindex constant
+
+This switch activates warnings for conditional expressions used in
+tests that are known to be True or False at compile time. The default
+is that such warnings are not generated.
+Note that this warning does
+not get issued for the use of boolean constants whose
+values are known at compile time, since this is a standard technique
+for conditional compilation in Ada, and this would generate too many
+false positive warnings.
+
+This warning option also activates a special test for comparisons using
+the operators ‘>=’ and’ <=’.
+If the compiler can tell that only the equality condition is possible,
+then it will warn that the ‘>’ or ‘<’ part of the test
+is useless and that the operator could be replaced by ‘=’.
+An example would be comparing a @code{Natural} variable <= 0.
+
+This warning option also generates warnings if
+one or both tests is optimized away in a membership test for integer
+values if the result can be determined at compile time. Range tests on
+enumeration types are not included, since it is common for such tests
+to include an end point.
+
+This warning can also be turned on using @code{-gnatwa}.
+@end table
+
+@geindex -gnatwC (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwC}
+
+`Suppress warnings on conditionals.'
+
+This switch suppresses warnings for conditional expressions used in
+tests that are known to be True or False at compile time.
+@end table
+
+@geindex -gnatw.c (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.c}
+
+`Activate warnings on missing component clauses.'
+
+@geindex Component clause
+@geindex missing
+
+This switch activates warnings for record components where a record
+representation clause is present and has component clauses for the
+majority, but not all, of the components. A warning is given for each
+component for which no component clause is present.
+@end table
+
+@geindex -gnatw.C (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.C}
+
+`Suppress warnings on missing component clauses.'
+
+This switch suppresses warnings for record components that are
+missing a component clause in the situation described above.
+@end table
+
+@geindex -gnatw_c (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_c}
+
+`Activate warnings on unknown condition in Compile_Time_Warning.'
+
+@geindex Compile_Time_Warning
+
+@geindex Compile_Time_Error
+
+This switch activates warnings on a pragma Compile_Time_Warning
+or Compile_Time_Error whose condition has a value that is not
+known at compile time.
+The default is that such warnings are generated.
+@end table
+
+@geindex -gnatw_C (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_C}
+
+`Suppress warnings on unknown condition in Compile_Time_Warning.'
+
+This switch supresses warnings on a pragma Compile_Time_Warning
+or Compile_Time_Error whose condition has a value that is not
+known at compile time.
+@end table
+
+@geindex -gnatwd (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwd}
+
+`Activate warnings on implicit dereferencing.'
+
+If this switch is set, then the use of a prefix of an access type
+in an indexed component, slice, or selected component without an
+explicit @code{.all} will generate a warning. With this warning
+enabled, access checks occur only at points where an explicit
+@code{.all} appears in the source code (assuming no warnings are
+generated as a result of this switch). The default is that such
+warnings are not generated.
+@end table
+
+@geindex -gnatwD (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwD}
+
+`Suppress warnings on implicit dereferencing.'
+
+@geindex Implicit dereferencing
+
+@geindex Dereferencing
+@geindex implicit
+
+This switch suppresses warnings for implicit dereferences in
+indexed components, slices, and selected components.
+@end table
+
+@geindex -gnatw.d (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.d}
+
+`Activate tagging of warning and info messages.'
+
+If this switch is set, then warning messages are tagged, with one of the
+following strings:
+
+@quotation
+
+
+@itemize -
+
+@item
+`[-gnatw?]'
+Used to tag warnings controlled by the switch @code{-gnatwx} where x
+is a letter a-z.
+
+@item
+`[-gnatw.?]'
+Used to tag warnings controlled by the switch @code{-gnatw.x} where x
+is a letter a-z.
+
+@item
+`[-gnatel]'
+Used to tag elaboration information (info) messages generated when the
+static model of elaboration is used and the @code{-gnatel} switch is set.
+
+@item
+`[restriction warning]'
+Used to tag warning messages for restriction violations, activated by use
+of the pragma @code{Restriction_Warnings}.
+
+@item
+`[warning-as-error]'
+Used to tag warning messages that have been converted to error messages by
+use of the pragma Warning_As_Error. Note that such warnings are prefixed by
+the string “error: “ rather than “warning: “.
+
+@item
+`[enabled by default]'
+Used to tag all other warnings that are always given by default, unless
+warnings are completely suppressed using pragma `Warnings(Off)' or
+the switch @code{-gnatws}.
+@end itemize
+@end quotation
+@end table
+
+@geindex -gnatw.d (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.D}
+
+`Deactivate tagging of warning and info messages messages.'
+
+If this switch is set, then warning messages return to the default
+mode in which warnings and info messages are not tagged as described above for
+@code{-gnatw.d}.
+@end table
+
+@geindex -gnatwe (gcc)
+
+@geindex Warnings
+@geindex treat as error
+
+
+@table @asis
+
+@item @code{-gnatwe}
+
+`Treat warnings and style checks as errors.'
+
+This switch causes warning messages and style check messages to be
+treated as errors.
+The warning string still appears, but the warning messages are counted
+as errors, and prevent the generation of an object file. Note that this
+is the only -gnatw switch that affects the handling of style check messages.
+Note also that this switch has no effect on info (information) messages, which
+are not treated as errors if this switch is present.
+@end table
+
+@geindex -gnatw.e (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.e}
+
+`Activate every optional warning.'
+
+@geindex Warnings
+@geindex activate every optional warning
+
+This switch activates all optional warnings, including those which
+are not activated by @code{-gnatwa}. The use of this switch is not
+recommended for normal use. If you turn this switch on, it is almost
+certain that you will get large numbers of useless warnings. The
+warnings that are excluded from @code{-gnatwa} are typically highly
+specialized warnings that are suitable for use only in code that has
+been specifically designed according to specialized coding rules.
+@end table
+
+@geindex -gnatwE (gcc)
+
+@geindex Warnings
+@geindex treat as error
+
+
+@table @asis
+
+@item @code{-gnatwE}
+
+`Treat all run-time exception warnings as errors.'
+
+This switch causes warning messages regarding errors that will be raised
+during run-time execution to be treated as errors.
+@end table
+
+@geindex -gnatwf (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwf}
+
+`Activate warnings on unreferenced formals.'
+
+@geindex Formals
+@geindex unreferenced
+
+This switch causes a warning to be generated if a formal parameter
+is not referenced in the body of the subprogram. This warning can
+also be turned on using @code{-gnatwu}. The
+default is that these warnings are not generated.
+@end table
+
+@geindex -gnatwF (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwF}
+
+`Suppress warnings on unreferenced formals.'
+
+This switch suppresses warnings for unreferenced formal
+parameters. Note that the
+combination @code{-gnatwu} followed by @code{-gnatwF} has the
+effect of warning on unreferenced entities other than subprogram
+formals.
+@end table
+
+@geindex -gnatwg (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwg}
+
+`Activate warnings on unrecognized pragmas.'
+
+@geindex Pragmas
+@geindex unrecognized
+
+This switch causes a warning to be generated if an unrecognized
+pragma is encountered. Apart from issuing this warning, the
+pragma is ignored and has no effect. The default
+is that such warnings are issued (satisfying the Ada Reference
+Manual requirement that such warnings appear).
+@end table
+
+@geindex -gnatwG (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwG}
+
+`Suppress warnings on unrecognized pragmas.'
+
+This switch suppresses warnings for unrecognized pragmas.
+@end table
+
+@geindex -gnatw.g (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.g}
+
+`Warnings used for GNAT sources.'
+
+This switch sets the warning categories that are used by the standard
+GNAT style. Currently this is equivalent to
+@code{-gnatwAao.q.s.CI.V.X.Z}
+but more warnings may be added in the future without advanced notice.
+@end table
+
+@geindex -gnatwh (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwh}
+
+`Activate warnings on hiding.'
+
+@geindex Hiding of Declarations
+
+This switch activates warnings on hiding declarations that are considered
+potentially confusing. Not all cases of hiding cause warnings; for example an
+overriding declaration hides an implicit declaration, which is just normal
+code. The default is that warnings on hiding are not generated.
+@end table
+
+@geindex -gnatwH (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwH}
+
+`Suppress warnings on hiding.'
+
+This switch suppresses warnings on hiding declarations.
+@end table
+
+@geindex -gnatw.h (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.h}
+
+`Activate warnings on holes/gaps in records.'
+
+@geindex Record Representation (gaps)
+
+This switch activates warnings on component clauses in record
+representation clauses that leave holes (gaps) in the record layout.
+If this warning option is active, then record representation clauses
+should specify a contiguous layout, adding unused fill fields if needed.
+@end table
+
+@geindex -gnatw.H (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.H}
+
+`Suppress warnings on holes/gaps in records.'
+
+This switch suppresses warnings on component clauses in record
+representation clauses that leave holes (haps) in the record layout.
+@end table
+
+@geindex -gnatwi (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwi}
+
+`Activate warnings on implementation units.'
+
+This switch activates warnings for a `with' of an internal GNAT
+implementation unit, defined as any unit from the @code{Ada},
+@code{Interfaces}, @code{GNAT},
+or @code{System}
+hierarchies that is not
+documented in either the Ada Reference Manual or the GNAT
+Programmer’s Reference Manual. Such units are intended only
+for internal implementation purposes and should not be `with'ed
+by user programs. The default is that such warnings are generated
+@end table
+
+@geindex -gnatwI (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwI}
+
+`Disable warnings on implementation units.'
+
+This switch disables warnings for a `with' of an internal GNAT
+implementation unit.
+@end table
+
+@geindex -gnatw.i (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.i}
+
+`Activate warnings on overlapping actuals.'
+
+This switch enables a warning on statically detectable overlapping actuals in
+a subprogram call, when one of the actuals is an in-out parameter, and the
+types of the actuals are not by-copy types. This warning is off by default.
+@end table
+
+@geindex -gnatw.I (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.I}
+
+`Disable warnings on overlapping actuals.'
+
+This switch disables warnings on overlapping actuals in a call.
+@end table
+
+@geindex -gnatwj (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwj}
+
+`Activate warnings on obsolescent features (Annex J).'
+
+@geindex Features
+@geindex obsolescent
+
+@geindex Obsolescent features
+
+If this warning option is activated, then warnings are generated for
+calls to subprograms marked with @code{pragma Obsolescent} and
+for use of features in Annex J of the Ada Reference Manual. In the
+case of Annex J, not all features are flagged. In particular, uses of package
+@code{ASCII} are not flagged, since these are very common and
+would generate many annoying positive warnings. The default is that
+such warnings are not generated.
+
+In addition to the above cases, warnings are also generated for
+GNAT features that have been provided in past versions but which
+have been superseded (typically by features in the new Ada standard).
+For example, @code{pragma Ravenscar} will be flagged since its
+function is replaced by @code{pragma Profile(Ravenscar)}, and
+@code{pragma Interface_Name} will be flagged since its function
+is replaced by @code{pragma Import}.
+
+Note that this warning option functions differently from the
+restriction @code{No_Obsolescent_Features} in two respects.
+First, the restriction applies only to annex J features.
+Second, the restriction does flag uses of package @code{ASCII}.
+@end table
+
+@geindex -gnatwJ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwJ}
+
+`Suppress warnings on obsolescent features (Annex J).'
+
+This switch disables warnings on use of obsolescent features.
+@end table
+
+@geindex -gnatw.j (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.j}
+
+`Activate warnings on late declarations of tagged type primitives.'
+
+This switch activates warnings on visible primitives added to a
+tagged type after deriving a private extension from it.
+@end table
+
+@geindex -gnatw.J (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.J}
+
+`Suppress warnings on late declarations of tagged type primitives.'
+
+This switch suppresses warnings on visible primitives added to a
+tagged type after deriving a private extension from it.
+@end table
+
+@geindex -gnatwk (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwk}
+
+`Activate warnings on variables that could be constants.'
+
+This switch activates warnings for variables that are initialized but
+never modified, and then could be declared constants. The default is that
+such warnings are not given.
+@end table
+
+@geindex -gnatwK (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwK}
+
+`Suppress warnings on variables that could be constants.'
+
+This switch disables warnings on variables that could be declared constants.
+@end table
+
+@geindex -gnatw.k (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.k}
+
+`Activate warnings on redefinition of names in standard.'
+
+This switch activates warnings for declarations that declare a name that
+is defined in package Standard. Such declarations can be confusing,
+especially since the names in package Standard continue to be directly
+visible, meaning that use visibiliy on such redeclared names does not
+work as expected. Names of discriminants and components in records are
+not included in this check.
+@end table
+
+@geindex -gnatwK (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.K}
+
+`Suppress warnings on redefinition of names in standard.'
+
+This switch disables warnings for declarations that declare a name that
+is defined in package Standard.
+@end table
+
+@geindex -gnatwl (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwl}
+
+`Activate warnings for elaboration pragmas.'
+
+@geindex Elaboration
+@geindex warnings
+
+This switch activates warnings for possible elaboration problems,
+including suspicious use
+of @code{Elaborate} pragmas, when using the static elaboration model, and
+possible situations that may raise @code{Program_Error} when using the
+dynamic elaboration model.
+See the section in this guide on elaboration checking for further details.
+The default is that such warnings
+are not generated.
+@end table
+
+@geindex -gnatwL (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwL}
+
+`Suppress warnings for elaboration pragmas.'
+
+This switch suppresses warnings for possible elaboration problems.
+@end table
+
+@geindex -gnatw.l (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.l}
+
+`List inherited aspects.'
+
+This switch causes the compiler to list inherited invariants,
+preconditions, and postconditions from Type_Invariant’Class, Invariant’Class,
+Pre’Class, and Post’Class aspects. Also list inherited subtype predicates.
+@end table
+
+@geindex -gnatw.L (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.L}
+
+`Suppress listing of inherited aspects.'
+
+This switch suppresses listing of inherited aspects.
+@end table
+
+@geindex -gnatwm (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwm}
+
+`Activate warnings on modified but unreferenced variables.'
+
+This switch activates warnings for variables that are assigned (using
+an initialization value or with one or more assignment statements) but
+whose value is never read. The warning is suppressed for volatile
+variables and also for variables that are renamings of other variables
+or for which an address clause is given.
+The default is that these warnings are not given.
+@end table
+
+@geindex -gnatwM (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwM}
+
+`Disable warnings on modified but unreferenced variables.'
+
+This switch disables warnings for variables that are assigned or
+initialized, but never read.
+@end table
+
+@geindex -gnatw.m (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.m}
+
+`Activate warnings on suspicious modulus values.'
+
+This switch activates warnings for modulus values that seem suspicious.
+The cases caught are where the size is the same as the modulus (e.g.
+a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
+with no size clause. The guess in both cases is that 2**x was intended
+rather than x. In addition expressions of the form 2*x for small x
+generate a warning (the almost certainly accurate guess being that
+2**x was intended). This switch also activates warnings for negative
+literal values of a modular type, which are interpreted as large positive
+integers after wrap-around. The default is that these warnings are given.
+@end table
+
+@geindex -gnatw.M (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.M}
+
+`Disable warnings on suspicious modulus values.'
+
+This switch disables warnings for suspicious modulus values.
+@end table
+
+@geindex -gnatwn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwn}
+
+`Set normal warnings mode.'
+
+This switch sets normal warning mode, in which enabled warnings are
+issued and treated as warnings rather than errors. This is the default
+mode. the switch @code{-gnatwn} can be used to cancel the effect of
+an explicit @code{-gnatws} or
+@code{-gnatwe}. It also cancels the effect of the
+implicit @code{-gnatwe} that is activated by the
+use of @code{-gnatg}.
+@end table
+
+@geindex -gnatw.n (gcc)
+
+@geindex Atomic Synchronization
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatw.n}
+
+`Activate warnings on atomic synchronization.'
+
+This switch actives warnings when an access to an atomic variable
+requires the generation of atomic synchronization code. These
+warnings are off by default.
+@end table
+
+@geindex -gnatw.N (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.N}
+
+`Suppress warnings on atomic synchronization.'
+
+@geindex Atomic Synchronization
+@geindex warnings
+
+This switch suppresses warnings when an access to an atomic variable
+requires the generation of atomic synchronization code.
+@end table
+
+@geindex -gnatwo (gcc)
+
+@geindex Address Clauses
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatwo}
+
+`Activate warnings on address clause overlays.'
+
+This switch activates warnings for possibly unintended initialization
+effects of defining address clauses that cause one variable to overlap
+another. The default is that such warnings are generated.
+@end table
+
+@geindex -gnatwO (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwO}
+
+`Suppress warnings on address clause overlays.'
+
+This switch suppresses warnings on possibly unintended initialization
+effects of defining address clauses that cause one variable to overlap
+another.
+@end table
+
+@geindex -gnatw.o (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.o}
+
+`Activate warnings on modified but unreferenced out parameters.'
+
+This switch activates warnings for variables that are modified by using
+them as actuals for a call to a procedure with an out mode formal, where
+the resulting assigned value is never read. It is applicable in the case
+where there is more than one out mode formal. If there is only one out
+mode formal, the warning is issued by default (controlled by -gnatwu).
+The warning is suppressed for volatile
+variables and also for variables that are renamings of other variables
+or for which an address clause is given.
+The default is that these warnings are not given.
+@end table
+
+@geindex -gnatw.O (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.O}
+
+`Disable warnings on modified but unreferenced out parameters.'
+
+This switch suppresses warnings for variables that are modified by using
+them as actuals for a call to a procedure with an out mode formal, where
+the resulting assigned value is never read.
+@end table
+
+@geindex -gnatwp (gcc)
+
+@geindex Inlining
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatwp}
+
+`Activate warnings on ineffective pragma Inlines.'
+
+This switch activates warnings for failure of front end inlining
+(activated by @code{-gnatN}) to inline a particular call. There are
+many reasons for not being able to inline a call, including most
+commonly that the call is too complex to inline. The default is
+that such warnings are not given.
+Warnings on ineffective inlining by the gcc back-end can be activated
+separately, using the gcc switch -Winline.
+@end table
+
+@geindex -gnatwP (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwP}
+
+`Suppress warnings on ineffective pragma Inlines.'
+
+This switch suppresses warnings on ineffective pragma Inlines. If the
+inlining mechanism cannot inline a call, it will simply ignore the
+request silently.
+@end table
+
+@geindex -gnatw.p (gcc)
+
+@geindex Parameter order
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatw.p}
+
+`Activate warnings on parameter ordering.'
+
+This switch activates warnings for cases of suspicious parameter
+ordering when the list of arguments are all simple identifiers that
+match the names of the formals, but are in a different order. The
+warning is suppressed if any use of named parameter notation is used,
+so this is the appropriate way to suppress a false positive (and
+serves to emphasize that the “misordering” is deliberate). The
+default is that such warnings are not given.
+@end table
+
+@geindex -gnatw.P (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.P}
+
+`Suppress warnings on parameter ordering.'
+
+This switch suppresses warnings on cases of suspicious parameter
+ordering.
+@end table
+
+@geindex -gnatw_p (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_p}
+
+`Activate warnings for pedantic checks.'
+
+This switch activates warnings for the failure of certain pedantic checks.
+The only case currently supported is a check that the subtype_marks given
+for corresponding formal parameter and function results in a subprogram
+declaration and its body denote the same subtype declaration. The default
+is that such warnings are not given.
+@end table
+
+@geindex -gnatw_P (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_P}
+
+`Suppress warnings for pedantic checks.'
+
+This switch suppresses warnings on violations of pedantic checks.
+@end table
+
+@geindex -gnatwq (gcc)
+
+@geindex Parentheses
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatwq}
+
+`Activate warnings on questionable missing parentheses.'
+
+This switch activates warnings for cases where parentheses are not used and
+the result is potential ambiguity from a readers point of view. For example
+(not a > b) when a and b are modular means ((not a) > b) and very likely the
+programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
+quite likely ((-x) mod 5) was intended. In such situations it seems best to
+follow the rule of always parenthesizing to make the association clear, and
+this warning switch warns if such parentheses are not present. The default
+is that these warnings are given.
+@end table
+
+@geindex -gnatwQ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwQ}
+
+`Suppress warnings on questionable missing parentheses.'
+
+This switch suppresses warnings for cases where the association is not
+clear and the use of parentheses is preferred.
+@end table
+
+@geindex -gnatw.q (gcc)
+
+@geindex Layout
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatw.q}
+
+`Activate warnings on questionable layout of record types.'
+
+This switch activates warnings for cases where the default layout of
+a record type, that is to say the layout of its components in textual
+order of the source code, would very likely cause inefficiencies in
+the code generated by the compiler, both in terms of space and speed
+during execution. One warning is issued for each problematic component
+without representation clause in the nonvariant part and then in each
+variant recursively, if any.
+
+The purpose of these warnings is neither to prescribe an optimal layout
+nor to force the use of representation clauses, but rather to get rid of
+the most blatant inefficiencies in the layout. Therefore, the default
+layout is matched against the following synthetic ordered layout and
+the deviations are flagged on a component-by-component basis:
+
+
+@itemize *
+
+@item
+first all components or groups of components whose length is fixed
+and a multiple of the storage unit,
+
+@item
+then the remaining components whose length is fixed and not a multiple
+of the storage unit,
+
+@item
+then the remaining components whose length doesn’t depend on discriminants
+(that is to say, with variable but uniform length for all objects),
+
+@item
+then all components whose length depends on discriminants,
+
+@item
+finally the variant part (if any),
+@end itemize
+
+for the nonvariant part and for each variant recursively, if any.
+
+The exact wording of the warning depends on whether the compiler is allowed
+to reorder the components in the record type or precluded from doing it by
+means of pragma @code{No_Component_Reordering}.
+
+The default is that these warnings are not given.
+@end table
+
+@geindex -gnatw.Q (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.Q}
+
+`Suppress warnings on questionable layout of record types.'
+
+This switch suppresses warnings for cases where the default layout of
+a record type would very likely cause inefficiencies.
+@end table
+
+@geindex -gnatw_q (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_q}
+
+`Activate warnings for ignored equality operators.'
+
+This switch activates warnings for a user-defined “=” function that does
+not compose (i.e. is ignored for a predefined “=” for a composite type
+containing a component whose type has the user-defined “=” as
+primitive). Note that the user-defined “=” must be a primitive operator
+in order to trigger the warning.
+
+The default is that these warnings are not given.
+@end table
+
+@geindex -gnatw_Q (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_Q}
+
+`Suppress warnings for ignored equality operators.'
+@end table
+
+@geindex -gnatwr (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwr}
+
+`Activate warnings on redundant constructs.'
+
+This switch activates warnings for redundant constructs. The following
+is the current list of constructs regarded as redundant:
+
+
+@itemize *
+
+@item
+Assignment of an item to itself.
+
+@item
+Type conversion that converts an expression to its own type.
+
+@item
+Use of the attribute @code{Base} where @code{typ'Base} is the same
+as @code{typ}.
+
+@item
+Use of pragma @code{Pack} when all components are placed by a record
+representation clause.
+
+@item
+Exception handler containing only a reraise statement (raise with no
+operand) which has no effect.
+
+@item
+Use of the operator abs on an operand that is known at compile time
+to be non-negative
+
+@item
+Comparison of an object or (unary or binary) operation of boolean type to
+an explicit True value.
+
+@item
+Import of parent package.
+@end itemize
+
+The default is that warnings for redundant constructs are not given.
+@end table
+
+@geindex -gnatwR (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwR}
+
+`Suppress warnings on redundant constructs.'
+
+This switch suppresses warnings for redundant constructs.
+@end table
+
+@geindex -gnatw.r (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.r}
+
+`Activate warnings for object renaming function.'
+
+This switch activates warnings for an object renaming that renames a
+function call, which is equivalent to a constant declaration (as
+opposed to renaming the function itself). The default is that these
+warnings are given.
+@end table
+
+@geindex -gnatw.R (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.R}
+
+`Suppress warnings for object renaming function.'
+
+This switch suppresses warnings for object renaming function.
+@end table
+
+@geindex -gnatw_r (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_r}
+
+`Activate warnings for out-of-order record representation clauses.'
+
+This switch activates warnings for record representation clauses,
+if the order of component declarations, component clauses,
+and bit-level layout do not all agree.
+The default is that these warnings are not given.
+@end table
+
+@geindex -gnatw_R (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_R}
+
+`Suppress warnings for out-of-order record representation clauses.'
+@end table
+
+@geindex -gnatws (gcc)
+
+
+@table @asis
+
+@item @code{-gnatws}
+
+`Suppress all warnings.'
+
+This switch completely suppresses the
+output of all warning messages from the GNAT front end, including
+both warnings that can be controlled by switches described in this
+section, and those that are normally given unconditionally. The
+effect of this suppress action can only be cancelled by a subsequent
+use of the switch @code{-gnatwn}.
+
+Note that switch @code{-gnatws} does not suppress
+warnings from the @code{gcc} back end.
+To suppress these back end warnings as well, use the switch @code{-w}
+in addition to @code{-gnatws}. Also this switch has no effect on the
+handling of style check messages.
+@end table
+
+@geindex -gnatw.s (gcc)
+
+@geindex Record Representation (component sizes)
+
+
+@table @asis
+
+@item @code{-gnatw.s}
+
+`Activate warnings on overridden size clauses.'
+
+This switch activates warnings on component clauses in record
+representation clauses where the length given overrides that
+specified by an explicit size clause for the component type. A
+warning is similarly given in the array case if a specified
+component size overrides an explicit size clause for the array
+component type.
+@end table
+
+@geindex -gnatw.S (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.S}
+
+`Suppress warnings on overridden size clauses.'
+
+This switch suppresses warnings on component clauses in record
+representation clauses that override size clauses, and similar
+warnings when an array component size overrides a size clause.
+@end table
+
+@geindex -gnatwt (gcc)
+
+@geindex Deactivated code
+@geindex warnings
+
+@geindex Deleted code
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatwt}
+
+`Activate warnings for tracking of deleted conditional code.'
+
+This switch activates warnings for tracking of code in conditionals (IF and
+CASE statements) that is detected to be dead code which cannot be executed, and
+which is removed by the front end. This warning is off by default. This may be
+useful for detecting deactivated code in certified applications.
+@end table
+
+@geindex -gnatwT (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwT}
+
+`Suppress warnings for tracking of deleted conditional code.'
+
+This switch suppresses warnings for tracking of deleted conditional code.
+@end table
+
+@geindex -gnatw.t (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.t}
+
+`Activate warnings on suspicious contracts.'
+
+This switch activates warnings on suspicious contracts. This includes
+warnings on suspicious postconditions (whether a pragma @code{Postcondition} or a
+@code{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect
+@code{Contract_Cases}). A function postcondition or contract case is suspicious
+when no postcondition or contract case for this function mentions the result
+of the function. A procedure postcondition or contract case is suspicious
+when it only refers to the pre-state of the procedure, because in that case
+it should rather be expressed as a precondition. This switch also controls
+warnings on suspicious cases of expressions typically found in contracts like
+quantified expressions and uses of Update attribute. The default is that such
+warnings are generated.
+@end table
+
+@geindex -gnatw.T (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.T}
+
+`Suppress warnings on suspicious contracts.'
+
+This switch suppresses warnings on suspicious contracts.
+@end table
+
+@geindex -gnatwu (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwu}
+
+`Activate warnings on unused entities.'
+
+This switch activates warnings to be generated for entities that
+are declared but not referenced, and for units that are `with'ed
+and not
+referenced. In the case of packages, a warning is also generated if
+no entities in the package are referenced. This means that if a with’ed
+package is referenced but the only references are in @code{use}
+clauses or @code{renames}
+declarations, a warning is still generated. A warning is also generated
+for a generic package that is `with'ed but never instantiated.
+In the case where a package or subprogram body is compiled, and there
+is a `with' on the corresponding spec
+that is only referenced in the body,
+a warning is also generated, noting that the
+`with' can be moved to the body. The default is that
+such warnings are not generated.
+This switch also activates warnings on unreferenced formals
+(it includes the effect of @code{-gnatwf}).
+@end table
+
+@geindex -gnatwU (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwU}
+
+`Suppress warnings on unused entities.'
+
+This switch suppresses warnings for unused entities and packages.
+It also turns off warnings on unreferenced formals (and thus includes
+the effect of @code{-gnatwF}).
+@end table
+
+@geindex -gnatw.u (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.u}
+
+`Activate warnings on unordered enumeration types.'
+
+This switch causes enumeration types to be considered as conceptually
+unordered, unless an explicit pragma @code{Ordered} is given for the type.
+The effect is to generate warnings in clients that use explicit comparisons
+or subranges, since these constructs both treat objects of the type as
+ordered. (A `client' is defined as a unit that is other than the unit in
+which the type is declared, or its body or subunits.) Please refer to
+the description of pragma @code{Ordered} in the
+@cite{GNAT Reference Manual} for further details.
+The default is that such warnings are not generated.
+@end table
+
+@geindex -gnatw.U (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.U}
+
+`Deactivate warnings on unordered enumeration types.'
+
+This switch causes all enumeration types to be considered as ordered, so
+that no warnings are given for comparisons or subranges for any type.
+@end table
+
+@geindex -gnatwv (gcc)
+
+@geindex Unassigned variable warnings
+
+
+@table @asis
+
+@item @code{-gnatwv}
+
+`Activate warnings on unassigned variables.'
+
+This switch activates warnings for access to variables which
+may not be properly initialized. The default is that
+such warnings are generated. This switch will also be emitted when
+initializing an array or record object via the following aggregate:
+
+@example
+Array_Or_Record : XXX := (others => <>);
+@end example
+
+unless the relevant type fully initializes all components.
+@end table
+
+@geindex -gnatwV (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwV}
+
+`Suppress warnings on unassigned variables.'
+
+This switch suppresses warnings for access to variables which
+may not be properly initialized.
+@end table
+
+@geindex -gnatw.v (gcc)
+
+@geindex bit order warnings
+
+
+@table @asis
+
+@item @code{-gnatw.v}
+
+`Activate info messages for non-default bit order.'
+
+This switch activates messages (labeled “info”, they are not warnings,
+just informational messages) about the effects of non-default bit-order
+on records to which a component clause is applied. The effect of specifying
+non-default bit ordering is a bit subtle (and changed with Ada 2005), so
+these messages, which are given by default, are useful in understanding the
+exact consequences of using this feature.
+@end table
+
+@geindex -gnatw.V (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.V}
+
+`Suppress info messages for non-default bit order.'
+
+This switch suppresses information messages for the effects of specifying
+non-default bit order on record components with component clauses.
+@end table
+
+@geindex -gnatww (gcc)
+
+@geindex String indexing warnings
+
+
+@table @asis
+
+@item @code{-gnatww}
+
+`Activate warnings on wrong low bound assumption.'
+
+This switch activates warnings for indexing an unconstrained string parameter
+with a literal or S’Length. This is a case where the code is assuming that the
+low bound is one, which is in general not true (for example when a slice is
+passed). The default is that such warnings are generated.
+@end table
+
+@geindex -gnatwW (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwW}
+
+`Suppress warnings on wrong low bound assumption.'
+
+This switch suppresses warnings for indexing an unconstrained string parameter
+with a literal or S’Length. Note that this warning can also be suppressed
+in a particular case by adding an assertion that the lower bound is 1,
+as shown in the following example:
+
+@example
+procedure K (S : String) is
+ pragma Assert (S'First = 1);
+ ...
+@end example
+@end table
+
+@geindex -gnatw.w (gcc)
+
+@geindex Warnings Off control
+
+
+@table @asis
+
+@item @code{-gnatw.w}
+
+`Activate warnings on Warnings Off pragmas.'
+
+This switch activates warnings for use of @code{pragma Warnings (Off, entity)}
+where either the pragma is entirely useless (because it suppresses no
+warnings), or it could be replaced by @code{pragma Unreferenced} or
+@code{pragma Unmodified}.
+Also activates warnings for the case of
+Warnings (Off, String), where either there is no matching
+Warnings (On, String), or the Warnings (Off) did not suppress any warning.
+The default is that these warnings are not given.
+@end table
+
+@geindex -gnatw.W (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.W}
+
+`Suppress warnings on unnecessary Warnings Off pragmas.'
+
+This switch suppresses warnings for use of @code{pragma Warnings (Off, ...)}.
+@end table
+
+@geindex -gnatwx (gcc)
+
+@geindex Export/Import pragma warnings
+
+
+@table @asis
+
+@item @code{-gnatwx}
+
+`Activate warnings on Export/Import pragmas.'
+
+This switch activates warnings on Export/Import pragmas when
+the compiler detects a possible conflict between the Ada and
+foreign language calling sequences. For example, the use of
+default parameters in a convention C procedure is dubious
+because the C compiler cannot supply the proper default, so
+a warning is issued. The default is that such warnings are
+generated.
+@end table
+
+@geindex -gnatwX (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwX}
+
+`Suppress warnings on Export/Import pragmas.'
+
+This switch suppresses warnings on Export/Import pragmas.
+The sense of this is that you are telling the compiler that
+you know what you are doing in writing the pragma, and it
+should not complain at you.
+@end table
+
+@geindex -gnatwm (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.x}
+
+`Activate warnings for No_Exception_Propagation mode.'
+
+This switch activates warnings for exception usage when pragma Restrictions
+(No_Exception_Propagation) is in effect. Warnings are given for implicit or
+explicit exception raises which are not covered by a local handler, and for
+exception handlers which do not cover a local raise. The default is that
+these warnings are given for units that contain exception handlers.
+
+@item @code{-gnatw.X}
+
+`Disable warnings for No_Exception_Propagation mode.'
+
+This switch disables warnings for exception usage when pragma Restrictions
+(No_Exception_Propagation) is in effect.
+@end table
+
+@geindex -gnatwy (gcc)
+
+@geindex Ada compatibility issues warnings
+
+
+@table @asis
+
+@item @code{-gnatwy}
+
+`Activate warnings for Ada compatibility issues.'
+
+For the most part, newer versions of Ada are upwards compatible
+with older versions. For example, Ada 2005 programs will almost
+always work when compiled as Ada 2012.
+However there are some exceptions (for example the fact that
+@code{some} is now a reserved word in Ada 2012). This
+switch activates several warnings to help in identifying
+and correcting such incompatibilities. The default is that
+these warnings are generated. Note that at one point Ada 2005
+was called Ada 0Y, hence the choice of character.
+@end table
+
+@geindex -gnatwY (gcc)
+
+@geindex Ada compatibility issues warnings
+
+
+@table @asis
+
+@item @code{-gnatwY}
+
+`Disable warnings for Ada compatibility issues.'
+
+This switch suppresses the warnings intended to help in identifying
+incompatibilities between Ada language versions.
+@end table
+
+@geindex -gnatw.y (gcc)
+
+@geindex Package spec needing body
+
+
+@table @asis
+
+@item @code{-gnatw.y}
+
+`Activate information messages for why package spec needs body.'
+
+There are a number of cases in which a package spec needs a body.
+For example, the use of pragma Elaborate_Body, or the declaration
+of a procedure specification requiring a completion. This switch
+causes information messages to be output showing why a package
+specification requires a body. This can be useful in the case of
+a large package specification which is unexpectedly requiring a
+body. The default is that such information messages are not output.
+@end table
+
+@geindex -gnatw.Y (gcc)
+
+@geindex No information messages for why package spec needs body
+
+
+@table @asis
+
+@item @code{-gnatw.Y}
+
+`Disable information messages for why package spec needs body.'
+
+This switch suppresses the output of information messages showing why
+a package specification needs a body.
+@end table
+
+@geindex -gnatwz (gcc)
+
+@geindex Unchecked_Conversion warnings
+
+
+@table @asis
+
+@item @code{-gnatwz}
+
+`Activate warnings on unchecked conversions.'
+
+This switch activates warnings for unchecked conversions
+where the types are known at compile time to have different
+sizes. The default is that such warnings are generated. Warnings are also
+generated for subprogram pointers with different conventions.
+@end table
+
+@geindex -gnatwZ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwZ}
+
+`Suppress warnings on unchecked conversions.'
+
+This switch suppresses warnings for unchecked conversions
+where the types are known at compile time to have different
+sizes or conventions.
+@end table
+
+@geindex -gnatw.z (gcc)
+
+@geindex Size/Alignment warnings
+
+
+@table @asis
+
+@item @code{-gnatw.z}
+
+`Activate warnings for size not a multiple of alignment.'
+
+This switch activates warnings for cases of array and record types
+with specified @code{Size} and @code{Alignment} attributes where the
+size is not a multiple of the alignment, resulting in an object
+size that is greater than the specified size. The default
+is that such warnings are generated.
+@end table
+
+@geindex -gnatw.Z (gcc)
+
+@geindex Size/Alignment warnings
+
+
+@table @asis
+
+@item @code{-gnatw.Z}
+
+`Suppress warnings for size not a multiple of alignment.'
+
+This switch suppresses warnings for cases of array and record types
+with specified @code{Size} and @code{Alignment} attributes where the
+size is not a multiple of the alignment, resulting in an object
+size that is greater than the specified size. The warning can also
+be suppressed by giving an explicit @code{Object_Size} value.
+@end table
+
+@geindex -Wunused (gcc)
+
+
+@table @asis
+
+@item @code{-Wunused}
+
+The warnings controlled by the @code{-gnatw} switch are generated by
+the front end of the compiler. The GCC back end can provide
+additional warnings and they are controlled by the @code{-W} switch.
+For example, @code{-Wunused} activates back end
+warnings for entities that are declared but not referenced.
+@end table
+
+@geindex -Wuninitialized (gcc)
+
+
+@table @asis
+
+@item @code{-Wuninitialized}
+
+Similarly, @code{-Wuninitialized} activates
+the back end warning for uninitialized variables. This switch must be
+used in conjunction with an optimization level greater than zero.
+@end table
+
+@geindex -Wstack-usage (gcc)
+
+
+@table @asis
+
+@item @code{-Wstack-usage=`len'}
+
+Warn if the stack usage of a subprogram might be larger than @code{len} bytes.
+See @ref{e6,,Static Stack Usage Analysis} for details.
+@end table
+
+@geindex -Wall (gcc)
+
+
+@table @asis
+
+@item @code{-Wall}
+
+This switch enables most warnings from the GCC back end.
+The code generator detects a number of warning situations that are missed
+by the GNAT front end, and this switch can be used to activate them.
+The use of this switch also sets the default front-end warning mode to
+@code{-gnatwa}, that is, most front-end warnings are activated as well.
+@end table
+
+@geindex -w (gcc)
+
+
+@table @asis
+
+@item @code{-w}
+
+Conversely, this switch suppresses warnings from the GCC back end.
+The use of this switch also sets the default front-end warning mode to
+@code{-gnatws}, that is, front-end warnings are suppressed as well.
+@end table
+
+@geindex -Werror (gcc)
+
+
+@table @asis
+
+@item @code{-Werror}
+
+This switch causes warnings from the GCC back end to be treated as
+errors. The warning string still appears, but the warning messages are
+counted as errors, and prevent the generation of an object file.
+The use of this switch also sets the default front-end warning mode to
+@code{-gnatwe}, that is, front-end warning messages and style check
+messages are treated as errors as well.
+@end table
+
+A string of warning parameters can be used in the same parameter. For example:
+
+@example
+-gnatwaGe
+@end example
+
+will turn on all optional warnings except for unrecognized pragma warnings,
+and also specify that warnings should be treated as errors.
+
+When no switch @code{-gnatw} is used, this is equivalent to:
+
+@quotation
+
+
+@itemize *
+
+@item
+@code{-gnatw.a}
+
+@item
+@code{-gnatwB}
+
+@item
+@code{-gnatw.b}
+
+@item
+@code{-gnatwC}
+
+@item
+@code{-gnatw.C}
+
+@item
+@code{-gnatwD}
+
+@item
+@code{-gnatw.D}
+
+@item
+@code{-gnatwF}
+
+@item
+@code{-gnatw.F}
+
+@item
+@code{-gnatwg}
+
+@item
+@code{-gnatwH}
+
+@item
+@code{-gnatw.H}
+
+@item
+@code{-gnatwi}
+
+@item
+@code{-gnatwJ}
+
+@item
+@code{-gnatw.J}
+
+@item
+@code{-gnatwK}
+
+@item
+@code{-gnatw.K}
+
+@item
+@code{-gnatwL}
+
+@item
+@code{-gnatw.L}
+
+@item
+@code{-gnatwM}
+
+@item
+@code{-gnatw.m}
+
+@item
+@code{-gnatwn}
+
+@item
+@code{-gnatw.N}
+
+@item
+@code{-gnatwo}
+
+@item
+@code{-gnatw.O}
+
+@item
+@code{-gnatwP}
+
+@item
+@code{-gnatw.P}
+
+@item
+@code{-gnatwq}
+
+@item
+@code{-gnatw.Q}
+
+@item
+@code{-gnatwR}
+
+@item
+@code{-gnatw.R}
+
+@item
+@code{-gnatw.S}
+
+@item
+@code{-gnatwT}
+
+@item
+@code{-gnatw.t}
+
+@item
+@code{-gnatwU}
+
+@item
+@code{-gnatw.U}
+
+@item
+@code{-gnatwv}
+
+@item
+@code{-gnatw.v}
+
+@item
+@code{-gnatww}
+
+@item
+@code{-gnatw.W}
+
+@item
+@code{-gnatwx}
+
+@item
+@code{-gnatw.X}
+
+@item
+@code{-gnatwy}
+
+@item
+@code{-gnatw.Y}
+
+@item
+@code{-gnatwz}
+
+@item
+@code{-gnatw.z}
+@end itemize
+@end quotation
+
+@node Debugging and Assertion Control,Validity Checking,Warning Message Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-and-assertion-control}@anchor{f1}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{f2}
+@subsection Debugging and Assertion Control
+
+
+@geindex -gnata (gcc)
+
+
+@table @asis
+
+@item @code{-gnata}
+
+@geindex Assert
+
+@geindex Debug
+
+@geindex Assertions
+
+@geindex Precondition
+
+@geindex Postcondition
+
+@geindex Type invariants
+
+@geindex Subtype predicates
+
+The @code{-gnata} option is equivalent to the following @code{Assertion_Policy} pragma:
+
+@example
+pragma Assertion_Policy (Check);
+@end example
+
+Which is a shorthand for:
+
+@example
+pragma Assertion_Policy
+-- Ada RM assertion pragmas
+ (Assert => Check,
+ Static_Predicate => Check,
+ Dynamic_Predicate => Check,
+ Pre => Check,
+ Pre'Class => Check,
+ Post => Check,
+ Post'Class => Check,
+ Type_Invariant => Check,
+ Type_Invariant'Class => Check,
+ Default_Initial_Condition => Check,
+-- GNAT specific assertion pragmas
+ Assert_And_Cut => Check,
+ Assume => Check,
+ Contract_Cases => Check,
+ Debug => Check,
+ Ghost => Check,
+ Initial_Condition => Check,
+ Loop_Invariant => Check,
+ Loop_Variant => Check,
+ Postcondition => Check,
+ Precondition => Check,
+ Predicate => Check,
+ Refined_Post => Check,
+ Subprogram_Variant => Check);
+@end example
+
+The pragmas @code{Assert} and @code{Debug} normally have no effect and
+are ignored. This switch, where @code{a} stands for ‘assert’, causes
+pragmas @code{Assert} and @code{Debug} to be activated. This switch also
+causes preconditions, postconditions, subtype predicates, and
+type invariants to be activated.
+
+The pragmas have the form:
+
+@example
+pragma Assert (<Boolean-expression> [, <static-string-expression>])
+pragma Debug (<procedure call>)
+pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
+pragma Predicate (<type-local-name>, <Boolean-expression>)
+pragma Precondition (<Boolean-expression>, <string-expression>)
+pragma Postcondition (<Boolean-expression>, <string-expression>)
+@end example
+
+The aspects have the form:
+
+@example
+with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
+ => <Boolean-expression>;
+@end example
+
+The @code{Assert} pragma causes @code{Boolean-expression} to be tested.
+If the result is @code{True}, the pragma has no effect (other than
+possible side effects from evaluating the expression). If the result is
+@code{False}, the exception @code{Assert_Failure} declared in the package
+@code{System.Assertions} is raised (passing @code{static-string-expression}, if
+present, as the message associated with the exception). If no string
+expression is given, the default is a string containing the file name and
+line number of the pragma.
+
+The @code{Debug} pragma causes @code{procedure} to be called. Note that
+@code{pragma Debug} may appear within a declaration sequence, allowing
+debugging procedures to be called between declarations.
+
+For the aspect specification, the @code{Boolean-expression} is evaluated.
+If the result is @code{True}, the aspect has no effect. If the result
+is @code{False}, the exception @code{Assert_Failure} is raised.
+@end table
+
+@node Validity Checking,Style Checking,Debugging and Assertion Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{f3}@anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{e7}
+@subsection Validity Checking
+
+
+@geindex Validity Checking
+
+The Ada Reference Manual defines the concept of invalid values (see
+RM 13.9.1). The primary source of invalid values is uninitialized
+variables. A scalar variable that is left uninitialized may contain
+an invalid value; the concept of invalid does not apply to access or
+composite types.
+
+It is an error to read an invalid value, but the RM does not require
+run-time checks to detect such errors, except for some minimal
+checking to prevent erroneous execution (i.e. unpredictable
+behavior). This corresponds to the @code{-gnatVd} switch below,
+which is the default. For example, by default, if the expression of a
+case statement is invalid, it will raise Constraint_Error rather than
+causing a wild jump, and if an array index on the left-hand side of an
+assignment is invalid, it will raise Constraint_Error rather than
+overwriting an arbitrary memory location.
+
+The @code{-gnatVa} may be used to enable additional validity checks,
+which are not required by the RM. These checks are often very
+expensive (which is why the RM does not require them). These checks
+are useful in tracking down uninitialized variables, but they are
+not usually recommended for production builds, and in particular
+we do not recommend using these extra validity checking options in
+combination with optimization, since this can confuse the optimizer.
+If performance is a consideration, leading to the need to optimize,
+then the validity checking options should not be used.
+
+The other @code{-gnatV`x'} switches below allow finer-grained
+control; you can enable whichever validity checks you desire. However,
+for most debugging purposes, @code{-gnatVa} is sufficient, and the
+default @code{-gnatVd} (i.e. standard Ada behavior) is usually
+sufficient for non-debugging use.
+
+The @code{-gnatB} switch tells the compiler to assume that all
+values are valid (that is, within their declared subtype range)
+except in the context of a use of the Valid attribute. This means
+the compiler can generate more efficient code, since the range
+of values is better known at compile time. However, an uninitialized
+variable can cause wild jumps and memory corruption in this mode.
+
+The @code{-gnatV`x'} switch allows control over the validity
+checking mode as described below.
+The @code{x} argument is a string of letters that
+indicate validity checks that are performed or not performed in addition
+to the default checks required by Ada as described above.
+
+@geindex -gnatVa (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVa}
+
+`All validity checks.'
+
+All validity checks are turned on.
+That is, @code{-gnatVa} is
+equivalent to @code{gnatVcdefimoprst}.
+@end table
+
+@geindex -gnatVc (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVc}
+
+`Validity checks for copies.'
+
+The right-hand side of assignments, and the (explicit) initializing values
+of object declarations are validity checked.
+@end table
+
+@geindex -gnatVd (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVd}
+
+`Default (RM) validity checks.'
+
+Some validity checks are required by Ada (see RM 13.9.1 (9-11)); these
+(and only these) validity checks are enabled by default.
+For case statements (and case expressions) that lack a “when others =>”
+choice, a check is made that the value of the selector expression
+belongs to its nominal subtype. If it does not, Constraint_Error is raised.
+For assignments to array components (and for indexed components in some
+other contexts), a check is made that each index expression belongs to the
+corresponding index subtype. If it does not, Constraint_Error is raised.
+Both these validity checks may be turned off using switch @code{-gnatVD}.
+They are turned on by default. If @code{-gnatVD} is specified, a subsequent
+switch @code{-gnatVd} will leave the checks turned on.
+Switch @code{-gnatVD} should be used only if you are sure that all such
+expressions have valid values. If you use this switch and invalid values
+are present, then the program is erroneous, and wild jumps or memory
+overwriting may occur.
+@end table
+
+@geindex -gnatVe (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVe}
+
+`Validity checks for scalar components.'
+
+In the absence of this switch, assignments to scalar components of
+enclosing record or array objects are not validity checked, even if
+validity checks for assignments generally (@code{-gnatVc}) are turned on.
+Specifying this switch enables such checks.
+This switch has no effect if the @code{-gnatVc} switch is not specified.
+@end table
+
+@geindex -gnatVf (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVf}
+
+`Validity checks for floating-point values.'
+
+Specifying this switch enables validity checking for floating-point
+values in the same contexts where validity checking is enabled for
+other scalar values.
+In the absence of this switch, validity checking is not performed for
+floating-point values. This takes precedence over other statements about
+performing validity checking for scalar objects in various scenarios.
+One way to look at it is that if this switch is not set, then whenever
+any of the other rules in this section use the word “scalar” they
+really mean “scalar and not floating-point”.
+If @code{-gnatVf} is specified, then validity checking also applies
+for floating-point values, and NaNs and infinities are considered invalid,
+as well as out-of-range values for constrained types. The exact contexts
+in which floating-point values are checked depends on the setting of other
+options. For example, @code{-gnatVif} or @code{-gnatVfi}
+(the order does not matter) specifies that floating-point parameters of mode
+@code{in} should be validity checked.
+@end table
+
+@geindex -gnatVi (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVi}
+
+`Validity checks for `@w{`}in`@w{`} mode parameters.'
+
+Arguments for parameters of mode @code{in} are validity checked in function
+and procedure calls at the point of call.
+@end table
+
+@geindex -gnatVm (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVm}
+
+`Validity checks for `@w{`}in out`@w{`} mode parameters.'
+
+Arguments for parameters of mode @code{in out} are validity checked in
+procedure calls at the point of call. The @code{'m'} here stands for
+modify, since this concerns parameters that can be modified by the call.
+Note that there is no specific option to test @code{out} parameters,
+but any reference within the subprogram will be tested in the usual
+manner, and if an invalid value is copied back, any reference to it
+will be subject to validity checking.
+@end table
+
+@geindex -gnatVn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVn}
+
+`No validity checks.'
+
+This switch turns off all validity checking, including the default checking
+for case statements and left hand side subscripts. Note that the use of
+the switch @code{-gnatp} suppresses all run-time checks, including
+validity checks, and thus implies @code{-gnatVn}. When this switch
+is used, it cancels any other @code{-gnatV} previously issued.
+@end table
+
+@geindex -gnatVo (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVo}
+
+`Validity checks for operator and attribute operands.'
+
+Scalar arguments for predefined operators and for attributes are
+validity checked.
+This includes all operators in package @code{Standard},
+the shift operators defined as intrinsic in package @code{Interfaces}
+and operands for attributes such as @code{Pos}. Checks are also made
+on individual component values for composite comparisons, and on the
+expressions in type conversions and qualified expressions. Checks are
+also made on explicit ranges using @code{..} (e.g., slices, loops etc).
+@end table
+
+@geindex -gnatVp (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVp}
+
+`Validity checks for parameters.'
+
+This controls the treatment of formal parameters within a subprogram (as
+opposed to @code{-gnatVi} and @code{-gnatVm}, which control validity
+testing of actual parameters of a call). If either of these call options is
+specified, then normally an assumption is made within a subprogram that
+the validity of any incoming formal parameters of the corresponding mode(s)
+has already been checked at the point of call and does not need rechecking.
+If @code{-gnatVp} is set, then this assumption is not made and so their
+validity may be checked (or rechecked) within the subprogram. If neither of
+the two call-related options is specified, then this switch has no effect.
+@end table
+
+@geindex -gnatVr (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVr}
+
+`Validity checks for function returns.'
+
+The expression in simple @code{return} statements in functions is validity
+checked.
+@end table
+
+@geindex -gnatVs (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVs}
+
+`Validity checks for subscripts.'
+
+All subscript expressions are checked for validity, whatever context
+they occur in (in default mode some subscripts are not validity checked;
+for example, validity checking may be omitted in some cases involving
+a read of a component of an array).
+@end table
+
+@geindex -gnatVt (gcc)
+
+
+@table @asis
+
+@item @code{-gnatVt}
+
+`Validity checks for tests.'
+
+Expressions used as conditions in @code{if}, @code{while} or @code{exit}
+statements are checked, as well as guard expressions in entry calls.
+@end table
+
+The @code{-gnatV} switch may be followed by a string of letters
+to turn on a series of validity checking options.
+For example, @code{-gnatVcr}
+specifies that in addition to the default validity checking, copies and
+function return expressions are to be validity checked.
+In order to make it easier to specify the desired combination of effects,
+the upper case letters @code{CDFIMORST} may
+be used to turn off the corresponding lower case option.
+Thus @code{-gnatVaM} turns on all validity checking options except for
+checking of @code{in out} parameters.
+
+The specification of additional validity checking generates extra code (and
+in the case of @code{-gnatVa} the code expansion can be substantial).
+However, these additional checks can be very useful in detecting
+uninitialized variables, incorrect use of unchecked conversion, and other
+errors leading to invalid values. The use of pragma @code{Initialize_Scalars}
+is useful in conjunction with the extra validity checking, since this
+ensures that wherever possible uninitialized variables have invalid values.
+
+See also the pragma @code{Validity_Checks} which allows modification of
+the validity checking mode at the program source level, and also allows for
+temporary disabling of validity checks.
+
+@node Style Checking,Run-Time Checks,Validity Checking,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id18}@anchor{f4}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{ec}
+@subsection Style Checking
+
+
+@geindex Style checking
+
+@geindex -gnaty (gcc)
+
+The @code{-gnatyx} switch causes the compiler to
+enforce specified style rules. A limited set of style rules has been used
+in writing the GNAT sources themselves. This switch allows user programs
+to activate all or some of these checks. If the source program fails a
+specified style check, an appropriate message is given, preceded by
+the character sequence ‘(style)’. This message does not prevent
+successful compilation (unless the @code{-gnatwe} switch is used).
+
+Note that this is by no means intended to be a general facility for
+checking arbitrary coding standards. It is simply an embedding of the
+style rules we have chosen for the GNAT sources. If you are starting
+a project which does not have established style standards, you may
+find it useful to adopt the entire set of GNAT coding standards, or
+some subset of them.
+
+
+The string @code{x} is a sequence of letters or digits
+indicating the particular style
+checks to be performed. The following checks are defined:
+
+@geindex -gnaty[0-9] (gcc)
+
+
+@table @asis
+
+@item @code{-gnaty0}
+
+`Specify indentation level.'
+
+If a digit from 1-9 appears
+in the string after @code{-gnaty}
+then proper indentation is checked, with the digit indicating the
+indentation level required. A value of zero turns off this style check.
+The rule checks that the following constructs start on a column that is
+a multiple of the alignment level:
+
+
+@itemize *
+
+@item
+beginnings of declarations (except record component declarations)
+and statements;
+
+@item
+beginnings of the structural components of compound statements;
+
+@item
+@code{end} keyword that completes the declaration of a program unit declaration
+or body or that completes a compound statement.
+@end itemize
+
+Full line comments must be
+aligned with the @code{--} starting on a column that is a multiple of
+the alignment level, or they may be aligned the same way as the following
+non-blank line (this is useful when full line comments appear in the middle
+of a statement, or they may be aligned with the source line on the previous
+non-blank line.
+@end table
+
+@geindex -gnatya (gcc)
+
+
+@table @asis
+
+@item @code{-gnatya}
+
+`Check attribute casing.'
+
+Attribute names, including the case of keywords such as @code{digits}
+used as attributes names, must be written in mixed case, that is, the
+initial letter and any letter following an underscore must be uppercase.
+All other letters must be lowercase.
+@end table
+
+@geindex -gnatyA (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyA}
+
+`Use of array index numbers in array attributes.'
+
+When using the array attributes First, Last, Range,
+or Length, the index number must be omitted for one-dimensional arrays
+and is required for multi-dimensional arrays.
+@end table
+
+@geindex -gnatyb (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyb}
+
+`Blanks not allowed at statement end.'
+
+Trailing blanks are not allowed at the end of statements. The purpose of this
+rule, together with h (no horizontal tabs), is to enforce a canonical format
+for the use of blanks to separate source tokens.
+@end table
+
+@geindex -gnatyB (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyB}
+
+`Check Boolean operators.'
+
+The use of AND/OR operators is not permitted except in the cases of modular
+operands, array operands, and simple stand-alone boolean variables or
+boolean constants. In all other cases @code{and then}/@cite{or else} are
+required.
+@end table
+
+@geindex -gnatyc (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyc}
+
+`Check comments, double space.'
+
+Comments must meet the following set of rules:
+
+
+@itemize *
+
+@item
+The @code{--} that starts the column must either start in column one,
+or else at least one blank must precede this sequence.
+
+@item
+Comments that follow other tokens on a line must have at least one blank
+following the @code{--} at the start of the comment.
+
+@item
+Full line comments must have at least two blanks following the
+@code{--} that starts the comment, with the following exceptions.
+
+@item
+A line consisting only of the @code{--} characters, possibly preceded
+by blanks is permitted.
+
+@item
+A comment starting with @code{--x} where @code{x} is a special character
+is permitted.
+This allows proper processing of the output from specialized tools
+such as @code{gnatprep} (where @code{--!} is used) and in earlier versions of the SPARK
+annotation
+language (where @code{--#} is used). For the purposes of this rule, a
+special character is defined as being in one of the ASCII ranges
+@code{16#21#...16#2F#} or @code{16#3A#...16#3F#}.
+Note that this usage is not permitted
+in GNAT implementation units (i.e., when @code{-gnatg} is used).
+
+@item
+A line consisting entirely of minus signs, possibly preceded by blanks, is
+permitted. This allows the construction of box comments where lines of minus
+signs are used to form the top and bottom of the box.
+
+@item
+A comment that starts and ends with @code{--} is permitted as long as at
+least one blank follows the initial @code{--}. Together with the preceding
+rule, this allows the construction of box comments, as shown in the following
+example:
+
+@example
+---------------------------
+-- This is a box comment --
+-- with two text lines. --
+---------------------------
+@end example
+@end itemize
+@end table
+
+@geindex -gnatyC (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyC}
+
+`Check comments, single space.'
+
+This is identical to @code{c} except that only one space
+is required following the @code{--} of a comment instead of two.
+@end table
+
+@geindex -gnatyd (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyd}
+
+`Check no DOS line terminators present.'
+
+All lines must be terminated by a single ASCII.LF
+character (in particular the DOS line terminator sequence CR/LF is not
+allowed).
+@end table
+
+@geindex -gnatyD (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyD}
+
+`Check declared identifiers in mixed case.'
+
+Declared identifiers must be in mixed case, as in
+This_Is_An_Identifier. Use -gnatyr in addition to ensure
+that references match declarations.
+@end table
+
+@geindex -gnatye (gcc)
+
+
+@table @asis
+
+@item @code{-gnatye}
+
+`Check end/exit labels.'
+
+Optional labels on @code{end} statements ending subprograms and on
+@code{exit} statements exiting named loops, are required to be present.
+@end table
+
+@geindex -gnatyf (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyf}
+
+`No form feeds or vertical tabs.'
+
+Neither form feeds nor vertical tab characters are permitted
+in the source text.
+@end table
+
+@geindex -gnatyg (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyg}
+
+`GNAT style mode.'
+
+The set of style check switches is set to match that used by the GNAT sources.
+This may be useful when developing code that is eventually intended to be
+incorporated into GNAT. Currently this is equivalent to @code{-gnatyydISux})
+but additional style switches may be added to this set in the future without
+advance notice.
+@end table
+
+@geindex -gnatyh (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyh}
+
+`No horizontal tabs.'
+
+Horizontal tab characters are not permitted in the source text.
+Together with the b (no blanks at end of line) check, this
+enforces a canonical form for the use of blanks to separate
+source tokens.
+@end table
+
+@geindex -gnatyi (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyi}
+
+`Check if-then layout.'
+
+The keyword @code{then} must appear either on the same
+line as corresponding @code{if}, or on a line on its own, lined
+up under the @code{if}.
+@end table
+
+@geindex -gnatyI (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyI}
+
+`check mode IN keywords.'
+
+Mode @code{in} (the default mode) is not
+allowed to be given explicitly. @code{in out} is fine,
+but not @code{in} on its own.
+@end table
+
+@geindex -gnatyk (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyk}
+
+`Check keyword casing.'
+
+All keywords must be in lower case (with the exception of keywords
+such as @code{digits} used as attribute names to which this check
+does not apply). A single error is reported for each line breaking
+this rule even if multiple casing issues exist on a same line.
+@end table
+
+@geindex -gnatyl (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyl}
+
+`Check layout.'
+
+Layout of statement and declaration constructs must follow the
+recommendations in the Ada Reference Manual, as indicated by the
+form of the syntax rules. For example an @code{else} keyword must
+be lined up with the corresponding @code{if} keyword.
+
+There are two respects in which the style rule enforced by this check
+option are more liberal than those in the Ada Reference Manual. First
+in the case of record declarations, it is permissible to put the
+@code{record} keyword on the same line as the @code{type} keyword, and
+then the @code{end} in @code{end record} must line up under @code{type}.
+This is also permitted when the type declaration is split on two lines.
+For example, any of the following three layouts is acceptable:
+
+@example
+type q is record
+ a : integer;
+ b : integer;
+end record;
+
+type q is
+ record
+ a : integer;
+ b : integer;
+ end record;
+
+type q is
+ record
+ a : integer;
+ b : integer;
+end record;
+@end example
+
+Second, in the case of a block statement, a permitted alternative
+is to put the block label on the same line as the @code{declare} or
+@code{begin} keyword, and then line the @code{end} keyword up under
+the block label. For example both the following are permitted:
+
+@example
+Block : declare
+ A : Integer := 3;
+begin
+ Proc (A, A);
+end Block;
+
+Block :
+ declare
+ A : Integer := 3;
+ begin
+ Proc (A, A);
+ end Block;
+@end example
+
+The same alternative format is allowed for loops. For example, both of
+the following are permitted:
+
+@example
+Clear : while J < 10 loop
+ A (J) := 0;
+end loop Clear;
+
+Clear :
+ while J < 10 loop
+ A (J) := 0;
+ end loop Clear;
+@end example
+@end table
+
+@geindex -gnatyLnnn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyL}
+
+`Set maximum nesting level.'
+
+The maximum level of nesting of constructs (including subprograms, loops,
+blocks, packages, and conditionals) may not exceed the given value
+`nnn'. A value of zero disconnects this style check.
+@end table
+
+@geindex -gnatym (gcc)
+
+
+@table @asis
+
+@item @code{-gnatym}
+
+`Check maximum line length.'
+
+The length of source lines must not exceed 79 characters, including
+any trailing blanks. The value of 79 allows convenient display on an
+80 character wide device or window, allowing for possible special
+treatment of 80 character lines. Note that this count is of
+characters in the source text. This means that a tab character counts
+as one character in this count and a wide character sequence counts as
+a single character (however many bytes are needed in the encoding).
+@end table
+
+@geindex -gnatyMnnn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyM}
+
+`Set maximum line length.'
+
+The length of lines must not exceed the
+given value `nnn'. The maximum value that can be specified is 32767.
+If neither style option for setting the line length is used, then the
+default is 255. This also controls the maximum length of lexical elements,
+where the only restriction is that they must fit on a single line.
+@end table
+
+@geindex -gnatyn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyn}
+
+`Check casing of entities in Standard.'
+
+Any identifier from Standard must be cased
+to match the presentation in the Ada Reference Manual (for example,
+@code{Integer} and @code{ASCII.NUL}).
+@end table
+
+@geindex -gnatyN (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyN}
+
+`Turn off all style checks.'
+
+All style check options are turned off.
+@end table
+
+@geindex -gnatyo (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyo}
+
+`Check order of subprogram bodies.'
+
+All subprogram bodies in a given scope
+(e.g., a package body) must be in alphabetical order. The ordering
+rule uses normal Ada rules for comparing strings, ignoring casing
+of letters, except that if there is a trailing numeric suffix, then
+the value of this suffix is used in the ordering (e.g., Junk2 comes
+before Junk10).
+@end table
+
+@geindex -gnatyO (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyO}
+
+`Check that overriding subprograms are explicitly marked as such.'
+
+This applies to all subprograms of a derived type that override a primitive
+operation of the type, for both tagged and untagged types. In particular,
+the declaration of a primitive operation of a type extension that overrides
+an inherited operation must carry an overriding indicator. Another case is
+the declaration of a function that overrides a predefined operator (such
+as an equality operator).
+@end table
+
+@geindex -gnatyp (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyp}
+
+`Check pragma casing.'
+
+Pragma names must be written in mixed case, that is, the
+initial letter and any letter following an underscore must be uppercase.
+All other letters must be lowercase. An exception is that SPARK_Mode is
+allowed as an alternative for Spark_Mode.
+@end table
+
+@geindex -gnatyr (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyr}
+
+`Check references.'
+
+All identifier references must be cased in the same way as the
+corresponding declaration. No specific casing style is imposed on
+identifiers. The only requirement is for consistency of references
+with declarations.
+@end table
+
+@geindex -gnatys (gcc)
+
+
+@table @asis
+
+@item @code{-gnatys}
+
+`Check separate specs.'
+
+Separate declarations (‘specs’) are required for subprograms (a
+body is not allowed to serve as its own declaration). The only
+exception is that parameterless library level procedures are
+not required to have a separate declaration. This exception covers
+the most frequent form of main program procedures.
+@end table
+
+@geindex -gnatyS (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyS}
+
+`Check no statements after then/else.'
+
+No statements are allowed
+on the same line as a @code{then} or @code{else} keyword following the
+keyword in an @code{if} statement. @code{or else} and @code{and then} are not
+affected, and a special exception allows a pragma to appear after @code{else}.
+@end table
+
+@geindex -gnatyt (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyt}
+
+`Check token spacing.'
+
+The following token spacing rules are enforced:
+
+
+@itemize *
+
+@item
+The keywords @code{abs} and @code{not} must be followed by a space.
+
+@item
+The token @code{=>} must be surrounded by spaces.
+
+@item
+The token @code{<>} must be preceded by a space or a left parenthesis.
+
+@item
+Binary operators other than @code{**} must be surrounded by spaces.
+There is no restriction on the layout of the @code{**} binary operator.
+
+@item
+Colon must be surrounded by spaces.
+
+@item
+Colon-equal (assignment, initialization) must be surrounded by spaces.
+
+@item
+Comma must be the first non-blank character on the line, or be
+immediately preceded by a non-blank character, and must be followed
+by a space.
+
+@item
+If the token preceding a left parenthesis ends with a letter or digit, then
+a space must separate the two tokens.
+
+@item
+If the token following a right parenthesis starts with a letter or digit, then
+a space must separate the two tokens.
+
+@item
+A right parenthesis must either be the first non-blank character on
+a line, or it must be preceded by a non-blank character.
+
+@item
+A semicolon must not be preceded by a space, and must not be followed by
+a non-blank character.
+
+@item
+A unary plus or minus may not be followed by a space.
+
+@item
+A vertical bar must be surrounded by spaces.
+@end itemize
+
+Exactly one blank (and no other white space) must appear between
+a @code{not} token and a following @code{in} token.
+@end table
+
+@geindex -gnatyu (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyu}
+
+`Check unnecessary blank lines.'
+
+Unnecessary blank lines are not allowed. A blank line is considered
+unnecessary if it appears at the end of the file, or if more than
+one blank line occurs in sequence.
+@end table
+
+@geindex -gnatyx (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyx}
+
+`Check extra parentheses.'
+
+Unnecessary extra level of parentheses (C-style) are not allowed
+around conditions in @code{if} statements, @code{while} statements and
+@code{exit} statements.
+@end table
+
+@geindex -gnatyy (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyy}
+
+`Set all standard style check options.'
+
+This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
+options enabled with the exception of @code{-gnatyB}, @code{-gnatyd},
+@code{-gnatyI}, @code{-gnatyLnnn}, @code{-gnatyo}, @code{-gnatyO},
+@code{-gnatyS}, @code{-gnatyu}, and @code{-gnatyx}.
+@end table
+
+@geindex -gnaty- (gcc)
+
+
+@table @asis
+
+@item @code{-gnaty-}
+
+`Remove style check options.'
+
+This causes any subsequent options in the string to act as canceling the
+corresponding style check option. To cancel maximum nesting level control,
+use the @code{L} parameter without any integer value after that, because any
+digit following `-' in the parameter string of the @code{-gnaty}
+option will be treated as canceling the indentation check. The same is true
+for the @code{M} parameter. @code{y} and @code{N} parameters are not
+allowed after `-'.
+@end table
+
+@geindex -gnaty+ (gcc)
+
+
+@table @asis
+
+@item @code{-gnaty+}
+
+`Enable style check options.'
+
+This causes any subsequent options in the string to enable the corresponding
+style check option. That is, it cancels the effect of a previous -,
+if any.
+@end table
+
+@c end of switch description (leave this comment to ease automatic parsing for
+
+@c GNAT Studio)
+
+In the above rules, appearing in column one is always permitted, that is,
+counts as meeting either a requirement for a required preceding space,
+or as meeting a requirement for no preceding space.
+
+Appearing at the end of a line is also always permitted, that is, counts
+as meeting either a requirement for a following space, or as meeting
+a requirement for no following space.
+
+If any of these style rules is violated, a message is generated giving
+details on the violation. The initial characters of such messages are
+always ‘@cite{(style)}’. Note that these messages are treated as warning
+messages, so they normally do not prevent the generation of an object
+file. The @code{-gnatwe} switch can be used to treat warning messages,
+including style messages, as fatal errors.
+
+The switch @code{-gnaty} on its own (that is not
+followed by any letters or digits) is equivalent
+to the use of @code{-gnatyy} as described above, that is all
+built-in standard style check options are enabled.
+
+The switch @code{-gnatyN} clears any previously set style checks.
+
+@node Run-Time Checks,Using gcc for Syntax Checking,Style Checking,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{f5}@anchor{gnat_ugn/building_executable_programs_with_gnat run-time-checks}@anchor{ea}
+@subsection Run-Time Checks
+
+
+@geindex Division by zero
+
+@geindex Access before elaboration
+
+@geindex Checks
+@geindex division by zero
+
+@geindex Checks
+@geindex access before elaboration
+
+@geindex Checks
+@geindex stack overflow checking
+
+By default, the following checks are suppressed: stack overflow
+checks, and checks for access before elaboration on subprogram
+calls. All other checks, including overflow checks, range checks and
+array bounds checks, are turned on by default. The following @code{gcc}
+switches refine this default behavior.
+
+@geindex -gnatp (gcc)
+
+
+@table @asis
+
+@item @code{-gnatp}
+
+@geindex Suppressing checks
+
+@geindex Checks
+@geindex suppressing
+
+This switch causes the unit to be compiled
+as though @code{pragma Suppress (All_checks)}
+had been present in the source. Validity checks are also eliminated (in
+other words @code{-gnatp} also implies @code{-gnatVn}.
+Use this switch to improve the performance
+of the code at the expense of safety in the presence of invalid data or
+program bugs.
+
+Note that when checks are suppressed, the compiler is allowed, but not
+required, to omit the checking code. If the run-time cost of the
+checking code is zero or near-zero, the compiler will generate it even
+if checks 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. Another case in which checks may not be
+eliminated is when they are embedded in certain run-time routines such
+as math library routines.
+
+Of course, run-time checks are omitted whenever the compiler can prove
+that they will not fail, whether or not checks are suppressed.
+
+Note that if you suppress a check that would have failed, program
+execution is erroneous, which means the behavior is totally
+unpredictable. The program might crash, or print wrong answers, or
+do anything else. It might even do exactly what you wanted it to do
+(and then it might start failing mysteriously next week or next
+year). The compiler will generate code based on the assumption that
+the condition being checked is true, which can result in erroneous
+execution if that assumption is wrong.
+
+The checks subject to suppression include all the checks defined by the Ada
+standard, the additional implementation defined checks @code{Alignment_Check},
+@code{Duplicated_Tag_Check}, @code{Predicate_Check}, @code{Container_Checks}, @code{Tampering_Check},
+and @code{Validity_Check}, as well as any checks introduced using @code{pragma Check_Name}.
+Note that @code{Atomic_Synchronization} is not automatically suppressed by use of this option.
+
+If the code depends on certain checks being active, you can use
+pragma @code{Unsuppress} either as a configuration pragma or as
+a local pragma to make sure that a specified check is performed
+even if @code{gnatp} is specified.
+
+The @code{-gnatp} switch has no effect if a subsequent
+@code{-gnat-p} switch appears.
+@end table
+
+@geindex -gnat-p (gcc)
+
+@geindex Suppressing checks
+
+@geindex Checks
+@geindex suppressing
+
+@geindex Suppress
+
+
+@table @asis
+
+@item @code{-gnat-p}
+
+This switch cancels the effect of a previous @code{gnatp} switch.
+@end table
+
+@geindex -gnato?? (gcc)
+
+@geindex Overflow checks
+
+@geindex Overflow mode
+
+@geindex Check
+@geindex overflow
+
+
+@table @asis
+
+@item @code{-gnato??}
+
+This switch controls the mode used for computing intermediate
+arithmetic integer operations, and also enables overflow checking.
+For a full description of overflow mode and checking control, see
+the ‘Overflow Check Handling in GNAT’ appendix in this
+User’s Guide.
+
+Overflow checks are always enabled by this switch. The argument
+controls the mode, using the codes
+
+
+@table @asis
+
+@item `1 = STRICT'
+
+In STRICT mode, intermediate operations are always done using the
+base type, and overflow checking ensures that the result is within
+the base type range.
+
+@item `2 = MINIMIZED'
+
+In MINIMIZED mode, overflows in intermediate operations are avoided
+where possible by using a larger integer type for the computation
+(typically @code{Long_Long_Integer}). Overflow checking ensures that
+the result fits in this larger integer type.
+
+@item `3 = ELIMINATED'
+
+In ELIMINATED mode, overflows in intermediate operations are avoided
+by using multi-precision arithmetic. In this case, overflow checking
+has no effect on intermediate operations (since overflow is impossible).
+@end table
+
+If two digits are present after @code{-gnato} then the first digit
+sets the mode for expressions outside assertions, and the second digit
+sets the mode for expressions within assertions. Here assertions is used
+in the technical sense (which includes for example precondition and
+postcondition expressions).
+
+If one digit is present, the corresponding mode is applicable to both
+expressions within and outside assertion expressions.
+
+If no digits are present, the default is to enable overflow checks
+and set STRICT mode for both kinds of expressions. This is compatible
+with the use of @code{-gnato} in previous versions of GNAT.
+
+@geindex Machine_Overflows
+
+Note that the @code{-gnato??} switch does not affect the code generated
+for any floating-point operations; it applies only to integer semantics.
+For floating-point, GNAT has the @code{Machine_Overflows}
+attribute set to @code{False} and the normal mode of operation is to
+generate IEEE NaN and infinite values on overflow or invalid operations
+(such as dividing 0.0 by 0.0).
+
+The reason that we distinguish overflow checking from other kinds of
+range constraint checking is that a failure of an overflow check, unlike
+for example the failure of a range check, can result in an incorrect
+value, but cannot cause random memory destruction (like an out of range
+subscript), or a wild jump (from an out of range case value). Overflow
+checking is also quite expensive in time and space, since in general it
+requires the use of double length arithmetic.
+
+Note again that the default is @code{-gnato11} (equivalent to @code{-gnato1}),
+so overflow checking is performed in STRICT mode by default.
+@end table
+
+@geindex -gnatE (gcc)
+
+@geindex Elaboration checks
+
+@geindex Check
+@geindex elaboration
+
+
+@table @asis
+
+@item @code{-gnatE}
+
+Enables dynamic checks for access-before-elaboration
+on subprogram calls and generic instantiations.
+Note that @code{-gnatE} is not necessary for safety, because in the
+default mode, GNAT ensures statically that the checks would not fail.
+For full details of the effect and use of this switch,
+@ref{c7,,Compiling with gcc}.
+@end table
+
+@geindex -fstack-check (gcc)
+
+@geindex Stack Overflow Checking
+
+@geindex Checks
+@geindex stack overflow checking
+
+
+@table @asis
+
+@item @code{-fstack-check}
+
+Activates stack overflow checking. For full details of the effect and use of
+this switch see @ref{e5,,Stack Overflow Checking}.
+@end table
+
+@geindex Unsuppress
+
+The setting of these switches only controls the default setting of the
+checks. You may modify them using either @code{Suppress} (to remove
+checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in
+the program source.
+
+@node Using gcc for Syntax Checking,Using gcc for Semantic Checking,Run-Time Checks,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id20}@anchor{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{f7}
+@subsection Using @code{gcc} for Syntax Checking
+
+
+@geindex -gnats (gcc)
+
+
+@table @asis
+
+@item @code{-gnats}
+
+The @code{s} stands for ‘syntax’.
+
+Run GNAT in syntax checking only mode. For
+example, the command
+
+@example
+$ gcc -c -gnats x.adb
+@end example
+
+compiles file @code{x.adb} in syntax-check-only mode. You can check a
+series of files in a single command
+, and can use wildcards to specify such a group of files.
+Note that you must specify the @code{-c} (compile
+only) flag in addition to the @code{-gnats} flag.
+
+You may use other switches in conjunction with @code{-gnats}. In
+particular, @code{-gnatl} and @code{-gnatv} are useful to control the
+format of any generated error messages.
+
+When the source file is empty or contains only empty lines and/or comments,
+the output is a warning:
+
+@example
+$ gcc -c -gnats -x ada toto.txt
+toto.txt:1:01: warning: empty file, contains no compilation units
+$
+@end example
+
+Otherwise, the output is simply the error messages, if any. No object file or
+ALI file is generated by a syntax-only compilation. Also, no units other
+than the one specified are accessed. For example, if a unit @code{X}
+`with's a unit @code{Y}, compiling unit @code{X} in syntax
+check only mode does not access the source file containing unit
+@code{Y}.
+
+@geindex Multiple units
+@geindex syntax checking
+
+Normally, GNAT allows only a single unit in a source file. However, this
+restriction does not apply in syntax-check-only mode, and it is possible
+to check a file containing multiple compilation units concatenated
+together. This is primarily used by the @code{gnatchop} utility
+(@ref{1d,,Renaming Files with gnatchop}).
+@end table
+
+@node Using gcc for Semantic Checking,Compiling Different Versions of Ada,Using gcc for Syntax Checking,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id21}@anchor{f8}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{f9}
+@subsection Using @code{gcc} for Semantic Checking
+
+
+@geindex -gnatc (gcc)
+
+
+@table @asis
+
+@item @code{-gnatc}
+
+The @code{c} stands for ‘check’.
+Causes the compiler to operate in semantic check mode,
+with full checking for all illegalities specified in the
+Ada Reference Manual, but without generation of any object code
+(no object file is generated).
+
+Because dependent files must be accessed, you must follow the GNAT
+semantic restrictions on file structuring to operate in this mode:
+
+
+@itemize *
+
+@item
+The needed source files must be accessible
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
+
+@item
+Each file must contain only one compilation unit.
+
+@item
+The file name and unit name must match (@ref{3b,,File Naming Rules}).
+@end itemize
+
+The output consists of error messages as appropriate. No object file is
+generated. An @code{ALI} file is generated for use in the context of
+cross-reference tools, but this file is marked as not being suitable
+for binding (since no object file is generated).
+The checking corresponds exactly to the notion of
+legality in the Ada Reference Manual.
+
+Any unit can be compiled in semantics-checking-only mode, including
+units that would not normally be compiled (subunits,
+and specifications where a separate body is present).
+@end table
+
+@node Compiling Different Versions of Ada,Character Set Control,Using gcc for Semantic Checking,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-different-versions-of-ada}@anchor{6}@anchor{gnat_ugn/building_executable_programs_with_gnat id22}@anchor{fa}
+@subsection Compiling Different Versions of Ada
+
+
+The switches described in this section allow you to explicitly specify
+the version of the Ada language that your programs are written in.
+The default mode is Ada 2012,
+but you can also specify Ada 95, Ada 2005 mode, or
+indicate Ada 83 compatibility mode.
+
+@geindex Compatibility with Ada 83
+
+@geindex -gnat83 (gcc)
+
+@geindex ACVC
+@geindex Ada 83 tests
+
+@geindex Ada 83 mode
+
+
+@table @asis
+
+@item @code{-gnat83} (Ada 83 Compatibility Mode)
+
+Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
+specifies that the program is to be compiled in Ada 83 mode. With
+@code{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83
+semantics where this can be done easily.
+It is not possible to guarantee this switch does a perfect
+job; some subtle tests, such as are
+found in earlier ACVC tests (and that have been removed from the ACATS suite
+for Ada 95), might not compile correctly.
+Nevertheless, this switch may be useful in some circumstances, for example
+where, due to contractual reasons, existing code needs to be maintained
+using only Ada 83 features.
+
+With few exceptions (most notably the need to use @code{<>} on
+unconstrained
+@geindex Generic formal parameters
+generic formal parameters,
+the use of the new Ada 95 / Ada 2005
+reserved words, and the use of packages
+with optional bodies), it is not necessary to specify the
+@code{-gnat83} switch when compiling Ada 83 programs, because, with rare
+exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
+a correct Ada 83 program is usually also a correct program
+in these later versions of the language standard. For further information
+please refer to the `Compatibility and Porting Guide' chapter in the
+@cite{GNAT Reference Manual}.
+@end table
+
+@geindex -gnat95 (gcc)
+
+@geindex Ada 95 mode
+
+
+@table @asis
+
+@item @code{-gnat95} (Ada 95 mode)
+
+This switch directs the compiler to implement the Ada 95 version of the
+language.
+Since Ada 95 is almost completely upwards
+compatible with Ada 83, Ada 83 programs may generally be compiled using
+this switch (see the description of the @code{-gnat83} switch for further
+information about Ada 83 mode).
+If an Ada 2005 program is compiled in Ada 95 mode,
+uses of the new Ada 2005 features will cause error
+messages or warnings.
+
+This switch also can be used to cancel the effect of a previous
+@code{-gnat83}, @code{-gnat05/2005}, or @code{-gnat12/2012}
+switch earlier in the command line.
+@end table
+
+@geindex -gnat05 (gcc)
+
+@geindex -gnat2005 (gcc)
+
+@geindex Ada 2005 mode
+
+
+@table @asis
+
+@item @code{-gnat05} or @code{-gnat2005} (Ada 2005 mode)
+
+This switch directs the compiler to implement the Ada 2005 version of the
+language, as documented in the official Ada standards document.
+Since Ada 2005 is almost completely upwards
+compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
+may generally be compiled using this switch (see the description of the
+@code{-gnat83} and @code{-gnat95} switches for further
+information).
+@end table
+
+@geindex -gnat12 (gcc)
+
+@geindex -gnat2012 (gcc)
+
+@geindex Ada 2012 mode
+
+
+@table @asis
+
+@item @code{-gnat12} or @code{-gnat2012} (Ada 2012 mode)
+
+This switch directs the compiler to implement the Ada 2012 version of the
+language (also the default).
+Since Ada 2012 is almost completely upwards
+compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
+Ada 83 and Ada 95 programs
+may generally be compiled using this switch (see the description of the
+@code{-gnat83}, @code{-gnat95}, and @code{-gnat05/2005} switches
+for further information).
+@end table
+
+@geindex -gnat2022 (gcc)
+
+@geindex Ada 2022 mode
+
+
+@table @asis
+
+@item @code{-gnat2022} (Ada 2022 mode)
+
+This switch directs the compiler to implement the Ada 2022 version of the
+language.
+@end table
+
+@geindex -gnatX0 (gcc)
+
+@geindex Ada language extensions
+
+@geindex GNAT extensions
+
+
+@table @asis
+
+@item @code{-gnatX0} (Enable GNAT Extensions)
+
+This switch directs the compiler to implement the latest version of the
+language (currently Ada 2022) and also to enable certain GNAT implementation
+extensions that are not part of any Ada standard. For a full list of these
+extensions, see the GNAT reference manual, @code{Pragma Extensions_Allowed}.
+@end table
+
+@geindex -gnatX (gcc)
+
+@geindex Ada language extensions
+
+@geindex GNAT extensions
+
+
+@table @asis
+
+@item @code{-gnatX} (Enable core GNAT Extensions)
+
+This switch is similar to -gnatX0 except that only some, not all, of the
+GNAT-defined language extensions are enabled. For a list of the
+extensions enabled by this switch, see the GNAT reference manual
+@code{Pragma Extensions_Allowed} and the description of that pragma’s
+“On” (as opposed to “All”) argument.
+@end table
+
+@node Character Set Control,File Naming Control,Compiling Different Versions of Ada,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{31}@anchor{gnat_ugn/building_executable_programs_with_gnat id23}@anchor{fb}
+@subsection Character Set Control
+
+
+@geindex -gnati (gcc)
+
+
+@table @asis
+
+@item @code{-gnati`c'}
+
+Normally GNAT recognizes the Latin-1 character set in source program
+identifiers, as described in the Ada Reference Manual.
+This switch causes
+GNAT to recognize alternate character sets in identifiers. @code{c} is a
+single character indicating the character set, as follows:
+
+
+@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+`1'
+
+@tab
+
+ISO 8859-1 (Latin-1) identifiers
+
+@item
+
+`2'
+
+@tab
+
+ISO 8859-2 (Latin-2) letters allowed in identifiers
+
+@item
+
+`3'
+
+@tab
+
+ISO 8859-3 (Latin-3) letters allowed in identifiers
+
+@item
+
+`4'
+
+@tab
+
+ISO 8859-4 (Latin-4) letters allowed in identifiers
+
+@item
+
+`5'
+
+@tab
+
+ISO 8859-5 (Cyrillic) letters allowed in identifiers
+
+@item
+
+`9'
+
+@tab
+
+ISO 8859-15 (Latin-9) letters allowed in identifiers
+
+@item
+
+`p'
+
+@tab
+
+IBM PC letters (code page 437) allowed in identifiers
+
+@item
+
+`8'
+
+@tab
+
+IBM PC letters (code page 850) allowed in identifiers
+
+@item
+
+`f'
+
+@tab
+
+Full upper-half codes allowed in identifiers
+
+@item
+
+`n'
+
+@tab
+
+No upper-half codes allowed in identifiers
+
+@item
+
+`w'
+
+@tab
+
+Wide-character codes (that is, codes greater than 255)
+allowed in identifiers
+
+@end multitable
+
+
+See @ref{23,,Foreign Language Representation} for full details on the
+implementation of these character sets.
+@end table
+
+@geindex -gnatW (gcc)
+
+
+@table @asis
+
+@item @code{-gnatW`e'}
+
+Specify the method of encoding for wide characters.
+@code{e} is one of the following:
+
+
+@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+`h'
+
+@tab
+
+Hex encoding (brackets coding also recognized)
+
+@item
+
+`u'
+
+@tab
+
+Upper half encoding (brackets encoding also recognized)
+
+@item
+
+`s'
+
+@tab
+
+Shift/JIS encoding (brackets encoding also recognized)
+
+@item
+
+`e'
+
+@tab
+
+EUC encoding (brackets encoding also recognized)
+
+@item
+
+`8'
+
+@tab
+
+UTF-8 encoding (brackets encoding also recognized)
+
+@item
+
+`b'
+
+@tab
+
+Brackets encoding only (default value)
+
+@end multitable
+
+
+For full details on these encoding
+methods see @ref{37,,Wide_Character Encodings}.
+Note that brackets coding is always accepted, even if one of the other
+options is specified, so for example @code{-gnatW8} specifies that both
+brackets and UTF-8 encodings will be recognized. The units that are
+with’ed directly or indirectly will be scanned using the specified
+representation scheme, and so if one of the non-brackets scheme is
+used, it must be used consistently throughout the program. However,
+since brackets encoding is always recognized, it may be conveniently
+used in standard libraries, allowing these libraries to be used with
+any of the available coding schemes.
+
+Note that brackets encoding only applies to program text. Within comments,
+brackets are considered to be normal graphic characters, and bracket sequences
+are never recognized as wide characters.
+
+If no @code{-gnatW?} parameter is present, then the default
+representation is normally Brackets encoding only. However, if the
+first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
+byte order mark or BOM for UTF-8), then these three characters are
+skipped and the default representation for the file is set to UTF-8.
+
+Note that the wide character representation that is specified (explicitly
+or by default) for the main program also acts as the default encoding used
+for Wide_Text_IO files if not specifically overridden by a WCEM form
+parameter.
+@end table
+
+When no @code{-gnatW?} is specified, then characters (other than wide
+characters represented using brackets notation) are treated as 8-bit
+Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
+and ASCII format effectors (CR, LF, HT, VT). Other lower half control
+characters in the range 16#00#..16#1F# are not accepted in program text
+or in comments. Upper half control characters (16#80#..16#9F#) are rejected
+in program text, but allowed and ignored in comments. Note in particular
+that the Next Line (NEL) character whose encoding is 16#85# is not recognized
+as an end of line in this default mode. If your source program contains
+instances of the NEL character used as a line terminator,
+you must use UTF-8 encoding for the whole
+source program. In default mode, all lines must be ended by a standard
+end of line sequence (CR, CR/LF, or LF).
+
+Note that the convention of simply accepting all upper half characters in
+comments means that programs that use standard ASCII for program text, but
+UTF-8 encoding for comments are accepted in default mode, providing that the
+comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
+This is a common mode for many programs with foreign language comments.
+
+@node File Naming Control,Subprogram Inlining Control,Character Set Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat file-naming-control}@anchor{fc}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{fd}
+@subsection File Naming Control
+
+
+@geindex -gnatk (gcc)
+
+
+@table @asis
+
+@item @code{-gnatk`n'}
+
+Activates file name ‘krunching’. @code{n}, a decimal integer in the range
+1-999, indicates the maximum allowable length of a file name (not
+including the @code{.ads} or @code{.adb} extension). The default is not
+to enable file name krunching.
+
+For the source file naming rules, @ref{3b,,File Naming Rules}.
+@end table
+
+@node Subprogram Inlining Control,Auxiliary Output Control,File Naming Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{fe}@anchor{gnat_ugn/building_executable_programs_with_gnat subprogram-inlining-control}@anchor{ff}
+@subsection Subprogram Inlining Control
+
+
+@geindex -gnatn (gcc)
+
+
+@table @asis
+
+@item @code{-gnatn[12]}
+
+The @code{n} here is intended to suggest the first syllable of the word ‘inline’.
+GNAT recognizes and processes @code{Inline} pragmas. However, for inlining to
+actually occur, optimization must be enabled and, by default, inlining of
+subprograms across units is not performed. If you want to additionally
+enable inlining of subprograms specified by pragma @code{Inline} across units,
+you must also specify this switch.
+
+In the absence of this switch, GNAT does not attempt inlining across units
+and does not access the bodies of subprograms for which @code{pragma Inline} is
+specified if they are not in the current unit.
+
+You can optionally specify the inlining level: 1 for moderate inlining across
+units, which is a good compromise between compilation times and performances
+at run time, or 2 for full inlining across units, which may bring about
+longer compilation times. If no inlining level is specified, the compiler will
+pick it based on the optimization level: 1 for @code{-O1}, @code{-O2} or
+@code{-Os} and 2 for @code{-O3}.
+
+If you specify this switch the compiler will access these bodies,
+creating an extra source dependency for the resulting object file, and
+where possible, the call will be inlined.
+For further details on when inlining is possible
+see @ref{100,,Inlining of Subprograms}.
+@end table
+
+@geindex -gnatN (gcc)
+
+
+@table @asis
+
+@item @code{-gnatN}
+
+This switch activates front-end inlining which also
+generates additional dependencies.
+
+When using a gcc-based back end, then the use of
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
+@end table
+
+@node Auxiliary Output Control,Debugging Control,Subprogram Inlining Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat auxiliary-output-control}@anchor{101}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{102}
+@subsection Auxiliary Output Control
+
+
+@geindex -gnatu (gcc)
+
+
+@table @asis
+
+@item @code{-gnatu}
+
+Print a list of units required by this compilation on @code{stdout}.
+The listing includes all units on which the unit being compiled depends
+either directly or indirectly.
+@end table
+
+@geindex -pass-exit-codes (gcc)
+
+
+@table @asis
+
+@item @code{-pass-exit-codes}
+
+If this switch is not used, the exit code returned by @code{gcc} when
+compiling multiple files indicates whether all source files have
+been successfully used to generate object files or not.
+
+When @code{-pass-exit-codes} is used, @code{gcc} exits with an extended
+exit status and allows an integrated development environment to better
+react to a compilation failure. Those exit status are:
+
+
+@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+`5'
+
+@tab
+
+There was an error in at least one source file.
+
+@item
+
+`3'
+
+@tab
+
+At least one source file did not generate an object file.
+
+@item
+
+`2'
+
+@tab
+
+The compiler died unexpectedly (internal error for example).
+
+@item
+
+`0'
+
+@tab
+
+An object file has been generated for every source file.
+
+@end multitable
+
+@end table
+
+@node Debugging Control,Exception Handling Control,Auxiliary Output Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{103}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{104}
+@subsection Debugging Control
+
+
+@quotation
+
+@geindex Debugging options
+@end quotation
+
+@geindex -gnatd (gcc)
+
+
+@table @asis
+
+@item @code{-gnatd`x'}
+
+Activate internal debugging switches. @code{x} is a letter or digit, or
+string of letters or digits, which specifies the type of debugging
+outputs desired. Normally these are used only for internal development
+or system debugging purposes. You can find full documentation for these
+switches in the body of the @code{Debug} unit in the compiler source
+file @code{debug.adb}.
+@end table
+
+@geindex -gnatG (gcc)
+
+
+@table @asis
+
+@item @code{-gnatG[=`nn']}
+
+This switch causes the compiler to generate auxiliary output containing
+a pseudo-source listing of the generated expanded code. Like most Ada
+compilers, GNAT works by first transforming the high level Ada code into
+lower level constructs. For example, tasking operations are transformed
+into calls to the tasking run-time routines. A unique capability of GNAT
+is to list this expanded code in a form very close to normal Ada source.
+This is very useful in understanding the implications of various Ada
+usage on the efficiency of the generated code. There are many cases in
+Ada (e.g., the use of controlled types), where simple Ada statements can
+generate a lot of run-time code. By using @code{-gnatG} you can identify
+these cases, and consider whether it may be desirable to modify the coding
+approach to improve efficiency.
+
+The optional parameter @code{nn} if present after -gnatG specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+
+The format of the output is very similar to standard Ada source, and is
+easily understood by an Ada programmer. The following special syntactic
+additions correspond to low level features used in the generated code that
+do not have any exact analogies in pure Ada source form. The following
+is a partial list of these special constructions. See the spec
+of package @code{Sprint} in file @code{sprint.ads} for a full list.
+
+@geindex -gnatL (gcc)
+
+If the switch @code{-gnatL} is used in conjunction with
+@code{-gnatG}, then the original source lines are interspersed
+in the expanded source (as comment lines with the original line number).
+
+
+@table @asis
+
+@item @code{new @var{xxx} [storage_pool = @var{yyy}]}
+
+Shows the storage pool being used for an allocator.
+
+@item @code{at end @var{procedure-name};}
+
+Shows the finalization (cleanup) procedure for a scope.
+
+@item @code{(if @var{expr} then @var{expr} else @var{expr})}
+
+Conditional expression equivalent to the @code{x?y:z} construction in C.
+
+@item @code{@var{target}^(@var{source})}
+
+A conversion with floating-point truncation instead of rounding.
+
+@item @code{@var{target}?(@var{source})}
+
+A conversion that bypasses normal Ada semantic checking. In particular
+enumeration types and fixed-point types are treated simply as integers.
+
+@item @code{@var{target}?^(@var{source})}
+
+Combines the above two cases.
+@end table
+
+@code{@var{x} #/ @var{y}}
+
+@code{@var{x} #mod @var{y}}
+
+@code{@var{x} # @var{y}}
+
+
+@table @asis
+
+@item @code{@var{x} #rem @var{y}}
+
+A division or multiplication of fixed-point values which are treated as
+integers without any kind of scaling.
+
+@item @code{free @var{expr} [storage_pool = @var{xxx}]}
+
+Shows the storage pool associated with a @code{free} statement.
+
+@item @code{[subtype or type declaration]}
+
+Used to list an equivalent declaration for an internally generated
+type that is referenced elsewhere in the listing.
+
+@item @code{freeze @var{type-name} [@var{actions}]}
+
+Shows the point at which @code{type-name} is frozen, with possible
+associated actions to be performed at the freeze point.
+
+@item @code{reference @var{itype}}
+
+Reference (and hence definition) to internal type @code{itype}.
+
+@item @code{@var{function-name}! (@var{arg}, @var{arg}, @var{arg})}
+
+Intrinsic function call.
+
+@item @code{@var{label-name} : label}
+
+Declaration of label @code{labelname}.
+
+@item @code{#$ @var{subprogram-name}}
+
+An implicit call to a run-time support routine
+(to meet the requirement of H.3.1(9) in a
+convenient manner).
+
+@item @code{@var{expr} && @var{expr} && @var{expr} ... && @var{expr}}
+
+A multiple concatenation (same effect as @code{expr} & @code{expr} &
+@code{expr}, but handled more efficiently).
+
+@item @code{[constraint_error]}
+
+Raise the @code{Constraint_Error} exception.
+
+@item @code{@var{expression}'reference}
+
+A pointer to the result of evaluating @{expression@}.
+
+@item @code{@var{target-type}!(@var{source-expression})}
+
+An unchecked conversion of @code{source-expression} to @code{target-type}.
+
+@item @code{[@var{numerator}/@var{denominator}]}
+
+Used to represent internal real literals (that) have no exact
+representation in base 2-16 (for example, the result of compile time
+evaluation of the expression 1.0/27.0).
+@end table
+@end table
+
+@geindex -gnatD (gcc)
+
+
+@table @asis
+
+@item @code{-gnatD[=nn]}
+
+When used in conjunction with @code{-gnatG}, this switch causes
+the expanded source, as described above for
+@code{-gnatG} to be written to files with names
+@code{xxx.dg}, where @code{xxx} is the normal file name,
+instead of to the standard output file. For
+example, if the source file name is @code{hello.adb}, then a file
+@code{hello.adb.dg} will be written. The debugging
+information generated by the @code{gcc} @code{-g} switch
+will refer to the generated @code{xxx.dg} file. This allows
+you to do source level debugging using the generated code which is
+sometimes useful for complex code, for example to find out exactly
+which part of a complex construction raised an exception. This switch
+also suppresses generation of cross-reference information (see
+@code{-gnatx}) since otherwise the cross-reference information
+would refer to the @code{.dg} file, which would cause
+confusion since this is not the original source file.
+
+Note that @code{-gnatD} actually implies @code{-gnatG}
+automatically, so it is not necessary to give both options.
+In other words @code{-gnatD} is equivalent to @code{-gnatDG}).
+
+@geindex -gnatL (gcc)
+
+If the switch @code{-gnatL} is used in conjunction with
+@code{-gnatDG}, then the original source lines are interspersed
+in the expanded source (as comment lines with the original line number).
+
+The optional parameter @code{nn} if present after -gnatD specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+@end table
+
+@geindex -gnatr (gcc)
+
+@geindex pragma Restrictions
+
+
+@table @asis
+
+@item @code{-gnatr}
+
+This switch causes pragma Restrictions to be treated as Restriction_Warnings
+so that violation of restrictions causes warnings rather than illegalities.
+This is useful during the development process when new restrictions are added
+or investigated. The switch also causes pragma Profile to be treated as
+Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
+restriction warnings rather than restrictions.
+@end table
+
+@geindex -gnatR (gcc)
+
+
+@table @asis
+
+@item @code{-gnatR[0|1|2|3|4][e][j][m][s]}
+
+This switch controls output from the compiler of a listing showing
+representation information for declared types, objects and subprograms.
+For @code{-gnatR0}, no information is output (equivalent to omitting
+the @code{-gnatR} switch). For @code{-gnatR1} (which is the default,
+so @code{-gnatR} with no parameter has the same effect), size and
+alignment information is listed for declared array and record types.
+
+For @code{-gnatR2}, size and alignment information is listed for all
+declared types and objects. The @code{Linker_Section} is also listed for any
+entity for which the @code{Linker_Section} is set explicitly or implicitly (the
+latter case occurs for objects of a type for which a @code{Linker_Section}
+is set).
+
+For @code{-gnatR3}, symbolic expressions for values that are computed
+at run time for records are included. These symbolic expressions have
+a mostly obvious format with #n being used to represent the value of the
+n’th discriminant. See source files @code{repinfo.ads/adb} in the
+GNAT sources for full details on the format of @code{-gnatR3} output.
+
+For @code{-gnatR4}, information for relevant compiler-generated types
+is also listed, i.e. when they are structurally part of other declared
+types and objects.
+
+If the switch is followed by an @code{e} (e.g. @code{-gnatR2e}), then
+extended representation information for record sub-components of records
+is included.
+
+If the switch is followed by an @code{m} (e.g. @code{-gnatRm}), then
+subprogram conventions and parameter passing mechanisms for all the
+subprograms are included.
+
+If the switch is followed by a @code{j} (e.g., @code{-gnatRj}), then
+the output is in the JSON data interchange format specified by the
+ECMA-404 standard. The semantic description of this JSON output is
+available in the specification of the Repinfo unit present in the
+compiler sources.
+
+If the switch is followed by an @code{s} (e.g., @code{-gnatR3s}), then
+the output is to a file with the name @code{file.rep} where @code{file} is
+the name of the corresponding source file, except if @code{j} is also
+specified, in which case the file name is @code{file.json}.
+
+Note that it is possible for record components to have zero size. In
+this case, the component clause uses an obvious extension of permitted
+Ada syntax, for example @code{at 0 range 0 .. -1}.
+@end table
+
+@geindex -gnatS (gcc)
+
+
+@table @asis
+
+@item @code{-gnatS}
+
+The use of the switch @code{-gnatS} for an
+Ada compilation will cause the compiler to output a
+representation of package Standard in a form very
+close to standard Ada. It is not quite possible to
+do this entirely in standard Ada (since new
+numeric base types cannot be created in standard
+Ada), but the output is easily
+readable to any Ada programmer, and is useful to
+determine the characteristics of target dependent
+types in package Standard.
+@end table
+
+@geindex -gnatx (gcc)
+
+
+@table @asis
+
+@item @code{-gnatx}
+
+Normally the compiler generates full cross-referencing information in
+the @code{ALI} file. This information is used by a number of tools.
+The @code{-gnatx} switch suppresses this information. This saves some space
+and may slightly speed up compilation, but means that tools depending
+on this information cannot be used.
+@end table
+
+@geindex -fgnat-encodings (gcc)
+
+
+@table @asis
+
+@item @code{-fgnat-encodings=[all|gdb|minimal]}
+
+This switch controls the balance between GNAT encodings and standard DWARF
+emitted in the debug information.
+
+Historically, old debug formats like stabs were not powerful enough to
+express some Ada types (for instance, variant records or fixed-point types).
+To work around this, GNAT introduced proprietary encodings that embed the
+missing information (“GNAT encodings”).
+
+Recent versions of the DWARF debug information format are now able to
+correctly describe most of these Ada constructs (“standard DWARF”). As
+third-party tools started to use this format, GNAT has been enhanced to
+generate it. However, most tools (including GDB) are still relying on GNAT
+encodings.
+
+To support all tools, GNAT needs to be versatile about the balance between
+generation of GNAT encodings and standard DWARF. This is what
+@code{-fgnat-encodings} is about.
+
+
+@itemize *
+
+@item
+@code{=all}: Emit all GNAT encodings, and then emit as much standard DWARF as
+possible so it does not conflict with GNAT encodings.
+
+@item
+@code{=gdb}: Emit as much standard DWARF as possible as long as the current
+GDB handles it. Emit GNAT encodings for the rest.
+
+@item
+@code{=minimal}: Emit as much standard DWARF as possible and emit GNAT
+encodings for the rest.
+@end itemize
+@end table
+
+@node Exception Handling Control,Units to Sources Mapping Files,Debugging Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{106}
+@subsection Exception Handling Control
+
+
+GNAT uses two methods for handling exceptions at run time. The
+@code{setjmp/longjmp} method saves the context when entering
+a frame with an exception handler. Then when an exception is
+raised, the context can be restored immediately, without the
+need for tracing stack frames. This method provides very fast
+exception propagation, but introduces significant overhead for
+the use of exception handlers, even if no exception is raised.
+
+The other approach is called ‘zero cost’ exception handling.
+With this method, the compiler builds static tables to describe
+the exception ranges. No dynamic code is required when entering
+a frame containing an exception handler. When an exception is
+raised, the tables are used to control a back trace of the
+subprogram invocation stack to locate the required exception
+handler. This method has considerably poorer performance for
+the propagation of exceptions, but there is no overhead for
+exception handlers if no exception is raised. Note that in this
+mode and in the context of mixed Ada and C/C++ programming,
+to propagate an exception through a C/C++ code, the C/C++ code
+must be compiled with the @code{-funwind-tables} GCC’s
+option.
+
+The following switches may be used to control which of the
+two exception handling methods is used.
+
+@geindex --RTS=sjlj (gnatmake)
+
+
+@table @asis
+
+@item @code{--RTS=sjlj}
+
+This switch causes the setjmp/longjmp run-time (when available) to be used
+for exception handling. If the default
+mechanism for the target is zero cost exceptions, then
+this switch can be used to modify this default, and must be
+used for all units in the partition.
+This option is rarely used. One case in which it may be
+advantageous is if you have an application where exception
+raising is common and the overall performance of the
+application is improved by favoring exception propagation.
+@end table
+
+@geindex --RTS=zcx (gnatmake)
+
+@geindex Zero Cost Exceptions
+
+
+@table @asis
+
+@item @code{--RTS=zcx}
+
+This switch causes the zero cost approach to be used
+for exception handling. If this is the default mechanism for the
+target (see below), then this switch is unneeded. If the default
+mechanism for the target is setjmp/longjmp exceptions, then
+this switch can be used to modify this default, and must be
+used for all units in the partition.
+This option can only be used if the zero cost approach
+is available for the target in use, otherwise it will generate an error.
+@end table
+
+The same option @code{--RTS} must be used both for @code{gcc}
+and @code{gnatbind}. Passing this option to @code{gnatmake}
+(@ref{ce,,Switches for gnatmake}) will ensure the required consistency
+through the compilation and binding steps.
+
+@node Units to Sources Mapping Files,Code Generation Control,Exception Handling Control,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat id29}@anchor{107}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{e8}
+@subsection Units to Sources Mapping Files
+
+
+@geindex -gnatem (gcc)
+
+
+@table @asis
+
+@item @code{-gnatem=`path'}
+
+A mapping file is a way to communicate to the compiler two mappings:
+from unit names to file names (without any directory information) and from
+file names to path names (with full directory information). These mappings
+are used by the compiler to short-circuit the path search.
+
+The use of mapping files is not required for correct operation of the
+compiler, but mapping files can improve efficiency, particularly when
+sources are read over a slow network connection. In normal operation,
+you need not be concerned with the format or use of mapping files,
+and the @code{-gnatem} switch is not a switch that you would use
+explicitly. It is intended primarily for use by automatic tools such as
+@code{gnatmake} running under the project file facility. The
+description here of the format of mapping files is provided
+for completeness and for possible use by other tools.
+
+A mapping file is a sequence of sets of three lines. In each set, the
+first line is the unit name, in lower case, with @code{%s} appended
+for specs and @code{%b} appended for bodies; the second line is the
+file name; and the third line is the path name.
+
+Example:
+
+@example
+main%b
+main.2.ada
+/gnat/project1/sources/main.2.ada
+@end example
+
+When the switch @code{-gnatem} is specified, the compiler will
+create in memory the two mappings from the specified file. If there is
+any problem (nonexistent file, truncated file or duplicate entries),
+no mapping will be created.
+
+Several @code{-gnatem} switches may be specified; however, only the
+last one on the command line will be taken into account.
+
+When using a project file, @code{gnatmake} creates a temporary
+mapping file and communicates it to the compiler using this switch.
+@end table
+
+@node Code Generation Control,,Units to Sources Mapping Files,Compiler Switches
+@anchor{gnat_ugn/building_executable_programs_with_gnat code-generation-control}@anchor{108}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{109}
+@subsection Code Generation Control
+
+
+The GCC technology provides a wide range of target dependent
+@code{-m} switches for controlling
+details of code generation with respect to different versions of
+architectures. This includes variations in instruction sets (e.g.,
+different members of the power pc family), and different requirements
+for optimal arrangement of instructions (e.g., different members of
+the x86 family). The list of available @code{-m} switches may be
+found in the GCC documentation.
+
+Use of these @code{-m} switches may in some cases result in improved
+code performance.
+
+The GNAT technology is tested and qualified without any
+@code{-m} switches,
+so generally the most reliable approach is to avoid the use of these
+switches. However, we generally expect most of these switches to work
+successfully with GNAT, and many customers have reported successful
+use of these options.
+
+Our general advice is to avoid the use of @code{-m} switches unless
+special needs lead to requirements in this area. In particular,
+there is no point in using @code{-m} switches to improve performance
+unless you actually see a performance improvement.
+
+@node Linker Switches,Binding with gnatbind,Compiler Switches,Building Executable Programs with GNAT
+@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{10a}@anchor{gnat_ugn/building_executable_programs_with_gnat linker-switches}@anchor{10b}
+@section Linker Switches
+
+
+Linker switches can be specified after @code{-largs} builder switch.
+
+@geindex -fuse-ld=name
+
+
+@table @asis
+
+@item @code{-fuse-ld=`name'}
+
+Linker to be used. The default is @code{bfd} for @code{ld.bfd}; @code{gold}
+(for @code{ld.gold}) and @code{mold} (for @code{ld.mold}) are more
+recent and faster alternatives, but only available on GNU/Linux
+platforms.
+
+@end table
+
+@node Binding with gnatbind,Linking with gnatlink,Linker Switches,Building Executable Programs with GNAT
+@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{c8}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{10c}
+@section Binding with @code{gnatbind}
+
+
+@geindex gnatbind
+
+This chapter describes the GNAT binder, @code{gnatbind}, which is used
+to bind compiled GNAT objects.
+
+The @code{gnatbind} program performs four separate functions:
+
+
+@itemize *
+
+@item
+Checks that a program is consistent, in accordance with the rules in
+Chapter 10 of the Ada Reference Manual. In particular, error
+messages are generated if a program uses inconsistent versions of a
+given unit.
+
+@item
+Checks that an acceptable order of elaboration exists for the program
+and issues an error message if it cannot find an order of elaboration
+that satisfies the rules in Chapter 10 of the Ada Language Manual.
+
+@item
+Generates a main program incorporating the given elaboration order.
+This program is a small Ada package (body and spec) that
+must be subsequently compiled
+using the GNAT compiler. The necessary compilation step is usually
+performed automatically by @code{gnatlink}. The two most important
+functions of this program
+are to call the elaboration routines of units in an appropriate order
+and to call the main program.
+
+@item
+Determines the set of object files required by the given main program.
+This information is output in the forms of comments in the generated program,
+to be read by the @code{gnatlink} utility used to link the Ada application.
+@end itemize
+
+@menu
+* Running gnatbind::
+* Switches for gnatbind::
+* Command-Line Access::
+* Search Paths for gnatbind::
+* Examples of gnatbind Usage::
+
+@end menu
+
+@node Running gnatbind,Switches for gnatbind,,Binding with gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{10d}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{10e}
+@subsection Running @code{gnatbind}
+
+
+The form of the @code{gnatbind} command is
+
+@example
+$ gnatbind [ switches ] mainprog[.ali] [ switches ]
+@end example
+
+where @code{mainprog.adb} is the Ada file containing the main program
+unit body. @code{gnatbind} constructs an Ada
+package in two files whose names are
+@code{b~mainprog.ads}, and @code{b~mainprog.adb}.
+For example, if given the
+parameter @code{hello.ali}, for a main program contained in file
+@code{hello.adb}, the binder output files would be @code{b~hello.ads}
+and @code{b~hello.adb}.
+
+When doing consistency checking, the binder takes into consideration
+any source files it can locate. For example, if the binder determines
+that the given main program requires the package @code{Pack}, whose
+@code{.ALI}
+file is @code{pack.ali} and whose corresponding source spec file is
+@code{pack.ads}, it attempts to locate the source file @code{pack.ads}
+(using the same search path conventions as previously described for the
+@code{gcc} command). If it can locate this source file, it checks that
+the time stamps
+or source checksums of the source and its references to in @code{ALI} files
+match. In other words, any @code{ALI} files that mentions this spec must have
+resulted from compiling this version of the source file (or in the case
+where the source checksums match, a version close enough that the
+difference does not matter).
+
+@geindex Source files
+@geindex use by binder
+
+The effect of this consistency checking, which includes source files, is
+that the binder ensures that the program is consistent with the latest
+version of the source files that can be located at bind time. Editing a
+source file without compiling files that depend on the source file cause
+error messages to be generated by the binder.
+
+For example, suppose you have a main program @code{hello.adb} and a
+package @code{P}, from file @code{p.ads} and you perform the following
+steps:
+
+
+@itemize *
+
+@item
+Enter @code{gcc -c hello.adb} to compile the main program.
+
+@item
+Enter @code{gcc -c p.ads} to compile package @code{P}.
+
+@item
+Edit file @code{p.ads}.
+
+@item
+Enter @code{gnatbind hello}.
+@end itemize
+
+At this point, the file @code{p.ali} contains an out-of-date time stamp
+because the file @code{p.ads} has been edited. The attempt at binding
+fails, and the binder generates the following error messages:
+
+@example
+error: "hello.adb" must be recompiled ("p.ads" has been modified)
+error: "p.ads" has been modified and must be recompiled
+@end example
+
+Now both files must be recompiled as indicated, and then the bind can
+succeed, generating a main program. You need not normally be concerned
+with the contents of this file, but for reference purposes a sample
+binder output file is given in @ref{e,,Example of Binder Output File}.
+
+In most normal usage, the default mode of @code{gnatbind} which is to
+generate the main package in Ada, as described in the previous section.
+In particular, this means that any Ada programmer can read and understand
+the generated main program. It can also be debugged just like any other
+Ada code provided the @code{-g} switch is used for
+@code{gnatbind} and @code{gnatlink}.
+
+@node Switches for gnatbind,Command-Line Access,Running gnatbind,Binding with gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{10f}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{110}
+@subsection Switches for @code{gnatbind}
+
+
+The following switches are available with @code{gnatbind}; details will
+be presented in subsequent sections.
+
+@geindex --version (gnatbind)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display Copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatbind)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+@end table
+
+@geindex -a (gnatbind)
+
+
+@table @asis
+
+@item @code{-a}
+
+Indicates that, if supported by the platform, the adainit procedure should
+be treated as an initialisation routine by the linker (a constructor). This
+is intended to be used by the Project Manager to automatically initialize
+shared Stand-Alone Libraries.
+@end table
+
+@geindex -aO (gnatbind)
+
+
+@table @asis
+
+@item @code{-aO}
+
+Specify directory to be searched for ALI files.
+@end table
+
+@geindex -aI (gnatbind)
+
+
+@table @asis
+
+@item @code{-aI}
+
+Specify directory to be searched for source file.
+@end table
+
+@geindex -A (gnatbind)
+
+
+@table @asis
+
+@item @code{-A[=`filename']}
+
+Output ALI list (to standard output or to the named file).
+@end table
+
+@geindex -b (gnatbind)
+
+
+@table @asis
+
+@item @code{-b}
+
+Generate brief messages to @code{stderr} even if verbose mode set.
+@end table
+
+@geindex -c (gnatbind)
+
+
+@table @asis
+
+@item @code{-c}
+
+Check only, no generation of binder output file.
+@end table
+
+@geindex -dnn[k|m] (gnatbind)
+
+
+@table @asis
+
+@item @code{-d`nn'[k|m]}
+
+This switch can be used to change the default task stack size value
+to a specified size @code{nn}, which is expressed in bytes by default, or
+in kilobytes when suffixed with @code{k} or in megabytes when suffixed
+with @code{m}.
+In the absence of a @code{[k|m]} suffix, this switch is equivalent,
+in effect, to completing all task specs with
+
+@example
+pragma Storage_Size (nn);
+@end example
+
+When they do not already have such a pragma.
+@end table
+
+@geindex -D (gnatbind)
+
+
+@table @asis
+
+@item @code{-D`nn'[k|m]}
+
+Set the default secondary stack size to @code{nn}. The suffix indicates whether
+the size is in bytes (no suffix), kilobytes (@code{k} suffix) or megabytes
+(@code{m} suffix).
+
+The secondary stack holds objects of unconstrained types that are returned by
+functions, for example unconstrained Strings. The size of the secondary stack
+can be dynamic or fixed depending on the target.
+
+For most targets, the secondary stack grows on demand and is implemented as
+a chain of blocks in the heap. In this case, the default secondary stack size
+determines the initial size of the secondary stack for each task and the
+smallest amount the secondary stack can grow by.
+
+For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
+fixed. This switch can be used to change the default size of these stacks.
+The default secondary stack size can be overridden on a per-task basis if
+individual tasks have different secondary stack requirements. This is
+achieved through the Secondary_Stack_Size aspect that takes the size of the
+secondary stack in bytes.
+@end table
+
+@geindex -e (gnatbind)
+
+
+@table @asis
+
+@item @code{-e}
+
+Output complete list of elaboration-order dependencies.
+@end table
+
+@geindex -Ea (gnatbind)
+
+
+@table @asis
+
+@item @code{-Ea}
+
+Store tracebacks in exception occurrences when the target supports it.
+The “a” is for “address”; tracebacks will contain hexadecimal addresses,
+unless symbolic tracebacks are enabled.
+
+See also the packages @code{GNAT.Traceback} and
+@code{GNAT.Traceback.Symbolic} for more information.
+Note that on x86 ports, you must not use @code{-fomit-frame-pointer}
+@code{gcc} option.
+@end table
+
+@geindex -Es (gnatbind)
+
+
+@table @asis
+
+@item @code{-Es}
+
+Store tracebacks in exception occurrences when the target supports it.
+The “s” is for “symbolic”; symbolic tracebacks are enabled.
+@end table
+
+@geindex -E (gnatbind)
+
+
+@table @asis
+
+@item @code{-E}
+
+Currently the same as @code{-Ea}.
+@end table
+
+@geindex -f (gnatbind)
+
+
+@table @asis
+
+@item @code{-f`elab-order'}
+
+Force elaboration order. For further details see @ref{111,,Elaboration Control}
+and @ref{f,,Elaboration Order Handling in GNAT}.
+@end table
+
+@geindex -F (gnatbind)
+
+
+@table @asis
+
+@item @code{-F}
+
+Force the checks of elaboration flags. @code{gnatbind} does not normally
+generate checks of elaboration flags for the main executable, except when
+a Stand-Alone Library is used. However, there are cases when this cannot be
+detected by gnatbind. An example is importing an interface of a Stand-Alone
+Library through a pragma Import and only specifying through a linker switch
+this Stand-Alone Library. This switch is used to guarantee that elaboration
+flag checks are generated.
+@end table
+
+@geindex -h (gnatbind)
+
+
+@table @asis
+
+@item @code{-h}
+
+Output usage (help) information.
+@end table
+
+@geindex -H (gnatbind)
+
+
+@table @asis
+
+@item @code{-H}
+
+Legacy elaboration order model enabled. For further details see
+@ref{f,,Elaboration Order Handling in GNAT}.
+@end table
+
+@geindex -H32 (gnatbind)
+
+
+@table @asis
+
+@item @code{-H32}
+
+Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types).
+For further details see @ref{112,,Dynamic Allocation Control}.
+@end table
+
+@geindex -H64 (gnatbind)
+
+@geindex __gnat_malloc
+
+
+@table @asis
+
+@item @code{-H64}
+
+Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types).
+For further details see @ref{112,,Dynamic Allocation Control}.
+
+@geindex -I (gnatbind)
+
+@item @code{-I}
+
+Specify directory to be searched for source and ALI files.
+
+@geindex -I- (gnatbind)
+
+@item @code{-I-}
+
+Do not look for sources in the current directory where @code{gnatbind} was
+invoked, and do not look for ALI files in the directory containing the
+ALI file named in the @code{gnatbind} command line.
+
+@geindex -k (gnatbind)
+
+@item @code{-k}
+
+Disable checking of elaboration flags. When using @code{-n}
+either explicitly or implicitly, @code{-F} is also implied,
+unless @code{-k} is used. This switch should be used with care
+and you should ensure manually that elaboration routines are not called
+twice unintentionally.
+
+@geindex -K (gnatbind)
+
+@item @code{-K}
+
+Give list of linker options specified for link.
+
+@geindex -l (gnatbind)
+
+@item @code{-l}
+
+Output chosen elaboration order.
+
+@geindex -L (gnatbind)
+
+@item @code{-L`xxx'}
+
+Bind the units for library building. In this case the @code{adainit} and
+@code{adafinal} procedures (@ref{a0,,Binding with Non-Ada Main Programs})
+are renamed to @code{@var{xxx}init} and
+@code{@var{xxx}final}.
+Implies -n.
+(@ref{2a,,GNAT and Libraries}, for more details.)
+
+@geindex -M (gnatbind)
+
+@item @code{-M`xyz'}
+
+Rename generated main program from main to xyz. This option is
+supported on cross environments only.
+
+@geindex -m (gnatbind)
+
+@item @code{-m`n'}
+
+Limit number of detected errors or warnings to @code{n}, where @code{n} is
+in the range 1..999999. The default value if no switch is
+given is 9999. If the number of warnings reaches this limit, then a
+message is output and further warnings are suppressed, the bind
+continues in this case. If the number of errors reaches this
+limit, then a message is output and the bind is abandoned.
+A value of zero means that no limit is enforced. The equal
+sign is optional.
+
+@geindex -minimal (gnatbind)
+
+@item @code{-minimal}
+
+Generate a binder file suitable for space-constrained applications. When
+active, binder-generated objects not required for program operation are no
+longer generated. `Warning:' this option comes with the following
+limitations:
+
+
+@itemize *
+
+@item
+Starting the program’s execution in the debugger will cause it to
+stop at the start of the @code{main} function instead of the main subprogram.
+This can be worked around by manually inserting a breakpoint on that
+subprogram and resuming the program’s execution until reaching that breakpoint.
+
+@item
+Programs using GNAT.Compiler_Version will not link.
+@end itemize
+
+@geindex -n (gnatbind)
+
+@item @code{-n}
+
+No main program.
+
+@geindex -nostdinc (gnatbind)
+
+@item @code{-nostdinc}
+
+Do not look for sources in the system default directory.
+
+@geindex -nostdlib (gnatbind)
+
+@item @code{-nostdlib}
+
+Do not look for library files in the system default directory.
+
+@geindex --RTS (gnatbind)
+
+@item @code{--RTS=`rts-path'}
+
+Specifies the default location of the run-time library. Same meaning as the
+equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}).
+
+@geindex -o (gnatbind)
+
+@item @code{-o `file'}
+
+Name the output file @code{file} (default is @code{b~`xxx}.adb`).
+Note that if this option is used, then linking must be done manually,
+gnatlink cannot be used.
+
+@geindex -O (gnatbind)
+
+@item @code{-O[=`filename']}
+
+Output object list (to standard output or to the named file).
+
+@geindex -p (gnatbind)
+
+@item @code{-p}
+
+Pessimistic (worst-case) elaboration order.
+
+@geindex -P (gnatbind)
+
+@item @code{-P}
+
+Generate binder file suitable for CodePeer.
+
+@geindex -R (gnatbind)
+
+@item @code{-R}
+
+Output closure source list, which includes all non-run-time units that are
+included in the bind.
+
+@geindex -Ra (gnatbind)
+
+@item @code{-Ra}
+
+Like @code{-R} but the list includes run-time units.
+
+@geindex -s (gnatbind)
+
+@item @code{-s}
+
+Require all source files to be present.
+
+@geindex -S (gnatbind)
+
+@item @code{-S`xxx'}
+
+Specifies the value to be used when detecting uninitialized scalar
+objects with pragma Initialize_Scalars.
+The @code{xxx} string specified with the switch is one of:
+
+
+@itemize *
+
+@item
+@code{in} for an invalid value.
+
+If zero is invalid for the discrete type in question,
+then the scalar value is set to all zero bits.
+For signed discrete types, the largest possible negative value of
+the underlying scalar is set (i.e. a one bit followed by all zero bits).
+For unsigned discrete types, the underlying scalar value is set to all
+one bits. For floating-point types, a NaN value is set
+(see body of package System.Scalar_Values for exact values).
+
+@item
+@code{lo} for low value.
+
+If zero is invalid for the discrete type in question,
+then the scalar value is set to all zero bits.
+For signed discrete types, the largest possible negative value of
+the underlying scalar is set (i.e. a one bit followed by all zero bits).
+For unsigned discrete types, the underlying scalar value is set to all
+zero bits. For floating-point, a small value is set
+(see body of package System.Scalar_Values for exact values).
+
+@item
+@code{hi} for high value.
+
+If zero is invalid for the discrete type in question,
+then the scalar value is set to all one bits.
+For signed discrete types, the largest possible positive value of
+the underlying scalar is set (i.e. a zero bit followed by all one bits).
+For unsigned discrete types, the underlying scalar value is set to all
+one bits. For floating-point, a large value is set
+(see body of package System.Scalar_Values for exact values).
+
+@item
+@code{xx} for hex value (two hex digits).
+
+The underlying scalar is set to a value consisting of repeated bytes, whose
+value corresponds to the given value. For example if @code{BF} is given,
+then a 32-bit scalar value will be set to the bit patterm @code{16#BFBFBFBF#}.
+@end itemize
+
+@geindex GNAT_INIT_SCALARS
+
+In addition, you can specify @code{-Sev} to indicate that the value is
+to be set at run time. In this case, the program will look for an environment
+variable of the form @code{GNAT_INIT_SCALARS=@var{yy}}, where @code{yy} is one
+of @code{in/lo/hi/@var{xx}} with the same meanings as above.
+If no environment variable is found, or if it does not have a valid value,
+then the default is @code{in} (invalid values).
+@end table
+
+@geindex -static (gnatbind)
+
+
+@table @asis
+
+@item @code{-static}
+
+Link against a static GNAT run-time.
+
+@geindex -shared (gnatbind)
+
+@item @code{-shared}
+
+Link against a shared GNAT run-time when available.
+
+@geindex -t (gnatbind)
+
+@item @code{-t}
+
+Tolerate time stamp and other consistency errors.
+
+@geindex -T (gnatbind)
+
+@item @code{-T`n'}
+
+Set the time slice value to @code{n} milliseconds. If the system supports
+the specification of a specific time slice value, then the indicated value
+is used. If the system does not support specific time slice values, but
+does support some general notion of round-robin scheduling, then any
+nonzero value will activate round-robin scheduling.
+
+A value of zero is treated specially. It turns off time
+slicing, and in addition, indicates to the tasking run-time that the
+semantics should match as closely as possible the Annex D
+requirements of the Ada RM, and in particular sets the default
+scheduling policy to @code{FIFO_Within_Priorities}.
+
+@geindex -u (gnatbind)
+
+@item @code{-u`n'}
+
+Enable dynamic stack usage, with @code{n} results stored and displayed
+at program termination. A result is generated when a task
+terminates. Results that can’t be stored are displayed on the fly, at
+task termination. This option is currently not supported on Itanium
+platforms. (See @ref{113,,Dynamic Stack Usage Analysis} for details.)
+
+@geindex -v (gnatbind)
+
+@item @code{-v}
+
+Verbose mode. Write error messages, header, summary output to
+@code{stdout}.
+
+@geindex -V (gnatbind)
+
+@item @code{-V`key'=`value'}
+
+Store the given association of @code{key} to @code{value} in the bind environment.
+Values stored this way can be retrieved at run time using
+@code{GNAT.Bind_Environment}.
+
+@geindex -w (gnatbind)
+
+@item @code{-w`x'}
+
+Warning mode; @code{x} = s/e for suppress/treat as error.
+
+@geindex -Wx (gnatbind)
+
+@item @code{-Wx`e'}
+
+Override default wide character encoding for standard Text_IO files.
+
+@geindex -x (gnatbind)
+
+@item @code{-x}
+
+Exclude source files (check object consistency only).
+
+@geindex -xdr (gnatbind)
+
+@item @code{-xdr}
+
+Use the target-independent XDR protocol for stream oriented attributes
+instead of the default implementation which is based on direct binary
+representations and is therefore target-and endianness-dependent.
+However it does not support 128-bit integer types and the exception
+@code{Ada.IO_Exceptions.Device_Error} is raised if any attempt is made
+at streaming 128-bit integer types with it.
+
+@geindex -Xnnn (gnatbind)
+
+@item @code{-X`nnn'}
+
+Set default exit status value, normally 0 for POSIX compliance.
+
+@geindex -y (gnatbind)
+
+@item @code{-y}
+
+Enable leap seconds support in @code{Ada.Calendar} and its children.
+
+@geindex -z (gnatbind)
+
+@item @code{-z}
+
+No main subprogram.
+@end table
+
+You may obtain this listing of switches by running @code{gnatbind} with
+no arguments.
+
+@menu
+* Consistency-Checking Modes::
+* Binder Error Message Control::
+* Elaboration Control::
+* Output Control::
+* Dynamic Allocation Control::
+* Binding with Non-Ada Main Programs::
+* Binding Programs with No Main Subprogram::
+
+@end menu
+
+@node Consistency-Checking Modes,Binder Error Message Control,,Switches for gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat consistency-checking-modes}@anchor{114}@anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{115}
+@subsubsection Consistency-Checking Modes
+
+
+As described earlier, by default @code{gnatbind} checks
+that object files are consistent with one another and are consistent
+with any source files it can locate. The following switches control binder
+access to sources.
+
+@quotation
+
+@geindex -s (gnatbind)
+@end quotation
+
+
+@table @asis
+
+@item @code{-s}
+
+Require source files to be present. In this mode, the binder must be
+able to locate all source files that are referenced, in order to check
+their consistency. In normal mode, if a source file cannot be located it
+is simply ignored. If you specify this switch, a missing source
+file is an error.
+
+@geindex -Wx (gnatbind)
+
+@item @code{-Wx`e'}
+
+Override default wide character encoding for standard Text_IO files.
+Normally the default wide character encoding method used for standard
+[Wide_[Wide_]]Text_IO files is taken from the encoding specified for
+the main source input (see description of switch
+@code{-gnatWx} for the compiler). The
+use of this switch for the binder (which has the same set of
+possible arguments) overrides this default as specified.
+
+@geindex -x (gnatbind)
+
+@item @code{-x}
+
+Exclude source files. In this mode, the binder only checks that ALI
+files are consistent with one another. Source files are not accessed.
+The binder runs faster in this mode, and there is still a guarantee that
+the resulting program is self-consistent.
+If a source file has been edited since it was last compiled, and you
+specify this switch, the binder will not detect that the object
+file is out of date with respect to the source file. Note that this is the
+mode that is automatically used by @code{gnatmake} because in this
+case the checking against sources has already been performed by
+@code{gnatmake} in the course of compilation (i.e., before binding).
+@end table
+
+@node Binder Error Message Control,Elaboration Control,Consistency-Checking Modes,Switches for gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{116}@anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{117}
+@subsubsection Binder Error Message Control
+
+
+The following switches provide control over the generation of error
+messages from the binder:
+
+@quotation
+
+@geindex -v (gnatbind)
+@end quotation
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose mode. In the normal mode, brief error messages are generated to
+@code{stderr}. If this switch is present, a header is written
+to @code{stdout} and any error messages are directed to @code{stdout}.
+All that is written to @code{stderr} is a brief summary message.
+
+@geindex -b (gnatbind)
+
+@item @code{-b}
+
+Generate brief error messages to @code{stderr} even if verbose mode is
+specified. This is relevant only when used with the
+@code{-v} switch.
+
+@geindex -m (gnatbind)
+
+@item @code{-m`n'}
+
+Limits the number of error messages to @code{n}, a decimal integer in the
+range 1-999. The binder terminates immediately if this limit is reached.
+
+@geindex -M (gnatbind)
+
+@item @code{-M`xxx'}
+
+Renames the generated main program from @code{main} to @code{xxx}.
+This is useful in the case of some cross-building environments, where
+the actual main program is separate from the one generated
+by @code{gnatbind}.
+
+@geindex -ws (gnatbind)
+
+@geindex Warnings
+
+@item @code{-ws}
+
+Suppress all warning messages.
+
+@geindex -we (gnatbind)
+
+@item @code{-we}
+
+Treat any warning messages as fatal errors.
+
+@geindex -t (gnatbind)
+
+@geindex Time stamp checks
+@geindex in binder
+
+@geindex Binder consistency checks
+
+@geindex Consistency checks
+@geindex in binder
+
+@item @code{-t}
+
+The binder performs a number of consistency checks including:
+
+
+@itemize *
+
+@item
+Check that time stamps of a given source unit are consistent
+
+@item
+Check that checksums of a given source unit are consistent
+
+@item
+Check that consistent versions of @code{GNAT} were used for compilation
+
+@item
+Check consistency of configuration pragmas as required
+@end itemize
+
+Normally failure of such checks, in accordance with the consistency
+requirements of the Ada Reference Manual, causes error messages to be
+generated which abort the binder and prevent the output of a binder
+file and subsequent link to obtain an executable.
+
+The @code{-t} switch converts these error messages
+into warnings, so that
+binding and linking can continue to completion even in the presence of such
+errors. The result may be a failed link (due to missing symbols), or a
+non-functional executable which has undefined semantics.
+
+@cartouche
+@quotation Note
+This means that @code{-t} should be used only in unusual situations,
+with extreme care.
+@end quotation
+@end cartouche
+@end table
+
+@node Elaboration Control,Output Control,Binder Error Message Control,Switches for gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{111}@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{118}
+@subsubsection Elaboration Control
+
+
+The following switches provide additional control over the elaboration
+order. For further details see @ref{f,,Elaboration Order Handling in GNAT}.
+
+@geindex -f (gnatbind)
+
+
+@table @asis
+
+@item @code{-f`elab-order'}
+
+Force elaboration order.
+
+@code{elab-order} should be the name of a “forced elaboration order file”, that
+is, a text file containing library item names, one per line. A name of the
+form “some.unit%s” or “some.unit (spec)” denotes the spec of Some.Unit. A
+name of the form “some.unit%b” or “some.unit (body)” denotes the body of
+Some.Unit. Each pair of lines is taken to mean that there is an elaboration
+dependence of the second line on the first. For example, if the file
+contains:
+
+@example
+this (spec)
+this (body)
+that (spec)
+that (body)
+@end example
+
+then the spec of This will be elaborated before the body of This, and the
+body of This will be elaborated before the spec of That, and the spec of That
+will be elaborated before the body of That. The first and last of these three
+dependences are already required by Ada rules, so this file is really just
+forcing the body of This to be elaborated before the spec of That.
+
+The given order must be consistent with Ada rules, or else @code{gnatbind} will
+give elaboration cycle errors. For example, if you say x (body) should be
+elaborated before x (spec), there will be a cycle, because Ada rules require
+x (spec) to be elaborated before x (body); you can’t have the spec and body
+both elaborated before each other.
+
+If you later add “with That;” to the body of This, there will be a cycle, in
+which case you should erase either “this (body)” or “that (spec)” from the
+above forced elaboration order file.
+
+Blank lines and Ada-style comments are ignored. Unit names that do not exist
+in the program are ignored. Units in the GNAT predefined library are also
+ignored.
+@end table
+
+@geindex -p (gnatbind)
+
+
+@table @asis
+
+@item @code{-p}
+
+Pessimistic elaboration order
+
+This switch is only applicable to the pre-20.x legacy elaboration models.
+The post-20.x elaboration model uses a more informed approach of ordering
+the units.
+
+Normally the binder attempts to choose an elaboration order that is likely to
+minimize the likelihood of an elaboration order error resulting in raising a
+@code{Program_Error} exception. This switch reverses the action of the binder,
+and requests that it deliberately choose an order that is likely to maximize
+the likelihood of an elaboration error. This is useful in ensuring
+portability and avoiding dependence on accidental fortuitous elaboration
+ordering.
+
+Normally it only makes sense to use the @code{-p} switch if dynamic
+elaboration checking is used (@code{-gnatE} switch used for compilation).
+This is because in the default static elaboration mode, all necessary
+@code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted.
+These implicit pragmas are still respected by the binder in @code{-p}
+mode, so a safe elaboration order is assured.
+
+Note that @code{-p} is not intended for production use; it is more for
+debugging/experimental use.
+@end table
+
+@node Output Control,Dynamic Allocation Control,Elaboration Control,Switches for gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{119}@anchor{gnat_ugn/building_executable_programs_with_gnat output-control}@anchor{11a}
+@subsubsection Output Control
+
+
+The following switches allow additional control over the output
+generated by the binder.
+
+@quotation
+
+@geindex -c (gnatbind)
+@end quotation
+
+
+@table @asis
+
+@item @code{-c}
+
+Check only. Do not generate the binder output file. In this mode the
+binder performs all error checks but does not generate an output file.
+
+@geindex -e (gnatbind)
+
+@item @code{-e}
+
+Output complete list of elaboration-order dependencies, showing the
+reason for each dependency. This output can be rather extensive but may
+be useful in diagnosing problems with elaboration order. The output is
+written to @code{stdout}.
+
+@geindex -h (gnatbind)
+
+@item @code{-h}
+
+Output usage information. The output is written to @code{stdout}.
+
+@geindex -K (gnatbind)
+
+@item @code{-K}
+
+Output linker options to @code{stdout}. Includes library search paths,
+contents of pragmas Ident and Linker_Options, and libraries added
+by @code{gnatbind}.
+
+@geindex -l (gnatbind)
+
+@item @code{-l}
+
+Output chosen elaboration order. The output is written to @code{stdout}.
+
+@geindex -O (gnatbind)
+
+@item @code{-O}
+
+Output full names of all the object files that must be linked to provide
+the Ada component of the program. The output is written to @code{stdout}.
+This list includes the files explicitly supplied and referenced by the user
+as well as implicitly referenced run-time unit files. The latter are
+omitted if the corresponding units reside in shared libraries. The
+directory names for the run-time units depend on the system configuration.
+
+@geindex -o (gnatbind)
+
+@item @code{-o `file'}
+
+Set name of output file to @code{file} instead of the normal
+@code{b~`mainprog}.adb` default. Note that @code{file} denote the Ada
+binder generated body filename.
+Note that if this option is used, then linking must be done manually.
+It is not possible to use gnatlink in this case, since it cannot locate
+the binder file.
+
+@geindex -r (gnatbind)
+
+@item @code{-r}
+
+Generate list of @code{pragma Restrictions} that could be applied to
+the current unit. This is useful for code audit purposes, and also may
+be used to improve code generation in some cases.
+@end table
+
+@node Dynamic Allocation Control,Binding with Non-Ada Main Programs,Output Control,Switches for gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat dynamic-allocation-control}@anchor{112}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{11b}
+@subsubsection Dynamic Allocation Control
+
+
+The heap control switches – @code{-H32} and @code{-H64} –
+determine whether dynamic allocation uses 32-bit or 64-bit memory.
+They only affect compiler-generated allocations via @code{__gnat_malloc};
+explicit calls to @code{malloc} and related functions from the C
+run-time library are unaffected.
+
+
+@table @asis
+
+@item @code{-H32}
+
+Allocate memory on 32-bit heap
+
+@item @code{-H64}
+
+Allocate memory on 64-bit heap. This is the default
+unless explicitly overridden by a @code{'Size} clause on the access type.
+@end table
+
+These switches are only effective on VMS platforms.
+
+@node Binding with Non-Ada Main Programs,Binding Programs with No Main Subprogram,Dynamic Allocation Control,Switches for gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-non-ada-main-programs}@anchor{a0}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{11c}
+@subsubsection Binding with Non-Ada Main Programs
+
+
+The description so far has assumed that the main
+program is in Ada, and that the task of the binder is to generate a
+corresponding function @code{main} that invokes this Ada main
+program. GNAT also supports the building of executable programs where
+the main program is not in Ada, but some of the called routines are
+written in Ada and compiled using GNAT (@ref{2c,,Mixed Language Programming}).
+The following switch is used in this situation:
+
+@quotation
+
+@geindex -n (gnatbind)
+@end quotation
+
+
+@table @asis
+
+@item @code{-n}
+
+No main program. The main program is not in Ada.
+@end table
+
+In this case, most of the functions of the binder are still required,
+but instead of generating a main program, the binder generates a file
+containing the following callable routines:
+
+@quotation
+
+@geindex adainit
+
+
+@table @asis
+
+@item @code{adainit}
+
+You must call this routine to initialize the Ada part of the program by
+calling the necessary elaboration routines. A call to @code{adainit} is
+required before the first call to an Ada subprogram.
+
+Note that it is assumed that the basic execution environment must be setup
+to be appropriate for Ada execution at the point where the first Ada
+subprogram is called. In particular, if the Ada code will do any
+floating-point operations, then the FPU must be setup in an appropriate
+manner. For the case of the x86, for example, full precision mode is
+required. The procedure GNAT.Float_Control.Reset may be used to ensure
+that the FPU is in the right state.
+@end table
+
+@geindex adafinal
+
+
+@table @asis
+
+@item @code{adafinal}
+
+You must call this routine to perform any library-level finalization
+required by the Ada subprograms. A call to @code{adafinal} is required
+after the last call to an Ada subprogram, and before the program
+terminates.
+@end table
+@end quotation
+
+@geindex -n (gnatbind)
+
+@geindex Binder
+@geindex multiple input files
+
+If the @code{-n} switch
+is given, more than one ALI file may appear on
+the command line for @code{gnatbind}. The normal @code{closure}
+calculation is performed for each of the specified units. Calculating
+the closure means finding out the set of units involved by tracing
+`with' references. The reason it is necessary to be able to
+specify more than one ALI file is that a given program may invoke two or
+more quite separate groups of Ada units.
+
+The binder takes the name of its output file from the last specified ALI
+file, unless overridden by the use of the @code{-o file}.
+
+@geindex -o (gnatbind)
+
+The output is an Ada unit in source form that can be compiled with GNAT.
+This compilation occurs automatically as part of the @code{gnatlink}
+processing.
+
+Currently the GNAT run-time requires a FPU using 80 bits mode
+precision. Under targets where this is not the default it is required to
+call GNAT.Float_Control.Reset before using floating point numbers (this
+include float computation, float input and output) in the Ada code. A
+side effect is that this could be the wrong mode for the foreign code
+where floating point computation could be broken after this call.
+
+@node Binding Programs with No Main Subprogram,,Binding with Non-Ada Main Programs,Switches for gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat binding-programs-with-no-main-subprogram}@anchor{11d}@anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{11e}
+@subsubsection Binding Programs with No Main Subprogram
+
+
+It is possible to have an Ada program which does not have a main
+subprogram. This program will call the elaboration routines of all the
+packages, then the finalization routines.
+
+The following switch is used to bind programs organized in this manner:
+
+@quotation
+
+@geindex -z (gnatbind)
+@end quotation
+
+
+@table @asis
+
+@item @code{-z}
+
+Normally the binder checks that the unit name given on the command line
+corresponds to a suitable main subprogram. When this switch is used,
+a list of ALI files can be given, and the execution of the program
+consists of elaboration of these units in an appropriate order. Note
+that the default wide character encoding method for standard Text_IO
+files is always set to Brackets if this switch is set (you can use
+the binder switch
+@code{-Wx} to override this default).
+@end table
+
+@node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{11f}@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{120}
+@subsection Command-Line Access
+
+
+The package @code{Ada.Command_Line} provides access to the command-line
+arguments and program name. In order for this interface to operate
+correctly, the two variables
+
+@example
+int gnat_argc;
+char **gnat_argv;
+@end example
+
+@geindex gnat_argv
+
+@geindex gnat_argc
+
+are declared in one of the GNAT library routines. These variables must
+be set from the actual @code{argc} and @code{argv} values passed to the
+main program. With no `n' present, @code{gnatbind}
+generates the C main program to automatically set these variables.
+If the `n' switch is used, there is no automatic way to
+set these variables. If they are not set, the procedures in
+@code{Ada.Command_Line} will not be available, and any attempt to use
+them will raise @code{Constraint_Error}. If command line access is
+required, your main program must set @code{gnat_argc} and
+@code{gnat_argv} from the @code{argc} and @code{argv} values passed to
+it.
+
+@node Search Paths for gnatbind,Examples of gnatbind Usage,Command-Line Access,Binding with gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{121}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{76}
+@subsection Search Paths for @code{gnatbind}
+
+
+The binder takes the name of an ALI file as its argument and needs to
+locate source files as well as other ALI files to verify object consistency.
+
+For source files, it follows exactly the same search rules as @code{gcc}
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). For ALI files the
+directories searched are:
+
+
+@itemize *
+
+@item
+The directory containing the ALI file named in the command line, unless
+the switch @code{-I-} is specified.
+
+@item
+All directories specified by @code{-I}
+switches on the @code{gnatbind}
+command line, in the order given.
+
+@geindex ADA_PRJ_OBJECTS_FILE
+
+@item
+Each of the directories listed in the text file whose name is given
+by the
+@geindex ADA_PRJ_OBJECTS_FILE
+@geindex environment variable; ADA_PRJ_OBJECTS_FILE
+@code{ADA_PRJ_OBJECTS_FILE} environment variable.
+
+@geindex ADA_PRJ_OBJECTS_FILE
+@geindex environment variable; ADA_PRJ_OBJECTS_FILE
+@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the gnat
+driver when project files are used. It should not normally be set
+by other means.
+
+@geindex ADA_OBJECTS_PATH
+
+@item
+Each of the directories listed in the value of the
+@geindex ADA_OBJECTS_PATH
+@geindex environment variable; ADA_OBJECTS_PATH
+@code{ADA_OBJECTS_PATH} environment variable.
+Construct this value
+exactly as the
+@geindex PATH
+@geindex environment variable; PATH
+@code{PATH} environment variable: a list of directory
+names separated by colons (semicolons when working with the NT version
+of GNAT).
+
+@item
+The content of the @code{ada_object_path} file which is part of the GNAT
+installation tree and is used to store standard libraries such as the
+GNAT Run-Time Library (RTL) unless the switch @code{-nostdlib} is
+specified. See @ref{72,,Installing a library}
+@end itemize
+
+@geindex -I (gnatbind)
+
+@geindex -aI (gnatbind)
+
+@geindex -aO (gnatbind)
+
+In the binder the switch @code{-I}
+is used to specify both source and
+library file paths. Use @code{-aI}
+instead if you want to specify
+source paths only, and @code{-aO}
+if you want to specify library paths
+only. This means that for the binder
+@code{-I`dir'} is equivalent to
+@code{-aI`dir'}
+@code{-aO``dir'}.
+The binder generates the bind file (a C language source file) in the
+current working directory.
+
+@geindex Ada
+
+@geindex System
+
+@geindex Interfaces
+
+@geindex GNAT
+
+The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
+children make up the GNAT Run-Time Library, together with the package
+GNAT and its children, which contain a set of useful additional
+library functions provided by GNAT. The sources for these units are
+needed by the compiler and are kept together in one directory. The ALI
+files and object files generated by compiling the RTL are needed by the
+binder and the linker and are kept together in one directory, typically
+different from the directory containing the sources. In a normal
+installation, you need not specify these directory names when compiling
+or binding. Either the environment variables or the built-in defaults
+cause these files to be found.
+
+Besides simplifying access to the RTL, a major use of search paths is
+in compiling sources from multiple directories. This can make
+development environments much more flexible.
+
+@node Examples of gnatbind Usage,,Search Paths for gnatbind,Binding with gnatbind
+@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{122}@anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{123}
+@subsection Examples of @code{gnatbind} Usage
+
+
+Here are some examples of @code{gnatbind} invocations:
+
+@quotation
+
+@example
+gnatbind hello
+@end example
+
+The main program @code{Hello} (source program in @code{hello.adb}) is
+bound using the standard switch settings. The generated main program is
+@code{b~hello.adb}. This is the normal, default use of the binder.
+
+@example
+gnatbind hello -o mainprog.adb
+@end example
+
+The main program @code{Hello} (source program in @code{hello.adb}) is
+bound using the standard switch settings. The generated main program is
+@code{mainprog.adb} with the associated spec in
+@code{mainprog.ads}. Note that you must specify the body here not the
+spec. Note that if this option is used, then linking must be done manually,
+since gnatlink will not be able to find the generated file.
+@end quotation
+
+@node Linking with gnatlink,Using the GNU make Utility,Binding with gnatbind,Building Executable Programs with GNAT
+@anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{124}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{c9}
+@section Linking with @code{gnatlink}
+
+
+@geindex gnatlink
+
+This chapter discusses @code{gnatlink}, a tool that links
+an Ada program and builds an executable file. This utility
+invokes the system linker (via the @code{gcc} command)
+with a correct list of object files and library references.
+@code{gnatlink} automatically determines the list of files and
+references for the Ada part of a program. It uses the binder file
+generated by the @code{gnatbind} to determine this list.
+
+@menu
+* Running gnatlink::
+* Switches for gnatlink::
+
+@end menu
+
+@node Running gnatlink,Switches for gnatlink,,Linking with gnatlink
+@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{125}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{126}
+@subsection Running @code{gnatlink}
+
+
+The form of the @code{gnatlink} command is
+
+@example
+$ gnatlink [ switches ] mainprog [.ali]
+ [ non-Ada objects ] [ linker options ]
+@end example
+
+The arguments of @code{gnatlink} (switches, main @code{ALI} file,
+non-Ada objects
+or linker options) may be in any order, provided that no non-Ada object may
+be mistaken for a main @code{ALI} file.
+Any file name @code{F} without the @code{.ali}
+extension will be taken as the main @code{ALI} file if a file exists
+whose name is the concatenation of @code{F} and @code{.ali}.
+
+@code{mainprog.ali} references the ALI file of the main program.
+The @code{.ali} extension of this file can be omitted. From this
+reference, @code{gnatlink} locates the corresponding binder file
+@code{b~mainprog.adb} and, using the information in this file along
+with the list of non-Ada objects and linker options, constructs a
+linker command file to create the executable.
+
+The arguments other than the @code{gnatlink} switches and the main
+@code{ALI} file are passed to the linker uninterpreted.
+They typically include the names of
+object files for units written in other languages than Ada and any library
+references required to resolve references in any of these foreign language
+units, or in @code{Import} pragmas in any Ada units.
+
+@code{linker options} is an optional list of linker specific
+switches.
+The default linker called by gnatlink is @code{gcc} which in
+turn calls the appropriate system linker.
+
+One useful option for the linker is @code{-s}: it reduces the size of the
+executable by removing all symbol table and relocation information from the
+executable.
+
+Standard options for the linker such as @code{-lmy_lib} or
+@code{-Ldir} can be added as is.
+For options that are not recognized by
+@code{gcc} as linker options, use the @code{gcc} switches
+@code{-Xlinker} or @code{-Wl,}.
+
+Refer to the GCC documentation for
+details.
+
+Here is an example showing how to generate a linker map:
+
+@example
+$ gnatlink my_prog -Wl,-Map,MAPFILE
+@end example
+
+Using @code{linker options} it is possible to set the program stack and
+heap size.
+See @ref{127,,Setting Stack Size from gnatlink} and
+@ref{128,,Setting Heap Size from gnatlink}.
+
+@code{gnatlink} determines the list of objects required by the Ada
+program and prepends them to the list of objects passed to the linker.
+@code{gnatlink} also gathers any arguments set by the use of
+@code{pragma Linker_Options} and adds them to the list of arguments
+presented to the linker.
+
+@node Switches for gnatlink,,Running gnatlink,Linking with gnatlink
+@anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{129}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{12a}
+@subsection Switches for @code{gnatlink}
+
+
+The following switches are available with the @code{gnatlink} utility:
+
+@geindex --version (gnatlink)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display Copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatlink)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+@end table
+
+@geindex Command line length
+
+@geindex -f (gnatlink)
+
+
+@table @asis
+
+@item @code{-f}
+
+On some targets, the command line length is limited, and @code{gnatlink}
+will generate a separate file for the linker if the list of object files
+is too long.
+The @code{-f} switch forces this file
+to be generated even if
+the limit is not exceeded. This is useful in some cases to deal with
+special situations where the command line length is exceeded.
+@end table
+
+@geindex Debugging information
+@geindex including
+
+@geindex -g (gnatlink)
+
+
+@table @asis
+
+@item @code{-g}
+
+The option to include debugging information causes the Ada bind file (in
+other words, @code{b~mainprog.adb}) to be compiled with @code{-g}.
+In addition, the binder does not delete the @code{b~mainprog.adb},
+@code{b~mainprog.o} and @code{b~mainprog.ali} files.
+Without @code{-g}, the binder removes these files by default.
+@end table
+
+@geindex -n (gnatlink)
+
+
+@table @asis
+
+@item @code{-n}
+
+Do not compile the file generated by the binder. This may be used when
+a link is rerun with different options, but there is no need to recompile
+the binder file.
+@end table
+
+@geindex -v (gnatlink)
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose mode. Causes additional information to be output, including a full
+list of the included object files.
+This switch option is most useful when you want
+to see what set of object files are being used in the link step.
+@end table
+
+@geindex -v -v (gnatlink)
+
+
+@table @asis
+
+@item @code{-v -v}
+
+Very verbose mode. Requests that the compiler operate in verbose mode when
+it compiles the binder file, and that the system linker run in verbose mode.
+@end table
+
+@geindex -o (gnatlink)
+
+
+@table @asis
+
+@item @code{-o `exec-name'}
+
+@code{exec-name} specifies an alternate name for the generated
+executable program. If this switch is omitted, the executable has the same
+name as the main unit. For example, @code{gnatlink try.ali} creates
+an executable called @code{try}.
+@end table
+
+@geindex -B (gnatlink)
+
+
+@table @asis
+
+@item @code{-B`dir'}
+
+Load compiler executables (for example, @code{gnat1}, the Ada compiler)
+from @code{dir} instead of the default location. Only use this switch
+when multiple versions of the GNAT compiler are available.
+See the @code{Directory Options} section in @cite{The_GNU_Compiler_Collection}
+for further details. You would normally use the @code{-b} or
+@code{-V} switch instead.
+@end table
+
+@geindex -M (gnatlink)
+
+
+@table @asis
+
+@item @code{-M}
+
+When linking an executable, create a map file. The name of the map file
+has the same name as the executable with extension “.map”.
+@end table
+
+@geindex -M= (gnatlink)
+
+
+@table @asis
+
+@item @code{-M=`mapfile'}
+
+When linking an executable, create a map file. The name of the map file is
+@code{mapfile}.
+@end table
+
+@geindex --GCC=compiler_name (gnatlink)
+
+
+@table @asis
+
+@item @code{--GCC=`compiler_name'}
+
+Program used for compiling the binder file. The default is
+@code{gcc}. You need to use quotes around @code{compiler_name} if
+@code{compiler_name} contains spaces or other separator characters.
+As an example @code{--GCC="foo -x -y"} will instruct @code{gnatlink} to
+use @code{foo -x -y} as your compiler. Note that switch @code{-c} is always
+inserted after your command name. Thus in the above example the compiler
+command that will be used by @code{gnatlink} will be @code{foo -c -x -y}.
+A limitation of this syntax is that the name and path name of the executable
+itself must not include any embedded spaces. If the compiler executable is
+different from the default one (gcc or <prefix>-gcc), then the back-end
+switches in the ALI file are not used to compile the binder generated source.
+For example, this is the case with @code{--GCC="foo -x -y"}. But the back end
+switches will be used for @code{--GCC="gcc -gnatv"}. If several
+@code{--GCC=compiler_name} are used, only the last @code{compiler_name}
+is taken into account. However, all the additional switches are also taken
+into account. Thus,
+@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
+@code{--GCC="bar -x -y -z -t"}.
+@end table
+
+@geindex --LINK= (gnatlink)
+
+
+@table @asis
+
+@item @code{--LINK=`name'}
+
+@code{name} is the name of the linker to be invoked. This is especially
+useful in mixed language programs since languages such as C++ require
+their own linker to be used. When this switch is omitted, the default
+name for the linker is @code{gcc}. When this switch is used, the
+specified linker is called instead of @code{gcc} with exactly the same
+parameters that would have been passed to @code{gcc} so if the desired
+linker requires different parameters it is necessary to use a wrapper
+script that massages the parameters before invoking the real linker. It
+may be useful to control the exact invocation by using the verbose
+switch.
+@end table
+
+@node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT
+@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{12b}@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{70}
+@section Using the GNU @code{make} Utility
+
+
+@geindex make (GNU)
+@geindex GNU make
+
+This chapter offers some examples of makefiles that solve specific
+problems. It does not explain how to write a makefile, nor does it try to replace the
+@code{gnatmake} utility (@ref{c6,,Building with gnatmake}).
+
+All the examples in this section are specific to the GNU version of
+make. Although @code{make} is a standard utility, and the basic language
+is the same, these examples use some advanced features found only in
+@code{GNU make}.
+
+@menu
+* Using gnatmake in a Makefile::
+* Automatically Creating a List of Directories::
+* Generating the Command Line Switches::
+* Overcoming Command Line Length Limits::
+
+@end menu
+
+@node Using gnatmake in a Makefile,Automatically Creating a List of Directories,,Using the GNU make Utility
+@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{12c}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gnatmake-in-a-makefile}@anchor{12d}
+@subsection Using gnatmake in a Makefile
+
+
+@c index makefile (GNU make)
+
+Complex project organizations can be handled in a very powerful way by
+using GNU make combined with gnatmake. For instance, here is a Makefile
+which allows you to build each subsystem of a big project into a separate
+shared library. Such a makefile allows you to significantly reduce the link
+time of very big applications while maintaining full coherence at
+each step of the build process.
+
+The list of dependencies are handled automatically by
+@code{gnatmake}. The Makefile is simply used to call gnatmake in each of
+the appropriate directories.
+
+Note that you should also read the example on how to automatically
+create the list of directories
+(@ref{12e,,Automatically Creating a List of Directories})
+which might help you in case your project has a lot of subdirectories.
+
+@example
+## This Makefile is intended to be used with the following directory
+## configuration:
+## - The sources are split into a series of csc (computer software components)
+## Each of these csc is put in its own directory.
+## Their name are referenced by the directory names.
+## They will be compiled into shared library (although this would also work
+## with static libraries)
+## - The main program (and possibly other packages that do not belong to any
+## csc) is put in the top level directory (where the Makefile is).
+## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
+## \\_ second_csc (sources) __ lib (will contain the library)
+## \\_ ...
+## Although this Makefile is build for shared library, it is easy to modify
+## to build partial link objects instead (modify the lines with -shared and
+## gnatlink below)
+##
+## With this makefile, you can change any file in the system or add any new
+## file, and everything will be recompiled correctly (only the relevant shared
+## objects will be recompiled, and the main program will be re-linked).
+
+# The list of computer software component for your project. This might be
+# generated automatically.
+CSC_LIST=aa bb cc
+
+# Name of the main program (no extension)
+MAIN=main
+
+# If we need to build objects with -fPIC, uncomment the following line
+#NEED_FPIC=-fPIC
+
+# The following variable should give the directory containing libgnat.so
+# You can get this directory through 'gnatls -v'. This is usually the last
+# directory in the Object_Path.
+GLIB=...
+
+# The directories for the libraries
+# (This macro expands the list of CSC to the list of shared libraries, you
+# could simply use the expanded form:
+# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
+LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@}
+
+$@{MAIN@}: objects $@{LIB_DIR@}
+ gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared
+ gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@}
+
+objects::
+ # recompile the sources
+ gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@}
+
+# Note: In a future version of GNAT, the following commands will be simplified
+# by a new tool, gnatmlib
+$@{LIB_DIR@}:
+ mkdir -p $@{dir $@@ @}
+ cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
+ cd $@{dir $@@ @} && cp -f ../*.ali .
+
+# The dependencies for the modules
+# Note that we have to force the expansion of *.o, since in some cases
+# make won't be able to do it itself.
+aa/lib/libaa.so: $@{wildcard aa/*.o@}
+bb/lib/libbb.so: $@{wildcard bb/*.o@}
+cc/lib/libcc.so: $@{wildcard cc/*.o@}
+
+# Make sure all of the shared libraries are in the path before starting the
+# program
+run::
+ LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@}
+
+clean::
+ $@{RM@} -rf $@{CSC_LIST:%=%/lib@}
+ $@{RM@} $@{CSC_LIST:%=%/*.ali@}
+ $@{RM@} $@{CSC_LIST:%=%/*.o@}
+ $@{RM@} *.o *.ali $@{MAIN@}
+@end example
+
+@node Automatically Creating a List of Directories,Generating the Command Line Switches,Using gnatmake in a Makefile,Using the GNU make Utility
+@anchor{gnat_ugn/building_executable_programs_with_gnat automatically-creating-a-list-of-directories}@anchor{12e}@anchor{gnat_ugn/building_executable_programs_with_gnat id50}@anchor{12f}
+@subsection Automatically Creating a List of Directories
+
+
+In most makefiles, you will have to specify a list of directories, and
+store it in a variable. For small projects, it is often easier to
+specify each of them by hand, since you then have full control over what
+is the proper order for these directories, which ones should be
+included.
+
+However, in larger projects, which might involve hundreds of
+subdirectories, it might be more convenient to generate this list
+automatically.
+
+The example below presents two methods. The first one, although less
+general, gives you more control over the list. It involves wildcard
+characters, that are automatically expanded by @code{make}. Its
+shortcoming is that you need to explicitly specify some of the
+organization of your project, such as for instance the directory tree
+depth, whether some directories are found in a separate tree, etc.
+
+The second method is the most general one. It requires an external
+program, called @code{find}, which is standard on all Unix systems. All
+the directories found under a given root directory will be added to the
+list.
+
+@example
+# The examples below are based on the following directory hierarchy:
+# All the directories can contain any number of files
+# ROOT_DIRECTORY -> a -> aa -> aaa
+# -> ab
+# -> ac
+# -> b -> ba -> baa
+# -> bb
+# -> bc
+# This Makefile creates a variable called DIRS, that can be reused any time
+# you need this list (see the other examples in this section)
+
+# The root of your project's directory hierarchy
+ROOT_DIRECTORY=.
+
+####
+# First method: specify explicitly the list of directories
+# This allows you to specify any subset of all the directories you need.
+####
+
+DIRS := a/aa/ a/ab/ b/ba/
+
+####
+# Second method: use wildcards
+# Note that the argument(s) to wildcard below should end with a '/'.
+# Since wildcards also return file names, we have to filter them out
+# to avoid duplicate directory names.
+# We thus use make's `@w{`}dir`@w{`} and `@w{`}sort`@w{`} functions.
+# It sets DIRs to the following value (note that the directories aaa and baa
+# are not given, unless you change the arguments to wildcard).
+# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
+####
+
+DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/
+ $@{ROOT_DIRECTORY@}/*/*/@}@}@}
+
+####
+# Third method: use an external program
+# This command is much faster if run on local disks, avoiding NFS slowdowns.
+# This is the most complete command: it sets DIRs to the following value:
+# DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
+####
+
+DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@}
+@end example
+
+@node Generating the Command Line Switches,Overcoming Command Line Length Limits,Automatically Creating a List of Directories,Using the GNU make Utility
+@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{130}@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{131}
+@subsection Generating the Command Line Switches
+
+
+Once you have created the list of directories as explained in the
+previous section (@ref{12e,,Automatically Creating a List of Directories}),
+you can easily generate the command line arguments to pass to gnatmake.
+
+For the sake of completeness, this example assumes that the source path
+is not the same as the object path, and that you have two separate lists
+of directories.
+
+@example
+# see "Automatically creating a list of directories" to create
+# these variables
+SOURCE_DIRS=
+OBJECT_DIRS=
+
+GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@}
+GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@}
+
+all:
+ gnatmake $@{GNATMAKE_SWITCHES@} main_unit
+@end example
+
+@node Overcoming Command Line Length Limits,,Generating the Command Line Switches,Using the GNU make Utility
+@anchor{gnat_ugn/building_executable_programs_with_gnat id52}@anchor{132}@anchor{gnat_ugn/building_executable_programs_with_gnat overcoming-command-line-length-limits}@anchor{133}
+@subsection Overcoming Command Line Length Limits
+
+
+One problem that might be encountered on big projects is that many
+operating systems limit the length of the command line. It is thus hard to give
+gnatmake the list of source and object directories.
+
+This example shows how you can set up environment variables, which will
+make @code{gnatmake} behave exactly as if the directories had been
+specified on the command line, but have a much higher length limit (or
+even none on most systems).
+
+It assumes that you have created a list of directories in your Makefile,
+using one of the methods presented in
+@ref{12e,,Automatically Creating a List of Directories}.
+For the sake of completeness, we assume that the object
+path (where the ALI files are found) is different from the sources patch.
+
+Note a small trick in the Makefile below: for efficiency reasons, we
+create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
+expanded immediately by @code{make}. This way we overcome the standard
+make behavior which is to expand the variables only when they are
+actually used.
+
+On Windows, if you are using the standard Windows command shell, you must
+replace colons with semicolons in the assignments to these variables.
+
+@example
+# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
+# This is the same thing as putting the -I arguments on the command line.
+# (the equivalent of using -aI on the command line would be to define
+# only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
+# You can of course have different values for these variables.
+#
+# Note also that we need to keep the previous values of these variables, since
+# they might have been set before running 'make' to specify where the GNAT
+# library is installed.
+
+# see "Automatically creating a list of directories" to create these
+# variables
+SOURCE_DIRS=
+OBJECT_DIRS=
+
+empty:=
+space:=$@{empty@} $@{empty@}
+SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@}
+OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@}
+ADA_INCLUDE_PATH += $@{SOURCE_LIST@}
+ADA_OBJECTS_PATH += $@{OBJECT_LIST@}
+export ADA_INCLUDE_PATH
+export ADA_OBJECTS_PATH
+
+all:
+ gnatmake main_unit
+@end example
+
+@node GNAT Utility Programs,GNAT and Program Execution,Building Executable Programs with GNAT,Top
+@anchor{gnat_ugn/gnat_utility_programs doc}@anchor{134}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{b}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{135}
+@chapter GNAT Utility Programs
+
+
+This chapter describes a number of utility programs:
+
+
+
+@itemize *
+
+@item
+@ref{136,,The File Cleanup Utility gnatclean}
+
+@item
+@ref{137,,The GNAT Library Browser gnatls}
+@end itemize
+
+Other GNAT utilities are described elsewhere in this manual:
+
+
+@itemize *
+
+@item
+@ref{42,,Handling Arbitrary File Naming Conventions with gnatname}
+
+@item
+@ref{4c,,File Name Krunching with gnatkr}
+
+@item
+@ref{1d,,Renaming Files with gnatchop}
+
+@item
+@ref{8f,,Preprocessing with gnatprep}
+@end itemize
+
+@menu
+* The File Cleanup Utility gnatclean::
+* The GNAT Library Browser gnatls::
+
+@end menu
+
+@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs
+@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{138}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{136}
+@section The File Cleanup Utility @code{gnatclean}
+
+
+@geindex File cleanup tool
+
+@geindex gnatclean
+
+@code{gnatclean} is a tool that allows the deletion of files produced by the
+compiler, binder and linker, including ALI files, object files, tree files,
+expanded source files, library files, interface copy source files, binder
+generated files and executable files.
+
+@menu
+* Running gnatclean::
+* Switches for gnatclean::
+
+@end menu
+
+@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean
+@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{13a}
+@subsection Running @code{gnatclean}
+
+
+The @code{gnatclean} command has the form:
+
+@quotation
+
+@example
+$ gnatclean switches names
+@end example
+@end quotation
+
+where @code{names} is a list of source file names. Suffixes @code{.ads} and
+@code{adb} may be omitted. If a project file is specified using switch
+@code{-P}, then @code{names} may be completely omitted.
+
+In normal mode, @code{gnatclean} delete the files produced by the compiler and,
+if switch @code{-c} is not specified, by the binder and
+the linker. In informative-only mode, specified by switch
+@code{-n}, the list of files that would have been deleted in
+normal mode is listed, but no file is actually deleted.
+
+@node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean
+@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{13b}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{13c}
+@subsection Switches for @code{gnatclean}
+
+
+@code{gnatclean} recognizes the following switches:
+
+@geindex --version (gnatclean)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatclean)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+
+@item @code{--subdirs=`subdir'}
+
+Actual object directory of each project file is the subdirectory subdir of the
+object directory specified or defaulted in the project file.
+
+@item @code{--unchecked-shared-lib-imports}
+
+By default, shared library projects are not allowed to import static library
+projects. When this switch is used on the command line, this restriction is
+relaxed.
+@end table
+
+@geindex -c (gnatclean)
+
+
+@table @asis
+
+@item @code{-c}
+
+Only attempt to delete the files produced by the compiler, not those produced
+by the binder or the linker. The files that are not to be deleted are library
+files, interface copy files, binder generated files and executable files.
+@end table
+
+@geindex -D (gnatclean)
+
+
+@table @asis
+
+@item @code{-D `dir'}
+
+Indicate that ALI and object files should normally be found in directory @code{dir}.
+@end table
+
+@geindex -F (gnatclean)
+
+
+@table @asis
+
+@item @code{-F}
+
+When using project files, if some errors or warnings are detected during
+parsing and verbose mode is not in effect (no use of switch
+-v), then error lines start with the full path name of the project
+file, rather than its simple file name.
+@end table
+
+@geindex -h (gnatclean)
+
+
+@table @asis
+
+@item @code{-h}
+
+Output a message explaining the usage of @code{gnatclean}.
+@end table
+
+@geindex -n (gnatclean)
+
+
+@table @asis
+
+@item @code{-n}
+
+Informative-only mode. Do not delete any files. Output the list of the files
+that would have been deleted if this switch was not specified.
+@end table
+
+@geindex -P (gnatclean)
+
+
+@table @asis
+
+@item @code{-P`project'}
+
+Use project file @code{project}. Only one such switch can be used.
+When cleaning a project file, the files produced by the compilation of the
+immediate sources or inherited sources of the project files are to be
+deleted. This is not depending on the presence or not of executable names
+on the command line.
+@end table
+
+@geindex -q (gnatclean)
+
+
+@table @asis
+
+@item @code{-q}
+
+Quiet output. If there are no errors, do not output anything, except in
+verbose mode (switch -v) or in informative-only mode
+(switch -n).
+@end table
+
+@geindex -r (gnatclean)
+
+
+@table @asis
+
+@item @code{-r}
+
+When a project file is specified (using switch -P),
+clean all imported and extended project files, recursively. If this switch
+is not specified, only the files related to the main project file are to be
+deleted. This switch has no effect if no project file is specified.
+@end table
+
+@geindex -v (gnatclean)
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose mode.
+@end table
+
+@geindex -vP (gnatclean)
+
+
+@table @asis
+
+@item @code{-vP`x'}
+
+Indicates the verbosity of the parsing of GNAT project files.
+@ref{cf,,Switches Related to Project Files}.
+@end table
+
+@geindex -X (gnatclean)
+
+
+@table @asis
+
+@item @code{-X`name'=`value'}
+
+Indicates that external variable @code{name} has the value @code{value}.
+The Project Manager will use this value for occurrences of
+@code{external(name)} when parsing the project file.
+See @ref{cf,,Switches Related to Project Files}.
+@end table
+
+@geindex -aO (gnatclean)
+
+
+@table @asis
+
+@item @code{-aO`dir'}
+
+When searching for ALI and object files, look in directory @code{dir}.
+@end table
+
+@geindex -I (gnatclean)
+
+
+@table @asis
+
+@item @code{-I`dir'}
+
+Equivalent to @code{-aO`dir'}.
+@end table
+
+@geindex -I- (gnatclean)
+
+@geindex Source files
+@geindex suppressing search
+
+
+@table @asis
+
+@item @code{-I-}
+
+Do not look for ALI or object files in the directory
+where @code{gnatclean} was invoked.
+@end table
+
+@node The GNAT Library Browser gnatls,,The File Cleanup Utility gnatclean,GNAT Utility Programs
+@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{13d}@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{137}
+@section The GNAT Library Browser @code{gnatls}
+
+
+@geindex Library browser
+
+@geindex gnatls
+
+@code{gnatls} is a tool that outputs information about compiled
+units. It gives the relationship between objects, unit names and source
+files. It can also be used to check the source dependencies of a unit
+as well as various characteristics.
+
+@menu
+* Running gnatls::
+* Switches for gnatls::
+* Example of gnatls Usage::
+
+@end menu
+
+@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls
+@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{13e}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{13f}
+@subsection Running @code{gnatls}
+
+
+The @code{gnatls} command has the form
+
+@quotation
+
+@example
+$ gnatls switches object_or_ali_file
+@end example
+@end quotation
+
+The main argument is the list of object or @code{ali} files
+(see @ref{28,,The Ada Library Information Files})
+for which information is requested.
+
+In normal mode, without additional option, @code{gnatls} produces a
+four-column listing. Each line represents information for a specific
+object. The first column gives the full path of the object, the second
+column gives the name of the principal unit in this object, the third
+column gives the status of the source and the fourth column gives the
+full path of the source representing this unit.
+Here is a simple example of use:
+
+@quotation
+
+@example
+$ gnatls *.o
+./demo1.o demo1 DIF demo1.adb
+./demo2.o demo2 OK demo2.adb
+./hello.o h1 OK hello.adb
+./instr-child.o instr.child MOK instr-child.adb
+./instr.o instr OK instr.adb
+./tef.o tef DIF tef.adb
+./text_io_example.o text_io_example OK text_io_example.adb
+./tgef.o tgef DIF tgef.adb
+@end example
+@end quotation
+
+The first line can be interpreted as follows: the main unit which is
+contained in
+object file @code{demo1.o} is demo1, whose main source is in
+@code{demo1.adb}. Furthermore, the version of the source used for the
+compilation of demo1 has been modified (DIF). Each source file has a status
+qualifier which can be:
+
+
+@table @asis
+
+@item `OK (unchanged)'
+
+The version of the source file used for the compilation of the
+specified unit corresponds exactly to the actual source file.
+
+@item `MOK (slightly modified)'
+
+The version of the source file used for the compilation of the
+specified unit differs from the actual source file but not enough to
+require recompilation. If you use gnatmake with the option
+@code{-m} (minimal recompilation), a file marked
+MOK will not be recompiled.
+
+@item `DIF (modified)'
+
+No version of the source found on the path corresponds to the source
+used to build this object.
+
+@item `??? (file not found)'
+
+No source file was found for this unit.
+
+@item `HID (hidden, unchanged version not first on PATH)'
+
+The version of the source that corresponds exactly to the source used
+for compilation has been found on the path but it is hidden by another
+version of the same source that has been modified.
+@end table
+
+@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls
+@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{140}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{141}
+@subsection Switches for @code{gnatls}
+
+
+@code{gnatls} recognizes the following switches:
+
+@geindex --version (gnatls)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatls)
+
+
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+@end table
+
+@geindex -a (gnatls)
+
+
+@table @asis
+
+@item @code{-a}
+
+Consider all units, including those of the predefined Ada library.
+Especially useful with @code{-d}.
+@end table
+
+@geindex -d (gnatls)
+
+
+@table @asis
+
+@item @code{-d}
+
+List sources from which specified units depend on.
+@end table
+
+@geindex -h (gnatls)
+
+
+@table @asis
+
+@item @code{-h}
+
+Output the list of options.
+@end table
+
+@geindex -o (gnatls)
+
+
+@table @asis
+
+@item @code{-o}
+
+Only output information about object files.
+@end table
+
+@geindex -s (gnatls)
+
+
+@table @asis
+
+@item @code{-s}
+
+Only output information about source files.
+@end table
+
+@geindex -u (gnatls)
+
+
+@table @asis
+
+@item @code{-u}
+
+Only output information about compilation units.
+@end table
+
+@geindex -files (gnatls)
+
+
+@table @asis
+
+@item @code{-files=`file'}
+
+Take as arguments the files listed in text file @code{file}.
+Text file @code{file} may contain empty lines that are ignored.
+Each nonempty line should contain the name of an existing file.
+Several such switches may be specified simultaneously.
+@end table
+
+@geindex -aO (gnatls)
+
+@geindex -aI (gnatls)
+
+@geindex -I (gnatls)
+
+@geindex -I- (gnatls)
+
+
+@table @asis
+
+@item @code{-aO`dir'}, @code{-aI`dir'}, @code{-I`dir'}, @code{-I-}, @code{-nostdinc}
+
+Source path manipulation. Same meaning as the equivalent @code{gnatmake}
+flags (@ref{ce,,Switches for gnatmake}).
+@end table
+
+@geindex -aP (gnatls)
+
+
+@table @asis
+
+@item @code{-aP`dir'}
+
+Add @code{dir} at the beginning of the project search dir.
+@end table
+
+@geindex --RTS (gnatls)
+
+
+@table @asis
+
+@item @code{--RTS=`rts-path'}
+
+Specifies the default location of the runtime library. Same meaning as the
+equivalent @code{gnatmake} flag (@ref{ce,,Switches for gnatmake}).
+@end table
+
+@geindex -v (gnatls)
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose mode. Output the complete source, object and project paths. Do not use
+the default column layout but instead use long format giving as much as
+information possible on each requested units, including special
+characteristics such as:
+
+
+@itemize *
+
+@item
+`Preelaborable': The unit is preelaborable in the Ada sense.
+
+@item
+`No_Elab_Code': No elaboration code has been produced by the compiler for this unit.
+
+@item
+`Pure': The unit is pure in the Ada sense.
+
+@item
+`Elaborate_Body': The unit contains a pragma Elaborate_Body.
+
+@item
+`Remote_Types': The unit contains a pragma Remote_Types.
+
+@item
+`Shared_Passive': The unit contains a pragma Shared_Passive.
+
+@item
+`Predefined': This unit is part of the predefined environment and cannot be modified
+by the user.
+
+@item
+`Remote_Call_Interface': The unit contains a pragma Remote_Call_Interface.
+@end itemize
+@end table
+
+@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls
+@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{142}@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{143}
+@subsection Example of @code{gnatls} Usage
+
+
+Example of using the verbose switch. Note how the source and
+object paths are affected by the -I switch.
+
+@quotation
+
+@example
+$ gnatls -v -I.. demo1.o
+
+GNATLS 5.03w (20041123-34)
+Copyright 1997-2004 Free Software Foundation, Inc.
+
+Source Search Path:
+ <Current_Directory>
+ ../
+ /home/comar/local/adainclude/
+
+Object Search Path:
+ <Current_Directory>
+ ../
+ /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
+
+Project Search Path:
+ <Current_Directory>
+ /home/comar/local/lib/gnat/
+
+./demo1.o
+ Unit =>
+ Name => demo1
+ Kind => subprogram body
+ Flags => No_Elab_Code
+ Source => demo1.adb modified
+@end example
+@end quotation
+
+The following is an example of use of the dependency list.
+Note the use of the -s switch
+which gives a straight list of source files. This can be useful for
+building specialized scripts.
+
+@quotation
+
+@example
+$ gnatls -d demo2.o
+./demo2.o demo2 OK demo2.adb
+ OK gen_list.ads
+ OK gen_list.adb
+ OK instr.ads
+ OK instr-child.ads
+
+$ gnatls -d -s -a demo1.o
+demo1.adb
+/home/comar/local/adainclude/ada.ads
+/home/comar/local/adainclude/a-finali.ads
+/home/comar/local/adainclude/a-filico.ads
+/home/comar/local/adainclude/a-stream.ads
+/home/comar/local/adainclude/a-tags.ads
+gen_list.ads
+gen_list.adb
+/home/comar/local/adainclude/gnat.ads
+/home/comar/local/adainclude/g-io.ads
+instr.ads
+/home/comar/local/adainclude/system.ads
+/home/comar/local/adainclude/s-exctab.ads
+/home/comar/local/adainclude/s-finimp.ads
+/home/comar/local/adainclude/s-finroo.ads
+/home/comar/local/adainclude/s-secsta.ads
+/home/comar/local/adainclude/s-stalib.ads
+/home/comar/local/adainclude/s-stoele.ads
+/home/comar/local/adainclude/s-stratt.ads
+/home/comar/local/adainclude/s-tasoli.ads
+/home/comar/local/adainclude/s-unstyp.ads
+/home/comar/local/adainclude/unchconv.ads
+@end example
+@end quotation
+
+
+
+
+
+
+@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
+
+@node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top
+@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{144}@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{145}
+@chapter GNAT and Program Execution
+
+
+This chapter covers several topics:
+
+
+@itemize *
+
+@item
+@ref{146,,Running and Debugging Ada Programs}
+
+@item
+@ref{147,,Profiling}
+
+@item
+@ref{148,,Improving Performance}
+
+@item
+@ref{149,,Overflow Check Handling in GNAT}
+
+@item
+@ref{14a,,Performing Dimensionality Analysis in GNAT}
+
+@item
+@ref{14b,,Stack Related Facilities}
+
+@item
+@ref{14c,,Memory Management Issues}
+@end itemize
+
+@menu
+* Running and Debugging Ada Programs::
+* Profiling::
+* Improving Performance::
+* Overflow Check Handling in GNAT::
+* Performing Dimensionality Analysis in GNAT::
+* Stack Related Facilities::
+* Memory Management Issues::
+
+@end menu
+
+@node Running and Debugging Ada Programs,Profiling,,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{146}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{14d}
+@section Running and Debugging Ada Programs
+
+
+@geindex Debugging
+
+This section discusses how to debug Ada programs.
+
+An incorrect Ada program may be handled in three ways by the GNAT compiler:
+
+
+@itemize *
+
+@item
+The illegality may be a violation of the static semantics of Ada. In
+that case GNAT diagnoses the constructs in the program that are illegal.
+It is then a straightforward matter for the user to modify those parts of
+the program.
+
+@item
+The illegality may be a violation of the dynamic semantics of Ada. In
+that case the program compiles and executes, but may generate incorrect
+results, or may terminate abnormally with some exception.
+
+@item
+When presented with a program that contains convoluted errors, GNAT
+itself may terminate abnormally without providing full diagnostics on
+the incorrect user program.
+@end itemize
+
+@geindex Debugger
+
+@geindex gdb
+
+@menu
+* The GNAT Debugger GDB::
+* Running GDB::
+* Introduction to GDB Commands::
+* Using Ada Expressions::
+* Calling User-Defined Subprograms::
+* Using the next Command in a Function::
+* Stopping When Ada Exceptions Are Raised::
+* Ada Tasks::
+* Debugging Generic Units::
+* Remote Debugging with gdbserver::
+* GNAT Abnormal Termination or Failure to Terminate::
+* Naming Conventions for GNAT Source Files::
+* Getting Internal Debugging Information::
+* Stack Traceback::
+* Pretty-Printers for the GNAT runtime::
+
+@end menu
+
+@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{14e}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{14f}
+@subsection The GNAT Debugger GDB
+
+
+@code{GDB} is a general purpose, platform-independent debugger that
+can be used to debug mixed-language programs compiled with @code{gcc},
+and in particular is capable of debugging Ada programs compiled with
+GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
+complex Ada data structures.
+
+See @cite{Debugging with GDB},
+for full details on the usage of @code{GDB}, including a section on
+its usage on programs. This manual should be consulted for full
+details. The section that follows is a brief introduction to the
+philosophy and use of @code{GDB}.
+
+When GNAT programs are compiled, the compiler optionally writes debugging
+information into the generated object file, including information on
+line numbers, and on declared types and variables. This information is
+separate from the generated code. It makes the object files considerably
+larger, but it does not add to the size of the actual executable that
+will be loaded into memory, and has no impact on run-time performance. The
+generation of debug information is triggered by the use of the
+@code{-g} switch in the @code{gcc} or @code{gnatmake} command
+used to carry out the compilations. It is important to emphasize that
+the use of these options does not change the generated code.
+
+The debugging information is written in standard system formats that
+are used by many tools, including debuggers and profilers. The format
+of the information is typically designed to describe C types and
+semantics, but GNAT implements a translation scheme which allows full
+details about Ada types and variables to be encoded into these
+standard C formats. Details of this encoding scheme may be found in
+the file exp_dbug.ads in the GNAT source distribution. However, the
+details of this encoding are, in general, of no interest to a user,
+since @code{GDB} automatically performs the necessary decoding.
+
+When a program is bound and linked, the debugging information is
+collected from the object files, and stored in the executable image of
+the program. Again, this process significantly increases the size of
+the generated executable file, but it does not increase the size of
+the executable program itself. Furthermore, if this program is run in
+the normal manner, it runs exactly as if the debug information were
+not present, and takes no more actual memory.
+
+However, if the program is run under control of @code{GDB}, the
+debugger is activated. The image of the program is loaded, at which
+point it is ready to run. If a run command is given, then the program
+will run exactly as it would have if @code{GDB} were not present. This
+is a crucial part of the @code{GDB} design philosophy. @code{GDB} is
+entirely non-intrusive until a breakpoint is encountered. If no
+breakpoint is ever hit, the program will run exactly as it would if no
+debugger were present. When a breakpoint is hit, @code{GDB} accesses
+the debugging information and can respond to user commands to inspect
+variables, and more generally to report on the state of execution.
+
+@node Running GDB,Introduction to GDB Commands,The GNAT Debugger GDB,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{150}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{151}
+@subsection Running GDB
+
+
+This section describes how to initiate the debugger.
+
+The debugger can be launched from a @code{GNAT Studio} menu or
+directly from the command line. The description below covers the latter use.
+All the commands shown can be used in the @code{GNAT Studio} debug console window,
+but there are usually more GUI-based ways to achieve the same effect.
+
+The command to run @code{GDB} is
+
+@quotation
+
+@example
+$ gdb program
+@end example
+@end quotation
+
+where @code{program} is the name of the executable file. This
+activates the debugger and results in a prompt for debugger commands.
+The simplest command is simply @code{run}, which causes the program to run
+exactly as if the debugger were not present. The following section
+describes some of the additional commands that can be given to @code{GDB}.
+
+@node Introduction to GDB Commands,Using Ada Expressions,Running GDB,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{152}@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{153}
+@subsection Introduction to GDB Commands
+
+
+@code{GDB} contains a large repertoire of commands.
+See @cite{Debugging with GDB} for extensive documentation on the use
+of these commands, together with examples of their use. Furthermore,
+the command `help' invoked from within GDB activates a simple help
+facility which summarizes the available commands and their options.
+In this section we summarize a few of the most commonly
+used commands to give an idea of what @code{GDB} is about. You should create
+a simple program with debugging information and experiment with the use of
+these @code{GDB} commands on the program as you read through the
+following section.
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item @code{set args @var{arguments}}
+
+The `arguments' list above is a list of arguments to be passed to
+the program on a subsequent run command, just as though the arguments
+had been entered on a normal invocation of the program. The @code{set args}
+command is not needed if the program does not require arguments.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{run}
+
+The @code{run} command causes execution of the program to start from
+the beginning. If the program is already running, that is to say if
+you are currently positioned at a breakpoint, then a prompt will ask
+for confirmation that you want to abandon the current execution and
+restart.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{breakpoint @var{location}}
+
+The breakpoint command sets a breakpoint, that is to say a point at which
+execution will halt and @code{GDB} will await further
+commands. `location' is
+either a line number within a file, given in the format @code{file:linenumber},
+or it is the name of a subprogram. If you request that a breakpoint be set on
+a subprogram that is overloaded, a prompt will ask you to specify on which of
+those subprograms you want to breakpoint. You can also
+specify that all of them should be breakpointed. If the program is run
+and execution encounters the breakpoint, then the program
+stops and @code{GDB} signals that the breakpoint was encountered by
+printing the line of code before which the program is halted.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{catch exception @var{name}}
+
+This command causes the program execution to stop whenever exception
+@code{name} is raised. If @code{name} is omitted, then the execution is
+suspended when any exception is raised.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{print @var{expression}}
+
+This will print the value of the given expression. Most simple
+Ada expression formats are properly handled by @code{GDB}, so the expression
+can contain function calls, variables, operators, and attribute references.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{continue}
+
+Continues execution following a breakpoint, until the next breakpoint or the
+termination of the program.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{step}
+
+Executes a single line after a breakpoint. If the next statement
+is a subprogram call, execution continues into (the first statement of)
+the called subprogram.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{next}
+
+Executes a single line. If this line is a subprogram call, executes and
+returns from the call.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{list}
+
+Lists a few lines around the current source location. In practice, it
+is usually more convenient to have a separate edit window open with the
+relevant source file displayed. Successive applications of this command
+print subsequent lines. The command can be given an argument which is a
+line number, in which case it displays a few lines around the specified one.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{backtrace}
+
+Displays a backtrace of the call chain. This command is typically
+used after a breakpoint has occurred, to examine the sequence of calls that
+leads to the current breakpoint. The display includes one line for each
+activation record (frame) corresponding to an active subprogram.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{up}
+
+At a breakpoint, @code{GDB} can display the values of variables local
+to the current frame. The command @code{up} can be used to
+examine the contents of other active frames, by moving the focus up
+the stack, that is to say from callee to caller, one frame at a time.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{down}
+
+Moves the focus of @code{GDB} down from the frame currently being
+examined to the frame of its callee (the reverse of the previous command),
+@end table
+
+@item
+
+@table @asis
+
+@item @code{frame @var{n}}
+
+Inspect the frame with the given number. The value 0 denotes the frame
+of the current breakpoint, that is to say the top of the call stack.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{kill}
+
+Kills the child process in which the program is running under GDB.
+This may be useful for several purposes:
+
+
+@itemize *
+
+@item
+It allows you to recompile and relink your program, since on many systems
+you cannot regenerate an executable file while it is running in a process.
+
+@item
+You can run your program outside the debugger, on systems that do not
+permit executing a program outside GDB while breakpoints are set
+within GDB.
+
+@item
+It allows you to debug a core dump rather than a running process.
+@end itemize
+@end table
+@end itemize
+
+The above list is a very short introduction to the commands that
+@code{GDB} provides. Important additional capabilities, including conditional
+breakpoints, the ability to execute command sequences on a breakpoint,
+the ability to debug at the machine instruction level and many other
+features are described in detail in @cite{Debugging with GDB}.
+Note that most commands can be abbreviated
+(for example, c for continue, bt for backtrace).
+
+@node Using Ada Expressions,Calling User-Defined Subprograms,Introduction to GDB Commands,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{154}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{155}
+@subsection Using Ada Expressions
+
+
+@geindex Ada expressions (in gdb)
+
+@code{GDB} supports a fairly large subset of Ada expression syntax, with some
+extensions. The philosophy behind the design of this subset is
+
+@quotation
+
+
+@itemize *
+
+@item
+That @code{GDB} should provide basic literals and access to operations for
+arithmetic, dereferencing, field selection, indexing, and subprogram calls,
+leaving more sophisticated computations to subprograms written into the
+program (which therefore may be called from @code{GDB}).
+
+@item
+That type safety and strict adherence to Ada language restrictions
+are not particularly relevant in a debugging context.
+
+@item
+That brevity is important to the @code{GDB} user.
+@end itemize
+@end quotation
+
+Thus, for brevity, the debugger acts as if there were
+implicit @code{with} and @code{use} clauses in effect for all user-written
+packages, thus making it unnecessary to fully qualify most names with
+their packages, regardless of context. Where this causes ambiguity,
+@code{GDB} asks the user’s intent.
+
+For details on the supported Ada syntax, see @cite{Debugging with GDB}.
+
+@node Calling User-Defined Subprograms,Using the next Command in a Function,Using Ada Expressions,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{156}@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{157}
+@subsection Calling User-Defined Subprograms
+
+
+An important capability of @code{GDB} is the ability to call user-defined
+subprograms while debugging. This is achieved simply by entering
+a subprogram call statement in the form:
+
+@quotation
+
+@example
+call subprogram-name (parameters)
+@end example
+@end quotation
+
+The keyword @code{call} can be omitted in the normal case where the
+@code{subprogram-name} does not coincide with any of the predefined
+@code{GDB} commands.
+
+The effect is to invoke the given subprogram, passing it the
+list of parameters that is supplied. The parameters can be expressions and
+can include variables from the program being debugged. The
+subprogram must be defined
+at the library level within your program, and @code{GDB} will call the
+subprogram within the environment of your program execution (which
+means that the subprogram is free to access or even modify variables
+within your program).
+
+The most important use of this facility is in allowing the inclusion of
+debugging routines that are tailored to particular data structures
+in your program. Such debugging routines can be written to provide a suitably
+high-level description of an abstract type, rather than a low-level dump
+of its physical layout. After all, the standard
+@code{GDB print} command only knows the physical layout of your
+types, not their abstract meaning. Debugging routines can provide information
+at the desired semantic level and are thus enormously useful.
+
+For example, when debugging GNAT itself, it is crucial to have access to
+the contents of the tree nodes used to represent the program internally.
+But tree nodes are represented simply by an integer value (which in turn
+is an index into a table of nodes).
+Using the @code{print} command on a tree node would simply print this integer
+value, which is not very useful. But the PN routine (defined in file
+treepr.adb in the GNAT sources) takes a tree node as input, and displays
+a useful high level representation of the tree node, which includes the
+syntactic category of the node, its position in the source, the integers
+that denote descendant nodes and parent node, as well as varied
+semantic information. To study this example in more detail, you might want to
+look at the body of the PN procedure in the stated file.
+
+Another useful application of this capability is to deal with situations of
+complex data which are not handled suitably by GDB. For example, if you specify
+Convention Fortran for a multi-dimensional array, GDB does not know that
+the ordering of array elements has been switched and will not properly
+address the array elements. In such a case, instead of trying to print the
+elements directly from GDB, you can write a callable procedure that prints
+the elements in the desired format.
+
+@node Using the next Command in a Function,Stopping When Ada Exceptions Are Raised,Calling User-Defined Subprograms,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{158}@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{159}
+@subsection Using the `next' Command in a Function
+
+
+When you use the @code{next} command in a function, the current source
+location will advance to the next statement as usual. A special case
+arises in the case of a @code{return} statement.
+
+Part of the code for a return statement is the ‘epilogue’ of the function.
+This is the code that returns to the caller. There is only one copy of
+this epilogue code, and it is typically associated with the last return
+statement in the function if there is more than one return. In some
+implementations, this epilogue is associated with the first statement
+of the function.
+
+The result is that if you use the @code{next} command from a return
+statement that is not the last return statement of the function you
+may see a strange apparent jump to the last return statement or to
+the start of the function. You should simply ignore this odd jump.
+The value returned is always that from the first return statement
+that was stepped through.
+
+@node Stopping When Ada Exceptions Are Raised,Ada Tasks,Using the next Command in a Function,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{15a}@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{15b}
+@subsection Stopping When Ada Exceptions Are Raised
+
+
+@geindex Exceptions (in gdb)
+
+You can set catchpoints that stop the program execution when your program
+raises selected exceptions.
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item @code{catch exception}
+
+Set a catchpoint that stops execution whenever (any task in the) program
+raises any exception.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{catch exception @var{name}}
+
+Set a catchpoint that stops execution whenever (any task in the) program
+raises the exception `name'.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{catch exception unhandled}
+
+Set a catchpoint that stops executing whenever (any task in the) program
+raises an exception for which there is no handler.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{info exceptions}, @code{info exceptions @var{regexp}}
+
+The @code{info exceptions} command permits the user to examine all defined
+exceptions within Ada programs. With a regular expression, `regexp', as
+argument, prints out only those exceptions whose name matches `regexp'.
+@end table
+@end itemize
+
+@geindex Tasks (in gdb)
+
+@node Ada Tasks,Debugging Generic Units,Stopping When Ada Exceptions Are Raised,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{15c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{15d}
+@subsection Ada Tasks
+
+
+@code{GDB} allows the following task-related commands:
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item @code{info tasks}
+
+This command shows a list of current Ada tasks, as in the following example:
+
+@example
+(gdb) info tasks
+ ID TID P-ID Thread Pri State Name
+ 1 8088000 0 807e000 15 Child Activation Wait main_task
+ 2 80a4000 1 80ae000 15 Accept/Select Wait b
+ 3 809a800 1 80a4800 15 Child Activation Wait a
+* 4 80ae800 3 80b8000 15 Running c
+@end example
+
+In this listing, the asterisk before the first task indicates it to be the
+currently running task. The first column lists the task ID that is used
+to refer to tasks in the following commands.
+@end table
+@end itemize
+
+@geindex Breakpoints and tasks
+
+
+@itemize *
+
+@item
+@code{break} `linespec' @code{task} `taskid', @code{break} `linespec' @code{task} `taskid' @code{if} …
+
+@quotation
+
+These commands are like the @code{break ... thread ...}.
+`linespec' specifies source lines.
+
+Use the qualifier @code{task @var{taskid}} with a breakpoint command
+to specify that you only want @code{GDB} to stop the program when a
+particular Ada task reaches this breakpoint. `taskid' is one of the
+numeric task identifiers assigned by @code{GDB}, shown in the first
+column of the @code{info tasks} display.
+
+If you do not specify @code{task @var{taskid}} when you set a
+breakpoint, the breakpoint applies to `all' tasks of your
+program.
+
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @code{task @var{taskid}} before the
+breakpoint condition (before the @code{if}).
+@end quotation
+@end itemize
+
+@geindex Task switching (in gdb)
+
+
+@itemize *
+
+@item
+@code{task @var{taskno}}
+
+@quotation
+
+This command allows switching to the task referred by `taskno'. In
+particular, this allows browsing of the backtrace of the specified
+task. It is advisable to switch back to the original task before
+continuing execution otherwise the scheduling of the program may be
+perturbed.
+@end quotation
+@end itemize
+
+For more detailed information on the tasking support,
+see @cite{Debugging with GDB}.
+
+@geindex Debugging Generic Units
+
+@geindex Generics
+
+@node Debugging Generic Units,Remote Debugging with gdbserver,Ada Tasks,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{15e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{15f}
+@subsection Debugging Generic Units
+
+
+GNAT always uses code expansion for generic instantiation. This means that
+each time an instantiation occurs, a complete copy of the original code is
+made, with appropriate substitutions of formals by actuals.
+
+It is not possible to refer to the original generic entities in
+@code{GDB}, but it is always possible to debug a particular instance of
+a generic, by using the appropriate expanded names. For example, if we have
+
+@quotation
+
+@example
+procedure g is
+
+ generic package k is
+ procedure kp (v1 : in out integer);
+ end k;
+
+ package body k is
+ procedure kp (v1 : in out integer) is
+ begin
+ v1 := v1 + 1;
+ end kp;
+ end k;
+
+ package k1 is new k;
+ package k2 is new k;
+
+ var : integer := 1;
+
+begin
+ k1.kp (var);
+ k2.kp (var);
+ k1.kp (var);
+ k2.kp (var);
+end;
+@end example
+@end quotation
+
+Then to break on a call to procedure kp in the k2 instance, simply
+use the command:
+
+@quotation
+
+@example
+(gdb) break g.k2.kp
+@end example
+@end quotation
+
+When the breakpoint occurs, you can step through the code of the
+instance in the normal manner and examine the values of local variables, as for
+other units.
+
+@geindex Remote Debugging with gdbserver
+
+@node Remote Debugging with gdbserver,GNAT Abnormal Termination or Failure to Terminate,Debugging Generic Units,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{160}@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{161}
+@subsection Remote Debugging with gdbserver
+
+
+On platforms where gdbserver is supported, it is possible to use this tool
+to debug your application remotely. This can be useful in situations
+where the program needs to be run on a target host that is different
+from the host used for development, particularly when the target has
+a limited amount of resources (either CPU and/or memory).
+
+To do so, start your program using gdbserver on the target machine.
+gdbserver then automatically suspends the execution of your program
+at its entry point, waiting for a debugger to connect to it. The
+following commands starts an application and tells gdbserver to
+wait for a connection with the debugger on localhost port 4444.
+
+@quotation
+
+@example
+$ gdbserver localhost:4444 program
+Process program created; pid = 5685
+Listening on port 4444
+@end example
+@end quotation
+
+Once gdbserver has started listening, we can tell the debugger to establish
+a connection with this gdbserver, and then start the same debugging session
+as if the program was being debugged on the same host, directly under
+the control of GDB.
+
+@quotation
+
+@example
+$ gdb program
+(gdb) target remote targethost:4444
+Remote debugging using targethost:4444
+0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so.
+(gdb) b foo.adb:3
+Breakpoint 1 at 0x401f0c: file foo.adb, line 3.
+(gdb) continue
+Continuing.
+
+Breakpoint 1, foo () at foo.adb:4
+4 end foo;
+@end example
+@end quotation
+
+It is also possible to use gdbserver to attach to an already running
+program, in which case the execution of that program is simply suspended
+until the connection between the debugger and gdbserver is established.
+
+For more information on how to use gdbserver, see the `Using the gdbserver Program'
+section in @cite{Debugging with GDB}.
+GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux.
+
+@geindex Abnormal Termination or Failure to Terminate
+
+@node GNAT Abnormal Termination or Failure to Terminate,Naming Conventions for GNAT Source Files,Remote Debugging with gdbserver,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{162}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{163}
+@subsection GNAT Abnormal Termination or Failure to Terminate
+
+
+When presented with programs that contain serious errors in syntax
+or semantics,
+GNAT may on rare occasions experience problems in operation, such
+as aborting with a
+segmentation fault or illegal memory access, raising an internal
+exception, terminating abnormally, or failing to terminate at all.
+In such cases, you can activate
+various features of GNAT that can help you pinpoint the construct in your
+program that is the likely source of the problem.
+
+The following strategies are presented in increasing order of
+difficulty, corresponding to your experience in using GNAT and your
+familiarity with compiler internals.
+
+
+@itemize *
+
+@item
+Run @code{gcc} with the @code{-gnatf}. This first
+switch causes all errors on a given line to be reported. In its absence,
+only the first error on a line is displayed.
+
+The @code{-gnatdO} switch causes errors to be displayed as soon as they
+are encountered, rather than after compilation is terminated. If GNAT
+terminates prematurely or goes into an infinite loop, the last error
+message displayed may help to pinpoint the culprit.
+
+@item
+Run @code{gcc} with the @code{-v} (verbose) switch. In this
+mode, @code{gcc} produces ongoing information about the progress of the
+compilation and provides the name of each procedure as code is
+generated. This switch allows you to find which Ada procedure was being
+compiled when it encountered a code generation problem.
+@end itemize
+
+@geindex -gnatdc switch
+
+
+@itemize *
+
+@item
+Run @code{gcc} with the @code{-gnatdc} switch. This is a GNAT specific
+switch that does for the front-end what @code{-v} does
+for the back end. The system prints the name of each unit,
+either a compilation unit or nested unit, as it is being analyzed.
+
+@item
+Finally, you can start
+@code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the
+front-end of GNAT, and can be run independently (normally it is just
+called from @code{gcc}). You can use @code{gdb} on @code{gnat1} as you
+would on a C program (but @ref{14f,,The GNAT Debugger GDB} for caveats). The
+@code{where} command is the first line of attack; the variable
+@code{lineno} (seen by @code{print lineno}), used by the second phase of
+@code{gnat1} and by the @code{gcc} backend, indicates the source line at
+which the execution stopped, and @code{input_file name} indicates the name of
+the source file.
+@end itemize
+
+@node Naming Conventions for GNAT Source Files,Getting Internal Debugging Information,GNAT Abnormal Termination or Failure to Terminate,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{164}@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{165}
+@subsection Naming Conventions for GNAT Source Files
+
+
+In order to examine the workings of the GNAT system, the following
+brief description of its organization may be helpful:
+
+
+@itemize *
+
+@item
+Files with prefix @code{sc} contain the lexical scanner.
+
+@item
+All files prefixed with @code{par} are components of the parser. The
+numbers correspond to chapters of the Ada Reference Manual. For example,
+parsing of select statements can be found in @code{par-ch9.adb}.
+
+@item
+All files prefixed with @code{sem} perform semantic analysis. The
+numbers correspond to chapters of the Ada standard. For example, all
+issues involving context clauses can be found in @code{sem_ch10.adb}. In
+addition, some features of the language require sufficient special processing
+to justify their own semantic files: sem_aggr for aggregates, sem_disp for
+dynamic dispatching, etc.
+
+@item
+All files prefixed with @code{exp} perform normalization and
+expansion of the intermediate representation (abstract syntax tree, or AST).
+these files use the same numbering scheme as the parser and semantics files.
+For example, the construction of record initialization procedures is done in
+@code{exp_ch3.adb}.
+
+@item
+The files prefixed with @code{bind} implement the binder, which
+verifies the consistency of the compilation, determines an order of
+elaboration, and generates the bind file.
+
+@item
+The files @code{atree.ads} and @code{atree.adb} detail the low-level
+data structures used by the front-end.
+
+@item
+The files @code{sinfo.ads} and @code{sinfo.adb} detail the structure of
+the abstract syntax tree as produced by the parser.
+
+@item
+The files @code{einfo.ads} and @code{einfo.adb} detail the attributes of
+all entities, computed during semantic analysis.
+
+@item
+Library management issues are dealt with in files with prefix
+@code{lib}.
+
+@geindex Annex A (in Ada Reference Manual)
+
+@item
+Ada files with the prefix @code{a-} are children of @code{Ada}, as
+defined in Annex A.
+
+@geindex Annex B (in Ada reference Manual)
+
+@item
+Files with prefix @code{i-} are children of @code{Interfaces}, as
+defined in Annex B.
+
+@geindex System (package in Ada Reference Manual)
+
+@item
+Files with prefix @code{s-} are children of @code{System}. This includes
+both language-defined children and GNAT run-time routines.
+
+@geindex GNAT (package)
+
+@item
+Files with prefix @code{g-} are children of @code{GNAT}. These are useful
+general-purpose packages, fully documented in their specs. All
+the other @code{.c} files are modifications of common @code{gcc} files.
+@end itemize
+
+@node Getting Internal Debugging Information,Stack Traceback,Naming Conventions for GNAT Source Files,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{166}@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{167}
+@subsection Getting Internal Debugging Information
+
+
+Most compilers have internal debugging switches and modes. GNAT
+does also, except GNAT internal debugging switches and modes are not
+secret. A summary and full description of all the compiler and binder
+debug flags are in the file @code{debug.adb}. You must obtain the
+sources of the compiler to see the full detailed effects of these flags.
+
+The switches that print the source of the program (reconstructed from
+the internal tree) are of general interest for user programs, as are the
+options to print
+the full internal tree, and the entity table (the symbol table
+information). The reconstructed source provides a readable version of the
+program after the front-end has completed analysis and expansion,
+and is useful when studying the performance of specific constructs.
+For example, constraint checks are indicated, complex aggregates
+are replaced with loops and assignments, and tasking primitives
+are replaced with run-time calls.
+
+@geindex traceback
+
+@geindex stack traceback
+
+@geindex stack unwinding
+
+@node Stack Traceback,Pretty-Printers for the GNAT runtime,Getting Internal Debugging Information,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{169}
+@subsection Stack Traceback
+
+
+Traceback is a mechanism to display the sequence of subprogram calls that
+leads to a specified execution point in a program. Often (but not always)
+the execution point is an instruction at which an exception has been raised.
+This mechanism is also known as `stack unwinding' because it obtains
+its information by scanning the run-time stack and recovering the activation
+records of all active subprograms. Stack unwinding is one of the most
+important tools for program debugging.
+
+The first entry stored in traceback corresponds to the deepest calling level,
+that is to say the subprogram currently executing the instruction
+from which we want to obtain the traceback.
+
+Note that there is no runtime performance penalty when stack traceback
+is enabled, and no exception is raised during program execution.
+
+@geindex traceback
+@geindex non-symbolic
+
+@menu
+* Non-Symbolic Traceback::
+* Symbolic Traceback::
+
+@end menu
+
+@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback
+@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{16b}
+@subsubsection Non-Symbolic Traceback
+
+
+Note: this feature is not supported on all platforms. See
+@code{GNAT.Traceback} spec in @code{g-traceb.ads}
+for a complete list of supported platforms.
+
+@subsubheading Tracebacks From an Unhandled Exception
+
+
+A runtime non-symbolic traceback is a list of addresses of call instructions.
+To enable this feature you must use the @code{-E} @code{gnatbind} option. With
+this option a stack traceback is stored as part of exception information.
+
+You can translate this information using the @code{addr2line} tool, provided that
+the program is compiled with debugging options (see @ref{db,,Compiler Switches})
+and linked at a fixed position with @code{-no-pie}.
+
+Here is a simple example with @code{gnatmake}:
+
+@quotation
+
+@example
+procedure STB is
+
+ procedure P1 is
+ begin
+ raise Constraint_Error;
+ end P1;
+
+ procedure P2 is
+ begin
+ P1;
+ end P2;
+
+begin
+ P2;
+end STB;
+@end example
+
+@example
+$ gnatmake stb -g -bargs -E -largs -no-pie
+$ stb
+
+Execution of stb terminated by unhandled exception
+raised CONSTRAINT_ERROR : stb.adb:5 explicit raise
+Load address: 0x400000
+Call stack traceback locations:
+0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
+@end example
+@end quotation
+
+As we see the traceback lists a sequence of addresses for the unhandled
+exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to
+guess that this exception come from procedure P1. To translate these
+addresses into the source lines where the calls appear, the @code{addr2line}
+tool needs to be invoked like this:
+
+@quotation
+
+@example
+$ addr2line -e stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4
+ 0x4011f1 0x77e892a4
+
+d:/stb/stb.adb:5
+d:/stb/stb.adb:10
+d:/stb/stb.adb:14
+d:/stb/b~stb.adb:197
+crtexe.c:?
+crtexe.c:?
+??:0
+@end example
+@end quotation
+
+The @code{addr2line} tool has several other useful options:
+
+@quotation
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+@code{-a --addresses}
+
+@tab
+
+to show the addresses alongside the line numbers
+
+@item
+
+@code{-f --functions}
+
+@tab
+
+to get the function name corresponding to a location
+
+@item
+
+@code{-p --pretty-print}
+
+@tab
+
+to print all the information on a single line
+
+@item
+
+@code{--demangle=gnat}
+
+@tab
+
+to use the GNAT decoding mode for the function names
+
+@end multitable
+
+
+@example
+$ addr2line -e stb -a -f -p --demangle=gnat 0x401373 0x40138b
+ 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
+
+0x00401373: stb.p1 at d:/stb/stb.adb:5
+0x0040138B: stb.p2 at d:/stb/stb.adb:10
+0x0040139C: stb at d:/stb/stb.adb:14
+0x00401335: main at d:/stb/b~stb.adb:197
+0x004011c4: ?? at crtexe.c:?
+0x004011f1: ?? at crtexe.c:?
+0x77e892a4: ?? ??:0
+@end example
+@end quotation
+
+From this traceback we can see that the exception was raised in @code{stb.adb}
+at line 5, which was reached from a procedure call in @code{stb.adb} at line
+10, and so on. The @code{b~std.adb} is the binder file, which contains the
+call to the main program. @ref{10e,,Running gnatbind}. The remaining entries are
+assorted runtime routines and the output will vary from platform to platform.
+
+It is also possible to use @code{GDB} with these traceback addresses to debug
+the program. For example, we can break at a given code location, as reported
+in the stack traceback:
+
+@example
+$ gdb -nw stb
+
+(gdb) break *0x401373
+Breakpoint 1 at 0x401373: file stb.adb, line 5.
+@end example
+
+It is important to note that the stack traceback addresses do not change when
+debug information is included. This is particularly useful because it makes it
+possible to release software without debug information (to minimize object
+size), get a field report that includes a stack traceback whenever an internal
+bug occurs, and then be able to retrieve the sequence of calls with the same
+program compiled with debug information.
+
+However the @code{addr2line} tool does not work with Position-Independent Code
+(PIC), the historical example being Windows DLLs, which nowadays encompasses
+Position-Independent Executables (PIE) on recent Windows versions.
+
+In order to translate addresses into the source lines with Position-Independent
+Executables on recent Windows versions, in other words without using the switch
+@code{-no-pie} during linking, you need to use the @code{gnatsymbolize} tool
+with @code{--load} instead of the @code{addr2line} tool. The main difference
+is that you need to copy the Load Address output in the traceback ahead of the
+sequence of addresses. And the default mode of @code{gnatsymbolize} is equivalent
+to that of @code{addr2line} with the above switches, so none of them is needed:
+
+@example
+$ gnatmake stb -g -bargs -E
+$ stb
+
+Execution of stb terminated by unhandled exception
+raised CONSTRAINT_ERROR : stb.adb:5 explicit raise
+Load address: 0x400000
+Call stack traceback locations:
+0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
+
+$ gnatsymbolize --load stb 0x400000 0x401373 0x40138b 0x40139c 0x401335
+ 0x4011c4 0x4011f1 0x77e892a4
+
+0x00401373 Stb.P1 at stb.adb:5
+0x0040138B Stb.P2 at stb.adb:10
+0x0040139C Stb at stb.adb:14
+0x00401335 Main at b~stb.adb:197
+0x004011c4 __tmainCRTStartup at ???
+0x004011f1 mainCRTStartup at ???
+0x77e892a4 ??? at ???
+@end example
+
+@subsubheading Tracebacks From Exception Occurrences
+
+
+Non-symbolic tracebacks are obtained by using the @code{-E} binder argument.
+The stack traceback is attached to the exception information string, and can
+be retrieved in an exception handler within the Ada program, by means of the
+Ada facilities defined in @code{Ada.Exceptions}. Here is a simple example:
+
+@quotation
+
+@example
+with Ada.Text_IO;
+with Ada.Exceptions;
+
+procedure STB is
+
+ use Ada;
+ use Ada.Exceptions;
+
+ procedure P1 is
+ K : Positive := 1;
+ begin
+ K := K - 1;
+ exception
+ when E : others =>
+ Text_IO.Put_Line (Exception_Information (E));
+ end P1;
+
+ procedure P2 is
+ begin
+ P1;
+ end P2;
+
+begin
+ P2;
+end STB;
+@end example
+@end quotation
+
+This program will output:
+
+@quotation
+
+@example
+$ stb
+
+raised CONSTRAINT_ERROR : stb.adb:12 range check failed
+Load address: 0x400000
+Call stack traceback locations:
+0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4
+@end example
+@end quotation
+
+@subsubheading Tracebacks From Anywhere in a Program
+
+
+It is also possible to retrieve a stack traceback from anywhere in a program.
+For this you need to use the @code{GNAT.Traceback} API. This package includes a
+procedure called @code{Call_Chain} that computes a complete stack traceback, as
+well as useful display procedures described below. It is not necessary to use
+the @code{-E} @code{gnatbind} option in this case, because the stack traceback
+mechanism is invoked explicitly.
+
+In the following example we compute a traceback at a specific location in the
+program, and we display it using @code{GNAT.Debug_Utilities.Image} to convert
+addresses to strings:
+
+@quotation
+
+@example
+with Ada.Text_IO;
+with GNAT.Traceback;
+with GNAT.Debug_Utilities;
+
+procedure STB is
+
+ use Ada;
+ use GNAT;
+ use GNAT.Traceback;
+
+ procedure P1 is
+ TB : Tracebacks_Array (1 .. 10);
+ -- We are asking for a maximum of 10 stack frames.
+ Len : Natural;
+ -- Len will receive the actual number of stack frames returned.
+ begin
+ Call_Chain (TB, Len);
+
+ Text_IO.Put ("In STB.P1 : ");
+
+ for K in 1 .. Len loop
+ Text_IO.Put (Debug_Utilities.Image (TB (K)));
+ Text_IO.Put (' ');
+ end loop;
+
+ Text_IO.New_Line;
+ end P1;
+
+ procedure P2 is
+ begin
+ P1;
+ end P2;
+
+begin
+ P2;
+end STB;
+@end example
+
+@example
+$ gnatmake stb -g
+$ stb
+
+In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C#
+16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4#
+@end example
+@end quotation
+
+You can then get further information by invoking the @code{addr2line} tool or
+the @code{gnatsymbolize} tool as described earlier (note that the hexadecimal
+addresses need to be specified in C format, with a leading ‘0x’).
+
+@geindex traceback
+@geindex symbolic
+
+@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback
+@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{16d}
+@subsubsection Symbolic Traceback
+
+
+A symbolic traceback is a stack traceback in which procedure names are
+associated with each code location.
+
+Note that this feature is not supported on all platforms. See
+@code{GNAT.Traceback.Symbolic} spec in @code{g-trasym.ads} for a complete
+list of currently supported platforms.
+
+Note that the symbolic traceback requires that the program be compiled
+with debug information. If it is not compiled with debug information
+only the non-symbolic information will be valid.
+
+@subsubheading Tracebacks From Exception Occurrences
+
+
+Here is an example:
+
+@quotation
+
+@example
+with Ada.Text_IO;
+with GNAT.Traceback.Symbolic;
+
+procedure STB is
+
+ procedure P1 is
+ begin
+ raise Constraint_Error;
+ end P1;
+
+ procedure P2 is
+ begin
+ P1;
+ end P2;
+
+ procedure P3 is
+ begin
+ P2;
+ end P3;
+
+begin
+ P3;
+exception
+ when E : others =>
+ Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E));
+end STB;
+@end example
+
+@example
+$ gnatmake -g .\stb -bargs -E
+$ stb
+
+0040149F in stb.p1 at stb.adb:8
+004014B7 in stb.p2 at stb.adb:13
+004014CF in stb.p3 at stb.adb:18
+004015DD in ada.stb at stb.adb:22
+00401461 in main at b~stb.adb:168
+004011C4 in __mingw_CRTStartup at crt1.c:200
+004011F1 in mainCRTStartup at crt1.c:222
+77E892A4 in ?? at ??:0
+@end example
+@end quotation
+
+In the above example the @code{.\} syntax in the @code{gnatmake} command
+is currently required by @code{addr2line} for files that are in
+the current working directory.
+Moreover, the exact sequence of linker options may vary from platform
+to platform.
+The above @code{-largs} section is for Windows platforms. By contrast,
+under Unix there is no need for the @code{-largs} section.
+Differences across platforms are due to details of linker implementation.
+
+@subsubheading Tracebacks From Anywhere in a Program
+
+
+It is possible to get a symbolic stack traceback
+from anywhere in a program, just as for non-symbolic tracebacks.
+The first step is to obtain a non-symbolic
+traceback, and then call @code{Symbolic_Traceback} to compute the symbolic
+information. Here is an example:
+
+@quotation
+
+@example
+with Ada.Text_IO;
+with GNAT.Traceback;
+with GNAT.Traceback.Symbolic;
+
+procedure STB is
+
+ use Ada;
+ use GNAT.Traceback;
+ use GNAT.Traceback.Symbolic;
+
+ procedure P1 is
+ TB : Tracebacks_Array (1 .. 10);
+ -- We are asking for a maximum of 10 stack frames.
+ Len : Natural;
+ -- Len will receive the actual number of stack frames returned.
+ begin
+ Call_Chain (TB, Len);
+ Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len)));
+ end P1;
+
+ procedure P2 is
+ begin
+ P1;
+ end P2;
+
+begin
+ P2;
+end STB;
+@end example
+@end quotation
+
+@subsubheading Automatic Symbolic Tracebacks
+
+
+Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as
+in @code{gprbuild -g ... -bargs -Es}).
+This will cause the Exception_Information to contain a symbolic traceback,
+which will also be printed if an unhandled exception terminates the
+program.
+
+@node Pretty-Printers for the GNAT runtime,,Stack Traceback,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{16e}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{16f}
+@subsection Pretty-Printers for the GNAT runtime
+
+
+As discussed in @cite{Calling User-Defined Subprograms}, GDB’s
+@code{print} command only knows about the physical layout of program data
+structures and therefore normally displays only low-level dumps, which
+are often hard to understand.
+
+An example of this is when trying to display the contents of an Ada
+standard container, such as @code{Ada.Containers.Ordered_Maps.Map}:
+
+@quotation
+
+@example
+with Ada.Containers.Ordered_Maps;
+
+procedure PP is
+ package Int_To_Nat is
+ new Ada.Containers.Ordered_Maps (Integer, Natural);
+
+ Map : Int_To_Nat.Map;
+begin
+ Map.Insert (1, 10);
+ Map.Insert (2, 20);
+ Map.Insert (3, 30);
+
+ Map.Clear; -- BREAK HERE
+end PP;
+@end example
+@end quotation
+
+When this program is built with debugging information and run under
+GDB up to the @code{Map.Clear} statement, trying to print @code{Map} will
+yield information that is only relevant to the developers of our standard
+containers:
+
+@quotation
+
+@example
+(gdb) print map
+$1 = (
+ tree => (
+ first => 0x64e010,
+ last => 0x64e070,
+ root => 0x64e040,
+ length => 3,
+ tc => (
+ busy => 0,
+ lock => 0
+ )
+ )
+)
+@end example
+@end quotation
+
+Fortunately, GDB has a feature called pretty-printers@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Introduction},
+which allows customizing how GDB displays data structures. The GDB
+shipped with GNAT embeds such pretty-printers for the most common
+containers in the standard library. To enable them, either run the
+following command manually under GDB or add it to your @code{.gdbinit} file:
+
+@quotation
+
+@example
+python import gnatdbg; gnatdbg.setup()
+@end example
+@end quotation
+
+Once this is done, GDB’s @code{print} command will automatically use
+these pretty-printers when appropriate. Using the previous example:
+
+@quotation
+
+@example
+(gdb) print map
+$1 = pp.int_to_nat.map of length 3 = @{
+ [1] = 10,
+ [2] = 20,
+ [3] = 30
+@}
+@end example
+@end quotation
+
+Pretty-printers are invoked each time GDB tries to display a value,
+including when displaying the arguments of a called subprogram (in
+GDB’s @code{backtrace} command) or when printing the value returned by a
+function (in GDB’s @code{finish} command).
+
+To display a value without involving pretty-printers, @code{print} can be
+invoked with its @code{/r} option:
+
+@quotation
+
+@example
+(gdb) print/r map
+$1 = (
+ tree => (...
+@end example
+@end quotation
+
+Finer control of pretty-printers is also possible: see GDB's online documentation@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands}
+for more information.
+
+@geindex Profiling
+
+@node Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{170}@anchor{gnat_ugn/gnat_and_program_execution profiling}@anchor{147}
+@section Profiling
+
+
+This section describes how to use the @code{gprof} profiler tool on Ada programs.
+
+@geindex gprof
+
+@geindex Profiling
+
+@menu
+* Profiling an Ada Program with gprof::
+
+@end menu
+
+@node Profiling an Ada Program with gprof,,,Profiling
+@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{171}@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{172}
+@subsection Profiling an Ada Program with gprof
+
+
+This section is not meant to be an exhaustive documentation of @code{gprof}.
+Full documentation for it can be found in the @cite{GNU Profiler User’s Guide}
+documentation that is part of this GNAT distribution.
+
+Profiling a program helps determine the parts of a program that are executed
+most often, and are therefore the most time-consuming.
+
+@code{gprof} is the standard GNU profiling tool; it has been enhanced to
+better handle Ada programs and multitasking.
+It is currently supported on the following platforms
+
+
+@itemize *
+
+@item
+Linux x86/x86_64
+
+@item
+Windows x86/x86_64 (without PIE support)
+@end itemize
+
+In order to profile a program using @code{gprof}, several steps are needed:
+
+
+@enumerate
+
+@item
+Instrument the code, which requires a full recompilation of the project with the
+proper switches.
+
+@item
+Execute the program under the analysis conditions, i.e. with the desired
+input.
+
+@item
+Analyze the results using the @code{gprof} tool.
+@end enumerate
+
+The following sections detail the different steps, and indicate how
+to interpret the results.
+
+@menu
+* Compilation for profiling::
+* Program execution::
+* Running gprof::
+* Interpretation of profiling results::
+
+@end menu
+
+@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof
+@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{173}@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{174}
+@subsubsection Compilation for profiling
+
+
+@geindex -pg (gcc)
+@geindex for profiling
+
+@geindex -pg (gnatlink)
+@geindex for profiling
+
+In order to profile a program the first step is to tell the compiler
+to generate the necessary profiling information. The compiler switch to be used
+is @code{-pg}, which must be added to other compilation switches. This
+switch needs to be specified both during compilation and link stages, and can
+be specified once when using gnatmake:
+
+@quotation
+
+@example
+$ gnatmake -f -pg -P my_project
+@end example
+@end quotation
+
+Note that only the objects that were compiled with the @code{-pg} switch will
+be profiled; if you need to profile your whole project, use the @code{-f}
+gnatmake switch to force full recompilation.
+
+Note that on Windows, gprof does not support PIE. The @code{-no-pie} switch
+should be added to the linker flags to disable this feature.
+
+@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof
+@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{175}@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{176}
+@subsubsection Program execution
+
+
+Once the program has been compiled for profiling, you can run it as usual.
+
+The only constraint imposed by profiling is that the program must terminate
+normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
+properly analyzed.
+
+Once the program completes execution, a data file called @code{gmon.out} is
+generated in the directory where the program was launched from. If this file
+already exists, it will be overwritten.
+
+@node Running gprof,Interpretation of profiling results,Program execution,Profiling an Ada Program with gprof
+@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{177}@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{178}
+@subsubsection Running gprof
+
+
+The @code{gprof} tool is called as follow:
+
+@quotation
+
+@example
+$ gprof my_prog gmon.out
+@end example
+@end quotation
+
+or simply:
+
+@quotation
+
+@example
+$ gprof my_prog
+@end example
+@end quotation
+
+The complete form of the gprof command line is the following:
+
+@quotation
+
+@example
+$ gprof [switches] [executable [data-file]]
+@end example
+@end quotation
+
+@code{gprof} supports numerous switches. The order of these
+switch does not matter. The full list of options can be found in
+the GNU Profiler User’s Guide documentation that comes with this documentation.
+
+The following is the subset of those switches that is most relevant:
+
+@geindex --demangle (gprof)
+
+
+@table @asis
+
+@item @code{--demangle[=@var{style}]}, @code{--no-demangle}
+
+These options control whether symbol names should be demangled when
+printing output. The default is to demangle C++ symbols. The
+@code{--no-demangle} option may be used to turn off demangling. Different
+compilers have different mangling styles. The optional demangling style
+argument can be used to choose an appropriate demangling style for your
+compiler, in particular Ada symbols generated by GNAT can be demangled using
+@code{--demangle=gnat}.
+@end table
+
+@geindex -e (gprof)
+
+
+@table @asis
+
+@item @code{-e @var{function_name}}
+
+The @code{-e @var{function}} option tells @code{gprof} not to print
+information about the function @code{function_name} (and its
+children…) in the call graph. The function will still be listed
+as a child of any functions that call it, but its index number will be
+shown as @code{[not printed]}. More than one @code{-e} option may be
+given; only one @code{function_name} may be indicated with each @code{-e}
+option.
+@end table
+
+@geindex -E (gprof)
+
+
+@table @asis
+
+@item @code{-E @var{function_name}}
+
+The @code{-E @var{function}} option works like the @code{-e} option, but
+execution time spent in the function (and children who were not called from
+anywhere else), will not be used to compute the percentages-of-time for
+the call graph. More than one @code{-E} option may be given; only one
+@code{function_name} may be indicated with each @code{-E`} option.
+@end table
+
+@geindex -f (gprof)
+
+
+@table @asis
+
+@item @code{-f @var{function_name}}
+
+The @code{-f @var{function}} option causes @code{gprof} to limit the
+call graph to the function @code{function_name} and its children (and
+their children…). More than one @code{-f} option may be given;
+only one @code{function_name} may be indicated with each @code{-f}
+option.
+@end table
+
+@geindex -F (gprof)
+
+
+@table @asis
+
+@item @code{-F @var{function_name}}
+
+The @code{-F @var{function}} option works like the @code{-f} option, but
+only time spent in the function and its children (and their
+children…) will be used to determine total-time and
+percentages-of-time for the call graph. More than one @code{-F} option
+may be given; only one @code{function_name} may be indicated with each
+@code{-F} option. The @code{-F} option overrides the @code{-E} option.
+@end table
+
+@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof
+@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{179}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{17a}
+@subsubsection Interpretation of profiling results
+
+
+The results of the profiling analysis are represented by two arrays: the
+‘flat profile’ and the ‘call graph’. Full documentation of those outputs
+can be found in the GNU Profiler User’s Guide.
+
+The flat profile shows the time spent in each function of the program, and how
+many time it has been called. This allows you to locate easily the most
+time-consuming functions.
+
+The call graph shows, for each subprogram, the subprograms that call it,
+and the subprograms that it calls. It also provides an estimate of the time
+spent in each of those callers/called subprograms.
+
+@node Improving Performance,Overflow Check Handling in GNAT,Profiling,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{148}@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{17b}
+@section Improving Performance
+
+
+@geindex Improving performance
+
+This section presents several topics related to program performance.
+It first describes some of the tradeoffs that need to be considered
+and some of the techniques for making your program run faster.
+
+It then documents the unused subprogram/data elimination feature,
+which can reduce the size of program executables.
+
+@menu
+* Performance Considerations::
+* Text_IO Suggestions::
+* Reducing Size of Executables with Unused Subprogram/Data Elimination::
+
+@end menu
+
+@node Performance Considerations,Text_IO Suggestions,,Improving Performance
+@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{17d}
+@subsection Performance Considerations
+
+
+The GNAT system provides a number of options that allow a trade-off
+between
+
+
+@itemize *
+
+@item
+performance of the generated code
+
+@item
+speed of compilation
+
+@item
+minimization of dependences and recompilation
+
+@item
+the degree of run-time checking.
+@end itemize
+
+The defaults (if no options are selected) aim at improving the speed
+of compilation and minimizing dependences, at the expense of performance
+of the generated code:
+
+
+@itemize *
+
+@item
+no optimization
+
+@item
+no inlining of subprogram calls
+
+@item
+all run-time checks enabled except overflow and elaboration checks
+@end itemize
+
+These options are suitable for most program development purposes. This
+section describes how you can modify these choices, and also provides
+some guidelines on debugging optimized code.
+
+@menu
+* Controlling Run-Time Checks::
+* Use of Restrictions::
+* Optimization Levels::
+* Debugging Optimized Code::
+* Inlining of Subprograms::
+* Floating Point Operations::
+* Vectorization of loops::
+* Other Optimization Switches::
+* Optimization and Strict Aliasing::
+* Aliased Variables and Optimization::
+* Atomic Variables and Optimization::
+* Passive Task Optimization::
+
+@end menu
+
+@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{17f}
+@subsubsection Controlling Run-Time Checks
+
+
+By default, GNAT generates all run-time checks, except stack overflow
+checks, and checks for access before elaboration on subprogram
+calls. The latter are not required in default mode, because all
+necessary checking is done at compile time.
+
+@geindex -gnatp (gcc)
+
+@geindex -gnato (gcc)
+
+The gnat switch, @code{-gnatp} allows this default to be modified. See
+@ref{ea,,Run-Time Checks}.
+
+Our experience is that the default is suitable for most development
+purposes.
+
+Elaboration checks are off by default, and also not needed by default, since
+GNAT uses a static elaboration analysis approach that avoids the need for
+run-time checking. This manual contains a full chapter discussing the issue
+of elaboration checks, and if the default is not satisfactory for your use,
+you should read this chapter.
+
+For validity checks, the minimal checks required by the Ada Reference
+Manual (for case statements and assignments to array elements) are on
+by default. These can be suppressed by use of the @code{-gnatVn} switch.
+Note that in Ada 83, there were no validity checks, so if the Ada 83 mode
+is acceptable (or when comparing GNAT performance with an Ada 83 compiler),
+it may be reasonable to routinely use @code{-gnatVn}. Validity checks
+are also suppressed entirely if @code{-gnatp} is used.
+
+@geindex Overflow checks
+
+@geindex Checks
+@geindex overflow
+
+@geindex Suppress
+
+@geindex Unsuppress
+
+@geindex pragma Suppress
+
+@geindex pragma Unsuppress
+
+Note that the setting of the switches controls the default setting of
+the checks. They may be modified using either @code{pragma Suppress} (to
+remove checks) or @code{pragma Unsuppress} (to add back suppressed
+checks) in the program source.
+
+@node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{180}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{181}
+@subsubsection Use of Restrictions
+
+
+The use of pragma Restrictions allows you to control which features are
+permitted in your program. Apart from the obvious point that if you avoid
+relatively expensive features like finalization (enforceable by the use
+of pragma Restrictions (No_Finalization)), the use of this pragma does not
+affect the generated code in most cases.
+
+One notable exception to this rule is that the possibility of task abort
+results in some distributed overhead, particularly if finalization or
+exception handlers are used. The reason is that certain sections of code
+have to be marked as non-abortable.
+
+If you use neither the @code{abort} statement, nor asynchronous transfer
+of control (@code{select ... then abort}), then this distributed overhead
+is removed, which may have a general positive effect in improving
+overall performance. Especially code involving frequent use of tasking
+constructs and controlled types will show much improved performance.
+The relevant restrictions pragmas are
+
+@quotation
+
+@example
+pragma Restrictions (No_Abort_Statements);
+pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);
+@end example
+@end quotation
+
+It is recommended that these restriction pragmas be used if possible. Note
+that this also means that you can write code without worrying about the
+possibility of an immediate abort at any point.
+
+@node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed}
+@subsubsection Optimization Levels
+
+
+@geindex -O (gcc)
+
+Without any optimization option,
+the compiler’s goal is to reduce the cost of
+compilation and to make debugging produce the expected results.
+Statements are independent: if you stop the program with a breakpoint between
+statements, you can then assign a new value to any variable or change
+the program counter to any other statement in the subprogram and get exactly
+the results you would expect from the source code.
+
+Turning on optimization makes the compiler attempt to improve the
+performance and/or code size at the expense of compilation time and
+possibly the ability to debug the program.
+
+If you use multiple
+-O options, with or without level numbers,
+the last such option is the one that is effective.
+
+The default is optimization off. This results in the fastest compile
+times, but GNAT makes absolutely no attempt to optimize, and the
+generated programs are considerably larger and slower than when
+optimization is enabled. You can use the
+@code{-O} switch (the permitted forms are @code{-O0}, @code{-O1}
+@code{-O2}, @code{-O3}, and @code{-Os})
+to @code{gcc} to control the optimization level:
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item @code{-O0}
+
+No optimization (the default);
+generates unoptimized code but has
+the fastest compilation time.
+
+Note that many other compilers do substantial optimization even
+if ‘no optimization’ is specified. With gcc, it is very unusual
+to use @code{-O0} for production if execution time is of any concern,
+since @code{-O0} means (almost) no optimization. This difference
+between gcc and other compilers should be kept in mind when
+doing performance comparisons.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-O1}
+
+Moderate optimization;
+optimizes reasonably well but does not
+degrade compilation time significantly.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-O2}
+
+Full optimization;
+generates highly optimized code and has
+the slowest compilation time.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-O3}
+
+Full optimization as in @code{-O2};
+also uses more aggressive automatic inlining of subprograms within a unit
+(@ref{100,,Inlining of Subprograms}) and attempts to vectorize loops.
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-Os}
+
+Optimize space usage (code and data) of resulting program.
+@end table
+@end itemize
+
+Higher optimization levels perform more global transformations on the
+program and apply more expensive analysis algorithms in order to generate
+faster and more compact code. The price in compilation time, and the
+resulting improvement in execution time,
+both depend on the particular application and the hardware environment.
+You should experiment to find the best level for your application.
+
+Since the precise set of optimizations done at each level will vary from
+release to release (and sometime from target to target), it is best to think
+of the optimization settings in general terms.
+See the `Options That Control Optimization' section in
+@cite{Using the GNU Compiler Collection (GCC)}
+for details about
+the @code{-O} settings and a number of @code{-f} options that
+individually enable or disable specific optimizations.
+
+Unlike some other compilation systems, @code{gcc} has
+been tested extensively at all optimization levels. There are some bugs
+which appear only with optimization turned on, but there have also been
+bugs which show up only in `unoptimized' code. Selecting a lower
+level of optimization does not improve the reliability of the code
+generator, which in practice is highly reliable at all optimization
+levels.
+
+Note regarding the use of @code{-O3}: The use of this optimization level
+ought not to be automatically preferred over that of level @code{-O2},
+since it often results in larger executables which may run more slowly.
+See further discussion of this point in @ref{100,,Inlining of Subprograms}.
+
+@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{183}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{184}
+@subsubsection Debugging Optimized Code
+
+
+@geindex Debugging optimized code
+
+@geindex Optimization and debugging
+
+Although it is possible to do a reasonable amount of debugging at
+nonzero optimization levels,
+the higher the level the more likely that
+source-level constructs will have been eliminated by optimization.
+For example, if a loop is strength-reduced, the loop
+control variable may be completely eliminated and thus cannot be
+displayed in the debugger.
+This can only happen at @code{-O2} or @code{-O3}.
+Explicit temporary variables that you code might be eliminated at
+level @code{-O1} or higher.
+
+@geindex -g (gcc)
+
+The use of the @code{-g} switch,
+which is needed for source-level debugging,
+affects the size of the program executable on disk,
+and indeed the debugging information can be quite large.
+However, it has no effect on the generated code (and thus does not
+degrade performance)
+
+Since the compiler generates debugging tables for a compilation unit before
+it performs optimizations, the optimizing transformations may invalidate some
+of the debugging data. You therefore need to anticipate certain
+anomalous situations that may arise while debugging optimized code.
+These are the most common cases:
+
+
+@itemize *
+
+@item
+`The ‘hopping Program Counter’:' Repeated @code{step} or @code{next}
+commands show
+the PC bouncing back and forth in the code. This may result from any of
+the following optimizations:
+
+
+@itemize -
+
+@item
+`Common subexpression elimination:' using a single instance of code for a
+quantity that the source computes several times. As a result you
+may not be able to stop on what looks like a statement.
+
+@item
+`Invariant code motion:' moving an expression that does not change within a
+loop, to the beginning of the loop.
+
+@item
+`Instruction scheduling:' moving instructions so as to
+overlap loads and stores (typically) with other code, or in
+general to move computations of values closer to their uses. Often
+this causes you to pass an assignment statement without the assignment
+happening and then later bounce back to the statement when the
+value is actually needed. Placing a breakpoint on a line of code
+and then stepping over it may, therefore, not always cause all the
+expected side-effects.
+@end itemize
+
+@item
+`The ‘big leap’:' More commonly known as `cross-jumping', in which
+two identical pieces of code are merged and the program counter suddenly
+jumps to a statement that is not supposed to be executed, simply because
+it (and the code following) translates to the same thing as the code
+that `was' supposed to be executed. This effect is typically seen in
+sequences that end in a jump, such as a @code{goto}, a @code{return}, or
+a @code{break} in a C @code{switch} statement.
+
+@item
+`The ‘roving variable’:' The symptom is an unexpected value in a variable.
+There are various reasons for this effect:
+
+
+@itemize -
+
+@item
+In a subprogram prologue, a parameter may not yet have been moved to its
+‘home’.
+
+@item
+A variable may be dead, and its register re-used. This is
+probably the most common cause.
+
+@item
+As mentioned above, the assignment of a value to a variable may
+have been moved.
+
+@item
+A variable may be eliminated entirely by value propagation or
+other means. In this case, GCC may incorrectly generate debugging
+information for the variable
+@end itemize
+
+In general, when an unexpected value appears for a local variable or parameter
+you should first ascertain if that value was actually computed by
+your program, as opposed to being incorrectly reported by the debugger.
+Record fields or
+array elements in an object designated by an access value
+are generally less of a problem, once you have ascertained that the access
+value is sensible.
+Typically, this means checking variables in the preceding code and in the
+calling subprogram to verify that the value observed is explainable from other
+values (one must apply the procedure recursively to those
+other values); or re-running the code and stopping a little earlier
+(perhaps before the call) and stepping to better see how the variable obtained
+the value in question; or continuing to step `from' the point of the
+strange value to see if code motion had simply moved the variable’s
+assignments later.
+@end itemize
+
+In light of such anomalies, a recommended technique is to use @code{-O0}
+early in the software development cycle, when extensive debugging capabilities
+are most needed, and then move to @code{-O1} and later @code{-O2} as
+the debugger becomes less critical.
+Whether to use the @code{-g} switch in the release version is
+a release management issue.
+Note that if you use @code{-g} you can then use the @code{strip} program
+on the resulting executable,
+which removes both debugging information and global symbols.
+
+@node Inlining of Subprograms,Floating Point Operations,Debugging Optimized Code,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{185}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{100}
+@subsubsection Inlining of Subprograms
+
+
+A call to a subprogram in the current unit is inlined if all the
+following conditions are met:
+
+
+@itemize *
+
+@item
+The optimization level is at least @code{-O1}.
+
+@item
+The called subprogram is suitable for inlining: It must be small enough
+and not contain something that @code{gcc} cannot support in inlined
+subprograms.
+
+@geindex pragma Inline
+
+@geindex Inline
+
+@item
+Any one of the following applies: @code{pragma Inline} is applied to the
+subprogram; the subprogram is local to the unit and called once from
+within it; the subprogram is small and optimization level @code{-O2} is
+specified; optimization level @code{-O3} is specified.
+@end itemize
+
+Calls to subprograms in `with'ed units are normally not inlined.
+To achieve actual inlining (that is, replacement of the call by the code
+in the body of the subprogram), the following conditions must all be true:
+
+
+@itemize *
+
+@item
+The optimization level is at least @code{-O1}.
+
+@item
+The called subprogram is suitable for inlining: It must be small enough
+and not contain something that @code{gcc} cannot support in inlined
+subprograms.
+
+@item
+There is a @code{pragma Inline} for the subprogram.
+
+@item
+The @code{-gnatn} switch is used on the command line.
+@end itemize
+
+Even if all these conditions are met, it may not be possible for
+the compiler to inline the call, due to the length of the body,
+or features in the body that make it impossible for the compiler
+to do the inlining.
+
+Note that specifying the @code{-gnatn} switch causes additional
+compilation dependencies. Consider the following:
+
+@quotation
+
+@example
+package R is
+ procedure Q;
+ pragma Inline (Q);
+end R;
+package body R is
+ ...
+end R;
+
+with R;
+procedure Main is
+begin
+ ...
+ R.Q;
+end Main;
+@end example
+@end quotation
+
+With the default behavior (no @code{-gnatn} switch specified), the
+compilation of the @code{Main} procedure depends only on its own source,
+@code{main.adb}, and the spec of the package in file @code{r.ads}. This
+means that editing the body of @code{R} does not require recompiling
+@code{Main}.
+
+On the other hand, the call @code{R.Q} is not inlined under these
+circumstances. If the @code{-gnatn} switch is present when @code{Main}
+is compiled, the call will be inlined if the body of @code{Q} is small
+enough, but now @code{Main} depends on the body of @code{R} in
+@code{r.adb} as well as on the spec. This means that if this body is edited,
+the main program must be recompiled. Note that this extra dependency
+occurs whether or not the call is in fact inlined by @code{gcc}.
+
+The use of front end inlining with @code{-gnatN} generates similar
+additional dependencies.
+
+@geindex -fno-inline (gcc)
+
+Note: The @code{-fno-inline} switch overrides all other conditions and ensures that
+no inlining occurs, unless requested with pragma Inline_Always for @code{gcc}
+back-ends. The extra dependences resulting from @code{-gnatn} will still be active,
+even if this switch is used to suppress the resulting inlining actions.
+
+@geindex -fno-inline-functions (gcc)
+
+Note: The @code{-fno-inline-functions} switch can be used to prevent
+automatic inlining of subprograms if @code{-O3} is used.
+
+@geindex -fno-inline-small-functions (gcc)
+
+Note: The @code{-fno-inline-small-functions} switch can be used to prevent
+automatic inlining of small subprograms if @code{-O2} is used.
+
+@geindex -fno-inline-functions-called-once (gcc)
+
+Note: The @code{-fno-inline-functions-called-once} switch
+can be used to prevent inlining of subprograms local to the unit
+and called once from within it if @code{-O1} is used.
+
+Note regarding the use of @code{-O3}: @code{-gnatn} is made up of two
+sub-switches @code{-gnatn1} and @code{-gnatn2} that can be directly
+specified in lieu of it, @code{-gnatn} being translated into one of them
+based on the optimization level. With @code{-O2} or below, @code{-gnatn}
+is equivalent to @code{-gnatn1} which activates pragma @code{Inline} with
+moderate inlining across modules. With @code{-O3}, @code{-gnatn} is
+equivalent to @code{-gnatn2} which activates pragma @code{Inline} with
+full inlining across modules. If you have used pragma @code{Inline} in
+appropriate cases, then it is usually much better to use @code{-O2}
+and @code{-gnatn} and avoid the use of @code{-O3} which has the additional
+effect of inlining subprograms you did not think should be inlined. We have
+found that the use of @code{-O3} may slow down the compilation and increase
+the code size by performing excessive inlining, leading to increased
+instruction cache pressure from the increased code size and thus minor
+performance improvements. So the bottom line here is that you should not
+automatically assume that @code{-O3} is better than @code{-O2}, and
+indeed you should use @code{-O3} only if tests show that it actually
+improves performance for your program.
+
+@node Floating Point Operations,Vectorization of loops,Inlining of Subprograms,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{186}@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{187}
+@subsubsection Floating Point Operations
+
+
+@geindex Floating-Point Operations
+
+On almost all targets, GNAT maps Float and Long_Float to the 32-bit and
+64-bit standard IEEE floating-point representations, and operations will
+use standard IEEE arithmetic as provided by the processor. On most, but
+not all, architectures, the attribute Machine_Overflows is False for these
+types, meaning that the semantics of overflow is implementation-defined.
+In the case of GNAT, these semantics correspond to the normal IEEE
+treatment of infinities and NaN (not a number) values. For example,
+1.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By
+avoiding explicit overflow checks, the performance is greatly improved
+on many targets. However, if required, floating-point overflow can be
+enabled by the use of the pragma Check_Float_Overflow.
+
+Another consideration that applies specifically to x86 32-bit
+architectures is which form of floating-point arithmetic is used.
+By default the operations use the old style x86 floating-point,
+which implements an 80-bit extended precision form (on these
+architectures the type Long_Long_Float corresponds to that form).
+In addition, generation of efficient code in this mode means that
+the extended precision form will be used for intermediate results.
+This may be helpful in improving the final precision of a complex
+expression. However it means that the results obtained on the x86
+will be different from those on other architectures, and for some
+algorithms, the extra intermediate precision can be detrimental.
+
+In addition to this old-style floating-point, all modern x86 chips
+implement an alternative floating-point operation model referred
+to as SSE2. In this model there is no extended form, and furthermore
+execution performance is significantly enhanced. To force GNAT to use
+this more modern form, use both of the switches:
+
+@quotation
+
+-msse2 -mfpmath=sse
+@end quotation
+
+A unit compiled with these switches will automatically use the more
+efficient SSE2 instruction set for Float and Long_Float operations.
+Note that the ABI has the same form for both floating-point models,
+so it is permissible to mix units compiled with and without these
+switches.
+
+@node Vectorization of loops,Other Optimization Switches,Floating Point Operations,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{188}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{189}
+@subsubsection Vectorization of loops
+
+
+@geindex Optimization Switches
+
+You can take advantage of the auto-vectorizer present in the @code{gcc}
+back end to vectorize loops with GNAT. The corresponding command line switch
+is @code{-ftree-vectorize} but, as it is enabled by default at @code{-O3}
+and other aggressive optimizations helpful for vectorization also are enabled
+by default at this level, using @code{-O3} directly is recommended.
+
+You also need to make sure that the target architecture features a supported
+SIMD instruction set. For example, for the x86 architecture, you should at
+least specify @code{-msse2} to get significant vectorization (but you don’t
+need to specify it for x86-64 as it is part of the base 64-bit architecture).
+Similarly, for the PowerPC architecture, you should specify @code{-maltivec}.
+
+The preferred loop form for vectorization is the @code{for} iteration scheme.
+Loops with a @code{while} iteration scheme can also be vectorized if they are
+very simple, but the vectorizer will quickly give up otherwise. With either
+iteration scheme, the flow of control must be straight, in particular no
+@code{exit} statement may appear in the loop body. The loop may however
+contain a single nested loop, if it can be vectorized when considered alone:
+
+@quotation
+
+@example
+A : array (1..4, 1..4) of Long_Float;
+S : array (1..4) of Long_Float;
+
+procedure Sum is
+begin
+ for I in A'Range(1) loop
+ for J in A'Range(2) loop
+ S (I) := S (I) + A (I, J);
+ end loop;
+ end loop;
+end Sum;
+@end example
+@end quotation
+
+The vectorizable operations depend on the targeted SIMD instruction set, but
+the adding and some of the multiplying operators are generally supported, as
+well as the logical operators for modular types. Note that compiling
+with @code{-gnatp} might well reveal cases where some checks do thwart
+vectorization.
+
+Type conversions may also prevent vectorization if they involve semantics that
+are not directly supported by the code generator or the SIMD instruction set.
+A typical example is direct conversion from floating-point to integer types.
+The solution in this case is to use the following idiom:
+
+@quotation
+
+@example
+Integer (S'Truncation (F))
+@end example
+@end quotation
+
+if @code{S} is the subtype of floating-point object @code{F}.
+
+In most cases, the vectorizable loops are loops that iterate over arrays.
+All kinds of array types are supported, i.e. constrained array types with
+static bounds:
+
+@quotation
+
+@example
+type Array_Type is array (1 .. 4) of Long_Float;
+@end example
+@end quotation
+
+constrained array types with dynamic bounds:
+
+@quotation
+
+@example
+type Array_Type is array (1 .. Q.N) of Long_Float;
+
+type Array_Type is array (Q.K .. 4) of Long_Float;
+
+type Array_Type is array (Q.K .. Q.N) of Long_Float;
+@end example
+@end quotation
+
+or unconstrained array types:
+
+@quotation
+
+@example
+type Array_Type is array (Positive range <>) of Long_Float;
+@end example
+@end quotation
+
+The quality of the generated code decreases when the dynamic aspect of the
+array type increases, the worst code being generated for unconstrained array
+types. This is so because, the less information the compiler has about the
+bounds of the array, the more fallback code it needs to generate in order to
+fix things up at run time.
+
+It is possible to specify that a given loop should be subject to vectorization
+preferably to other optimizations by means of pragma @code{Loop_Optimize}:
+
+@quotation
+
+@example
+pragma Loop_Optimize (Vector);
+@end example
+@end quotation
+
+placed immediately within the loop will convey the appropriate hint to the
+compiler for this loop.
+
+It is also possible to help the compiler generate better vectorized code
+for a given loop by asserting that there are no loop-carried dependencies
+in the loop. Consider for example the procedure:
+
+@quotation
+
+@example
+type Arr is array (1 .. 4) of Long_Float;
+
+procedure Add (X, Y : not null access Arr; R : not null access Arr) is
+begin
+ for I in Arr'Range loop
+ R(I) := X(I) + Y(I);
+ end loop;
+end;
+@end example
+@end quotation
+
+By default, the compiler cannot unconditionally vectorize the loop because
+assigning to a component of the array designated by R in one iteration could
+change the value read from the components of the array designated by X or Y
+in a later iteration. As a result, the compiler will generate two versions
+of the loop in the object code, one vectorized and the other not vectorized,
+as well as a test to select the appropriate version at run time. This can
+be overcome by another hint:
+
+@quotation
+
+@example
+pragma Loop_Optimize (Ivdep);
+@end example
+@end quotation
+
+placed immediately within the loop will tell the compiler that it can safely
+omit the non-vectorized version of the loop as well as the run-time test.
+
+@node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{18a}@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{18b}
+@subsubsection Other Optimization Switches
+
+
+@geindex Optimization Switches
+
+Since GNAT uses the @code{gcc} back end, all the specialized
+@code{gcc} optimization switches are potentially usable. These switches
+have not been extensively tested with GNAT but can generally be expected
+to work. Examples of switches in this category are @code{-funroll-loops}
+and the various target-specific @code{-m} options (in particular, it has
+been observed that @code{-march=xxx} can significantly improve performance
+on appropriate machines). For full details of these switches, see
+the `Submodel Options' section in the `Hardware Models and Configurations'
+chapter of @cite{Using the GNU Compiler Collection (GCC)}.
+
+@node Optimization and Strict Aliasing,Aliased Variables and Optimization,Other Optimization Switches,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{18c}@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{e4}
+@subsubsection Optimization and Strict Aliasing
+
+
+@geindex Aliasing
+
+@geindex Strict Aliasing
+
+@geindex No_Strict_Aliasing
+
+The strong typing capabilities of Ada allow an optimizer to generate
+efficient code in situations where other languages would be forced to
+make worst case assumptions preventing such optimizations. Consider
+the following example:
+
+@quotation
+
+@example
+procedure R is
+ type Int1 is new Integer;
+ type Int2 is new Integer;
+ type Int1A is access Int1;
+ type Int2A is access Int2;
+ Int1V : Int1A;
+ Int2V : Int2A;
+ ...
+
+begin
+ ...
+ for J in Data'Range loop
+ if Data (J) = Int1V.all then
+ Int2V.all := Int2V.all + 1;
+ end if;
+ end loop;
+ ...
+end R;
+@end example
+@end quotation
+
+In this example, since the variable @code{Int1V} can only access objects
+of type @code{Int1}, and @code{Int2V} can only access objects of type
+@code{Int2}, there is no possibility that the assignment to
+@code{Int2V.all} affects the value of @code{Int1V.all}. This means that
+the compiler optimizer can “know” that the value @code{Int1V.all} is constant
+for all iterations of the loop and avoid the extra memory reference
+required to dereference it each time through the loop.
+
+This kind of optimization, called strict aliasing analysis, is
+triggered by specifying an optimization level of @code{-O2} or
+higher or @code{-Os} and allows GNAT to generate more efficient code
+when access values are involved.
+
+However, although this optimization is always correct in terms of
+the formal semantics of the Ada Reference Manual, difficulties can
+arise if features like @code{Unchecked_Conversion} are used to break
+the typing system. Consider the following complete program example:
+
+@quotation
+
+@example
+package p1 is
+ type int1 is new integer;
+ type int2 is new integer;
+ type a1 is access int1;
+ type a2 is access int2;
+end p1;
+
+with p1; use p1;
+package p2 is
+ function to_a2 (Input : a1) return a2;
+end p2;
+
+with Ada.Unchecked_Conversion;
+package body p2 is
+ function to_a2 (Input : a1) return a2 is
+ function to_a2u is
+ new Ada.Unchecked_Conversion (a1, a2);
+ begin
+ return to_a2u (Input);
+ end to_a2;
+end p2;
+
+with p2; use p2;
+with p1; use p1;
+with Text_IO; use Text_IO;
+procedure m is
+ v1 : a1 := new int1;
+ v2 : a2 := to_a2 (v1);
+begin
+ v1.all := 1;
+ v2.all := 0;
+ put_line (int1'image (v1.all));
+end;
+@end example
+@end quotation
+
+This program prints out 0 in @code{-O0} or @code{-O1}
+mode, but it prints out 1 in @code{-O2} mode. That’s
+because in strict aliasing mode, the compiler can and
+does assume that the assignment to @code{v2.all} could not
+affect the value of @code{v1.all}, since different types
+are involved.
+
+This behavior is not a case of non-conformance with the standard, since
+the Ada RM specifies that an unchecked conversion where the resulting
+bit pattern is not a correct value of the target type can result in an
+abnormal value and attempting to reference an abnormal value makes the
+execution of a program erroneous. That’s the case here since the result
+does not point to an object of type @code{int2}. This means that the
+effect is entirely unpredictable.
+
+However, although that explanation may satisfy a language
+lawyer, in practice an applications programmer expects an
+unchecked conversion involving pointers to create true
+aliases and the behavior of printing 1 seems plain wrong.
+In this case, the strict aliasing optimization is unwelcome.
+
+Indeed the compiler recognizes this possibility, and the
+unchecked conversion generates a warning:
+
+@quotation
+
+@example
+p2.adb:5:07: warning: possible aliasing problem with type "a2"
+p2.adb:5:07: warning: use -fno-strict-aliasing switch for references
+p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);"
+@end example
+@end quotation
+
+Unfortunately the problem is recognized when compiling the body of
+package @code{p2}, but the actual “bad” code is generated while
+compiling the body of @code{m} and this latter compilation does not see
+the suspicious @code{Unchecked_Conversion}.
+
+As implied by the warning message, there are approaches you can use to
+avoid the unwanted strict aliasing optimization in a case like this.
+
+One possibility is to simply avoid the use of @code{-O2}, but
+that is a bit drastic, since it throws away a number of useful
+optimizations that do not involve strict aliasing assumptions.
+
+A less drastic approach is to compile the program using the
+option @code{-fno-strict-aliasing}. Actually it is only the
+unit containing the dereferencing of the suspicious pointer
+that needs to be compiled. So in this case, if we compile
+unit @code{m} with this switch, then we get the expected
+value of zero printed. Analyzing which units might need
+the switch can be painful, so a more reasonable approach
+is to compile the entire program with options @code{-O2}
+and @code{-fno-strict-aliasing}. If the performance is
+satisfactory with this combination of options, then the
+advantage is that the entire issue of possible “wrong”
+optimization due to strict aliasing is avoided.
+
+To avoid the use of compiler switches, the configuration
+pragma @code{No_Strict_Aliasing} with no parameters may be
+used to specify that for all access types, the strict
+aliasing optimization should be suppressed.
+
+However, these approaches are still overkill, in that they causes
+all manipulations of all access values to be deoptimized. A more
+refined approach is to concentrate attention on the specific
+access type identified as problematic.
+
+First, if a careful analysis of uses of the pointer shows
+that there are no possible problematic references, then
+the warning can be suppressed by bracketing the
+instantiation of @code{Unchecked_Conversion} to turn
+the warning off:
+
+@quotation
+
+@example
+pragma Warnings (Off);
+function to_a2u is
+ new Ada.Unchecked_Conversion (a1, a2);
+pragma Warnings (On);
+@end example
+@end quotation
+
+Of course that approach is not appropriate for this particular
+example, since indeed there is a problematic reference. In this
+case we can take one of two other approaches.
+
+The first possibility is to move the instantiation of unchecked
+conversion to the unit in which the type is declared. In
+this example, we would move the instantiation of
+@code{Unchecked_Conversion} from the body of package
+@code{p2} to the spec of package @code{p1}. Now the
+warning disappears. That’s because any use of the
+access type knows there is a suspicious unchecked
+conversion, and the strict aliasing optimization
+is automatically suppressed for the type.
+
+If it is not practical to move the unchecked conversion to the same unit
+in which the destination access type is declared (perhaps because the
+source type is not visible in that unit), you may use pragma
+@code{No_Strict_Aliasing} for the type. This pragma must occur in the
+same declarative sequence as the declaration of the access type:
+
+@quotation
+
+@example
+type a2 is access int2;
+pragma No_Strict_Aliasing (a2);
+@end example
+@end quotation
+
+Here again, the compiler now knows that the strict aliasing optimization
+should be suppressed for any reference to type @code{a2} and the
+expected behavior is obtained.
+
+Finally, note that although the compiler can generate warnings for
+simple cases of unchecked conversions, there are tricker and more
+indirect ways of creating type incorrect aliases which the compiler
+cannot detect. Examples are the use of address overlays and unchecked
+conversions involving composite types containing access types as
+components. In such cases, no warnings are generated, but there can
+still be aliasing problems. One safe coding practice is to forbid the
+use of address clauses for type overlaying, and to allow unchecked
+conversion only for primitive types. This is not really a significant
+restriction since any possible desired effect can be achieved by
+unchecked conversion of access values.
+
+The aliasing analysis done in strict aliasing mode can certainly
+have significant benefits. We have seen cases of large scale
+application code where the time is increased by up to 5% by turning
+this optimization off. If you have code that includes significant
+usage of unchecked conversion, you might want to just stick with
+@code{-O1} and avoid the entire issue. If you get adequate
+performance at this level of optimization level, that’s probably
+the safest approach. If tests show that you really need higher
+levels of optimization, then you can experiment with @code{-O2}
+and @code{-O2 -fno-strict-aliasing} to see how much effect this
+has on size and speed of the code. If you really need to use
+@code{-O2} with strict aliasing in effect, then you should
+review any uses of unchecked conversion of access types,
+particularly if you are getting the warnings described above.
+
+@node Aliased Variables and Optimization,Atomic Variables and Optimization,Optimization and Strict Aliasing,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{18d}@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{18e}
+@subsubsection Aliased Variables and Optimization
+
+
+@geindex Aliasing
+
+There are scenarios in which programs may
+use low level techniques to modify variables
+that otherwise might be considered to be unassigned. For example,
+a variable can be passed to a procedure by reference, which takes
+the address of the parameter and uses the address to modify the
+variable’s value, even though it is passed as an IN parameter.
+Consider the following example:
+
+@quotation
+
+@example
+procedure P is
+ Max_Length : constant Natural := 16;
+ type Char_Ptr is access all Character;
+
+ procedure Get_String(Buffer: Char_Ptr; Size : Integer);
+ pragma Import (C, Get_String, "get_string");
+
+ Name : aliased String (1 .. Max_Length) := (others => ' ');
+ Temp : Char_Ptr;
+
+ function Addr (S : String) return Char_Ptr is
+ function To_Char_Ptr is
+ new Ada.Unchecked_Conversion (System.Address, Char_Ptr);
+ begin
+ return To_Char_Ptr (S (S'First)'Address);
+ end;
+
+begin
+ Temp := Addr (Name);
+ Get_String (Temp, Max_Length);
+end;
+@end example
+@end quotation
+
+where Get_String is a C function that uses the address in Temp to
+modify the variable @code{Name}. This code is dubious, and arguably
+erroneous, and the compiler would be entitled to assume that
+@code{Name} is never modified, and generate code accordingly.
+
+However, in practice, this would cause some existing code that
+seems to work with no optimization to start failing at high
+levels of optimization.
+
+What the compiler does for such cases is to assume that marking
+a variable as aliased indicates that some “funny business” may
+be going on. The optimizer recognizes the aliased keyword and
+inhibits optimizations that assume the value cannot be assigned.
+This means that the above example will in fact “work” reliably,
+that is, it will produce the expected results.
+
+@node Atomic Variables and Optimization,Passive Task Optimization,Aliased Variables and Optimization,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{18f}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{190}
+@subsubsection Atomic Variables and Optimization
+
+
+@geindex Atomic
+
+There are two considerations with regard to performance when
+atomic variables are used.
+
+First, the RM only guarantees that access to atomic variables
+be atomic, it has nothing to say about how this is achieved,
+though there is a strong implication that this should not be
+achieved by explicit locking code. Indeed GNAT will never
+generate any locking code for atomic variable access (it will
+simply reject any attempt to make a variable or type atomic
+if the atomic access cannot be achieved without such locking code).
+
+That being said, it is important to understand that you cannot
+assume that the entire variable will always be accessed. Consider
+this example:
+
+@quotation
+
+@example
+type R is record
+ A,B,C,D : Character;
+end record;
+for R'Size use 32;
+for R'Alignment use 4;
+
+RV : R;
+pragma Atomic (RV);
+X : Character;
+...
+X := RV.B;
+@end example
+@end quotation
+
+You cannot assume that the reference to @code{RV.B}
+will read the entire 32-bit
+variable with a single load instruction. It is perfectly legitimate if
+the hardware allows it to do a byte read of just the B field. This read
+is still atomic, which is all the RM requires. GNAT can and does take
+advantage of this, depending on the architecture and optimization level.
+Any assumption to the contrary is non-portable and risky. Even if you
+examine the assembly language and see a full 32-bit load, this might
+change in a future version of the compiler.
+
+If your application requires that all accesses to @code{RV} in this
+example be full 32-bit loads, you need to make a copy for the access
+as in:
+
+@quotation
+
+@example
+declare
+ RV_Copy : constant R := RV;
+begin
+ X := RV_Copy.B;
+end;
+@end example
+@end quotation
+
+Now the reference to RV must read the whole variable.
+Actually one can imagine some compiler which figures
+out that the whole copy is not required (because only
+the B field is actually accessed), but GNAT
+certainly won’t do that, and we don’t know of any
+compiler that would not handle this right, and the
+above code will in practice work portably across
+all architectures (that permit the Atomic declaration).
+
+The second issue with atomic variables has to do with
+the possible requirement of generating synchronization
+code. For more details on this, consult the sections on
+the pragmas Enable/Disable_Atomic_Synchronization in the
+GNAT Reference Manual. If performance is critical, and
+such synchronization code is not required, it may be
+useful to disable it.
+
+@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{191}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{192}
+@subsubsection Passive Task Optimization
+
+
+@geindex Passive Task
+
+A passive task is one which is sufficiently simple that
+in theory a compiler could recognize it an implement it
+efficiently without creating a new thread. The original design
+of Ada 83 had in mind this kind of passive task optimization, but
+only a few Ada 83 compilers attempted it. The problem was that
+it was difficult to determine the exact conditions under which
+the optimization was possible. The result is a very fragile
+optimization where a very minor change in the program can
+suddenly silently make a task non-optimizable.
+
+With the revisiting of this issue in Ada 95, there was general
+agreement that this approach was fundamentally flawed, and the
+notion of protected types was introduced. When using protected
+types, the restrictions are well defined, and you KNOW that the
+operations will be optimized, and furthermore this optimized
+performance is fully portable.
+
+Although it would theoretically be possible for GNAT to attempt to
+do this optimization, but it really doesn’t make sense in the
+context of Ada 95, and none of the Ada 95 compilers implement
+this optimization as far as we know. In particular GNAT never
+attempts to perform this optimization.
+
+In any new Ada 95 code that is written, you should always
+use protected types in place of tasks that might be able to
+be optimized in this manner.
+Of course this does not help if you have legacy Ada 83 code
+that depends on this optimization, but it is unusual to encounter
+a case where the performance gains from this optimization
+are significant.
+
+Your program should work correctly without this optimization. If
+you have performance problems, then the most practical
+approach is to figure out exactly where these performance problems
+arise, and update those particular tasks to be protected types. Note
+that typically clients of the tasks who call entries, will not have
+to be modified, only the task definition itself.
+
+@node Text_IO Suggestions,Reducing Size of Executables with Unused Subprogram/Data Elimination,Performance Considerations,Improving Performance
+@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{193}@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{194}
+@subsection @code{Text_IO} Suggestions
+
+
+@geindex Text_IO and performance
+
+The @code{Ada.Text_IO} package has fairly high overheads due in part to
+the requirement of maintaining page and line counts. If performance
+is critical, a recommendation is to use @code{Stream_IO} instead of
+@code{Text_IO} for volume output, since this package has less overhead.
+
+If @code{Text_IO} must be used, note that by default output to the standard
+output and standard error files is unbuffered (this provides better
+behavior when output statements are used for debugging, or if the
+progress of a program is observed by tracking the output, e.g. by
+using the Unix `tail -f' command to watch redirected output).
+
+If you are generating large volumes of output with @code{Text_IO} and
+performance is an important factor, use a designated file instead
+of the standard output file, or change the standard output file to
+be buffered using @code{Interfaces.C_Streams.setvbuf}.
+
+@node Reducing Size of Executables with Unused Subprogram/Data Elimination,,Text_IO Suggestions,Improving Performance
+@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{195}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{196}
+@subsection Reducing Size of Executables with Unused Subprogram/Data Elimination
+
+
+@geindex Uunused subprogram/data elimination
+
+This section describes how you can eliminate unused subprograms and data from
+your executable just by setting options at compilation time.
+
+@menu
+* About unused subprogram/data elimination::
+* Compilation options::
+* Example of unused subprogram/data elimination::
+
+@end menu
+
+@node About unused subprogram/data elimination,Compilation options,,Reducing Size of Executables with Unused Subprogram/Data Elimination
+@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{197}@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{198}
+@subsubsection About unused subprogram/data elimination
+
+
+By default, an executable contains all code and data of its composing objects
+(directly linked or coming from statically linked libraries), even data or code
+never used by this executable.
+
+This feature will allow you to eliminate such unused code from your
+executable, making it smaller (in disk and in memory).
+
+This functionality is available on all Linux platforms except for the IA-64
+architecture and on all cross platforms using the ELF binary file format.
+In both cases GNU binutils version 2.16 or later are required to enable it.
+
+@node Compilation options,Example of unused subprogram/data elimination,About unused subprogram/data elimination,Reducing Size of Executables with Unused Subprogram/Data Elimination
+@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{19a}
+@subsubsection Compilation options
+
+
+The operation of eliminating the unused code and data from the final executable
+is directly performed by the linker.
+
+@geindex -ffunction-sections (gcc)
+
+@geindex -fdata-sections (gcc)
+
+In order to do this, it has to work with objects compiled with the
+following options:
+@code{-ffunction-sections} @code{-fdata-sections}.
+
+These options are usable with C and Ada files.
+They will place respectively each
+function or data in a separate section in the resulting object file.
+
+Once the objects and static libraries are created with these options, the
+linker can perform the dead code elimination. You can do this by setting
+the @code{-Wl,--gc-sections} option to gcc command or in the
+@code{-largs} section of @code{gnatmake}. This will perform a
+garbage collection of code and data never referenced.
+
+If the linker performs a partial link (@code{-r} linker option), then you
+will need to provide the entry point using the @code{-e} / @code{--entry}
+linker option.
+
+Note that objects compiled without the @code{-ffunction-sections} and
+@code{-fdata-sections} options can still be linked with the executable.
+However, no dead code elimination will be performed on those objects (they will
+be linked as is).
+
+The GNAT static library is now compiled with -ffunction-sections and
+-fdata-sections on some platforms. This allows you to eliminate the unused code
+and data of the GNAT library from your executable.
+
+@node Example of unused subprogram/data elimination,,Compilation options,Reducing Size of Executables with Unused Subprogram/Data Elimination
+@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{19b}@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{19c}
+@subsubsection Example of unused subprogram/data elimination
+
+
+Here is a simple example:
+
+@quotation
+
+@example
+with Aux;
+
+procedure Test is
+begin
+ Aux.Used (10);
+end Test;
+
+package Aux is
+ Used_Data : Integer;
+ Unused_Data : Integer;
+
+ procedure Used (Data : Integer);
+ procedure Unused (Data : Integer);
+end Aux;
+
+package body Aux is
+ procedure Used (Data : Integer) is
+ begin
+ Used_Data := Data;
+ end Used;
+
+ procedure Unused (Data : Integer) is
+ begin
+ Unused_Data := Data;
+ end Unused;
+end Aux;
+@end example
+@end quotation
+
+@code{Unused} and @code{Unused_Data} are never referenced in this code
+excerpt, and hence they may be safely removed from the final executable.
+
+@quotation
+
+@example
+$ gnatmake test
+
+$ nm test | grep used
+020015f0 T aux__unused
+02005d88 B aux__unused_data
+020015cc T aux__used
+02005d84 B aux__used_data
+
+$ gnatmake test -cargs -fdata-sections -ffunction-sections \\
+ -largs -Wl,--gc-sections
+
+$ nm test | grep used
+02005350 T aux__used
+0201ffe0 B aux__used_data
+@end example
+@end quotation
+
+It can be observed that the procedure @code{Unused} and the object
+@code{Unused_Data} are removed by the linker when using the
+appropriate options.
+
+@geindex Overflow checks
+
+@geindex Checks (overflow)
+
+@node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{149}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{19d}
+@section Overflow Check Handling in GNAT
+
+
+This section explains how to control the handling of overflow checks.
+
+@menu
+* Background::
+* Management of Overflows in GNAT::
+* Specifying the Desired Mode::
+* Default Settings::
+* Implementation Notes::
+
+@end menu
+
+@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{19f}
+@subsection Background
+
+
+Overflow checks are checks that the compiler may make to ensure
+that intermediate results are not out of range. For example:
+
+@quotation
+
+@example
+A : Integer;
+...
+A := A + 1;
+@end example
+@end quotation
+
+If @code{A} has the value @code{Integer'Last}, then the addition may cause
+overflow since the result is out of range of the type @code{Integer}.
+In this case @code{Constraint_Error} will be raised if checks are
+enabled.
+
+A trickier situation arises in examples like the following:
+
+@quotation
+
+@example
+A, C : Integer;
+...
+A := (A + 1) + C;
+@end example
+@end quotation
+
+where @code{A} is @code{Integer'Last} and @code{C} is @code{-1}.
+Now the final result of the expression on the right hand side is
+@code{Integer'Last} which is in range, but the question arises whether the
+intermediate addition of @code{(A + 1)} raises an overflow error.
+
+The (perhaps surprising) answer is that the Ada language
+definition does not answer this question. Instead it leaves
+it up to the implementation to do one of two things if overflow
+checks are enabled.
+
+
+@itemize *
+
+@item
+raise an exception (@code{Constraint_Error}), or
+
+@item
+yield the correct mathematical result which is then used in
+subsequent operations.
+@end itemize
+
+If the compiler chooses the first approach, then the assignment of this
+example will indeed raise @code{Constraint_Error} if overflow checking is
+enabled, or result in erroneous execution if overflow checks are suppressed.
+
+But if the compiler
+chooses the second approach, then it can perform both additions yielding
+the correct mathematical result, which is in range, so no exception
+will be raised, and the right result is obtained, regardless of whether
+overflow checks are suppressed.
+
+Note that in the first example an
+exception will be raised in either case, since if the compiler
+gives the correct mathematical result for the addition, it will
+be out of range of the target type of the assignment, and thus
+fails the range check.
+
+This lack of specified behavior in the handling of overflow for
+intermediate results is a source of non-portability, and can thus
+be problematic when programs are ported. Most typically this arises
+in a situation where the original compiler did not raise an exception,
+and then the application is moved to a compiler where the check is
+performed on the intermediate result and an unexpected exception is
+raised.
+
+Furthermore, when using Ada 2012’s preconditions and other
+assertion forms, another issue arises. Consider:
+
+@quotation
+
+@example
+procedure P (A, B : Integer) with
+ Pre => A + B <= Integer'Last;
+@end example
+@end quotation
+
+One often wants to regard arithmetic in a context like this from
+a mathematical point of view. So for example, if the two actual parameters
+for a call to @code{P} are both @code{Integer'Last}, then
+the precondition should be regarded as False. If we are executing
+in a mode with run-time checks enabled for preconditions, then we would
+like this precondition to fail, rather than raising an exception
+because of the intermediate overflow.
+
+However, the language definition leaves the specification of
+whether the above condition fails (raising @code{Assert_Error}) or
+causes an intermediate overflow (raising @code{Constraint_Error})
+up to the implementation.
+
+The situation is worse in a case such as the following:
+
+@quotation
+
+@example
+procedure Q (A, B, C : Integer) with
+ Pre => A + B + C <= Integer'Last;
+@end example
+@end quotation
+
+Consider the call
+
+@quotation
+
+@example
+Q (A => Integer'Last, B => 1, C => -1);
+@end example
+@end quotation
+
+From a mathematical point of view the precondition
+is True, but at run time we may (but are not guaranteed to) get an
+exception raised because of the intermediate overflow (and we really
+would prefer this precondition to be considered True at run time).
+
+@node Management of Overflows in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution id47}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1a1}
+@subsection Management of Overflows in GNAT
+
+
+To deal with the portability issue, and with the problem of
+mathematical versus run-time interpretation of the expressions in
+assertions, GNAT provides comprehensive control over the handling
+of intermediate overflow. GNAT can operate in three modes, and
+furthermore, permits separate selection of operating modes for
+the expressions within assertions (here the term ‘assertions’
+is used in the technical sense, which includes preconditions and so forth)
+and for expressions appearing outside assertions.
+
+The three modes are:
+
+
+@itemize *
+
+@item
+`Use base type for intermediate operations' (@code{STRICT})
+
+In this mode, all intermediate results for predefined arithmetic
+operators are computed using the base type, and the result must
+be in range of the base type. If this is not the
+case then either an exception is raised (if overflow checks are
+enabled) or the execution is erroneous (if overflow checks are suppressed).
+This is the normal default mode.
+
+@item
+`Most intermediate overflows avoided' (@code{MINIMIZED})
+
+In this mode, the compiler attempts to avoid intermediate overflows by
+using a larger integer type, typically @code{Long_Long_Integer},
+as the type in which arithmetic is
+performed for predefined arithmetic operators. This may be slightly more
+expensive at
+run time (compared to suppressing intermediate overflow checks), though
+the cost is negligible on modern 64-bit machines. For the examples given
+earlier, no intermediate overflows would have resulted in exceptions,
+since the intermediate results are all in the range of
+@code{Long_Long_Integer} (typically 64-bits on nearly all implementations
+of GNAT). In addition, if checks are enabled, this reduces the number of
+checks that must be made, so this choice may actually result in an
+improvement in space and time behavior.
+
+However, there are cases where @code{Long_Long_Integer} is not large
+enough, consider the following example:
+
+@quotation
+
+@example
+procedure R (A, B, C, D : Integer) with
+ Pre => (A**2 * B**2) / (C**2 * D**2) <= 10;
+@end example
+@end quotation
+
+where @code{A} = @code{B} = @code{C} = @code{D} = @code{Integer'Last}.
+Now the intermediate results are
+out of the range of @code{Long_Long_Integer} even though the final result
+is in range and the precondition is True (from a mathematical point
+of view). In such a case, operating in this mode, an overflow occurs
+for the intermediate computation (which is why this mode
+says `most' intermediate overflows are avoided). In this case,
+an exception is raised if overflow checks are enabled, and the
+execution is erroneous if overflow checks are suppressed.
+
+@item
+`All intermediate overflows avoided' (@code{ELIMINATED})
+
+In this mode, the compiler avoids all intermediate overflows
+by using arbitrary precision arithmetic as required. In this
+mode, the above example with @code{A**2 * B**2} would
+not cause intermediate overflow, because the intermediate result
+would be evaluated using sufficient precision, and the result
+of evaluating the precondition would be True.
+
+This mode has the advantage of avoiding any intermediate
+overflows, but at the expense of significant run-time overhead,
+including the use of a library (included automatically in this
+mode) for multiple-precision arithmetic.
+
+This mode provides cleaner semantics for assertions, since now
+the run-time behavior emulates true arithmetic behavior for the
+predefined arithmetic operators, meaning that there is never a
+conflict between the mathematical view of the assertion, and its
+run-time behavior.
+
+Note that in this mode, the behavior is unaffected by whether or
+not overflow checks are suppressed, since overflow does not occur.
+It is possible for gigantic intermediate expressions to raise
+@code{Storage_Error} as a result of attempting to compute the
+results of such expressions (e.g. @code{Integer'Last ** Integer'Last})
+but overflow is impossible.
+@end itemize
+
+Note that these modes apply only to the evaluation of predefined
+arithmetic, membership, and comparison operators for signed integer
+arithmetic.
+
+For fixed-point arithmetic, checks can be suppressed. But if checks
+are enabled
+then fixed-point values are always checked for overflow against the
+base type for intermediate expressions (that is such checks always
+operate in the equivalent of @code{STRICT} mode).
+
+For floating-point, on nearly all architectures, @code{Machine_Overflows}
+is False, and IEEE infinities are generated, so overflow exceptions
+are never raised. If you want to avoid infinities, and check that
+final results of expressions are in range, then you can declare a
+constrained floating-point type, and range checks will be carried
+out in the normal manner (with infinite values always failing all
+range checks).
+
+@node Specifying the Desired Mode,Default Settings,Management of Overflows in GNAT,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution id48}@anchor{1a2}@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{e9}
+@subsection Specifying the Desired Mode
+
+
+@geindex pragma Overflow_Mode
+
+The desired mode of for handling intermediate overflow can be specified using
+either the @code{Overflow_Mode} pragma or an equivalent compiler switch.
+The pragma has the form
+
+@quotation
+
+@example
+pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]);
+@end example
+@end quotation
+
+where @code{MODE} is one of
+
+
+@itemize *
+
+@item
+@code{STRICT}: intermediate overflows checked (using base type)
+
+@item
+@code{MINIMIZED}: minimize intermediate overflows
+
+@item
+@code{ELIMINATED}: eliminate intermediate overflows
+@end itemize
+
+The case is ignored, so @code{MINIMIZED}, @code{Minimized} and
+@code{minimized} all have the same effect.
+
+If only the @code{General} parameter is present, then the given @code{MODE} applies
+to expressions both within and outside assertions. If both arguments
+are present, then @code{General} applies to expressions outside assertions,
+and @code{Assertions} applies to expressions within assertions. For example:
+
+@quotation
+
+@example
+pragma Overflow_Mode
+ (General => Minimized, Assertions => Eliminated);
+@end example
+@end quotation
+
+specifies that general expressions outside assertions be evaluated
+in ‘minimize intermediate overflows’ mode, and expressions within
+assertions be evaluated in ‘eliminate intermediate overflows’ mode.
+This is often a reasonable choice, avoiding excessive overhead
+outside assertions, but assuring a high degree of portability
+when importing code from another compiler, while incurring
+the extra overhead for assertion expressions to ensure that
+the behavior at run time matches the expected mathematical
+behavior.
+
+The @code{Overflow_Mode} pragma has the same scoping and placement
+rules as pragma @code{Suppress}, so it can occur either as a
+configuration pragma, specifying a default for the whole
+program, or in a declarative scope, where it applies to the
+remaining declarations and statements in that scope.
+
+Note that pragma @code{Overflow_Mode} does not affect whether
+overflow checks are enabled or suppressed. It only controls the
+method used to compute intermediate values. To control whether
+overflow checking is enabled or suppressed, use pragma @code{Suppress}
+or @code{Unsuppress} in the usual manner.
+
+@geindex -gnato? (gcc)
+
+@geindex -gnato?? (gcc)
+
+Additionally, a compiler switch @code{-gnato?} or @code{-gnato??}
+can be used to control the checking mode default (which can be subsequently
+overridden using pragmas).
+
+Here @code{?} is one of the digits @code{1} through @code{3}:
+
+@quotation
+
+
+@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+@code{1}
+
+@tab
+
+use base type for intermediate operations (@code{STRICT})
+
+@item
+
+@code{2}
+
+@tab
+
+minimize intermediate overflows (@code{MINIMIZED})
+
+@item
+
+@code{3}
+
+@tab
+
+eliminate intermediate overflows (@code{ELIMINATED})
+
+@end multitable
+
+@end quotation
+
+As with the pragma, if only one digit appears then it applies to all
+cases; if two digits are given, then the first applies outside
+assertions, and the second within assertions. Thus the equivalent
+of the example pragma above would be
+@code{-gnato23}.
+
+If no digits follow the @code{-gnato}, then it is equivalent to
+@code{-gnato11},
+causing all intermediate operations to be computed using the base
+type (@code{STRICT} mode).
+
+@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1a4}
+@subsection Default Settings
+
+
+The default mode for overflow checks is
+
+@quotation
+
+@example
+General => Strict
+@end example
+@end quotation
+
+which causes all computations both inside and outside assertions to use
+the base type.
+
+This retains compatibility with previous versions of
+GNAT which suppressed overflow checks by default and always
+used the base type for computation of intermediate results.
+
+@c Sphinx allows no emphasis within :index: role. As a workaround we
+@c point the index to "switch" and use emphasis for "-gnato".
+
+The
+@geindex -gnato (gcc)
+switch @code{-gnato} (with no digits following)
+is equivalent to
+
+@quotation
+
+@example
+General => Strict
+@end example
+@end quotation
+
+which causes overflow checking of all intermediate overflows
+both inside and outside assertions against the base type.
+
+The pragma @code{Suppress (Overflow_Check)} disables overflow
+checking, but it has no effect on the method used for computing
+intermediate results.
+
+The pragma @code{Unsuppress (Overflow_Check)} enables overflow
+checking, but it has no effect on the method used for computing
+intermediate results.
+
+@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution id50}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1a6}
+@subsection Implementation Notes
+
+
+In practice on typical 64-bit machines, the @code{MINIMIZED} mode is
+reasonably efficient, and can be generally used. It also helps
+to ensure compatibility with code imported from some other
+compiler to GNAT.
+
+Setting all intermediate overflows checking (@code{CHECKED} mode)
+makes sense if you want to
+make sure that your code is compatible with any other possible
+Ada implementation. This may be useful in ensuring portability
+for code that is to be exported to some other compiler than GNAT.
+
+The Ada standard allows the reassociation of expressions at
+the same precedence level if no parentheses are present. For
+example, @code{A+B+C} parses as though it were @code{(A+B)+C}, but
+the compiler can reintepret this as @code{A+(B+C)}, possibly
+introducing or eliminating an overflow exception. The GNAT
+compiler never takes advantage of this freedom, and the
+expression @code{A+B+C} will be evaluated as @code{(A+B)+C}.
+If you need the other order, you can write the parentheses
+explicitly @code{A+(B+C)} and GNAT will respect this order.
+
+The use of @code{ELIMINATED} mode will cause the compiler to
+automatically include an appropriate arbitrary precision
+integer arithmetic package. The compiler will make calls
+to this package, though only in cases where it cannot be
+sure that @code{Long_Long_Integer} is sufficient to guard against
+intermediate overflows. This package does not use dynamic
+allocation, but it does use the secondary stack, so an
+appropriate secondary stack package must be present (this
+is always true for standard full Ada, but may require
+specific steps for restricted run times such as ZFP).
+
+Although @code{ELIMINATED} mode causes expressions to use arbitrary
+precision arithmetic, avoiding overflow, the final result
+must be in an appropriate range. This is true even if the
+final result is of type @code{[Long_[Long_]]Integer'Base}, which
+still has the same bounds as its associated constrained
+type at run-time.
+
+Currently, the @code{ELIMINATED} mode is only available on target
+platforms for which @code{Long_Long_Integer} is 64-bits (nearly all GNAT
+platforms).
+
+@node Performing Dimensionality Analysis in GNAT,Stack Related Facilities,Overflow Check Handling in GNAT,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id51}@anchor{14a}@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{1a7}
+@section Performing Dimensionality Analysis in GNAT
+
+
+@geindex Dimensionality analysis
+
+The GNAT compiler supports dimensionality checking. The user can
+specify physical units for objects, and the compiler will verify that uses
+of these objects are compatible with their dimensions, in a fashion that is
+familiar to engineering practice. The dimensions of algebraic expressions
+(including powers with static exponents) are computed from their constituents.
+
+@geindex Dimension_System aspect
+
+@geindex Dimension aspect
+
+This feature depends on Ada 2012 aspect specifications, and is available from
+version 7.0.1 of GNAT onwards.
+The GNAT-specific aspect @code{Dimension_System}
+allows you to define a system of units; the aspect @code{Dimension}
+then allows the user to declare dimensioned quantities within a given system.
+(These aspects are described in the `Implementation Defined Aspects'
+chapter of the `GNAT Reference Manual').
+
+The major advantage of this model is that it does not require the declaration of
+multiple operators for all possible combinations of types: it is only necessary
+to use the proper subtypes in object declarations.
+
+@geindex System.Dim.Mks package (GNAT library)
+
+@geindex MKS_Type type
+
+The simplest way to impose dimensionality checking on a computation is to make
+use of one of the instantiations of the package @code{System.Dim.Generic_Mks}, which
+are part of the GNAT library. This generic package defines a floating-point
+type @code{MKS_Type}, for which a sequence of dimension names are specified,
+together with their conventional abbreviations. The following should be read
+together with the full specification of the package, in file
+@code{s-digemk.ads}.
+
+@quotation
+
+@geindex s-digemk.ads file
+
+@example
+type Mks_Type is new Float_Type
+ with
+ Dimension_System => (
+ (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
+ (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
+ (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
+ (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
+ (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"),
+ (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
+ (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
+@end example
+@end quotation
+
+The package then defines a series of subtypes that correspond to these
+conventional units. For example:
+
+@quotation
+
+@example
+subtype Length is Mks_Type
+ with
+ Dimension => (Symbol => 'm', Meter => 1, others => 0);
+@end example
+@end quotation
+
+and similarly for @code{Mass}, @code{Time}, @code{Electric_Current},
+@code{Thermodynamic_Temperature}, @code{Amount_Of_Substance}, and
+@code{Luminous_Intensity} (the standard set of units of the SI system).
+
+The package also defines conventional names for values of each unit, for
+example:
+
+@quotation
+
+@example
+m : constant Length := 1.0;
+kg : constant Mass := 1.0;
+s : constant Time := 1.0;
+A : constant Electric_Current := 1.0;
+@end example
+@end quotation
+
+as well as useful multiples of these units:
+
+@quotation
+
+@example
+ cm : constant Length := 1.0E-02;
+ g : constant Mass := 1.0E-03;
+ min : constant Time := 60.0;
+ day : constant Time := 60.0 * 24.0 * min;
+...
+@end example
+@end quotation
+
+There are three instantiations of @code{System.Dim.Generic_Mks} defined in the
+GNAT library:
+
+
+@itemize *
+
+@item
+@code{System.Dim.Float_Mks} based on @code{Float} defined in @code{s-diflmk.ads}.
+
+@item
+@code{System.Dim.Long_Mks} based on @code{Long_Float} defined in @code{s-dilomk.ads}.
+
+@item
+@code{System.Dim.Mks} based on @code{Long_Long_Float} defined in @code{s-dimmks.ads}.
+@end itemize
+
+Using one of these packages, you can then define a derived unit by providing
+the aspect that specifies its dimensions within the MKS system, as well as the
+string to be used for output of a value of that unit:
+
+@quotation
+
+@example
+subtype Acceleration is Mks_Type
+ with Dimension => ("m/sec^2",
+ Meter => 1,
+ Second => -2,
+ others => 0);
+@end example
+@end quotation
+
+Here is a complete example of use:
+
+@quotation
+
+@example
+with System.Dim.MKS; use System.Dim.Mks;
+with System.Dim.Mks_IO; use System.Dim.Mks_IO;
+with Text_IO; use Text_IO;
+procedure Free_Fall is
+ subtype Acceleration is Mks_Type
+ with Dimension => ("m/sec^2", 1, 0, -2, others => 0);
+ G : constant acceleration := 9.81 * m / (s ** 2);
+ T : Time := 10.0*s;
+ Distance : Length;
+
+begin
+ Put ("Gravitational constant: ");
+ Put (G, Aft => 2, Exp => 0); Put_Line ("");
+ Distance := 0.5 * G * T ** 2;
+ Put ("distance travelled in 10 seconds of free fall ");
+ Put (Distance, Aft => 2, Exp => 0);
+ Put_Line ("");
+end Free_Fall;
+@end example
+@end quotation
+
+Execution of this program yields:
+
+@quotation
+
+@example
+Gravitational constant: 9.81 m/sec^2
+distance travelled in 10 seconds of free fall 490.50 m
+@end example
+@end quotation
+
+However, incorrect assignments such as:
+
+@quotation
+
+@example
+Distance := 5.0;
+Distance := 5.0 * kg;
+@end example
+@end quotation
+
+are rejected with the following diagnoses:
+
+@quotation
+
+@example
+Distance := 5.0;
+ >>> dimensions mismatch in assignment
+ >>> left-hand side has dimension [L]
+ >>> right-hand side is dimensionless
+
+Distance := 5.0 * kg:
+ >>> dimensions mismatch in assignment
+ >>> left-hand side has dimension [L]
+ >>> right-hand side has dimension [M]
+@end example
+@end quotation
+
+The dimensions of an expression are properly displayed, even if there is
+no explicit subtype for it. If we add to the program:
+
+@quotation
+
+@example
+Put ("Final velocity: ");
+Put (G * T, Aft =>2, Exp =>0);
+Put_Line ("");
+@end example
+@end quotation
+
+then the output includes:
+
+@quotation
+
+@example
+Final velocity: 98.10 m.s**(-1)
+@end example
+
+@geindex Dimensionable type
+
+@geindex Dimensioned subtype
+@end quotation
+
+The type @code{Mks_Type} is said to be a `dimensionable type' since it has a
+@code{Dimension_System} aspect, and the subtypes @code{Length}, @code{Mass}, etc.,
+are said to be `dimensioned subtypes' since each one has a @code{Dimension}
+aspect.
+
+@quotation
+
+@geindex Dimension Vector (for a dimensioned subtype)
+
+@geindex Dimension aspect
+
+@geindex Dimension_System aspect
+@end quotation
+
+The @code{Dimension} aspect of a dimensioned subtype @code{S} defines a mapping
+from the base type’s Unit_Names to integer (or, more generally, rational)
+values. This mapping is the `dimension vector' (also referred to as the
+`dimensionality') for that subtype, denoted by @code{DV(S)}, and thus for each
+object of that subtype. Intuitively, the value specified for each
+@code{Unit_Name} is the exponent associated with that unit; a zero value
+means that the unit is not used. For example:
+
+@quotation
+
+@example
+declare
+ Acc : Acceleration;
+ ...
+begin
+ ...
+end;
+@end example
+@end quotation
+
+Here @code{DV(Acc)} = @code{DV(Acceleration)} =
+@code{(Meter=>1, Kilogram=>0, Second=>-2, Ampere=>0, Kelvin=>0, Mole=>0, Candela=>0)}.
+Symbolically, we can express this as @code{Meter / Second**2}.
+
+The dimension vector of an arithmetic expression is synthesized from the
+dimension vectors of its components, with compile-time dimensionality checks
+that help prevent mismatches such as using an @code{Acceleration} where a
+@code{Length} is required.
+
+The dimension vector of the result of an arithmetic expression `expr', or
+@code{DV(@var{expr})}, is defined as follows, assuming conventional
+mathematical definitions for the vector operations that are used:
+
+
+@itemize *
+
+@item
+If `expr' is of the type `universal_real', or is not of a dimensioned subtype,
+then `expr' is dimensionless; @code{DV(@var{expr})} is the empty vector.
+
+@item
+@code{DV(@var{op expr})}, where `op' is a unary operator, is @code{DV(@var{expr})}
+
+@item
+@code{DV(@var{expr1 op expr2})} where `op' is “+” or “-” is @code{DV(@var{expr1})}
+provided that @code{DV(@var{expr1})} = @code{DV(@var{expr2})}.
+If this condition is not met then the construct is illegal.
+
+@item
+@code{DV(@var{expr1} * @var{expr2})} is @code{DV(@var{expr1})} + @code{DV(@var{expr2})},
+and @code{DV(@var{expr1} / @var{expr2})} = @code{DV(@var{expr1})} - @code{DV(@var{expr2})}.
+In this context if one of the `expr's is dimensionless then its empty
+dimension vector is treated as @code{(others => 0)}.
+
+@item
+@code{DV(@var{expr} ** @var{power})} is `power' * @code{DV(@var{expr})},
+provided that `power' is a static rational value. If this condition is not
+met then the construct is illegal.
+@end itemize
+
+Note that, by the above rules, it is illegal to use binary “+” or “-” to
+combine a dimensioned and dimensionless value. Thus an expression such as
+@code{acc-10.0} is illegal, where @code{acc} is an object of subtype
+@code{Acceleration}.
+
+The dimensionality checks for relationals use the same rules as
+for “+” and “-”, except when comparing to a literal; thus
+
+@quotation
+
+@example
+acc > len
+@end example
+@end quotation
+
+is equivalent to
+
+@quotation
+
+@example
+acc-len > 0.0
+@end example
+@end quotation
+
+and is thus illegal, but
+
+@quotation
+
+@example
+acc > 10.0
+@end example
+@end quotation
+
+is accepted with a warning. Analogously a conditional expression requires the
+same dimension vector for each branch (with no exception for literals).
+
+The dimension vector of a type conversion @code{T(@var{expr})} is defined
+as follows, based on the nature of @code{T}:
+
+
+@itemize *
+
+@item
+If @code{T} is a dimensioned subtype then @code{DV(T(@var{expr}))} is @code{DV(T)}
+provided that either `expr' is dimensionless or
+@code{DV(T)} = @code{DV(@var{expr})}. The conversion is illegal
+if `expr' is dimensioned and @code{DV(@var{expr})} /= @code{DV(T)}.
+Note that vector equality does not require that the corresponding
+Unit_Names be the same.
+
+As a consequence of the above rule, it is possible to convert between
+different dimension systems that follow the same international system
+of units, with the seven physical components given in the standard order
+(length, mass, time, etc.). Thus a length in meters can be converted to
+a length in inches (with a suitable conversion factor) but cannot be
+converted, for example, to a mass in pounds.
+
+@item
+If @code{T} is the base type for `expr' (and the dimensionless root type of
+the dimension system), then @code{DV(T(@var{expr}))} is @code{DV(expr)}.
+Thus, if `expr' is of a dimensioned subtype of @code{T}, the conversion may
+be regarded as a “view conversion” that preserves dimensionality.
+
+This rule makes it possible to write generic code that can be instantiated
+with compatible dimensioned subtypes. The generic unit will contain
+conversions that will consequently be present in instantiations, but
+conversions to the base type will preserve dimensionality and make it
+possible to write generic code that is correct with respect to
+dimensionality.
+
+@item
+Otherwise (i.e., @code{T} is neither a dimensioned subtype nor a dimensionable
+base type), @code{DV(T(@var{expr}))} is the empty vector. Thus a dimensioned
+value can be explicitly converted to a non-dimensioned subtype, which
+of course then escapes dimensionality analysis.
+@end itemize
+
+The dimension vector for a type qualification @code{T'(@var{expr})} is the same
+as for the type conversion @code{T(@var{expr})}.
+
+An assignment statement
+
+@quotation
+
+@example
+Source := Target;
+@end example
+@end quotation
+
+requires @code{DV(Source)} = @code{DV(Target)}, and analogously for parameter
+passing (the dimension vector for the actual parameter must be equal to the
+dimension vector for the formal parameter).
+
+@node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id52}@anchor{14b}@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{1a8}
+@section Stack Related Facilities
+
+
+This section describes some useful tools associated with stack
+checking and analysis. In
+particular, it deals with dynamic and static stack usage measurements.
+
+@menu
+* Stack Overflow Checking::
+* Static Stack Usage Analysis::
+* Dynamic Stack Usage Analysis::
+
+@end menu
+
+@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities
+@anchor{gnat_ugn/gnat_and_program_execution id53}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{e5}
+@subsection Stack Overflow Checking
+
+
+@geindex Stack Overflow Checking
+
+@geindex -fstack-check (gcc)
+
+For most operating systems, @code{gcc} does not perform stack overflow
+checking by default. This means that if the main environment task or
+some other task exceeds the available stack space, then unpredictable
+behavior will occur. Most native systems offer some level of protection by
+adding a guard page at the end of each task stack. This mechanism is usually
+not enough for dealing properly with stack overflow situations because
+a large local variable could “jump” above the guard page.
+Furthermore, when the
+guard page is hit, there may not be any space left on the stack for executing
+the exception propagation code. Enabling stack checking avoids
+such situations.
+
+To activate stack checking, compile all units with the @code{gcc} option
+@code{-fstack-check}. For example:
+
+@quotation
+
+@example
+$ gcc -c -fstack-check package1.adb
+@end example
+@end quotation
+
+Units compiled with this option will generate extra instructions to check
+that any use of the stack (for procedure calls or for declaring local
+variables in declare blocks) does not exceed the available stack space.
+If the space is exceeded, then a @code{Storage_Error} exception is raised.
+
+For declared tasks, the default stack size is defined by the GNAT runtime,
+whose size may be modified at bind time through the @code{-d} bind switch
+(@ref{110,,Switches for gnatbind}). Task specific stack sizes may be set using the
+@code{Storage_Size} pragma.
+
+For the environment task, the stack size is determined by the operating system.
+Consequently, to modify the size of the environment task please refer to your
+operating system documentation.
+
+@node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities
+@anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6}
+@subsection Static Stack Usage Analysis
+
+
+@geindex Static Stack Usage Analysis
+
+@geindex -fstack-usage
+
+A unit compiled with @code{-fstack-usage} will generate an extra file
+that specifies
+the maximum amount of stack used, on a per-function basis.
+The file has the same
+basename as the target object file with a @code{.su} extension.
+Each line of this file is made up of three fields:
+
+
+@itemize *
+
+@item
+The name of the function.
+
+@item
+A number of bytes.
+
+@item
+One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
+@end itemize
+
+The second field corresponds to the size of the known part of the function
+frame.
+
+The qualifier @code{static} means that the function frame size
+is purely static.
+It usually means that all local variables have a static size.
+In this case, the second field is a reliable measure of the function stack
+utilization.
+
+The qualifier @code{dynamic} means that the function frame size is not static.
+It happens mainly when some local variables have a dynamic size. When this
+qualifier appears alone, the second field is not a reliable measure
+of the function stack analysis. When it is qualified with @code{bounded}, it
+means that the second field is a reliable maximum of the function stack
+utilization.
+
+A unit compiled with @code{-Wstack-usage} will issue a warning for each
+subprogram whose stack usage might be larger than the specified amount of
+bytes. The wording is in keeping with the qualifier documented above.
+
+@node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities
+@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{113}@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1ab}
+@subsection Dynamic Stack Usage Analysis
+
+
+It is possible to measure the maximum amount of stack used by a task, by
+adding a switch to @code{gnatbind}, as:
+
+@quotation
+
+@example
+$ gnatbind -u0 file
+@end example
+@end quotation
+
+With this option, at each task termination, its stack usage is output on
+@code{stderr}.
+Note that this switch is not compatible with tools like
+Valgrind and DrMemory; they will report errors.
+
+It is not always convenient to output the stack usage when the program
+is still running. Hence, it is possible to delay this output until program
+termination. for a given number of tasks specified as the argument of the
+@code{-u} option. For instance:
+
+@quotation
+
+@example
+$ gnatbind -u100 file
+@end example
+@end quotation
+
+will buffer the stack usage information of the first 100 tasks to terminate and
+output this info at program termination. Results are displayed in four
+columns:
+
+@quotation
+
+@example
+Index | Task Name | Stack Size | Stack Usage
+@end example
+@end quotation
+
+where:
+
+
+@itemize *
+
+@item
+`Index' is a number associated with each task.
+
+@item
+`Task Name' is the name of the task analyzed.
+
+@item
+`Stack Size' is the maximum size for the stack.
+
+@item
+`Stack Usage' is the measure done by the stack analyzer.
+In order to prevent overflow, the stack
+is not entirely analyzed, and it’s not possible to know exactly how
+much has actually been used.
+@end itemize
+
+By default the environment task stack, the stack that contains the main unit,
+is not processed. To enable processing of the environment task stack, the
+environment variable GNAT_STACK_LIMIT needs to be set to the maximum size of
+the environment task stack. This amount is given in kilobytes. For example:
+
+@quotation
+
+@example
+$ set GNAT_STACK_LIMIT 1600
+@end example
+@end quotation
+
+would specify to the analyzer that the environment task stack has a limit
+of 1.6 megabytes. Any stack usage beyond this will be ignored by the analysis.
+
+The package @code{GNAT.Task_Stack_Usage} provides facilities to get
+stack-usage reports at run time. See its body for the details.
+
+@node Memory Management Issues,,Stack Related Facilities,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{14c}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{1ac}
+@section Memory Management Issues
+
+
+This section describes some useful memory pools provided in the GNAT library
+and in particular the GNAT Debug Pool facility, which can be used to detect
+incorrect uses of access values (including ‘dangling references’).
+
+
+@menu
+* Some Useful Memory Pools::
+* The GNAT Debug Pool Facility::
+
+@end menu
+
+@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues
+@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1ad}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1ae}
+@subsection Some Useful Memory Pools
+
+
+@geindex Memory Pool
+
+@geindex storage
+@geindex pool
+
+The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
+storage pool. Allocations use the standard system call @code{malloc} while
+deallocations use the standard system call @code{free}. No reclamation is
+performed when the pool goes out of scope. For performance reasons, the
+standard default Ada allocators/deallocators do not use any explicit storage
+pools but if they did, they could use this storage pool without any change in
+behavior. That is why this storage pool is used when the user
+manages to make the default implicit allocator explicit as in this example:
+
+@quotation
+
+@example
+type T1 is access Something;
+ -- no Storage pool is defined for T2
+
+type T2 is access Something_Else;
+for T2'Storage_Pool use T1'Storage_Pool;
+-- the above is equivalent to
+for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
+@end example
+@end quotation
+
+The @code{System.Pool_Local} package offers the @code{Unbounded_Reclaim_Pool} storage
+pool. The allocation strategy is similar to @code{Pool_Local}
+except that the all
+storage allocated with this pool is reclaimed when the pool object goes out of
+scope. This pool provides a explicit mechanism similar to the implicit one
+provided by several Ada 83 compilers for allocations performed through a local
+access type and whose purpose was to reclaim memory when exiting the
+scope of a given local access. As an example, the following program does not
+leak memory even though it does not perform explicit deallocation:
+
+@quotation
+
+@example
+with System.Pool_Local;
+procedure Pooloc1 is
+ procedure Internal is
+ type A is access Integer;
+ X : System.Pool_Local.Unbounded_Reclaim_Pool;
+ for A'Storage_Pool use X;
+ v : A;
+ begin
+ for I in 1 .. 50 loop
+ v := new Integer;
+ end loop;
+ end Internal;
+begin
+ for I in 1 .. 100 loop
+ Internal;
+ end loop;
+end Pooloc1;
+@end example
+@end quotation
+
+The @code{System.Pool_Size} package implements the @code{Stack_Bounded_Pool} used when
+@code{Storage_Size} is specified for an access type.
+The whole storage for the pool is
+allocated at once, usually on the stack at the point where the access type is
+elaborated. It is automatically reclaimed when exiting the scope where the
+access type is defined. This package is not intended to be used directly by the
+user and it is implicitly used for each such declaration:
+
+@quotation
+
+@example
+type T1 is access Something;
+for T1'Storage_Size use 10_000;
+@end example
+@end quotation
+
+@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues
+@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1af}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1b0}
+@subsection The GNAT Debug Pool Facility
+
+
+@geindex Debug Pool
+
+@geindex storage
+@geindex pool
+@geindex memory corruption
+
+The use of unchecked deallocation and unchecked conversion can easily
+lead to incorrect memory references. The problems generated by such
+references are usually difficult to tackle because the symptoms can be
+very remote from the origin of the problem. In such cases, it is
+very helpful to detect the problem as early as possible. This is the
+purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}.
+
+In order to use the GNAT specific debugging pool, the user must
+associate a debug pool object with each of the access types that may be
+related to suspected memory problems. See Ada Reference Manual 13.11.
+
+@quotation
+
+@example
+type Ptr is access Some_Type;
+Pool : GNAT.Debug_Pools.Debug_Pool;
+for Ptr'Storage_Pool use Pool;
+@end example
+@end quotation
+
+@code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
+pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools,
+allow the user to redefine allocation and deallocation strategies. They
+also provide a checkpoint for each dereference, through the use of
+the primitive operation @code{Dereference} which is implicitly called at
+each dereference of an access value.
+
+Once an access type has been associated with a debug pool, operations on
+values of the type may raise four distinct exceptions,
+which correspond to four potential kinds of memory corruption:
+
+
+@itemize *
+
+@item
+@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
+
+@item
+@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
+
+@item
+@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
+
+@item
+@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage}
+@end itemize
+
+For types associated with a Debug_Pool, dynamic allocation is performed using
+the standard GNAT allocation routine. References to all allocated chunks of
+memory are kept in an internal dictionary. Several deallocation strategies are
+provided, whereupon the user can choose to release the memory to the system,
+keep it allocated for further invalid access checks, or fill it with an easily
+recognizable pattern for debug sessions. The memory pattern is the old IBM
+hexadecimal convention: @code{16#DEADBEEF#}.
+
+See the documentation in the file g-debpoo.ads for more information on the
+various strategies.
+
+Upon each dereference, a check is made that the access value denotes a
+properly allocated memory location. Here is a complete example of use of
+@code{Debug_Pools}, that includes typical instances of memory corruption:
+
+@quotation
+
+@example
+with GNAT.IO; use GNAT.IO;
+with Ada.Unchecked_Deallocation;
+with Ada.Unchecked_Conversion;
+with GNAT.Debug_Pools;
+with System.Storage_Elements;
+with Ada.Exceptions; use Ada.Exceptions;
+procedure Debug_Pool_Test is
+
+ type T is access Integer;
+ type U is access all T;
+
+ P : GNAT.Debug_Pools.Debug_Pool;
+ for T'Storage_Pool use P;
+
+ procedure Free is new Ada.Unchecked_Deallocation (Integer, T);
+ function UC is new Ada.Unchecked_Conversion (U, T);
+ A, B : aliased T;
+
+ procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
+
+begin
+ Info (P);
+ A := new Integer;
+ B := new Integer;
+ B := A;
+ Info (P);
+ Free (A);
+ begin
+ Put_Line (Integer'Image(B.all));
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ begin
+ Free (B);
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ B := UC(A'Access);
+ begin
+ Put_Line (Integer'Image(B.all));
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ begin
+ Free (B);
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ Info (P);
+end Debug_Pool_Test;
+@end example
+@end quotation
+
+The debug pool mechanism provides the following precise diagnostics on the
+execution of this erroneous program:
+
+@quotation
+
+@example
+Debug Pool info:
+ Total allocated bytes : 0
+ Total deallocated bytes : 0
+ Current Water Mark: 0
+ High Water Mark: 0
+
+Debug Pool info:
+ Total allocated bytes : 8
+ Total deallocated bytes : 0
+ Current Water Mark: 8
+ High Water Mark: 8
+
+raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE
+Debug Pool info:
+ Total allocated bytes : 8
+ Total deallocated bytes : 4
+ Current Water Mark: 4
+ High Water Mark: 8
+@end example
+@end quotation
+
+
+@c -- Non-breaking space in running text
+@c -- E.g. Ada |nbsp| 95
+
+@node Platform-Specific Information,Example of Binder Output File,GNAT and Program Execution,Top
+@anchor{gnat_ugn/platform_specific_information doc}@anchor{1b1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1b2}@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}
+@chapter Platform-Specific Information
+
+
+This appendix contains information relating to the implementation
+of run-time libraries on various platforms and also covers
+topics related to the GNAT implementation on Windows and Mac OS.
+
+@menu
+* Run-Time Libraries::
+* Specifying a Run-Time Library::
+* GNU/Linux Topics::
+* Microsoft Windows Topics::
+* Mac OS Topics::
+
+@end menu
+
+@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information id2}@anchor{1b3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1b4}
+@section Run-Time Libraries
+
+
+@geindex Tasking and threads libraries
+
+@geindex Threads libraries and tasking
+
+@geindex Run-time libraries (platform-specific information)
+
+The GNAT run-time implementation may vary with respect to both the
+underlying threads library and the exception-handling scheme.
+For threads support, the default run-time will bind to the thread
+package of the underlying operating system.
+
+For exception handling, either or both of two models are supplied:
+
+@quotation
+
+@geindex Zero-Cost Exceptions
+
+@geindex ZCX (Zero-Cost Exceptions)
+@end quotation
+
+
+@itemize *
+
+@item
+`Zero-Cost Exceptions' (“ZCX”),
+which uses binder-generated tables that
+are interrogated at run time to locate a handler.
+
+@geindex setjmp/longjmp Exception Model
+
+@geindex SJLJ (setjmp/longjmp Exception Model)
+
+@item
+`setjmp / longjmp' (‘SJLJ’),
+which uses dynamically-set data to establish
+the set of handlers
+@end itemize
+
+Most programs should experience a substantial speed improvement by
+being compiled with a ZCX run-time.
+This is especially true for
+tasking applications or applications with many exception handlers.
+Note however that the ZCX run-time does not support asynchronous abort
+of tasks (@code{abort} and @code{select-then-abort} constructs) and will instead
+implement abort by polling points in the runtime. You can also add additional
+polling points explicitly if needed in your application via @code{pragma
+Abort_Defer}.
+
+This section summarizes which combinations of threads and exception support
+are supplied on various GNAT platforms.
+
+@menu
+* Summary of Run-Time Configurations::
+
+@end menu
+
+@node Summary of Run-Time Configurations,,,Run-Time Libraries
+@anchor{gnat_ugn/platform_specific_information id3}@anchor{1b5}@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1b6}
+@subsection Summary of Run-Time Configurations
+
+
+
+@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
+@headitem
+
+Platform
+
+@tab
+
+Run-Time
+
+@tab
+
+Tasking
+
+@tab
+
+Exceptions
+
+@item
+
+GNU/Linux
+
+@tab
+
+rts-native
+(default)
+
+@tab
+
+pthread library
+
+@tab
+
+ZCX
+
+@item
+
+rts-sjlj
+
+@tab
+
+pthread library
+
+@tab
+
+SJLJ
+
+@item
+
+Windows
+
+@tab
+
+rts-native
+(default)
+
+@tab
+
+native Win32 threads
+
+@tab
+
+ZCX
+
+@item
+
+rts-sjlj
+
+@tab
+
+native Win32 threads
+
+@tab
+
+SJLJ
+
+@item
+
+Mac OS
+
+@tab
+
+rts-native
+
+@tab
+
+pthread library
+
+@tab
+
+ZCX
+
+@end multitable
+
+
+@node Specifying a Run-Time Library,GNU/Linux Topics,Run-Time Libraries,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information id4}@anchor{1b7}@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1b8}
+@section Specifying a Run-Time Library
+
+
+The @code{adainclude} subdirectory containing the sources of the GNAT
+run-time library, and the @code{adalib} subdirectory containing the
+@code{ALI} files and the static and/or shared GNAT library, are located
+in the gcc target-dependent area:
+
+@quotation
+
+@example
+target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/
+@end example
+@end quotation
+
+As indicated above, on some platforms several run-time libraries are supplied.
+These libraries are installed in the target dependent area and
+contain a complete source and binary subdirectory. The detailed description
+below explains the differences between the different libraries in terms of
+their thread support.
+
+The default run-time library (when GNAT is installed) is `rts-native'.
+This default run-time is selected by the means of soft links.
+For example on x86-linux:
+
+@c --
+@c -- $(target-dir)
+@c -- |
+@c -- +--- adainclude----------+
+@c -- | |
+@c -- +--- adalib-----------+ |
+@c -- | | |
+@c -- +--- rts-native | |
+@c -- | | | |
+@c -- | +--- adainclude <---+
+@c -- | | |
+@c -- | +--- adalib <----+
+@c -- |
+@c -- +--- rts-sjlj
+@c -- |
+@c -- +--- adainclude
+@c -- |
+@c -- +--- adalib
+
+
+@example
+ $(target-dir)
+ __/ / \ \___
+ _______/ / \ \_________________
+ / / \ \
+ / / \ \
+ADAINCLUDE ADALIB rts-native rts-sjlj
+ : : / \ / \
+ : : / \ / \
+ : : / \ / \
+ : : / \ / \
+ +-------------> adainclude adalib adainclude adalib
+ : ^
+ : :
+ +---------------------+
+
+ Run-Time Library Directory Structure
+ (Upper-case names and dotted/dashed arrows represent soft links)
+@end example
+
+If the `rts-sjlj' library is to be selected on a permanent basis,
+these soft links can be modified with the following commands:
+
+@quotation
+
+@example
+$ cd $target
+$ rm -f adainclude adalib
+$ ln -s rts-sjlj/adainclude adainclude
+$ ln -s rts-sjlj/adalib adalib
+@end example
+@end quotation
+
+Alternatively, you can specify @code{rts-sjlj/adainclude} in the file
+@code{$target/ada_source_path} and @code{rts-sjlj/adalib} in
+@code{$target/ada_object_path}.
+
+@geindex --RTS option
+
+Selecting another run-time library temporarily can be
+achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj}
+@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1b9}
+@geindex SCHED_FIFO scheduling policy
+
+@geindex SCHED_RR scheduling policy
+
+@geindex SCHED_OTHER scheduling policy
+
+@menu
+* Choosing the Scheduling Policy::
+
+@end menu
+
+@node Choosing the Scheduling Policy,,,Specifying a Run-Time Library
+@anchor{gnat_ugn/platform_specific_information id5}@anchor{1ba}
+@subsection Choosing the Scheduling Policy
+
+
+When using a POSIX threads implementation, you have a choice of several
+scheduling policies: @code{SCHED_FIFO}, @code{SCHED_RR} and @code{SCHED_OTHER}.
+
+Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO}
+or @code{SCHED_RR} requires special (e.g., root) privileges.
+
+@geindex pragma Time_Slice
+
+@geindex -T0 option
+
+@geindex pragma Task_Dispatching_Policy
+
+By default, GNAT uses the @code{SCHED_OTHER} policy. To specify
+@code{SCHED_FIFO},
+you can use one of the following:
+
+
+@itemize *
+
+@item
+@code{pragma Time_Slice (0.0)}
+
+@item
+the corresponding binder option @code{-T0}
+
+@item
+@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
+@end itemize
+
+To specify @code{SCHED_RR},
+you should use @code{pragma Time_Slice} with a
+value greater than 0.0, or else use the corresponding @code{-T}
+binder option.
+
+To make sure a program is running as root, you can put something like
+this in a library package body in your application:
+
+@quotation
+
+@example
+function geteuid return Integer;
+pragma Import (C, geteuid, "geteuid");
+Ignore : constant Boolean :=
+ (if geteuid = 0 then True else raise Program_Error with "must be root");
+@end example
+@end quotation
+
+It gets the effective user id, and if it’s not 0 (i.e. root), it raises
+Program_Error. Note that if you re running the code in a container, this may
+not be sufficient, as you may have sufficient priviledge on the container,
+but not on the host machine running the container, so check that you also
+have sufficient priviledge for running the container image.
+
+@geindex Linux
+
+@geindex GNU/Linux
+
+@node GNU/Linux Topics,Microsoft Windows Topics,Specifying a Run-Time Library,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1bb}@anchor{gnat_ugn/platform_specific_information id6}@anchor{1bc}
+@section GNU/Linux Topics
+
+
+This section describes topics that are specific to GNU/Linux platforms.
+
+@menu
+* Required Packages on GNU/Linux::
+* A GNU/Linux Debug Quirk::
+
+@end menu
+
+@node Required Packages on GNU/Linux,A GNU/Linux Debug Quirk,,GNU/Linux Topics
+@anchor{gnat_ugn/platform_specific_information id7}@anchor{1bd}@anchor{gnat_ugn/platform_specific_information required-packages-on-gnu-linux}@anchor{1be}
+@subsection Required Packages on GNU/Linux
+
+
+GNAT requires the C library developer’s package to be installed.
+The name of of that package depends on your GNU/Linux distribution:
+
+
+@itemize *
+
+@item
+RedHat, SUSE: @code{glibc-devel};
+
+@item
+Debian, Ubuntu: @code{libc6-dev} (normally installed by default).
+@end itemize
+
+If using the 32-bit version of GNAT on a 64-bit version of GNU/Linux,
+you’ll need the 32-bit version of the following packages:
+
+
+@itemize *
+
+@item
+RedHat, SUSE: @code{glibc.i686}, @code{glibc-devel.i686}, @code{ncurses-libs.i686}
+
+@item
+SUSE: @code{glibc-locale-base-32bit}
+
+@item
+Debian, Ubuntu: @code{libc6:i386}, @code{libc6-dev:i386}, @code{lib32ncursesw5}
+@end itemize
+
+Other GNU/Linux distributions might be choosing a different name
+for those packages.
+
+@node A GNU/Linux Debug Quirk,,Required Packages on GNU/Linux,GNU/Linux Topics
+@anchor{gnat_ugn/platform_specific_information a-gnu-linux-debug-quirk}@anchor{1bf}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1c0}
+@subsection A GNU/Linux Debug Quirk
+
+
+On SuSE 15, some kernels have a defect causing issues when debugging
+programs using threads or Ada tasks. Due to the lack of documentation
+found regarding this kernel issue, we can only provide limited
+information about which kernels are impacted: kernel version 5.3.18 is
+known to be impacted, and kernels in the 5.14 range or newer are
+believed to fix this problem.
+
+The bug affects the debugging of 32-bit processes on a 64-bit system.
+Symptoms can vary: Unexpected @code{SIGABRT} signals being received by
+the program, “The futex facility returned an unexpected error code”
+error message, and inferior programs hanging indefinitely range among
+the symptoms most commonly observed.
+
+@geindex Windows
+
+@node Microsoft Windows Topics,Mac OS Topics,GNU/Linux Topics,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information id9}@anchor{1c1}@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1c2}
+@section Microsoft Windows Topics
+
+
+This section describes topics that are specific to the Microsoft Windows
+platforms.
+
+
+@menu
+* Using GNAT on Windows::
+* Using a network installation of GNAT::
+* CONSOLE and WINDOWS subsystems::
+* Temporary Files::
+* Disabling Command Line Argument Expansion::
+* Windows Socket Timeouts::
+* Mixed-Language Programming on Windows::
+* Windows Specific Add-Ons::
+
+@end menu
+
+@node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information id10}@anchor{1c3}@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1c4}
+@subsection Using GNAT on Windows
+
+
+One of the strengths of the GNAT technology is that its tool set
+(@code{gcc}, @code{gnatbind}, @code{gnatlink}, @code{gnatmake}, the
+@code{gdb} debugger, etc.) is used in the same way regardless of the
+platform.
+
+On Windows this tool set is complemented by a number of Microsoft-specific
+tools that have been provided to facilitate interoperability with Windows
+when this is required. With these tools:
+
+
+@itemize *
+
+@item
+You can build applications using the @code{CONSOLE} or @code{WINDOWS}
+subsystems.
+
+@item
+You can use any Dynamically Linked Library (DLL) in your Ada code (both
+relocatable and non-relocatable DLLs are supported).
+
+@item
+You can build Ada DLLs for use in other applications. These applications
+can be written in a language other than Ada (e.g., C, C++, etc). Again both
+relocatable and non-relocatable Ada DLLs are supported.
+
+@item
+You can include Windows resources in your Ada application.
+
+@item
+You can use or create COM/DCOM objects.
+@end itemize
+
+Immediately below are listed all known general GNAT-for-Windows restrictions.
+Other restrictions about specific features like Windows Resources and DLLs
+are listed in separate sections below.
+
+
+@itemize *
+
+@item
+It is not possible to use @code{GetLastError} and @code{SetLastError}
+when tasking, protected records, or exceptions are used. In these
+cases, in order to implement Ada semantics, the GNAT run-time system
+calls certain Win32 routines that set the last error variable to 0 upon
+success. It should be possible to use @code{GetLastError} and
+@code{SetLastError} when tasking, protected record, and exception
+features are not used, but it is not guaranteed to work.
+
+@item
+It is not possible to link against Microsoft C++ libraries except for
+import libraries. Interfacing must be done by the mean of DLLs.
+
+@item
+It is possible to link against Microsoft C libraries. Yet the preferred
+solution is to use C/C++ compiler that comes with GNAT, since it
+doesn’t require having two different development environments and makes the
+inter-language debugging experience smoother.
+
+@item
+When the compilation environment is located on FAT32 drives, users may
+experience recompilations of the source files that have not changed if
+Daylight Saving Time (DST) state has changed since the last time files
+were compiled. NTFS drives do not have this problem.
+
+@item
+No components of the GNAT toolset use any entries in the Windows
+registry. The only entries that can be created are file associations and
+PATH settings, provided the user has chosen to create them at installation
+time, as well as some minimal book-keeping information needed to correctly
+uninstall or integrate different GNAT products.
+@end itemize
+
+@node Using a network installation of GNAT,CONSOLE and WINDOWS subsystems,Using GNAT on Windows,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information id11}@anchor{1c5}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1c6}
+@subsection Using a network installation of GNAT
+
+
+Make sure the system on which GNAT is installed is accessible from the
+current machine, i.e., the install location is shared over the network.
+Shared resources are accessed on Windows by means of UNC paths, which
+have the format @code{\\\\server\\sharename\\path}
+
+In order to use such a network installation, simply add the UNC path of the
+@code{bin} directory of your GNAT installation in front of your PATH. For
+example, if GNAT is installed in @code{\GNAT} directory of a share location
+called @code{c-drive} on a machine @code{LOKI}, the following command will
+make it available:
+
+@quotation
+
+@example
+$ path \\loki\c-drive\gnat\bin;%path%`
+@end example
+@end quotation
+
+Be aware that every compilation using the network installation results in the
+transfer of large amounts of data across the network and will likely cause
+serious performance penalty.
+
+@node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information id12}@anchor{1c8}
+@subsection CONSOLE and WINDOWS subsystems
+
+
+@geindex CONSOLE Subsystem
+
+@geindex WINDOWS Subsystem
+
+@geindex -mwindows
+
+There are two main subsystems under Windows. The @code{CONSOLE} subsystem
+(which is the default subsystem) will always create a console when
+launching the application. This is not something desirable when the
+application has a Windows GUI. To get rid of this console the
+application must be using the @code{WINDOWS} subsystem. To do so
+the @code{-mwindows} linker option must be specified.
+
+@quotation
+
+@example
+$ gnatmake winprog -largs -mwindows
+@end example
+@end quotation
+
+@node Temporary Files,Disabling Command Line Argument Expansion,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information id13}@anchor{1c9}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1ca}
+@subsection Temporary Files
+
+
+@geindex Temporary files
+
+It is possible to control where temporary files gets created by setting
+the
+@geindex TMP
+@geindex environment variable; TMP
+@code{TMP} environment variable. The file will be created:
+
+
+@itemize *
+
+@item
+Under the directory pointed to by the
+@geindex TMP
+@geindex environment variable; TMP
+@code{TMP} environment variable if
+this directory exists.
+
+@item
+Under @code{c:\temp}, if the
+@geindex TMP
+@geindex environment variable; TMP
+@code{TMP} environment variable is not
+set (or not pointing to a directory) and if this directory exists.
+
+@item
+Under the current working directory otherwise.
+@end itemize
+
+This allows you to determine exactly where the temporary
+file will be created. This is particularly useful in networked
+environments where you may not have write access to some
+directories.
+
+@node Disabling Command Line Argument Expansion,Windows Socket Timeouts,Temporary Files,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1cb}
+@subsection Disabling Command Line Argument Expansion
+
+
+@geindex Command Line Argument Expansion
+
+By default, an executable compiled for the Windows platform will do
+the following postprocessing on the arguments passed on the command
+line:
+
+
+@itemize *
+
+@item
+If the argument contains the characters @code{*} and/or @code{?}, then
+file expansion will be attempted. For example, if the current directory
+contains @code{a.txt} and @code{b.txt}, then when calling:
+
+@example
+$ my_ada_program *.txt
+@end example
+
+The following arguments will effectively be passed to the main program
+(for example when using @code{Ada.Command_Line.Argument}):
+
+@example
+Ada.Command_Line.Argument (1) -> "a.txt"
+Ada.Command_Line.Argument (2) -> "b.txt"
+@end example
+
+@item
+Filename expansion can be disabled for a given argument by using single
+quotes. Thus, calling:
+
+@example
+$ my_ada_program '*.txt'
+@end example
+
+will result in:
+
+@example
+Ada.Command_Line.Argument (1) -> "*.txt"
+@end example
+@end itemize
+
+Note that if the program is launched from a shell such as Cygwin Bash
+then quote removal might be performed by the shell.
+
+In some contexts it might be useful to disable this feature (for example if
+the program performs its own argument expansion). In order to do this, a C
+symbol needs to be defined and set to @code{0}. You can do this by
+adding the following code fragment in one of your Ada units:
+
+@example
+Do_Argv_Expansion : Integer := 0;
+pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion");
+@end example
+
+The results of previous examples will be respectively:
+
+@example
+Ada.Command_Line.Argument (1) -> "*.txt"
+@end example
+
+and:
+
+@example
+Ada.Command_Line.Argument (1) -> "'*.txt'"
+@end example
+
+@node Windows Socket Timeouts,Mixed-Language Programming on Windows,Disabling Command Line Argument Expansion,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information windows-socket-timeouts}@anchor{1cc}
+@subsection Windows Socket Timeouts
+
+
+Microsoft Windows desktops older than @code{8.0} and Microsoft Windows Servers
+older than @code{2019} set a socket timeout 500 milliseconds longer than the value
+set by setsockopt with @code{SO_RCVTIMEO} and @code{SO_SNDTIMEO} options. The GNAT
+runtime makes a correction for the difference in the corresponding Windows
+versions. For Windows Server starting with version @code{2019}, the user must
+provide a manifest file for the GNAT runtime to be able to recognize that
+the Windows version does not need the timeout correction. The manifest file
+should be located in the same directory as the executable file, and its file
+name must match the executable name suffixed by @code{.manifest}. For example,
+if the executable name is @code{sock_wto.exe}, then the manifest file name
+has to be @code{sock_wto.exe.manifest}. The manifest file must contain at
+least the following data:
+
+@example
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+<application>
+ <!-- Windows Vista -->
+ <supportedOS Id="@{e2011457-1546-43c5-a5fe-008deee3d3f0@}"/>
+ <!-- Windows 7 -->
+ <supportedOS Id="@{35138b9a-5d96-4fbd-8e2d-a2440225f93a@}"/>
+ <!-- Windows 8 -->
+ <supportedOS Id="@{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38@}"/>
+ <!-- Windows 8.1 -->
+ <supportedOS Id="@{1f676c76-80e1-4239-95bb-83d0f6d0da78@}"/>
+ <!-- Windows 10 -->
+ <supportedOS Id="@{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a@}"/>
+</application>
+</compatibility>
+</assembly>
+@end example
+
+Without the manifest file, the socket timeout is going to be overcorrected on
+these Windows Server versions and the actual time is going to be 500
+milliseconds shorter than what was set with GNAT.Sockets.Set_Socket_Option.
+Note that on Microsoft Windows versions where correction is necessary, there
+is no way to set a socket timeout shorter than 500 ms. If a socket timeout
+shorter than 500 ms is needed on these Windows versions, a call to
+Check_Selector should be added before any socket read or write operations.
+
+@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Windows Socket Timeouts,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information id14}@anchor{1cd}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1ce}
+@subsection Mixed-Language Programming on Windows
+
+
+Developing pure Ada applications on Windows is no different than on
+other GNAT-supported platforms. However, when developing or porting an
+application that contains a mix of Ada and C/C++, the choice of your
+Windows C/C++ development environment conditions your overall
+interoperability strategy.
+
+If you use @code{gcc} or Microsoft C to compile the non-Ada part of
+your application, there are no Windows-specific restrictions that
+affect the overall interoperability with your Ada code. If you do want
+to use the Microsoft tools for your C++ code, you have two choices:
+
+
+@itemize *
+
+@item
+Encapsulate your C++ code in a DLL to be linked with your Ada
+application. In this case, use the Microsoft or whatever environment to
+build the DLL and use GNAT to build your executable
+(@ref{1cf,,Using DLLs with GNAT}).
+
+@item
+Or you can encapsulate your Ada code in a DLL to be linked with the
+other part of your application. In this case, use GNAT to build the DLL
+(@ref{1d0,,Building DLLs with GNAT Project files}) and use the Microsoft
+or whatever environment to build your executable.
+@end itemize
+
+In addition to the description about C main in
+@ref{2c,,Mixed Language Programming} section, if the C main uses a
+stand-alone library it is required on x86-windows to
+setup the SEH context. For this the C main must looks like this:
+
+@quotation
+
+@example
+/* main.c */
+extern void adainit (void);
+extern void adafinal (void);
+extern void __gnat_initialize(void*);
+extern void call_to_ada (void);
+
+int main (int argc, char *argv[])
+@{
+ int SEH [2];
+
+ /* Initialize the SEH context */
+ __gnat_initialize (&SEH);
+
+ adainit();
+
+ /* Then call Ada services in the stand-alone library */
+
+ call_to_ada();
+
+ adafinal();
+@}
+@end example
+@end quotation
+
+Note that this is not needed on x86_64-windows where the Windows
+native SEH support is used.
+
+@menu
+* Windows Calling Conventions::
+* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs.
+* Using DLLs with GNAT::
+* Building DLLs with GNAT Project files::
+* Building DLLs with GNAT::
+* Building DLLs with gnatdll::
+* Ada DLLs and Finalization::
+* Creating a Spec for Ada DLLs::
+* GNAT and Windows Resources::
+* Using GNAT DLLs from Microsoft Visual Studio Applications::
+* Debugging a DLL::
+* Setting Stack Size from gnatlink::
+* Setting Heap Size from gnatlink::
+
+@end menu
+
+@node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information id15}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1d2}
+@subsubsection Windows Calling Conventions
+
+
+@geindex Stdcall
+
+@geindex APIENTRY
+
+This section pertain only to Win32. On Win64 there is a single native
+calling convention. All convention specifiers are ignored on this
+platform.
+
+When a subprogram @code{F} (caller) calls a subprogram @code{G}
+(callee), there are several ways to push @code{G}‘s parameters on the
+stack and there are several possible scenarios to clean up the stack
+upon @code{G}‘s return. A calling convention is an agreed upon software
+protocol whereby the responsibilities between the caller (@code{F}) and
+the callee (@code{G}) are clearly defined. Several calling conventions
+are available for Windows:
+
+
+@itemize *
+
+@item
+@code{C} (Microsoft defined)
+
+@item
+@code{Stdcall} (Microsoft defined)
+
+@item
+@code{Win32} (GNAT specific)
+
+@item
+@code{DLL} (GNAT specific)
+@end itemize
+
+@menu
+* C Calling Convention::
+* Stdcall Calling Convention::
+* Win32 Calling Convention::
+* DLL Calling Convention::
+
+@end menu
+
+@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions
+@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1d4}
+@subsubsection @code{C} Calling Convention
+
+
+This is the default calling convention used when interfacing to C/C++
+routines compiled with either @code{gcc} or Microsoft Visual C++.
+
+In the @code{C} calling convention subprogram parameters are pushed on the
+stack by the caller from right to left. The caller itself is in charge of
+cleaning up the stack after the call. In addition, the name of a routine
+with @code{C} calling convention is mangled by adding a leading underscore.
+
+The name to use on the Ada side when importing (or exporting) a routine
+with @code{C} calling convention is the name of the routine. For
+instance the C function:
+
+@quotation
+
+@example
+int get_val (long);
+@end example
+@end quotation
+
+should be imported from Ada as follows:
+
+@quotation
+
+@example
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (C, Get_Val, External_Name => "get_val");
+@end example
+@end quotation
+
+Note that in this particular case the @code{External_Name} parameter could
+have been omitted since, when missing, this parameter is taken to be the
+name of the Ada entity in lower case. When the @code{Link_Name} parameter
+is missing, as in the above example, this parameter is set to be the
+@code{External_Name} with a leading underscore.
+
+When importing a variable defined in C, you should always use the @code{C}
+calling convention unless the object containing the variable is part of a
+DLL (in which case you should use the @code{Stdcall} calling
+convention, @ref{1d5,,Stdcall Calling Convention}).
+
+@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions
+@anchor{gnat_ugn/platform_specific_information id17}@anchor{1d6}@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1d5}
+@subsubsection @code{Stdcall} Calling Convention
+
+
+This convention, which was the calling convention used for Pascal
+programs, is used by Microsoft for all the routines in the Win32 API for
+efficiency reasons. It must be used to import any routine for which this
+convention was specified.
+
+In the @code{Stdcall} calling convention subprogram parameters are pushed
+on the stack by the caller from right to left. The callee (and not the
+caller) is in charge of cleaning the stack on routine exit. In addition,
+the name of a routine with @code{Stdcall} calling convention is mangled by
+adding a leading underscore (as for the @code{C} calling convention) and a
+trailing @code{@@@var{nn}}, where @code{nn} is the overall size (in
+bytes) of the parameters passed to the routine.
+
+The name to use on the Ada side when importing a C routine with a
+@code{Stdcall} calling convention is the name of the C routine. The leading
+underscore and trailing @code{@@@var{nn}} are added automatically by
+the compiler. For instance the Win32 function:
+
+@quotation
+
+@example
+APIENTRY int get_val (long);
+@end example
+@end quotation
+
+should be imported from Ada as follows:
+
+@quotation
+
+@example
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (Stdcall, Get_Val);
+-- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4"
+@end example
+@end quotation
+
+As for the @code{C} calling convention, when the @code{External_Name}
+parameter is missing, it is taken to be the name of the Ada entity in lower
+case. If instead of writing the above import pragma you write:
+
+@quotation
+
+@example
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");
+@end example
+@end quotation
+
+then the imported routine is @code{_retrieve_val@@4}. However, if instead
+of specifying the @code{External_Name} parameter you specify the
+@code{Link_Name} as in the following example:
+
+@quotation
+
+@example
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
+@end example
+@end quotation
+
+then the imported routine is @code{retrieve_val}, that is, there is no
+decoration at all. No leading underscore and no Stdcall suffix
+@code{@@@var{nn}}.
+
+This is especially important as in some special cases a DLL’s entry
+point name lacks a trailing @code{@@@var{nn}} while the exported
+name generated for a call has it.
+
+It is also possible to import variables defined in a DLL by using an
+import pragma for a variable. As an example, if a DLL contains a
+variable defined as:
+
+@quotation
+
+@example
+int my_var;
+@end example
+@end quotation
+
+then, to access this variable from Ada you should write:
+
+@quotation
+
+@example
+My_Var : Interfaces.C.int;
+pragma Import (Stdcall, My_Var);
+@end example
+@end quotation
+
+Note that to ease building cross-platform bindings this convention
+will be handled as a @code{C} calling convention on non-Windows platforms.
+
+@node Win32 Calling Convention,DLL Calling Convention,Stdcall Calling Convention,Windows Calling Conventions
+@anchor{gnat_ugn/platform_specific_information id18}@anchor{1d7}@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1d8}
+@subsubsection @code{Win32} Calling Convention
+
+
+This convention, which is GNAT-specific is fully equivalent to the
+@code{Stdcall} calling convention described above.
+
+@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions
+@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1d9}@anchor{gnat_ugn/platform_specific_information id19}@anchor{1da}
+@subsubsection @code{DLL} Calling Convention
+
+
+This convention, which is GNAT-specific is fully equivalent to the
+@code{Stdcall} calling convention described above.
+
+@node Introduction to Dynamic Link Libraries DLLs,Using DLLs with GNAT,Windows Calling Conventions,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information id20}@anchor{1db}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1dc}
+@subsubsection Introduction to Dynamic Link Libraries (DLLs)
+
+
+@geindex DLL
+
+A Dynamically Linked Library (DLL) is a library that can be shared by
+several applications running under Windows. A DLL can contain any number of
+routines and variables.
+
+One advantage of DLLs is that you can change and enhance them without
+forcing all the applications that depend on them to be relinked or
+recompiled. However, you should be aware than all calls to DLL routines are
+slower since, as you will understand below, such calls are indirect.
+
+To illustrate the remainder of this section, suppose that an application
+wants to use the services of a DLL @code{API.dll}. To use the services
+provided by @code{API.dll} you must statically link against the DLL or
+an import library which contains a jump table with an entry for each
+routine and variable exported by the DLL. In the Microsoft world this
+import library is called @code{API.lib}. When using GNAT this import
+library is called either @code{libAPI.dll.a}, @code{libapi.dll.a},
+@code{libAPI.a} or @code{libapi.a} (names are case insensitive).
+
+After you have linked your application with the DLL or the import library
+and you run your application, here is what happens:
+
+
+@itemize *
+
+@item
+Your application is loaded into memory.
+
+@item
+The DLL @code{API.dll} is mapped into the address space of your
+application. This means that:
+
+
+@itemize -
+
+@item
+The DLL will use the stack of the calling thread.
+
+@item
+The DLL will use the virtual address space of the calling process.
+
+@item
+The DLL will allocate memory from the virtual address space of the calling
+process.
+
+@item
+Handles (pointers) can be safely exchanged between routines in the DLL
+routines and routines in the application using the DLL.
+@end itemize
+
+@item
+The entries in the jump table (from the import library @code{libAPI.dll.a}
+or @code{API.lib} or automatically created when linking against a DLL)
+which is part of your application are initialized with the addresses
+of the routines and variables in @code{API.dll}.
+
+@item
+If present in @code{API.dll}, routines @code{DllMain} or
+@code{DllMainCRTStartup} are invoked. These routines typically contain
+the initialization code needed for the well-being of the routines and
+variables exported by the DLL.
+@end itemize
+
+There is an additional point which is worth mentioning. In the Windows
+world there are two kind of DLLs: relocatable and non-relocatable
+DLLs. Non-relocatable DLLs can only be loaded at a very specific address
+in the target application address space. If the addresses of two
+non-relocatable DLLs overlap and these happen to be used by the same
+application, a conflict will occur and the application will run
+incorrectly. Hence, when possible, it is always preferable to use and
+build relocatable DLLs. Both relocatable and non-relocatable DLLs are
+supported by GNAT. Note that the @code{-s} linker option (see GNU Linker
+User’s Guide) removes the debugging symbols from the DLL but the DLL can
+still be relocated.
+
+As a side note, an interesting difference between Microsoft DLLs and
+Unix shared libraries, is the fact that on most Unix systems all public
+routines are exported by default in a Unix shared library, while under
+Windows it is possible (but not required) to list exported routines in
+a definition file (see @ref{1dd,,The Definition File}).
+
+@node Using DLLs with GNAT,Building DLLs with GNAT Project files,Introduction to Dynamic Link Libraries DLLs,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information id21}@anchor{1de}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1cf}
+@subsubsection Using DLLs with GNAT
+
+
+To use the services of a DLL, say @code{API.dll}, in your Ada application
+you must have:
+
+
+@itemize *
+
+@item
+The Ada spec for the routines and/or variables you want to access in
+@code{API.dll}. If not available this Ada spec must be built from the C/C++
+header files provided with the DLL.
+
+@item
+The import library (@code{libAPI.dll.a} or @code{API.lib}). As previously
+mentioned an import library is a statically linked library containing the
+import table which will be filled at load time to point to the actual
+@code{API.dll} routines. Sometimes you don’t have an import library for the
+DLL you want to use. The following sections will explain how to build
+one. Note that this is optional.
+
+@item
+The actual DLL, @code{API.dll}.
+@end itemize
+
+Once you have all the above, to compile an Ada application that uses the
+services of @code{API.dll} and whose main subprogram is @code{My_Ada_App},
+you simply issue the command
+
+@quotation
+
+@example
+$ gnatmake my_ada_app -largs -lAPI
+@end example
+@end quotation
+
+The argument @code{-largs -lAPI} at the end of the @code{gnatmake} command
+tells the GNAT linker to look for an import library. The linker will
+look for a library name in this specific order:
+
+
+@itemize *
+
+@item
+@code{libAPI.dll.a}
+
+@item
+@code{API.dll.a}
+
+@item
+@code{libAPI.a}
+
+@item
+@code{API.lib}
+
+@item
+@code{libAPI.dll}
+
+@item
+@code{API.dll}
+@end itemize
+
+The first three are the GNU style import libraries. The third is the
+Microsoft style import libraries. The last two are the actual DLL names.
+
+Note that if the Ada package spec for @code{API.dll} contains the
+following pragma
+
+@quotation
+
+@example
+pragma Linker_Options ("-lAPI");
+@end example
+@end quotation
+
+you do not have to add @code{-largs -lAPI} at the end of the
+@code{gnatmake} command.
+
+If any one of the items above is missing you will have to create it
+yourself. The following sections explain how to do so using as an
+example a fictitious DLL called @code{API.dll}.
+
+@menu
+* Creating an Ada Spec for the DLL Services::
+* Creating an Import Library::
+
+@end menu
+
+@node Creating an Ada Spec for the DLL Services,Creating an Import Library,,Using DLLs with GNAT
+@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1df}@anchor{gnat_ugn/platform_specific_information id22}@anchor{1e0}
+@subsubsection Creating an Ada Spec for the DLL Services
+
+
+A DLL typically comes with a C/C++ header file which provides the
+definitions of the routines and variables exported by the DLL. The Ada
+equivalent of this header file is a package spec that contains definitions
+for the imported entities. If the DLL you intend to use does not come with
+an Ada spec you have to generate one such spec yourself. For example if
+the header file of @code{API.dll} is a file @code{api.h} containing the
+following two definitions:
+
+@quotation
+
+@example
+int some_var;
+int get (char *);
+@end example
+@end quotation
+
+then the equivalent Ada spec could be:
+
+@quotation
+
+@example
+with Interfaces.C.Strings;
+package API is
+ use Interfaces;
+
+ Some_Var : C.int;
+ function Get (Str : C.Strings.Chars_Ptr) return C.int;
+
+private
+ pragma Import (C, Get);
+ pragma Import (DLL, Some_Var);
+end API;
+@end example
+@end quotation
+
+@node Creating an Import Library,,Creating an Ada Spec for the DLL Services,Using DLLs with GNAT
+@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1e1}@anchor{gnat_ugn/platform_specific_information id23}@anchor{1e2}
+@subsubsection Creating an Import Library
+
+
+@geindex Import library
+
+If a Microsoft-style import library @code{API.lib} or a GNAT-style
+import library @code{libAPI.dll.a} or @code{libAPI.a} is available
+with @code{API.dll} you can skip this section. You can also skip this
+section if @code{API.dll} or @code{libAPI.dll} is built with GNU tools
+as in this case it is possible to link directly against the
+DLL. Otherwise read on.
+
+@geindex Definition file
+@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1dd}
+@subsubheading The Definition File
+
+
+As previously mentioned, and unlike Unix systems, the list of symbols
+that are exported from a DLL must be provided explicitly in Windows.
+The main goal of a definition file is precisely that: list the symbols
+exported by a DLL. A definition file (usually a file with a @code{.def}
+suffix) has the following structure:
+
+@quotation
+
+@example
+[LIBRARY `@w{`}name`@w{`}]
+[DESCRIPTION `@w{`}string`@w{`}]
+EXPORTS
+ `@w{`}symbol1`@w{`}
+ `@w{`}symbol2`@w{`}
+ ...
+@end example
+@end quotation
+
+
+@table @asis
+
+@item `LIBRARY name'
+
+This section, which is optional, gives the name of the DLL.
+
+@item `DESCRIPTION string'
+
+This section, which is optional, gives a description string that will be
+embedded in the import library.
+
+@item `EXPORTS'
+
+This section gives the list of exported symbols (procedures, functions or
+variables). For instance in the case of @code{API.dll} the @code{EXPORTS}
+section of @code{API.def} looks like:
+
+@example
+EXPORTS
+ some_var
+ get
+@end example
+@end table
+
+Note that you must specify the correct suffix (@code{@@@var{nn}})
+(see @ref{1d2,,Windows Calling Conventions}) for a Stdcall
+calling convention function in the exported symbols list.
+
+There can actually be other sections in a definition file, but these
+sections are not relevant to the discussion at hand.
+@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{1e3}
+@subsubheading Creating a Definition File Automatically
+
+
+You can automatically create the definition file @code{API.def}
+(see @ref{1dd,,The Definition File}) from a DLL.
+For that use the @code{dlltool} program as follows:
+
+@quotation
+
+@example
+$ dlltool API.dll -z API.def --export-all-symbols
+@end example
+
+Note that if some routines in the DLL have the @code{Stdcall} convention
+(@ref{1d2,,Windows Calling Conventions}) with stripped @code{@@@var{nn}}
+suffix then you’ll have to edit @code{api.def} to add it, and specify
+@code{-k} to @code{gnatdll} when creating the import library.
+
+Here are some hints to find the right @code{@@@var{nn}} suffix.
+
+
+@itemize -
+
+@item
+If you have the Microsoft import library (.lib), it is possible to get
+the right symbols by using Microsoft @code{dumpbin} tool (see the
+corresponding Microsoft documentation for further details).
+
+@example
+$ dumpbin /exports api.lib
+@end example
+
+@item
+If you have a message about a missing symbol at link time the compiler
+tells you what symbol is expected. You just have to go back to the
+definition file and add the right suffix.
+@end itemize
+@end quotation
+@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1e4}
+@subsubheading GNAT-Style Import Library
+
+
+To create a static import library from @code{API.dll} with the GNAT tools
+you should create the .def file, then use @code{gnatdll} tool
+(see @ref{1e5,,Using gnatdll}) as follows:
+
+@quotation
+
+@example
+$ gnatdll -e API.def -d API.dll
+@end example
+
+@code{gnatdll} takes as input a definition file @code{API.def} and the
+name of the DLL containing the services listed in the definition file
+@code{API.dll}. The name of the static import library generated is
+computed from the name of the definition file as follows: if the
+definition file name is @code{xyz.def}, the import library name will
+be @code{libxyz.a}. Note that in the previous example option
+@code{-e} could have been removed because the name of the definition
+file (before the @code{.def} suffix) is the same as the name of the
+DLL (@ref{1e5,,Using gnatdll} for more information about @code{gnatdll}).
+@end quotation
+@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1e6}
+@subsubheading Microsoft-Style Import Library
+
+
+A Microsoft import library is needed only if you plan to make an
+Ada DLL available to applications developed with Microsoft
+tools (@ref{1ce,,Mixed-Language Programming on Windows}).
+
+To create a Microsoft-style import library for @code{API.dll} you
+should create the .def file, then build the actual import library using
+Microsoft’s @code{lib} utility:
+
+@quotation
+
+@example
+$ lib -machine:IX86 -def:API.def -out:API.lib
+@end example
+
+If you use the above command the definition file @code{API.def} must
+contain a line giving the name of the DLL:
+
+@example
+LIBRARY "API"
+@end example
+
+See the Microsoft documentation for further details about the usage of
+@code{lib}.
+@end quotation
+
+@node Building DLLs with GNAT Project files,Building DLLs with GNAT,Using DLLs with GNAT,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1d0}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1e7}
+@subsubsection Building DLLs with GNAT Project files
+
+
+@geindex DLLs
+@geindex building
+
+There is nothing specific to Windows in the build process.
+See the `Library Projects' section in the `GNAT Project Manager'
+chapter of the `GPRbuild User’s Guide'.
+
+Due to a system limitation, it is not possible under Windows to create threads
+when inside the @code{DllMain} routine which is used for auto-initialization
+of shared libraries, so it is not possible to have library level tasks in SALs.
+
+@node Building DLLs with GNAT,Building DLLs with gnatdll,Building DLLs with GNAT Project files,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{1e8}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1e9}
+@subsubsection Building DLLs with GNAT
+
+
+@geindex DLLs
+@geindex building
+
+This section explain how to build DLLs using the GNAT built-in DLL
+support. With the following procedure it is straight forward to build
+and use DLLs with GNAT.
+
+
+@itemize *
+
+@item
+Building object files.
+The first step is to build all objects files that are to be included
+into the DLL. This is done by using the standard @code{gnatmake} tool.
+
+@item
+Building the DLL.
+To build the DLL you must use the @code{gcc} @code{-shared} and
+@code{-shared-libgcc} options. It is quite simple to use this method:
+
+@example
+$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ...
+@end example
+
+It is important to note that in this case all symbols found in the
+object files are automatically exported. It is possible to restrict
+the set of symbols to export by passing to @code{gcc} a definition
+file (see @ref{1dd,,The Definition File}).
+For example:
+
+@example
+$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ...
+@end example
+
+If you use a definition file you must export the elaboration procedures
+for every package that required one. Elaboration procedures are named
+using the package name followed by “_E”.
+
+@item
+Preparing DLL to be used.
+For the DLL to be used by client programs the bodies must be hidden
+from it and the .ali set with read-only attribute. This is very important
+otherwise GNAT will recompile all packages and will not actually use
+the code in the DLL. For example:
+
+@example
+$ mkdir apilib
+$ copy *.ads *.ali api.dll apilib
+$ attrib +R apilib\\*.ali
+@end example
+@end itemize
+
+At this point it is possible to use the DLL by directly linking
+against it. Note that you must use the GNAT shared runtime when using
+GNAT shared libraries. This is achieved by using the @code{-shared} binder
+option.
+
+@quotation
+
+@example
+$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
+@end example
+@end quotation
+
+@node Building DLLs with gnatdll,Ada DLLs and Finalization,Building DLLs with GNAT,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{1ea}@anchor{gnat_ugn/platform_specific_information id26}@anchor{1eb}
+@subsubsection Building DLLs with gnatdll
+
+
+@geindex DLLs
+@geindex building
+
+Note that it is preferred to use GNAT Project files
+(@ref{1d0,,Building DLLs with GNAT Project files}) or the built-in GNAT
+DLL support (@ref{1e8,,Building DLLs with GNAT}) or to build DLLs.
+
+This section explains how to build DLLs containing Ada code using
+@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
+remainder of this section.
+
+The steps required to build an Ada DLL that is to be used by Ada as well as
+non-Ada applications are as follows:
+
+
+@itemize *
+
+@item
+You need to mark each Ada entity exported by the DLL with a @code{C} or
+@code{Stdcall} calling convention to avoid any Ada name mangling for the
+entities exported by the DLL
+(see @ref{1ec,,Exporting Ada Entities}). You can
+skip this step if you plan to use the Ada DLL only from Ada applications.
+
+@item
+Your Ada code must export an initialization routine which calls the routine
+@code{adainit} generated by @code{gnatbind} to perform the elaboration of
+the Ada code in the DLL (@ref{1ed,,Ada DLLs and Elaboration}). The initialization
+routine exported by the Ada DLL must be invoked by the clients of the DLL
+to initialize the DLL.
+
+@item
+When useful, the DLL should also export a finalization routine which calls
+routine @code{adafinal} generated by @code{gnatbind} to perform the
+finalization of the Ada code in the DLL (@ref{1ee,,Ada DLLs and Finalization}).
+The finalization routine exported by the Ada DLL must be invoked by the
+clients of the DLL when the DLL services are no further needed.
+
+@item
+You must provide a spec for the services exported by the Ada DLL in each
+of the programming languages to which you plan to make the DLL available.
+
+@item
+You must provide a definition file listing the exported entities
+(@ref{1dd,,The Definition File}).
+
+@item
+Finally you must use @code{gnatdll} to produce the DLL and the import
+library (@ref{1e5,,Using gnatdll}).
+@end itemize
+
+Note that a relocatable DLL stripped using the @code{strip}
+binutils tool will not be relocatable anymore. To build a DLL without
+debug information pass @code{-largs -s} to @code{gnatdll}. This
+restriction does not apply to a DLL built using a Library Project.
+See the `Library Projects' section in the `GNAT Project Manager'
+chapter of the `GPRbuild User’s Guide'.
+
+@c Limitations_When_Using_Ada_DLLs_from Ada:
+
+@menu
+* Limitations When Using Ada DLLs from Ada::
+* Exporting Ada Entities::
+* Ada DLLs and Elaboration::
+
+@end menu
+
+@node Limitations When Using Ada DLLs from Ada,Exporting Ada Entities,,Building DLLs with gnatdll
+@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{1ef}
+@subsubsection Limitations When Using Ada DLLs from Ada
+
+
+When using Ada DLLs from Ada applications there is a limitation users
+should be aware of. Because on Windows the GNAT run-time is not in a DLL of
+its own, each Ada DLL includes a part of the GNAT run-time. Specifically,
+each Ada DLL includes the services of the GNAT run-time that are necessary
+to the Ada code inside the DLL. As a result, when an Ada program uses an
+Ada DLL there are two independent GNAT run-times: one in the Ada DLL and
+one in the main program.
+
+It is therefore not possible to exchange GNAT run-time objects between the
+Ada DLL and the main Ada program. Example of GNAT run-time objects are file
+handles (e.g., @code{Text_IO.File_Type}), tasks types, protected objects
+types, etc.
+
+It is completely safe to exchange plain elementary, array or record types,
+Windows object handles, etc.
+
+@node Exporting Ada Entities,Ada DLLs and Elaboration,Limitations When Using Ada DLLs from Ada,Building DLLs with gnatdll
+@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{1ec}@anchor{gnat_ugn/platform_specific_information id27}@anchor{1f0}
+@subsubsection Exporting Ada Entities
+
+
+@geindex Export table
+
+Building a DLL is a way to encapsulate a set of services usable from any
+application. As a result, the Ada entities exported by a DLL should be
+exported with the @code{C} or @code{Stdcall} calling conventions to avoid
+any Ada name mangling. As an example here is an Ada package
+@code{API}, spec and body, exporting two procedures, a function, and a
+variable:
+
+@quotation
+
+@example
+with Interfaces.C; use Interfaces;
+package API is
+ Count : C.int := 0;
+ function Factorial (Val : C.int) return C.int;
+
+ procedure Initialize_API;
+ procedure Finalize_API;
+ -- Initialization & Finalization routines. More in the next section.
+private
+ pragma Export (C, Initialize_API);
+ pragma Export (C, Finalize_API);
+ pragma Export (C, Count);
+ pragma Export (C, Factorial);
+end API;
+@end example
+
+@example
+package body API is
+ function Factorial (Val : C.int) return C.int is
+ Fact : C.int := 1;
+ begin
+ Count := Count + 1;
+ for K in 1 .. Val loop
+ Fact := Fact * K;
+ end loop;
+ return Fact;
+ end Factorial;
+
+ procedure Initialize_API is
+ procedure Adainit;
+ pragma Import (C, Adainit);
+ begin
+ Adainit;
+ end Initialize_API;
+
+ procedure Finalize_API is
+ procedure Adafinal;
+ pragma Import (C, Adafinal);
+ begin
+ Adafinal;
+ end Finalize_API;
+end API;
+@end example
+@end quotation
+
+If the Ada DLL you are building will only be used by Ada applications
+you do not have to export Ada entities with a @code{C} or @code{Stdcall}
+convention. As an example, the previous package could be written as
+follows:
+
+@quotation
+
+@example
+package API is
+ Count : Integer := 0;
+ function Factorial (Val : Integer) return Integer;
+
+ procedure Initialize_API;
+ procedure Finalize_API;
+ -- Initialization and Finalization routines.
+end API;
+@end example
+
+@example
+package body API is
+ function Factorial (Val : Integer) return Integer is
+ Fact : Integer := 1;
+ begin
+ Count := Count + 1;
+ for K in 1 .. Val loop
+ Fact := Fact * K;
+ end loop;
+ return Fact;
+ end Factorial;
+
+ ...
+ -- The remainder of this package body is unchanged.
+end API;
+@end example
+@end quotation
+
+Note that if you do not export the Ada entities with a @code{C} or
+@code{Stdcall} convention you will have to provide the mangled Ada names
+in the definition file of the Ada DLL
+(@ref{1f1,,Creating the Definition File}).
+
+@node Ada DLLs and Elaboration,,Exporting Ada Entities,Building DLLs with gnatdll
+@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{1ed}@anchor{gnat_ugn/platform_specific_information id28}@anchor{1f2}
+@subsubsection Ada DLLs and Elaboration
+
+
+@geindex DLLs and elaboration
+
+The DLL that you are building contains your Ada code as well as all the
+routines in the Ada library that are needed by it. The first thing a
+user of your DLL must do is elaborate the Ada code
+(@ref{f,,Elaboration Order Handling in GNAT}).
+
+To achieve this you must export an initialization routine
+(@code{Initialize_API} in the previous example), which must be invoked
+before using any of the DLL services. This elaboration routine must call
+the Ada elaboration routine @code{adainit} generated by the GNAT binder
+(@ref{a0,,Binding with Non-Ada Main Programs}). See the body of
+@code{Initialize_Api} for an example. Note that the GNAT binder is
+automatically invoked during the DLL build process by the @code{gnatdll}
+tool (@ref{1e5,,Using gnatdll}).
+
+When a DLL is loaded, Windows systematically invokes a routine called
+@code{DllMain}. It would therefore be possible to call @code{adainit}
+directly from @code{DllMain} without having to provide an explicit
+initialization routine. Unfortunately, it is not possible to call
+@code{adainit} from the @code{DllMain} if your program has library level
+tasks because access to the @code{DllMain} entry point is serialized by
+the system (that is, only a single thread can execute ‘through’ it at a
+time), which means that the GNAT run-time will deadlock waiting for the
+newly created task to complete its initialization.
+
+@node Ada DLLs and Finalization,Creating a Spec for Ada DLLs,Building DLLs with gnatdll,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{1ee}@anchor{gnat_ugn/platform_specific_information id29}@anchor{1f3}
+@subsubsection Ada DLLs and Finalization
+
+
+@geindex DLLs and finalization
+
+When the services of an Ada DLL are no longer needed, the client code should
+invoke the DLL finalization routine, if available. The DLL finalization
+routine is in charge of releasing all resources acquired by the DLL. In the
+case of the Ada code contained in the DLL, this is achieved by calling
+routine @code{adafinal} generated by the GNAT binder
+(@ref{a0,,Binding with Non-Ada Main Programs}).
+See the body of @code{Finalize_Api} for an
+example. As already pointed out the GNAT binder is automatically invoked
+during the DLL build process by the @code{gnatdll} tool
+(@ref{1e5,,Using gnatdll}).
+
+@node Creating a Spec for Ada DLLs,GNAT and Windows Resources,Ada DLLs and Finalization,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{1f4}@anchor{gnat_ugn/platform_specific_information id30}@anchor{1f5}
+@subsubsection Creating a Spec for Ada DLLs
+
+
+To use the services exported by the Ada DLL from another programming
+language (e.g., C), you have to translate the specs of the exported Ada
+entities in that language. For instance in the case of @code{API.dll},
+the corresponding C header file could look like:
+
+@quotation
+
+@example
+extern int *_imp__count;
+#define count (*_imp__count)
+int factorial (int);
+@end example
+@end quotation
+
+It is important to understand that when building an Ada DLL to be used by
+other Ada applications, you need two different specs for the packages
+contained in the DLL: one for building the DLL and the other for using
+the DLL. This is because the @code{DLL} calling convention is needed to
+use a variable defined in a DLL, but when building the DLL, the variable
+must have either the @code{Ada} or @code{C} calling convention. As an
+example consider a DLL comprising the following package @code{API}:
+
+@quotation
+
+@example
+package API is
+ Count : Integer := 0;
+ ...
+ -- Remainder of the package omitted.
+end API;
+@end example
+@end quotation
+
+After producing a DLL containing package @code{API}, the spec that
+must be used to import @code{API.Count} from Ada code outside of the
+DLL is:
+
+@quotation
+
+@example
+package API is
+ Count : Integer;
+ pragma Import (DLL, Count);
+end API;
+@end example
+@end quotation
+
+@menu
+* Creating the Definition File::
+* Using gnatdll::
+
+@end menu
+
+@node Creating the Definition File,Using gnatdll,,Creating a Spec for Ada DLLs
+@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{1f1}@anchor{gnat_ugn/platform_specific_information id31}@anchor{1f6}
+@subsubsection Creating the Definition File
+
+
+The definition file is the last file needed to build the DLL. It lists
+the exported symbols. As an example, the definition file for a DLL
+containing only package @code{API} (where all the entities are exported
+with a @code{C} calling convention) is:
+
+@quotation
+
+@example
+EXPORTS
+ count
+ factorial
+ finalize_api
+ initialize_api
+@end example
+@end quotation
+
+If the @code{C} calling convention is missing from package @code{API},
+then the definition file contains the mangled Ada names of the above
+entities, which in this case are:
+
+@quotation
+
+@example
+EXPORTS
+ api__count
+ api__factorial
+ api__finalize_api
+ api__initialize_api
+@end example
+@end quotation
+
+@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs
+@anchor{gnat_ugn/platform_specific_information id32}@anchor{1f7}@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1e5}
+@subsubsection Using @code{gnatdll}
+
+
+@geindex gnatdll
+
+@code{gnatdll} is a tool to automate the DLL build process once all the Ada
+and non-Ada sources that make up your DLL have been compiled.
+@code{gnatdll} is actually in charge of two distinct tasks: build the
+static import library for the DLL and the actual DLL. The form of the
+@code{gnatdll} command is
+
+@quotation
+
+@example
+$ gnatdll [ switches ] list-of-files [ -largs opts ]
+@end example
+@end quotation
+
+where @code{list-of-files} is a list of ALI and object files. The object
+file list must be the exact list of objects corresponding to the non-Ada
+sources whose services are to be included in the DLL. The ALI file list
+must be the exact list of ALI files for the corresponding Ada sources
+whose services are to be included in the DLL. If @code{list-of-files} is
+missing, only the static import library is generated.
+
+You may specify any of the following switches to @code{gnatdll}:
+
+@quotation
+
+@geindex -a (gnatdll)
+@end quotation
+
+
+@table @asis
+
+@item @code{-a[`address']}
+
+Build a non-relocatable DLL at @code{address}. If @code{address} is not
+specified the default address @code{0x11000000} will be used. By default,
+when this switch is missing, @code{gnatdll} builds relocatable DLL. We
+advise the reader to build relocatable DLL.
+
+@geindex -b (gnatdll)
+
+@item @code{-b `address'}
+
+Set the relocatable DLL base address. By default the address is
+@code{0x11000000}.
+
+@geindex -bargs (gnatdll)
+
+@item @code{-bargs `opts'}
+
+Binder options. Pass @code{opts} to the binder.
+
+@geindex -d (gnatdll)
+
+@item @code{-d `dllfile'}
+
+@code{dllfile} is the name of the DLL. This switch must be present for
+@code{gnatdll} to do anything. The name of the generated import library is
+obtained algorithmically from @code{dllfile} as shown in the following
+example: if @code{dllfile} is @code{xyz.dll}, the import library name is
+@code{libxyz.dll.a}. The name of the definition file to use (if not specified
+by option @code{-e}) is obtained algorithmically from @code{dllfile}
+as shown in the following example:
+if @code{dllfile} is @code{xyz.dll}, the definition
+file used is @code{xyz.def}.
+
+@geindex -e (gnatdll)
+
+@item @code{-e `deffile'}
+
+@code{deffile} is the name of the definition file.
+
+@geindex -g (gnatdll)
+
+@item @code{-g}
+
+Generate debugging information. This information is stored in the object
+file and copied from there to the final DLL file by the linker,
+where it can be read by the debugger. You must use the
+@code{-g} switch if you plan on using the debugger or the symbolic
+stack traceback.
+
+@geindex -h (gnatdll)
+
+@item @code{-h}
+
+Help mode. Displays @code{gnatdll} switch usage information.
+
+@geindex -I (gnatdll)
+
+@item @code{-I`dir'}
+
+Direct @code{gnatdll} to search the @code{dir} directory for source and
+object files needed to build the DLL.
+(@ref{73,,Search Paths and the Run-Time Library (RTL)}).
+
+@geindex -k (gnatdll)
+
+@item @code{-k}
+
+Removes the @code{@@@var{nn}} suffix from the import library’s exported
+names, but keeps them for the link names. You must specify this
+option if you want to use a @code{Stdcall} function in a DLL for which
+the @code{@@@var{nn}} suffix has been removed. This is the case for most
+of the Windows NT DLL for example. This option has no effect when
+@code{-n} option is specified.
+
+@geindex -l (gnatdll)
+
+@item @code{-l `file'}
+
+The list of ALI and object files used to build the DLL are listed in
+@code{file}, instead of being given in the command line. Each line in
+@code{file} contains the name of an ALI or object file.
+
+@geindex -n (gnatdll)
+
+@item @code{-n}
+
+No Import. Do not create the import library.
+
+@geindex -q (gnatdll)
+
+@item @code{-q}
+
+Quiet mode. Do not display unnecessary messages.
+
+@geindex -v (gnatdll)
+
+@item @code{-v}
+
+Verbose mode. Display extra information.
+
+@geindex -largs (gnatdll)
+
+@item @code{-largs `opts'}
+
+Linker options. Pass @code{opts} to the linker.
+@end table
+
+@subsubheading @code{gnatdll} Example
+
+
+As an example the command to build a relocatable DLL from @code{api.adb}
+once @code{api.adb} has been compiled and @code{api.def} created is
+
+@quotation
+
+@example
+$ gnatdll -d api.dll api.ali
+@end example
+@end quotation
+
+The above command creates two files: @code{libapi.dll.a} (the import
+library) and @code{api.dll} (the actual DLL). If you want to create
+only the DLL, just type:
+
+@quotation
+
+@example
+$ gnatdll -d api.dll -n api.ali
+@end example
+@end quotation
+
+Alternatively if you want to create just the import library, type:
+
+@quotation
+
+@example
+$ gnatdll -d api.dll
+@end example
+@end quotation
+
+@subsubheading @code{gnatdll} behind the Scenes
+
+
+This section details the steps involved in creating a DLL. @code{gnatdll}
+does these steps for you. Unless you are interested in understanding what
+goes on behind the scenes, you should skip this section.
+
+We use the previous example of a DLL containing the Ada package @code{API},
+to illustrate the steps necessary to build a DLL. The starting point is a
+set of objects that will make up the DLL and the corresponding ALI
+files. In the case of this example this means that @code{api.o} and
+@code{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does
+the following:
+
+
+@itemize *
+
+@item
+@code{gnatdll} builds the base file (@code{api.base}). A base file gives
+the information necessary to generate relocation information for the
+DLL.
+
+@example
+$ gnatbind -n api
+$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
+@end example
+
+In addition to the base file, the @code{gnatlink} command generates an
+output file @code{api.jnk} which can be discarded. The @code{-mdll} switch
+asks @code{gnatlink} to generate the routines @code{DllMain} and
+@code{DllMainCRTStartup} that are called by the Windows loader when the DLL
+is loaded into memory.
+
+@item
+@code{gnatdll} uses @code{dlltool} (see @ref{1f8,,Using dlltool}) to build the
+export table (@code{api.exp}). The export table contains the relocation
+information in a form which can be used during the final link to ensure
+that the Windows loader is able to place the DLL anywhere in memory.
+
+@example
+$ dlltool --dllname api.dll --def api.def --base-file api.base \\
+ --output-exp api.exp
+@end example
+
+@item
+@code{gnatdll} builds the base file using the new export table. Note that
+@code{gnatbind} must be called once again since the binder generated file
+has been deleted during the previous call to @code{gnatlink}.
+
+@example
+$ gnatbind -n api
+$ gnatlink api -o api.jnk api.exp -mdll
+ -Wl,--base-file,api.base
+@end example
+
+@item
+@code{gnatdll} builds the new export table using the new base file and
+generates the DLL import library @code{libAPI.dll.a}.
+
+@example
+$ dlltool --dllname api.dll --def api.def --base-file api.base \\
+ --output-exp api.exp --output-lib libAPI.a
+@end example
+
+@item
+Finally @code{gnatdll} builds the relocatable DLL using the final export
+table.
+
+@example
+$ gnatbind -n api
+$ gnatlink api api.exp -o api.dll -mdll
+@end example
+@end itemize
+@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{1f8}
+@subsubheading Using @code{dlltool}
+
+
+@code{dlltool} is the low-level tool used by @code{gnatdll} to build
+DLLs and static import libraries. This section summarizes the most
+common @code{dlltool} switches. The form of the @code{dlltool} command
+is
+
+@quotation
+
+@example
+$ dlltool [`switches`]
+@end example
+@end quotation
+
+@code{dlltool} switches include:
+
+@geindex --base-file (dlltool)
+
+
+@table @asis
+
+@item @code{--base-file `basefile'}
+
+Read the base file @code{basefile} generated by the linker. This switch
+is used to create a relocatable DLL.
+@end table
+
+@geindex --def (dlltool)
+
+
+@table @asis
+
+@item @code{--def `deffile'}
+
+Read the definition file.
+@end table
+
+@geindex --dllname (dlltool)
+
+
+@table @asis
+
+@item @code{--dllname `name'}
+
+Gives the name of the DLL. This switch is used to embed the name of the
+DLL in the static import library generated by @code{dlltool} with switch
+@code{--output-lib}.
+@end table
+
+@geindex -k (dlltool)
+
+
+@table @asis
+
+@item @code{-k}
+
+Kill @code{@@@var{nn}} from exported names
+(@ref{1d2,,Windows Calling Conventions}
+for a discussion about @code{Stdcall}-style symbols).
+@end table
+
+@geindex --help (dlltool)
+
+
+@table @asis
+
+@item @code{--help}
+
+Prints the @code{dlltool} switches with a concise description.
+@end table
+
+@geindex --output-exp (dlltool)
+
+
+@table @asis
+
+@item @code{--output-exp `exportfile'}
+
+Generate an export file @code{exportfile}. The export file contains the
+export table (list of symbols in the DLL) and is used to create the DLL.
+@end table
+
+@geindex --output-lib (dlltool)
+
+
+@table @asis
+
+@item @code{--output-lib `libfile'}
+
+Generate a static import library @code{libfile}.
+@end table
+
+@geindex -v (dlltool)
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose mode.
+@end table
+
+@geindex --as (dlltool)
+
+
+@table @asis
+
+@item @code{--as `assembler-name'}
+
+Use @code{assembler-name} as the assembler. The default is @code{as}.
+@end table
+
+@node GNAT and Windows Resources,Using GNAT DLLs from Microsoft Visual Studio Applications,Creating a Spec for Ada DLLs,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information id33}@anchor{1fa}
+@subsubsection GNAT and Windows Resources
+
+
+@geindex Resources
+@geindex windows
+
+Resources are an easy way to add Windows specific objects to your
+application. The objects that can be added as resources include:
+
+
+@itemize *
+
+@item
+menus
+
+@item
+accelerators
+
+@item
+dialog boxes
+
+@item
+string tables
+
+@item
+bitmaps
+
+@item
+cursors
+
+@item
+icons
+
+@item
+fonts
+
+@item
+version information
+@end itemize
+
+For example, a version information resource can be defined as follow and
+embedded into an executable or DLL:
+
+A version information resource can be used to embed information into an
+executable or a DLL. These information can be viewed using the file properties
+from the Windows Explorer. Here is an example of a version information
+resource:
+
+@quotation
+
+@example
+1 VERSIONINFO
+FILEVERSION 1,0,0,0
+PRODUCTVERSION 1,0,0,0
+BEGIN
+ BLOCK "StringFileInfo"
+ BEGIN
+ BLOCK "080904E4"
+ BEGIN
+ VALUE "CompanyName", "My Company Name"
+ VALUE "FileDescription", "My application"
+ VALUE "FileVersion", "1.0"
+ VALUE "InternalName", "my_app"
+ VALUE "LegalCopyright", "My Name"
+ VALUE "OriginalFilename", "my_app.exe"
+ VALUE "ProductName", "My App"
+ VALUE "ProductVersion", "1.0"
+ END
+ END
+
+ BLOCK "VarFileInfo"
+ BEGIN
+ VALUE "Translation", 0x809, 1252
+ END
+END
+@end example
+@end quotation
+
+The value @code{0809} (langID) is for the U.K English language and
+@code{04E4} (charsetID), which is equal to @code{1252} decimal, for
+multilingual.
+
+This section explains how to build, compile and use resources. Note that this
+section does not cover all resource objects, for a complete description see
+the corresponding Microsoft documentation.
+
+@menu
+* Building Resources::
+* Compiling Resources::
+* Using Resources::
+
+@end menu
+
+@node Building Resources,Compiling Resources,,GNAT and Windows Resources
+@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information id34}@anchor{1fc}
+@subsubsection Building Resources
+
+
+@geindex Resources
+@geindex building
+
+A resource file is an ASCII file. By convention resource files have an
+@code{.rc} extension.
+The easiest way to build a resource file is to use Microsoft tools
+such as @code{imagedit.exe} to build bitmaps, icons and cursors and
+@code{dlgedit.exe} to build dialogs.
+It is always possible to build an @code{.rc} file yourself by writing a
+resource script.
+
+It is not our objective to explain how to write a resource file. A
+complete description of the resource script language can be found in the
+Microsoft documentation.
+
+@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources
+@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{1fd}@anchor{gnat_ugn/platform_specific_information id35}@anchor{1fe}
+@subsubsection Compiling Resources
+
+
+@geindex rc
+
+@geindex windres
+
+@geindex Resources
+@geindex compiling
+
+This section describes how to build a GNAT-compatible (COFF) object file
+containing the resources. This is done using the Resource Compiler
+@code{windres} as follows:
+
+@quotation
+
+@example
+$ windres -i myres.rc -o myres.o
+@end example
+@end quotation
+
+By default @code{windres} will run @code{gcc} to preprocess the @code{.rc}
+file. You can specify an alternate preprocessor (usually named
+@code{cpp.exe}) using the @code{windres} @code{--preprocessor}
+parameter. A list of all possible options may be obtained by entering
+the command @code{windres} @code{--help}.
+
+It is also possible to use the Microsoft resource compiler @code{rc.exe}
+to produce a @code{.res} file (binary resource file). See the
+corresponding Microsoft documentation for further details. In this case
+you need to use @code{windres} to translate the @code{.res} file to a
+GNAT-compatible object file as follows:
+
+@quotation
+
+@example
+$ windres -i myres.res -o myres.o
+@end example
+@end quotation
+
+@node Using Resources,,Compiling Resources,GNAT and Windows Resources
+@anchor{gnat_ugn/platform_specific_information id36}@anchor{1ff}@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{200}
+@subsubsection Using Resources
+
+
+@geindex Resources
+@geindex using
+
+To include the resource file in your program just add the
+GNAT-compatible object file for the resource(s) to the linker
+arguments. With @code{gnatmake} this is done by using the @code{-largs}
+option:
+
+@quotation
+
+@example
+$ gnatmake myprog -largs myres.o
+@end example
+@end quotation
+
+@node Using GNAT DLLs from Microsoft Visual Studio Applications,Debugging a DLL,GNAT and Windows Resources,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{201}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{202}
+@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications
+
+
+@geindex Microsoft Visual Studio
+@geindex use with GNAT DLLs
+
+This section describes a common case of mixed GNAT/Microsoft Visual Studio
+application development, where the main program is developed using MSVS, and
+is linked with a DLL developed using GNAT. Such a mixed application should
+be developed following the general guidelines outlined above; below is the
+cookbook-style sequence of steps to follow:
+
+
+@enumerate
+
+@item
+First develop and build the GNAT shared library using a library project
+(let’s assume the project is @code{mylib.gpr}, producing the library @code{libmylib.dll}):
+@end enumerate
+
+@quotation
+
+@example
+$ gprbuild -p mylib.gpr
+@end example
+@end quotation
+
+
+@enumerate 2
+
+@item
+Produce a .def file for the symbols you need to interface with, either by
+hand or automatically with possibly some manual adjustments
+(see @ref{1e3,,Creating Definition File Automatically}):
+@end enumerate
+
+@quotation
+
+@example
+$ dlltool libmylib.dll -z libmylib.def --export-all-symbols
+@end example
+@end quotation
+
+
+@enumerate 3
+
+@item
+Make sure that MSVS command-line tools are accessible on the path.
+
+@item
+Create the Microsoft-style import library (see @ref{1e6,,MSVS-Style Import Library}):
+@end enumerate
+
+@quotation
+
+@example
+$ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib
+@end example
+@end quotation
+
+If you are using a 64-bit toolchain, the above becomes…
+
+@quotation
+
+@example
+$ lib -machine:X64 -def:libmylib.def -out:libmylib.lib
+@end example
+@end quotation
+
+
+@enumerate 5
+
+@item
+Build the C main
+@end enumerate
+
+@quotation
+
+@example
+$ cl /O2 /MD main.c libmylib.lib
+@end example
+@end quotation
+
+
+@enumerate 6
+
+@item
+Before running the executable, make sure you have set the PATH to the DLL,
+or copy the DLL into into the directory containing the .exe.
+@end enumerate
+
+@node Debugging a DLL,Setting Stack Size from gnatlink,Using GNAT DLLs from Microsoft Visual Studio Applications,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{203}@anchor{gnat_ugn/platform_specific_information id37}@anchor{204}
+@subsubsection Debugging a DLL
+
+
+@geindex DLL debugging
+
+Debugging a DLL is similar to debugging a standard program. But
+we have to deal with two different executable parts: the DLL and the
+program that uses it. We have the following four possibilities:
+
+
+@itemize *
+
+@item
+The program and the DLL are built with GCC/GNAT.
+
+@item
+The program is built with foreign tools and the DLL is built with
+GCC/GNAT.
+
+@item
+The program is built with GCC/GNAT and the DLL is built with
+foreign tools.
+@end itemize
+
+In this section we address only cases one and two above.
+There is no point in trying to debug
+a DLL with GNU/GDB, if there is no GDB-compatible debugging
+information in it. To do so you must use a debugger compatible with the
+tools suite used to build the DLL.
+
+@menu
+* Program and DLL Both Built with GCC/GNAT::
+* Program Built with Foreign Tools and DLL Built with GCC/GNAT::
+
+@end menu
+
+@node Program and DLL Both Built with GCC/GNAT,Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Debugging a DLL
+@anchor{gnat_ugn/platform_specific_information id38}@anchor{205}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{206}
+@subsubsection Program and DLL Both Built with GCC/GNAT
+
+
+This is the simplest case. Both the DLL and the program have @code{GDB}
+compatible debugging information. It is then possible to break anywhere in
+the process. Let’s suppose here that the main procedure is named
+@code{ada_main} and that in the DLL there is an entry point named
+@code{ada_dll}.
+
+The DLL (@ref{1dc,,Introduction to Dynamic Link Libraries (DLLs)}) and
+program must have been built with the debugging information (see GNAT -g
+switch). Here are the step-by-step instructions for debugging it:
+
+
+@itemize *
+
+@item
+Launch @code{GDB} on the main program.
+
+@example
+$ gdb -nw ada_main
+@end example
+
+@item
+Start the program and stop at the beginning of the main procedure
+
+@example
+(gdb) start
+@end example
+
+This step is required to be able to set a breakpoint inside the DLL. As long
+as the program is not run, the DLL is not loaded. This has the
+consequence that the DLL debugging information is also not loaded, so it is not
+possible to set a breakpoint in the DLL.
+
+@item
+Set a breakpoint inside the DLL
+
+@example
+(gdb) break ada_dll
+(gdb) cont
+@end example
+@end itemize
+
+At this stage a breakpoint is set inside the DLL. From there on
+you can use the standard approach to debug the whole program
+(@ref{14d,,Running and Debugging Ada Programs}).
+
+@node Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Program and DLL Both Built with GCC/GNAT,Debugging a DLL
+@anchor{gnat_ugn/platform_specific_information id39}@anchor{207}@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{208}
+@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT
+
+
+In this case things are slightly more complex because it is not possible to
+start the main program and then break at the beginning to load the DLL and the
+associated DLL debugging information. It is not possible to break at the
+beginning of the program because there is no @code{GDB} debugging information,
+and therefore there is no direct way of getting initial control. This
+section addresses this issue by describing some methods that can be used
+to break somewhere in the DLL to debug it.
+
+First suppose that the main procedure is named @code{main} (this is for
+example some C code built with Microsoft Visual C) and that there is a
+DLL named @code{test.dll} containing an Ada entry point named
+@code{ada_dll}.
+
+The DLL (see @ref{1dc,,Introduction to Dynamic Link Libraries (DLLs)}) must have
+been built with debugging information (see the GNAT @code{-g} option).
+
+@subsubheading Debugging the DLL Directly
+
+
+
+@itemize *
+
+@item
+Find out the executable starting address
+
+@example
+$ objdump --file-header main.exe
+@end example
+
+The starting address is reported on the last line. For example:
+
+@example
+main.exe: file format pei-i386
+architecture: i386, flags 0x0000010a:
+EXEC_P, HAS_DEBUG, D_PAGED
+start address 0x00401010
+@end example
+
+@item
+Launch the debugger on the executable.
+
+@example
+$ gdb main.exe
+@end example
+
+@item
+Set a breakpoint at the starting address, and launch the program.
+
+@example
+$ (gdb) break *0x00401010
+$ (gdb) run
+@end example
+
+The program will stop at the given address.
+
+@item
+Set a breakpoint on a DLL subroutine.
+
+@example
+(gdb) break ada_dll.adb:45
+@end example
+
+Or if you want to break using a symbol on the DLL, you need first to
+select the Ada language (language used by the DLL).
+
+@example
+(gdb) set language ada
+(gdb) break ada_dll
+@end example
+
+@item
+Continue the program.
+
+@example
+(gdb) cont
+@end example
+
+This will run the program until it reaches the breakpoint that has been
+set. From that point you can use the standard way to debug a program
+as described in (@ref{14d,,Running and Debugging Ada Programs}).
+@end itemize
+
+It is also possible to debug the DLL by attaching to a running process.
+
+@subsubheading Attaching to a Running Process
+
+
+@geindex DLL debugging
+@geindex attach to process
+
+With @code{GDB} it is always possible to debug a running process by
+attaching to it. It is possible to debug a DLL this way. The limitation
+of this approach is that the DLL must run long enough to perform the
+attach operation. It may be useful for instance to insert a time wasting
+loop in the code of the DLL to meet this criterion.
+
+
+@itemize *
+
+@item
+Launch the main program @code{main.exe}.
+
+@example
+$ main
+@end example
+
+@item
+Use the Windows `Task Manager' to find the process ID. Let’s say
+that the process PID for @code{main.exe} is 208.
+
+@item
+Launch gdb.
+
+@example
+$ gdb
+@end example
+
+@item
+Attach to the running process to be debugged.
+
+@example
+(gdb) attach 208
+@end example
+
+@item
+Load the process debugging information.
+
+@example
+(gdb) symbol-file main.exe
+@end example
+
+@item
+Break somewhere in the DLL.
+
+@example
+(gdb) break ada_dll
+@end example
+
+@item
+Continue process execution.
+
+@example
+(gdb) cont
+@end example
+@end itemize
+
+This last step will resume the process execution, and stop at
+the breakpoint we have set. From there you can use the standard
+approach to debug a program as described in
+@ref{14d,,Running and Debugging Ada Programs}.
+
+@node Setting Stack Size from gnatlink,Setting Heap Size from gnatlink,Debugging a DLL,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information id40}@anchor{209}@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{127}
+@subsubsection Setting Stack Size from @code{gnatlink}
+
+
+It is possible to specify the program stack size at link time. On modern
+versions of Windows, starting with XP, this is mostly useful to set the size of
+the main stack (environment task). The other task stacks are set with pragma
+Storage_Size or with the `gnatbind -d' command.
+
+Since older versions of Windows (2000, NT4, etc.) do not allow setting the
+reserve size of individual tasks, the link-time stack size applies to all
+tasks, and pragma Storage_Size has no effect.
+In particular, Stack Overflow checks are made against this
+link-time specified size.
+
+This setting can be done with @code{gnatlink} using either of the following:
+
+
+@itemize *
+
+@item
+@code{-Xlinker} linker option
+
+@example
+$ gnatlink hello -Xlinker --stack=0x10000,0x1000
+@end example
+
+This sets the stack reserve size to 0x10000 bytes and the stack commit
+size to 0x1000 bytes.
+
+@item
+@code{-Wl} linker option
+
+@example
+$ gnatlink hello -Wl,--stack=0x1000000
+@end example
+
+This sets the stack reserve size to 0x1000000 bytes. Note that with
+@code{-Wl} option it is not possible to set the stack commit size
+because the comma is a separator for this option.
+@end itemize
+
+@node Setting Heap Size from gnatlink,,Setting Stack Size from gnatlink,Mixed-Language Programming on Windows
+@anchor{gnat_ugn/platform_specific_information id41}@anchor{20a}@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{128}
+@subsubsection Setting Heap Size from @code{gnatlink}
+
+
+Under Windows systems, it is possible to specify the program heap size from
+@code{gnatlink} using either of the following:
+
+
+@itemize *
+
+@item
+@code{-Xlinker} linker option
+
+@example
+$ gnatlink hello -Xlinker --heap=0x10000,0x1000
+@end example
+
+This sets the heap reserve size to 0x10000 bytes and the heap commit
+size to 0x1000 bytes.
+
+@item
+@code{-Wl} linker option
+
+@example
+$ gnatlink hello -Wl,--heap=0x1000000
+@end example
+
+This sets the heap reserve size to 0x1000000 bytes. Note that with
+@code{-Wl} option it is not possible to set the heap commit size
+because the comma is a separator for this option.
+@end itemize
+
+@node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{20b}@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{20c}
+@subsection Windows Specific Add-Ons
+
+
+This section describes the Windows specific add-ons.
+
+@menu
+* Win32Ada::
+* wPOSIX::
+
+@end menu
+
+@node Win32Ada,wPOSIX,,Windows Specific Add-Ons
+@anchor{gnat_ugn/platform_specific_information id42}@anchor{20d}@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{20e}
+@subsubsection Win32Ada
+
+
+Win32Ada is a binding for the Microsoft Win32 API. This binding can be
+easily installed from the provided installer. To use the Win32Ada
+binding you need to use a project file, and adding a single with_clause
+will give you full access to the Win32Ada binding sources and ensure
+that the proper libraries are passed to the linker.
+
+@quotation
+
+@example
+with "win32ada";
+project P is
+ for Sources use ...;
+end P;
+@end example
+@end quotation
+
+To build the application you just need to call gprbuild for the
+application’s project, here p.gpr:
+
+@quotation
+
+@example
+gprbuild p.gpr
+@end example
+@end quotation
+
+@node wPOSIX,,Win32Ada,Windows Specific Add-Ons
+@anchor{gnat_ugn/platform_specific_information id43}@anchor{20f}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{210}
+@subsubsection wPOSIX
+
+
+wPOSIX is a minimal POSIX binding whose goal is to help with building
+cross-platforms applications. This binding is not complete though, as
+the Win32 API does not provide the necessary support for all POSIX APIs.
+
+To use the wPOSIX binding you need to use a project file, and adding
+a single with_clause will give you full access to the wPOSIX binding
+sources and ensure that the proper libraries are passed to the linker.
+
+@quotation
+
+@example
+with "wposix";
+project P is
+ for Sources use ...;
+end P;
+@end example
+@end quotation
+
+To build the application you just need to call gprbuild for the
+application’s project, here p.gpr:
+
+@quotation
+
+@example
+gprbuild p.gpr
+@end example
+@end quotation
+
+@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information id44}@anchor{211}@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{212}
+@section Mac OS Topics
+
+
+@geindex OS X
+
+This section describes topics that are specific to Apple’s OS X
+platform.
+
+@menu
+* Codesigning the Debugger::
+
+@end menu
+
+@node Codesigning the Debugger,,,Mac OS Topics
+@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{213}
+@subsection Codesigning the Debugger
+
+
+The Darwin Kernel requires the debugger to have special permissions
+before it is allowed to control other processes. These permissions
+are granted by codesigning the GDB executable. Without these
+permissions, the debugger will report error messages such as:
+
+@example
+Starting program: /x/y/foo
+Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5).
+(please check gdb is codesigned - see taskgated(8))
+@end example
+
+Codesigning requires a certificate. The following procedure explains
+how to create one:
+
+
+@itemize *
+
+@item
+Start the Keychain Access application (in
+/Applications/Utilities/Keychain Access.app)
+
+@item
+Select the Keychain Access -> Certificate Assistant ->
+Create a Certificate… menu
+
+@item
+Then:
+
+
+@itemize *
+
+@item
+Choose a name for the new certificate (this procedure will use
+“gdb-cert” as an example)
+
+@item
+Set “Identity Type” to “Self Signed Root”
+
+@item
+Set “Certificate Type” to “Code Signing”
+
+@item
+Activate the “Let me override defaults” option
+@end itemize
+
+@item
+Click several times on “Continue” until the “Specify a Location
+For The Certificate” screen appears, then set “Keychain” to “System”
+
+@item
+Click on “Continue” until the certificate is created
+
+@item
+Finally, in the view, double-click on the new certificate,
+and set “When using this certificate” to “Always Trust”
+
+@item
+Exit the Keychain Access application and restart the computer
+(this is unfortunately required)
+@end itemize
+
+Once a certificate has been created, the debugger can be codesigned
+as follow. In a Terminal, run the following command:
+
+@quotation
+
+@example
+$ codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb
+@end example
+@end quotation
+
+where “gdb-cert” should be replaced by the actual certificate
+name chosen above, and <gnat_install_prefix> should be replaced by
+the location where you installed GNAT. Also, be sure that users are
+in the Unix group @code{_developer}.
+
+@node Example of Binder Output File,Elaboration Order Handling in GNAT,Platform-Specific Information,Top
+@anchor{gnat_ugn/example_of_binder_output doc}@anchor{214}@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{215}
+@chapter Example of Binder Output File
+
+
+@geindex Binder output (example)
+
+This Appendix displays the source code for the output file
+generated by `gnatbind' for a simple ‘Hello World’ program.
+Comments have been added for clarification purposes.
+
+@example
+-- The package is called Ada_Main unless this name is actually used
+-- as a unit name in the partition, in which case some other unique
+-- name is used.
+
+pragma Ada_95;
+with System;
+package ada_main is
+ pragma Warnings (Off);
+
+ -- The main program saves the parameters (argument count,
+ -- argument values, environment pointer) in global variables
+ -- for later access by other units including
+ -- Ada.Command_Line.
+
+ gnat_argc : Integer;
+ gnat_argv : System.Address;
+ gnat_envp : System.Address;
+
+ -- The actual variables are stored in a library routine. This
+ -- is useful for some shared library situations, where there
+ -- are problems if variables are not in the library.
+
+ pragma Import (C, gnat_argc);
+ pragma Import (C, gnat_argv);
+ pragma Import (C, gnat_envp);
+
+ -- The exit status is similarly an external location
+
+ gnat_exit_status : Integer;
+ pragma Import (C, gnat_exit_status);
+
+ GNAT_Version : constant String :=
+ "GNAT Version: Pro 7.4.0w (20141119-49)" & ASCII.NUL;
+ pragma Export (C, GNAT_Version, "__gnat_version");
+
+ Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL;
+ pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name");
+
+ -- This is the generated adainit routine that performs
+ -- initialization at the start of execution. In the case
+ -- where Ada is the main program, this main program makes
+ -- a call to adainit at program startup.
+
+ procedure adainit;
+ pragma Export (C, adainit, "adainit");
+
+ -- This is the generated adafinal routine that performs
+ -- finalization at the end of execution. In the case where
+ -- Ada is the main program, this main program makes a call
+ -- to adafinal at program termination.
+
+ procedure adafinal;
+ pragma Export (C, adafinal, "adafinal");
+
+ -- This routine is called at the start of execution. It is
+ -- a dummy routine that is used by the debugger to breakpoint
+ -- at the start of execution.
+
+ -- This is the actual generated main program (it would be
+ -- suppressed if the no main program switch were used). As
+ -- required by standard system conventions, this program has
+ -- the external name main.
+
+ function main
+ (argc : Integer;
+ argv : System.Address;
+ envp : System.Address)
+ return Integer;
+ pragma Export (C, main, "main");
+
+ -- The following set of constants give the version
+ -- identification values for every unit in the bound
+ -- partition. This identification is computed from all
+ -- dependent semantic units, and corresponds to the
+ -- string that would be returned by use of the
+ -- Body_Version or Version attributes.
+
+ -- The following Export pragmas export the version numbers
+ -- with symbolic names ending in B (for body) or S
+ -- (for spec) so that they can be located in a link. The
+ -- information provided here is sufficient to track down
+ -- the exact versions of units used in a given build.
+
+ type Version_32 is mod 2 ** 32;
+ u00001 : constant Version_32 := 16#8ad6e54a#;
+ pragma Export (C, u00001, "helloB");
+ u00002 : constant Version_32 := 16#fbff4c67#;
+ pragma Export (C, u00002, "system__standard_libraryB");
+ u00003 : constant Version_32 := 16#1ec6fd90#;
+ pragma Export (C, u00003, "system__standard_libraryS");
+ u00004 : constant Version_32 := 16#3ffc8e18#;
+ pragma Export (C, u00004, "adaS");
+ u00005 : constant Version_32 := 16#28f088c2#;
+ pragma Export (C, u00005, "ada__text_ioB");
+ u00006 : constant Version_32 := 16#f372c8ac#;
+ pragma Export (C, u00006, "ada__text_ioS");
+ u00007 : constant Version_32 := 16#2c143749#;
+ pragma Export (C, u00007, "ada__exceptionsB");
+ u00008 : constant Version_32 := 16#f4f0cce8#;
+ pragma Export (C, u00008, "ada__exceptionsS");
+ u00009 : constant Version_32 := 16#a46739c0#;
+ pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB");
+ u00010 : constant Version_32 := 16#3aac8c92#;
+ pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS");
+ u00011 : constant Version_32 := 16#1d274481#;
+ pragma Export (C, u00011, "systemS");
+ u00012 : constant Version_32 := 16#a207fefe#;
+ pragma Export (C, u00012, "system__soft_linksB");
+ u00013 : constant Version_32 := 16#467d9556#;
+ pragma Export (C, u00013, "system__soft_linksS");
+ u00014 : constant Version_32 := 16#b01dad17#;
+ pragma Export (C, u00014, "system__parametersB");
+ u00015 : constant Version_32 := 16#630d49fe#;
+ pragma Export (C, u00015, "system__parametersS");
+ u00016 : constant Version_32 := 16#b19b6653#;
+ pragma Export (C, u00016, "system__secondary_stackB");
+ u00017 : constant Version_32 := 16#b6468be8#;
+ pragma Export (C, u00017, "system__secondary_stackS");
+ u00018 : constant Version_32 := 16#39a03df9#;
+ pragma Export (C, u00018, "system__storage_elementsB");
+ u00019 : constant Version_32 := 16#30e40e85#;
+ pragma Export (C, u00019, "system__storage_elementsS");
+ u00020 : constant Version_32 := 16#41837d1e#;
+ pragma Export (C, u00020, "system__stack_checkingB");
+ u00021 : constant Version_32 := 16#93982f69#;
+ pragma Export (C, u00021, "system__stack_checkingS");
+ u00022 : constant Version_32 := 16#393398c1#;
+ pragma Export (C, u00022, "system__exception_tableB");
+ u00023 : constant Version_32 := 16#b33e2294#;
+ pragma Export (C, u00023, "system__exception_tableS");
+ u00024 : constant Version_32 := 16#ce4af020#;
+ pragma Export (C, u00024, "system__exceptionsB");
+ u00025 : constant Version_32 := 16#75442977#;
+ pragma Export (C, u00025, "system__exceptionsS");
+ u00026 : constant Version_32 := 16#37d758f1#;
+ pragma Export (C, u00026, "system__exceptions__machineS");
+ u00027 : constant Version_32 := 16#b895431d#;
+ pragma Export (C, u00027, "system__exceptions_debugB");
+ u00028 : constant Version_32 := 16#aec55d3f#;
+ pragma Export (C, u00028, "system__exceptions_debugS");
+ u00029 : constant Version_32 := 16#570325c8#;
+ pragma Export (C, u00029, "system__img_intB");
+ u00030 : constant Version_32 := 16#1ffca443#;
+ pragma Export (C, u00030, "system__img_intS");
+ u00031 : constant Version_32 := 16#b98c3e16#;
+ pragma Export (C, u00031, "system__tracebackB");
+ u00032 : constant Version_32 := 16#831a9d5a#;
+ pragma Export (C, u00032, "system__tracebackS");
+ u00033 : constant Version_32 := 16#9ed49525#;
+ pragma Export (C, u00033, "system__traceback_entriesB");
+ u00034 : constant Version_32 := 16#1d7cb2f1#;
+ pragma Export (C, u00034, "system__traceback_entriesS");
+ u00035 : constant Version_32 := 16#8c33a517#;
+ pragma Export (C, u00035, "system__wch_conB");
+ u00036 : constant Version_32 := 16#065a6653#;
+ pragma Export (C, u00036, "system__wch_conS");
+ u00037 : constant Version_32 := 16#9721e840#;
+ pragma Export (C, u00037, "system__wch_stwB");
+ u00038 : constant Version_32 := 16#2b4b4a52#;
+ pragma Export (C, u00038, "system__wch_stwS");
+ u00039 : constant Version_32 := 16#92b797cb#;
+ pragma Export (C, u00039, "system__wch_cnvB");
+ u00040 : constant Version_32 := 16#09eddca0#;
+ pragma Export (C, u00040, "system__wch_cnvS");
+ u00041 : constant Version_32 := 16#6033a23f#;
+ pragma Export (C, u00041, "interfacesS");
+ u00042 : constant Version_32 := 16#ece6fdb6#;
+ pragma Export (C, u00042, "system__wch_jisB");
+ u00043 : constant Version_32 := 16#899dc581#;
+ pragma Export (C, u00043, "system__wch_jisS");
+ u00044 : constant Version_32 := 16#10558b11#;
+ pragma Export (C, u00044, "ada__streamsB");
+ u00045 : constant Version_32 := 16#2e6701ab#;
+ pragma Export (C, u00045, "ada__streamsS");
+ u00046 : constant Version_32 := 16#db5c917c#;
+ pragma Export (C, u00046, "ada__io_exceptionsS");
+ u00047 : constant Version_32 := 16#12c8cd7d#;
+ pragma Export (C, u00047, "ada__tagsB");
+ u00048 : constant Version_32 := 16#ce72c228#;
+ pragma Export (C, u00048, "ada__tagsS");
+ u00049 : constant Version_32 := 16#c3335bfd#;
+ pragma Export (C, u00049, "system__htableB");
+ u00050 : constant Version_32 := 16#99e5f76b#;
+ pragma Export (C, u00050, "system__htableS");
+ u00051 : constant Version_32 := 16#089f5cd0#;
+ pragma Export (C, u00051, "system__string_hashB");
+ u00052 : constant Version_32 := 16#3bbb9c15#;
+ pragma Export (C, u00052, "system__string_hashS");
+ u00053 : constant Version_32 := 16#807fe041#;
+ pragma Export (C, u00053, "system__unsigned_typesS");
+ u00054 : constant Version_32 := 16#d27be59e#;
+ pragma Export (C, u00054, "system__val_lluB");
+ u00055 : constant Version_32 := 16#fa8db733#;
+ pragma Export (C, u00055, "system__val_lluS");
+ u00056 : constant Version_32 := 16#27b600b2#;
+ pragma Export (C, u00056, "system__val_utilB");
+ u00057 : constant Version_32 := 16#b187f27f#;
+ pragma Export (C, u00057, "system__val_utilS");
+ u00058 : constant Version_32 := 16#d1060688#;
+ pragma Export (C, u00058, "system__case_utilB");
+ u00059 : constant Version_32 := 16#392e2d56#;
+ pragma Export (C, u00059, "system__case_utilS");
+ u00060 : constant Version_32 := 16#84a27f0d#;
+ pragma Export (C, u00060, "interfaces__c_streamsB");
+ u00061 : constant Version_32 := 16#8bb5f2c0#;
+ pragma Export (C, u00061, "interfaces__c_streamsS");
+ u00062 : constant Version_32 := 16#6db6928f#;
+ pragma Export (C, u00062, "system__crtlS");
+ u00063 : constant Version_32 := 16#4e6a342b#;
+ pragma Export (C, u00063, "system__file_ioB");
+ u00064 : constant Version_32 := 16#ba56a5e4#;
+ pragma Export (C, u00064, "system__file_ioS");
+ u00065 : constant Version_32 := 16#b7ab275c#;
+ pragma Export (C, u00065, "ada__finalizationB");
+ u00066 : constant Version_32 := 16#19f764ca#;
+ pragma Export (C, u00066, "ada__finalizationS");
+ u00067 : constant Version_32 := 16#95817ed8#;
+ pragma Export (C, u00067, "system__finalization_rootB");
+ u00068 : constant Version_32 := 16#52d53711#;
+ pragma Export (C, u00068, "system__finalization_rootS");
+ u00069 : constant Version_32 := 16#769e25e6#;
+ pragma Export (C, u00069, "interfaces__cB");
+ u00070 : constant Version_32 := 16#4a38bedb#;
+ pragma Export (C, u00070, "interfaces__cS");
+ u00071 : constant Version_32 := 16#07e6ee66#;
+ pragma Export (C, u00071, "system__os_libB");
+ u00072 : constant Version_32 := 16#d7b69782#;
+ pragma Export (C, u00072, "system__os_libS");
+ u00073 : constant Version_32 := 16#1a817b8e#;
+ pragma Export (C, u00073, "system__stringsB");
+ u00074 : constant Version_32 := 16#639855e7#;
+ pragma Export (C, u00074, "system__stringsS");
+ u00075 : constant Version_32 := 16#e0b8de29#;
+ pragma Export (C, u00075, "system__file_control_blockS");
+ u00076 : constant Version_32 := 16#b5b2aca1#;
+ pragma Export (C, u00076, "system__finalization_mastersB");
+ u00077 : constant Version_32 := 16#69316dc1#;
+ pragma Export (C, u00077, "system__finalization_mastersS");
+ u00078 : constant Version_32 := 16#57a37a42#;
+ pragma Export (C, u00078, "system__address_imageB");
+ u00079 : constant Version_32 := 16#bccbd9bb#;
+ pragma Export (C, u00079, "system__address_imageS");
+ u00080 : constant Version_32 := 16#7268f812#;
+ pragma Export (C, u00080, "system__img_boolB");
+ u00081 : constant Version_32 := 16#e8fe356a#;
+ pragma Export (C, u00081, "system__img_boolS");
+ u00082 : constant Version_32 := 16#d7aac20c#;
+ pragma Export (C, u00082, "system__ioB");
+ u00083 : constant Version_32 := 16#8365b3ce#;
+ pragma Export (C, u00083, "system__ioS");
+ u00084 : constant Version_32 := 16#6d4d969a#;
+ pragma Export (C, u00084, "system__storage_poolsB");
+ u00085 : constant Version_32 := 16#e87cc305#;
+ pragma Export (C, u00085, "system__storage_poolsS");
+ u00086 : constant Version_32 := 16#e34550ca#;
+ pragma Export (C, u00086, "system__pool_globalB");
+ u00087 : constant Version_32 := 16#c88d2d16#;
+ pragma Export (C, u00087, "system__pool_globalS");
+ u00088 : constant Version_32 := 16#9d39c675#;
+ pragma Export (C, u00088, "system__memoryB");
+ u00089 : constant Version_32 := 16#445a22b5#;
+ pragma Export (C, u00089, "system__memoryS");
+ u00090 : constant Version_32 := 16#6a859064#;
+ pragma Export (C, u00090, "system__storage_pools__subpoolsB");
+ u00091 : constant Version_32 := 16#e3b008dc#;
+ pragma Export (C, u00091, "system__storage_pools__subpoolsS");
+ u00092 : constant Version_32 := 16#63f11652#;
+ pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB");
+ u00093 : constant Version_32 := 16#fe2f4b3a#;
+ pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS");
+
+ -- BEGIN ELABORATION ORDER
+ -- ada%s
+ -- interfaces%s
+ -- system%s
+ -- system.case_util%s
+ -- system.case_util%b
+ -- system.htable%s
+ -- system.img_bool%s
+ -- system.img_bool%b
+ -- system.img_int%s
+ -- system.img_int%b
+ -- system.io%s
+ -- system.io%b
+ -- system.parameters%s
+ -- system.parameters%b
+ -- system.crtl%s
+ -- interfaces.c_streams%s
+ -- interfaces.c_streams%b
+ -- system.standard_library%s
+ -- system.exceptions_debug%s
+ -- system.exceptions_debug%b
+ -- system.storage_elements%s
+ -- system.storage_elements%b
+ -- system.stack_checking%s
+ -- system.stack_checking%b
+ -- system.string_hash%s
+ -- system.string_hash%b
+ -- system.htable%b
+ -- system.strings%s
+ -- system.strings%b
+ -- system.os_lib%s
+ -- system.traceback_entries%s
+ -- system.traceback_entries%b
+ -- ada.exceptions%s
+ -- system.soft_links%s
+ -- system.unsigned_types%s
+ -- system.val_llu%s
+ -- system.val_util%s
+ -- system.val_util%b
+ -- system.val_llu%b
+ -- system.wch_con%s
+ -- system.wch_con%b
+ -- system.wch_cnv%s
+ -- system.wch_jis%s
+ -- system.wch_jis%b
+ -- system.wch_cnv%b
+ -- system.wch_stw%s
+ -- system.wch_stw%b
+ -- ada.exceptions.last_chance_handler%s
+ -- ada.exceptions.last_chance_handler%b
+ -- system.address_image%s
+ -- system.exception_table%s
+ -- system.exception_table%b
+ -- ada.io_exceptions%s
+ -- ada.tags%s
+ -- ada.streams%s
+ -- ada.streams%b
+ -- interfaces.c%s
+ -- system.exceptions%s
+ -- system.exceptions%b
+ -- system.exceptions.machine%s
+ -- system.finalization_root%s
+ -- system.finalization_root%b
+ -- ada.finalization%s
+ -- ada.finalization%b
+ -- system.storage_pools%s
+ -- system.storage_pools%b
+ -- system.finalization_masters%s
+ -- system.storage_pools.subpools%s
+ -- system.storage_pools.subpools.finalization%s
+ -- system.storage_pools.subpools.finalization%b
+ -- system.memory%s
+ -- system.memory%b
+ -- system.standard_library%b
+ -- system.pool_global%s
+ -- system.pool_global%b
+ -- system.file_control_block%s
+ -- system.file_io%s
+ -- system.secondary_stack%s
+ -- system.file_io%b
+ -- system.storage_pools.subpools%b
+ -- system.finalization_masters%b
+ -- interfaces.c%b
+ -- ada.tags%b
+ -- system.soft_links%b
+ -- system.os_lib%b
+ -- system.secondary_stack%b
+ -- system.address_image%b
+ -- system.traceback%s
+ -- ada.exceptions%b
+ -- system.traceback%b
+ -- ada.text_io%s
+ -- ada.text_io%b
+ -- hello%b
+ -- END ELABORATION ORDER
+
+end ada_main;
+@end example
+
+@example
+pragma Ada_95;
+-- The following source file name pragmas allow the generated file
+-- names to be unique for different main programs. They are needed
+-- since the package name will always be Ada_Main.
+
+pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads");
+pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb");
+
+pragma Suppress (Overflow_Check);
+with Ada.Exceptions;
+
+-- Generated package body for Ada_Main starts here
+
+package body ada_main is
+ pragma Warnings (Off);
+
+ -- These values are reference counter associated to units which have
+ -- been elaborated. It is also used to avoid elaborating the
+ -- same unit twice.
+
+ E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E");
+ E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E");
+ E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E");
+ E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E");
+ E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E");
+ E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E");
+ E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E");
+ E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E");
+ E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E");
+ E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E");
+ E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E");
+ E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E");
+ E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E");
+ E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E");
+ E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E");
+ E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E");
+ E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E");
+ E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E");
+
+ Local_Priority_Specific_Dispatching : constant String := "";
+ Local_Interrupt_States : constant String := "";
+
+ Is_Elaborated : Boolean := False;
+
+ procedure finalize_library is
+ begin
+ E06 := E06 - 1;
+ declare
+ procedure F1;
+ pragma Import (Ada, F1, "ada__text_io__finalize_spec");
+ begin
+ F1;
+ end;
+ E77 := E77 - 1;
+ E91 := E91 - 1;
+ declare
+ procedure F2;
+ pragma Import (Ada, F2, "system__file_io__finalize_body");
+ begin
+ E64 := E64 - 1;
+ F2;
+ end;
+ declare
+ procedure F3;
+ pragma Import (Ada, F3, "system__file_control_block__finalize_spec");
+ begin
+ E75 := E75 - 1;
+ F3;
+ end;
+ E87 := E87 - 1;
+ declare
+ procedure F4;
+ pragma Import (Ada, F4, "system__pool_global__finalize_spec");
+ begin
+ F4;
+ end;
+ declare
+ procedure F5;
+ pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec");
+ begin
+ F5;
+ end;
+ declare
+ procedure F6;
+ pragma Import (Ada, F6, "system__finalization_masters__finalize_spec");
+ begin
+ F6;
+ end;
+ declare
+ procedure Reraise_Library_Exception_If_Any;
+ pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any");
+ begin
+ Reraise_Library_Exception_If_Any;
+ end;
+ end finalize_library;
+
+ -------------
+ -- adainit --
+ -------------
+
+ procedure adainit is
+
+ Main_Priority : Integer;
+ pragma Import (C, Main_Priority, "__gl_main_priority");
+ Time_Slice_Value : Integer;
+ pragma Import (C, Time_Slice_Value, "__gl_time_slice_val");
+ WC_Encoding : Character;
+ pragma Import (C, WC_Encoding, "__gl_wc_encoding");
+ Locking_Policy : Character;
+ pragma Import (C, Locking_Policy, "__gl_locking_policy");
+ Queuing_Policy : Character;
+ pragma Import (C, Queuing_Policy, "__gl_queuing_policy");
+ Task_Dispatching_Policy : Character;
+ pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy");
+ Priority_Specific_Dispatching : System.Address;
+ pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching");
+ Num_Specific_Dispatching : Integer;
+ pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching");
+ Main_CPU : Integer;
+ pragma Import (C, Main_CPU, "__gl_main_cpu");
+ Interrupt_States : System.Address;
+ pragma Import (C, Interrupt_States, "__gl_interrupt_states");
+ Num_Interrupt_States : Integer;
+ pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states");
+ Unreserve_All_Interrupts : Integer;
+ pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts");
+ Detect_Blocking : Integer;
+ pragma Import (C, Detect_Blocking, "__gl_detect_blocking");
+ Default_Stack_Size : Integer;
+ pragma Import (C, Default_Stack_Size, "__gl_default_stack_size");
+ Leap_Seconds_Support : Integer;
+ pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support");
+
+ procedure Runtime_Initialize;
+ pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize");
+
+ Finalize_Library_Objects : No_Param_Proc;
+ pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects");
+
+ -- Start of processing for adainit
+
+ begin
+
+ -- Record various information for this partition. The values
+ -- are derived by the binder from information stored in the ali
+ -- files by the compiler.
+
+ if Is_Elaborated then
+ return;
+ end if;
+ Is_Elaborated := True;
+ Main_Priority := -1;
+ Time_Slice_Value := -1;
+ WC_Encoding := 'b';
+ Locking_Policy := ' ';
+ Queuing_Policy := ' ';
+ Task_Dispatching_Policy := ' ';
+ Priority_Specific_Dispatching :=
+ Local_Priority_Specific_Dispatching'Address;
+ Num_Specific_Dispatching := 0;
+ Main_CPU := -1;
+ Interrupt_States := Local_Interrupt_States'Address;
+ Num_Interrupt_States := 0;
+ Unreserve_All_Interrupts := 0;
+ Detect_Blocking := 0;
+ Default_Stack_Size := -1;
+ Leap_Seconds_Support := 0;
+
+ Runtime_Initialize;
+
+ Finalize_Library_Objects := finalize_library'access;
+
+ -- Now we have the elaboration calls for all units in the partition.
+ -- The Elab_Spec and Elab_Body attributes generate references to the
+ -- implicit elaboration procedures generated by the compiler for
+ -- each unit that requires elaboration. Increment a counter of
+ -- reference for each unit.
+
+ System.Soft_Links'Elab_Spec;
+ System.Exception_Table'Elab_Body;
+ E23 := E23 + 1;
+ Ada.Io_Exceptions'Elab_Spec;
+ E46 := E46 + 1;
+ Ada.Tags'Elab_Spec;
+ Ada.Streams'Elab_Spec;
+ E45 := E45 + 1;
+ Interfaces.C'Elab_Spec;
+ System.Exceptions'Elab_Spec;
+ E25 := E25 + 1;
+ System.Finalization_Root'Elab_Spec;
+ E68 := E68 + 1;
+ Ada.Finalization'Elab_Spec;
+ E66 := E66 + 1;
+ System.Storage_Pools'Elab_Spec;
+ E85 := E85 + 1;
+ System.Finalization_Masters'Elab_Spec;
+ System.Storage_Pools.Subpools'Elab_Spec;
+ System.Pool_Global'Elab_Spec;
+ E87 := E87 + 1;
+ System.File_Control_Block'Elab_Spec;
+ E75 := E75 + 1;
+ System.File_Io'Elab_Body;
+ E64 := E64 + 1;
+ E91 := E91 + 1;
+ System.Finalization_Masters'Elab_Body;
+ E77 := E77 + 1;
+ E70 := E70 + 1;
+ Ada.Tags'Elab_Body;
+ E48 := E48 + 1;
+ System.Soft_Links'Elab_Body;
+ E13 := E13 + 1;
+ System.Os_Lib'Elab_Body;
+ E72 := E72 + 1;
+ System.Secondary_Stack'Elab_Body;
+ E17 := E17 + 1;
+ Ada.Text_Io'Elab_Spec;
+ Ada.Text_Io'Elab_Body;
+ E06 := E06 + 1;
+ end adainit;
+
+ --------------
+ -- adafinal --
+ --------------
+
+ procedure adafinal is
+ procedure s_stalib_adafinal;
+ pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal");
+
+ procedure Runtime_Finalize;
+ pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize");
+
+ begin
+ if not Is_Elaborated then
+ return;
+ end if;
+ Is_Elaborated := False;
+ Runtime_Finalize;
+ s_stalib_adafinal;
+ end adafinal;
+
+ -- We get to the main program of the partition by using
+ -- pragma Import because if we try to with the unit and
+ -- call it Ada style, then not only do we waste time
+ -- recompiling it, but also, we don't really know the right
+ -- switches (e.g.@@: identifier character set) to be used
+ -- to compile it.
+
+ procedure Ada_Main_Program;
+ pragma Import (Ada, Ada_Main_Program, "_ada_hello");
+
+ ----------
+ -- main --
+ ----------
+
+ -- main is actually a function, as in the ANSI C standard,
+ -- defined to return the exit status. The three parameters
+ -- are the argument count, argument values and environment
+ -- pointer.
+
+ function main
+ (argc : Integer;
+ argv : System.Address;
+ envp : System.Address)
+ return Integer
+ is
+ -- The initialize routine performs low level system
+ -- initialization using a standard library routine which
+ -- sets up signal handling and performs any other
+ -- required setup. The routine can be found in file
+ -- a-init.c.
+
+ procedure initialize;
+ pragma Import (C, initialize, "__gnat_initialize");
+
+ -- The finalize routine performs low level system
+ -- finalization using a standard library routine. The
+ -- routine is found in file a-final.c and in the standard
+ -- distribution is a dummy routine that does nothing, so
+ -- really this is a hook for special user finalization.
+
+ procedure finalize;
+ pragma Import (C, finalize, "__gnat_finalize");
+
+ -- The following is to initialize the SEH exceptions
+
+ SEH : aliased array (1 .. 2) of Integer;
+
+ Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address;
+ pragma Volatile (Ensure_Reference);
+
+ -- Start of processing for main
+
+ begin
+ -- Save global variables
+
+ gnat_argc := argc;
+ gnat_argv := argv;
+ gnat_envp := envp;
+
+ -- Call low level system initialization
+
+ Initialize (SEH'Address);
+
+ -- Call our generated Ada initialization routine
+
+ adainit;
+
+ -- Now we call the main program of the partition
+
+ Ada_Main_Program;
+
+ -- Perform Ada finalization
+
+ adafinal;
+
+ -- Perform low level system finalization
+
+ Finalize;
+
+ -- Return the proper exit status
+ return (gnat_exit_status);
+ end;
+
+-- This section is entirely comments, so it has no effect on the
+-- compilation of the Ada_Main package. It provides the list of
+-- object files and linker options, as well as some standard
+-- libraries needed for the link. The gnatlink utility parses
+-- this b~hello.adb file to read these comment lines to generate
+-- the appropriate command line arguments for the call to the
+-- system linker. The BEGIN/END lines are used for sentinels for
+-- this parsing operation.
+
+-- The exact file names will of course depend on the environment,
+-- host/target and location of files on the host system.
+
+-- BEGIN Object file/option list
+ -- ./hello.o
+ -- -L./
+ -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/
+ -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a
+-- END Object file/option list
+
+end ada_main;
+@end example
+
+The Ada code in the above example is exactly what is generated by the
+binder. We have added comments to more clearly indicate the function
+of each part of the generated @code{Ada_Main} package.
+
+The code is standard Ada in all respects, and can be processed by any
+tools that handle Ada. In particular, it is possible to use the debugger
+in Ada mode to debug the generated @code{Ada_Main} package. For example,
+suppose that for reasons that you do not understand, your program is crashing
+during elaboration of the body of @code{Ada.Text_IO}. To locate this bug,
+you can place a breakpoint on the call:
+
+@quotation
+
+@example
+Ada.Text_Io'Elab_Body;
+@end example
+@end quotation
+
+and trace the elaboration routine for this package to find out where
+the problem might be (more usually of course you would be debugging
+elaboration code in your own application).
+
+@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
+
+@node Elaboration Order Handling in GNAT,Inline Assembler,Example of Binder Output File,Top
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{216}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{217}
+@chapter Elaboration Order Handling in GNAT
+
+
+@geindex Order of elaboration
+
+@geindex Elaboration control
+
+This appendix describes the handling of elaboration code in Ada and GNAT, and
+discusses how the order of elaboration of program units can be controlled in
+GNAT, either automatically or with explicit programming features.
+
+@menu
+* Elaboration Code::
+* Elaboration Order::
+* Checking the Elaboration Order::
+* Controlling the Elaboration Order in Ada::
+* Controlling the Elaboration Order in GNAT::
+* Mixing Elaboration Models::
+* ABE Diagnostics::
+* SPARK Diagnostics::
+* Elaboration Circularities::
+* Resolving Elaboration Circularities::
+* Elaboration-related Compiler Switches::
+* Summary of Procedures for Elaboration Control::
+* Inspecting the Chosen Elaboration Order::
+
+@end menu
+
+@node Elaboration Code,Elaboration Order,,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{218}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{219}
+@section Elaboration Code
+
+
+Ada defines the term `execution' as the process by which a construct achieves
+its run-time effect. This process is also referred to as `elaboration' for
+declarations and `evaluation' for expressions.
+
+The execution model in Ada allows for certain sections of an Ada program to be
+executed prior to execution of the program itself, primarily with the intent of
+initializing data. These sections are referred to as `elaboration code'.
+Elaboration code is executed as follows:
+
+
+@itemize *
+
+@item
+All partitions of an Ada program are executed in parallel with one another,
+possibly in a separate address space, and possibly on a separate computer.
+
+@item
+The execution of a partition involves running the environment task for that
+partition.
+
+@item
+The environment task executes all elaboration code (if available) for all
+units within that partition. This code is said to be executed at
+`elaboration time'.
+
+@item
+The environment task executes the Ada program (if available) for that
+partition.
+@end itemize
+
+In addition to the Ada terminology, this appendix defines the following terms:
+
+
+@itemize *
+
+@item
+`Invocation'
+
+The act of calling a subprogram, instantiating a generic, or activating a
+task.
+
+@item
+`Scenario'
+
+A construct that is elaborated or invoked by elaboration code is referred to
+as an `elaboration scenario' or simply a `scenario'. GNAT recognizes the
+following scenarios:
+
+
+@itemize -
+
+@item
+@code{'Access} of entries, operators, and subprograms
+
+@item
+Activation of tasks
+
+@item
+Calls to entries, operators, and subprograms
+
+@item
+Instantiations of generic templates
+@end itemize
+
+@item
+`Target'
+
+A construct elaborated by a scenario is referred to as `elaboration target'
+or simply `target'. GNAT recognizes the following targets:
+
+
+@itemize -
+
+@item
+For @code{'Access} of entries, operators, and subprograms, the target is the
+entry, operator, or subprogram being aliased.
+
+@item
+For activation of tasks, the target is the task body
+
+@item
+For calls to entries, operators, and subprograms, the target is the entry,
+operator, or subprogram being invoked.
+
+@item
+For instantiations of generic templates, the target is the generic template
+being instantiated.
+@end itemize
+@end itemize
+
+Elaboration code may appear in two distinct contexts:
+
+
+@itemize *
+
+@item
+`Library level'
+
+A scenario appears at the library level when it is encapsulated by a package
+[body] compilation unit, ignoring any other package [body] declarations in
+between.
+
+@example
+with Server;
+package Client is
+ procedure Proc;
+
+ package Nested is
+ Val : ... := Server.Func;
+ end Nested;
+end Client;
+@end example
+
+In the example above, the call to @code{Server.Func} is an elaboration scenario
+because it appears at the library level of package @code{Client}. Note that the
+declaration of package @code{Nested} is ignored according to the definition
+given above. As a result, the call to @code{Server.Func} will be invoked when
+the spec of unit @code{Client} is elaborated.
+
+@item
+`Package body statements'
+
+A scenario appears within the statement sequence of a package body when it is
+bounded by the region starting from the @code{begin} keyword of the package body
+and ending at the @code{end} keyword of the package body.
+
+@example
+package body Client is
+ procedure Proc is
+ begin
+ ...
+ end Proc;
+begin
+ Proc;
+end Client;
+@end example
+
+In the example above, the call to @code{Proc} is an elaboration scenario because
+it appears within the statement sequence of package body @code{Client}. As a
+result, the call to @code{Proc} will be invoked when the body of @code{Client} is
+elaborated.
+@end itemize
+
+@node Elaboration Order,Checking the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order}@anchor{21a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{21b}
+@section Elaboration Order
+
+
+The sequence by which the elaboration code of all units within a partition is
+executed is referred to as `elaboration order'.
+
+Within a single unit, elaboration code is executed in sequential order.
+
+@quotation
+
+@example
+package body Client is
+ Result : ... := Server.Func;
+
+ procedure Proc is
+ package Inst is new Server.Gen;
+ begin
+ Inst.Eval (Result);
+ end Proc;
+begin
+ Proc;
+end Client;
+@end example
+@end quotation
+
+In the example above, the elaboration order within package body @code{Client} is
+as follows:
+
+
+@enumerate
+
+@item
+The object declaration of @code{Result} is elaborated.
+
+
+@itemize *
+
+@item
+Function @code{Server.Func} is invoked.
+@end itemize
+
+@item
+The subprogram body of @code{Proc} is elaborated.
+
+@item
+Procedure @code{Proc} is invoked.
+
+
+@itemize *
+
+@item
+Generic unit @code{Server.Gen} is instantiated as @code{Inst}.
+
+@item
+Instance @code{Inst} is elaborated.
+
+@item
+Procedure @code{Inst.Eval} is invoked.
+@end itemize
+@end enumerate
+
+The elaboration order of all units within a partition depends on the following
+factors:
+
+
+@itemize *
+
+@item
+`with'ed units
+
+@item
+parent units
+
+@item
+purity of units
+
+@item
+preelaborability of units
+
+@item
+presence of elaboration-control pragmas
+
+@item
+invocations performed in elaboration code
+@end itemize
+
+A program may have several elaboration orders depending on its structure.
+
+@quotation
+
+@example
+package Server is
+ function Func (Index : Integer) return Integer;
+end Server;
+@end example
+
+@example
+package body Server is
+ Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5);
+
+ function Func (Index : Integer) return Integer is
+ begin
+ return Results (Index);
+ end Func;
+end Server;
+@end example
+
+@example
+with Server;
+package Client is
+ Val : constant Integer := Server.Func (3);
+end Client;
+@end example
+
+@example
+with Client;
+procedure Main is begin null; end Main;
+@end example
+@end quotation
+
+The following elaboration order exhibits a fundamental problem referred to as
+`access-before-elaboration' or simply `ABE'.
+
+@quotation
+
+@example
+spec of Server
+spec of Client
+body of Server
+body of Main
+@end example
+@end quotation
+
+The elaboration of @code{Server}’s spec materializes function @code{Func}, making it
+callable. The elaboration of @code{Client}’s spec elaborates the declaration of
+@code{Val}. This invokes function @code{Server.Func}, however the body of
+@code{Server.Func} has not been elaborated yet because @code{Server}’s body comes
+after @code{Client}’s spec in the elaboration order. As a result, the value of
+constant @code{Val} is now undefined.
+
+Without any guarantees from the language, an undetected ABE problem may hinder
+proper initialization of data, which in turn may lead to undefined behavior at
+run time. To prevent such ABE problems, Ada employs dynamic checks in the same
+vein as index or null exclusion checks. A failed ABE check raises exception
+@code{Program_Error}.
+
+The following elaboration order avoids the ABE problem and the program can be
+successfully elaborated.
+
+@quotation
+
+@example
+spec of Server
+body of Server
+spec of Client
+body of Main
+@end example
+@end quotation
+
+Ada states that a total elaboration order must exist, but it does not define
+what this order is. A compiler is thus tasked with choosing a suitable
+elaboration order which satisfies the dependencies imposed by `with' clauses,
+unit categorization, elaboration-control pragmas, and invocations performed in
+elaboration code. Ideally an order that avoids ABE problems should be chosen,
+however a compiler may not always find such an order due to complications with
+respect to control and data flow.
+
+@node Checking the Elaboration Order,Controlling the Elaboration Order in Ada,Elaboration Order,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{21c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{21d}
+@section Checking the Elaboration Order
+
+
+To avoid placing the entire elaboration-order burden on the programmer, Ada
+provides three lines of defense:
+
+
+@itemize *
+
+@item
+`Static semantics'
+
+Static semantic rules restrict the possible choice of elaboration order. For
+instance, if unit Client `with's unit Server, then the spec of Server is
+always elaborated prior to Client. The same principle applies to child units
+- the spec of a parent unit is always elaborated prior to the child unit.
+
+@item
+`Dynamic semantics'
+
+Dynamic checks are performed at run time, to ensure that a target is
+elaborated prior to a scenario that invokes it, thus avoiding ABE problems.
+A failed run-time check raises exception @code{Program_Error}. The following
+restrictions apply:
+
+
+@itemize -
+
+@item
+`Restrictions on calls'
+
+An entry, operator, or subprogram can be called from elaboration code only
+when the corresponding body has been elaborated.
+
+@item
+`Restrictions on instantiations'
+
+A generic unit can be instantiated by elaboration code only when the
+corresponding body has been elaborated.
+
+@item
+`Restrictions on task activation'
+
+A task can be activated by elaboration code only when the body of the
+associated task type has been elaborated.
+@end itemize
+
+The restrictions above can be summarized by the following rule:
+
+`If a target has a body, then this body must be elaborated prior to the
+scenario that invokes the target.'
+
+@item
+`Elaboration control'
+
+Pragmas are provided for the programmer to specify the desired elaboration
+order.
+@end itemize
+
+@node Controlling the Elaboration Order in Ada,Controlling the Elaboration Order in GNAT,Checking the Elaboration Order,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-ada}@anchor{21e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{21f}
+@section Controlling the Elaboration Order in Ada
+
+
+Ada provides several idioms and pragmas to aid the programmer with specifying
+the desired elaboration order and avoiding ABE problems altogether.
+
+
+@itemize *
+
+@item
+`Packages without a body'
+
+A library package which does not require a completing body does not suffer
+from ABE problems.
+
+@example
+package Pack is
+ generic
+ type Element is private;
+ package Containers is
+ type Element_Array is array (1 .. 10) of Element;
+ end Containers;
+end Pack;
+@end example
+
+In the example above, package @code{Pack} does not require a body because it
+does not contain any constructs which require completion in a body. As a
+result, generic @code{Pack.Containers} can be instantiated without encountering
+any ABE problems.
+@end itemize
+
+@geindex pragma Pure
+
+
+@itemize *
+
+@item
+`pragma Pure'
+
+Pragma @code{Pure} places sufficient restrictions on a unit to guarantee that no
+scenario within the unit can result in an ABE problem.
+@end itemize
+
+@geindex pragma Preelaborate
+
+
+@itemize *
+
+@item
+`pragma Preelaborate'
+
+Pragma @code{Preelaborate} is slightly less restrictive than pragma @code{Pure},
+but still strong enough to prevent ABE problems within a unit.
+@end itemize
+
+@geindex pragma Elaborate_Body
+
+
+@itemize *
+
+@item
+`pragma Elaborate_Body'
+
+Pragma @code{Elaborate_Body} requires that the body of a unit is elaborated
+immediately after its spec. This restriction guarantees that no client
+scenario can invoke a server target before the target body has been
+elaborated because the spec and body are effectively “glued” together.
+
+@example
+package Server is
+ pragma Elaborate_Body;
+
+ function Func return Integer;
+end Server;
+@end example
+
+@example
+package body Server is
+ function Func return Integer is
+ begin
+ ...
+ end Func;
+end Server;
+@end example
+
+@example
+with Server;
+package Client is
+ Val : constant Integer := Server.Func;
+end Client;
+@end example
+
+In the example above, pragma @code{Elaborate_Body} guarantees the following
+elaboration order:
+
+@example
+spec of Server
+body of Server
+spec of Client
+@end example
+
+because the spec of @code{Server} must be elaborated prior to @code{Client} by
+virtue of the `with' clause, and in addition the body of @code{Server} must be
+elaborated immediately after the spec of @code{Server}.
+
+Removing pragma @code{Elaborate_Body} could result in the following incorrect
+elaboration order:
+
+@example
+spec of Server
+spec of Client
+body of Server
+@end example
+
+where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func} has
+not been elaborated yet.
+@end itemize
+
+The pragmas outlined above allow a server unit to guarantee safe elaboration
+use by client units. Thus it is a good rule to mark units as @code{Pure} or
+@code{Preelaborate}, and if this is not possible, mark them as @code{Elaborate_Body}.
+
+There are however situations where @code{Pure}, @code{Preelaborate}, and
+@code{Elaborate_Body} are not applicable. Ada provides another set of pragmas for
+use by client units to help ensure the elaboration safety of server units they
+depend on.
+
+@geindex pragma Elaborate (Unit)
+
+
+@itemize *
+
+@item
+`pragma Elaborate (Unit)'
+
+Pragma @code{Elaborate} can be placed in the context clauses of a unit, after a
+`with' clause. It guarantees that both the spec and body of its argument will
+be elaborated prior to the unit with the pragma. Note that other unrelated
+units may be elaborated in between the spec and the body.
+
+@example
+package Server is
+ function Func return Integer;
+end Server;
+@end example
+
+@example
+package body Server is
+ function Func return Integer is
+ begin
+ ...
+ end Func;
+end Server;
+@end example
+
+@example
+with Server;
+pragma Elaborate (Server);
+package Client is
+ Val : constant Integer := Server.Func;
+end Client;
+@end example
+
+In the example above, pragma @code{Elaborate} guarantees the following
+elaboration order:
+
+@example
+spec of Server
+body of Server
+spec of Client
+@end example
+
+Removing pragma @code{Elaborate} could result in the following incorrect
+elaboration order:
+
+@example
+spec of Server
+spec of Client
+body of Server
+@end example
+
+where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func}
+has not been elaborated yet.
+@end itemize
+
+@geindex pragma Elaborate_All (Unit)
+
+
+@itemize *
+
+@item
+`pragma Elaborate_All (Unit)'
+
+Pragma @code{Elaborate_All} is placed in the context clauses of a unit, after
+a `with' clause. It guarantees that both the spec and body of its argument
+will be elaborated prior to the unit with the pragma, as well as all units
+`with'ed by the spec and body of the argument, recursively. Note that other
+unrelated units may be elaborated in between the spec and the body.
+
+@example
+package Math is
+ function Factorial (Val : Natural) return Natural;
+end Math;
+@end example
+
+@example
+package body Math is
+ function Factorial (Val : Natural) return Natural is
+ begin
+ ...;
+ end Factorial;
+end Math;
+@end example
+
+@example
+package Computer is
+ type Operation_Kind is (None, Op_Factorial);
+
+ function Compute
+ (Val : Natural;
+ Op : Operation_Kind) return Natural;
+end Computer;
+@end example
+
+@example
+with Math;
+package body Computer is
+ function Compute
+ (Val : Natural;
+ Op : Operation_Kind) return Natural
+ is
+ if Op = Op_Factorial then
+ return Math.Factorial (Val);
+ end if;
+
+ return 0;
+ end Compute;
+end Computer;
+@end example
+
+@example
+with Computer;
+pragma Elaborate_All (Computer);
+package Client is
+ Val : constant Natural :=
+ Computer.Compute (123, Computer.Op_Factorial);
+end Client;
+@end example
+
+In the example above, pragma @code{Elaborate_All} can result in the following
+elaboration order:
+
+@example
+spec of Math
+body of Math
+spec of Computer
+body of Computer
+spec of Client
+@end example
+
+Note that there are several allowable suborders for the specs and bodies of
+@code{Math} and @code{Computer}, but the point is that these specs and bodies will
+be elaborated prior to @code{Client}.
+
+Removing pragma @code{Elaborate_All} could result in the following incorrect
+elaboration order:
+
+@example
+spec of Math
+spec of Computer
+body of Computer
+spec of Client
+body of Math
+@end example
+
+where @code{Client} invokes @code{Computer.Compute}, which in turn invokes
+@code{Math.Factorial}, but the body of @code{Math.Factorial} has not been
+elaborated yet.
+@end itemize
+
+All pragmas shown above can be summarized by the following rule:
+
+`If a client unit elaborates a server target directly or indirectly, then if
+the server unit requires a body and does not have pragma Pure, Preelaborate,
+or Elaborate_Body, then the client unit should have pragma Elaborate or
+Elaborate_All for the server unit.'
+
+If the rule outlined above is not followed, then a program may fall in one of
+the following states:
+
+
+@itemize *
+
+@item
+`No elaboration order exists'
+
+In this case a compiler must diagnose the situation, and refuse to build an
+executable program.
+
+@item
+`One or more incorrect elaboration orders exist'
+
+In this case a compiler can build an executable program, but
+@code{Program_Error} will be raised when the program is run.
+
+@item
+`Several elaboration orders exist, some correct, some incorrect'
+
+In this case the programmer has not controlled the elaboration order. As a
+result, a compiler may or may not pick one of the correct orders, and the
+program may or may not raise @code{Program_Error} when it is run. This is the
+worst possible state because the program may fail on another compiler, or
+even another version of the same compiler.
+
+@item
+`One or more correct orders exist'
+
+In this case a compiler can build an executable program, and the program is
+run successfully. This state may be guaranteed by following the outlined
+rules, or may be the result of good program architecture.
+@end itemize
+
+Note that one additional advantage of using @code{Elaborate} and @code{Elaborate_All}
+is that the program continues to stay in the last state (one or more correct
+orders exist) even if maintenance changes the bodies of targets.
+
+@node Controlling the Elaboration Order in GNAT,Mixing Elaboration Models,Controlling the Elaboration Order in Ada,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-gnat}@anchor{220}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{221}
+@section Controlling the Elaboration Order in GNAT
+
+
+In addition to Ada semantics and rules synthesized from them, GNAT offers
+three elaboration models to aid the programmer with specifying the correct
+elaboration order and to diagnose elaboration problems.
+
+@geindex Dynamic elaboration model
+
+
+@itemize *
+
+@item
+`Dynamic elaboration model'
+
+This is the most permissive of the three elaboration models and emulates the
+behavior specified by the Ada Reference Manual. When the dynamic model is in
+effect, GNAT makes the following assumptions:
+
+
+@itemize -
+
+@item
+All code within all units in a partition is considered to be elaboration
+code.
+
+@item
+Some of the invocations in elaboration code may not take place at run time
+due to conditional execution.
+@end itemize
+
+GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
+that invoke internal targets. In addition, GNAT generates run-time checks for
+all external targets and for all scenarios that may exhibit ABE problems.
+
+The elaboration order is obtained by honoring all `with' clauses, purity and
+preelaborability of units, and elaboration-control pragmas. The dynamic model
+attempts to take all invocations in elaboration code into account. If an
+invocation leads to a circularity, GNAT ignores the invocation based on the
+assumptions stated above. An order obtained using the dynamic model may fail
+an ABE check at run time when GNAT ignored an invocation.
+
+The dynamic model is enabled with compiler switch @code{-gnatE}.
+@end itemize
+
+@geindex Static elaboration model
+
+
+@itemize *
+
+@item
+`Static elaboration model'
+
+This is the middle ground of the three models. When the static model is in
+effect, GNAT makes the following assumptions:
+
+
+@itemize -
+
+@item
+Only code at the library level and in package body statements within all
+units in a partition is considered to be elaboration code.
+
+@item
+All invocations in elaboration will take place at run time, regardless of
+conditional execution.
+@end itemize
+
+GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
+that invoke internal targets. In addition, GNAT generates run-time checks for
+all external targets and for all scenarios that may exhibit ABE problems.
+
+The elaboration order is obtained by honoring all `with' clauses, purity and
+preelaborability of units, presence of elaboration-control pragmas, and all
+invocations in elaboration code. An order obtained using the static model is
+guaranteed to be ABE problem-free, excluding dispatching calls and
+access-to-subprogram types.
+
+The static model is the default model in GNAT.
+@end itemize
+
+@geindex SPARK elaboration model
+
+
+@itemize *
+
+@item
+`SPARK elaboration model'
+
+This is the most conservative of the three models and enforces the SPARK
+rules of elaboration as defined in the SPARK Reference Manual, section 7.7.
+The SPARK model is in effect only when a scenario and a target reside in a
+region subject to @code{SPARK_Mode On}, otherwise the dynamic or static model
+is in effect.
+
+The SPARK model is enabled with compiler switch @code{-gnatd.v}.
+@end itemize
+
+@geindex Legacy elaboration models
+
+
+@itemize *
+
+@item
+`Legacy elaboration models'
+
+In addition to the three elaboration models outlined above, GNAT provides the
+following legacy models:
+
+
+@itemize -
+
+@item
+@cite{Legacy elaboration-checking model} available in pre-18.x versions of GNAT.
+This model is enabled with compiler switch @code{-gnatH}.
+
+@item
+@cite{Legacy elaboration-order model} available in pre-20.x versions of GNAT.
+This model is enabled with binder switch @code{-H}.
+@end itemize
+@end itemize
+
+@geindex Relaxed elaboration mode
+
+The dynamic, legacy, and static models can be relaxed using compiler switch
+@code{-gnatJ}, making them more permissive. Note that in this mode, GNAT
+may not diagnose certain elaboration issues or install run-time checks.
+
+@node Mixing Elaboration Models,ABE Diagnostics,Controlling the Elaboration Order in GNAT,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{222}@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{223}
+@section Mixing Elaboration Models
+
+
+It is possible to mix units compiled with a different elaboration model,
+however the following rules must be observed:
+
+
+@itemize *
+
+@item
+A client unit compiled with the dynamic model can only `with' a server unit
+that meets at least one of the following criteria:
+
+
+@itemize -
+
+@item
+The server unit is compiled with the dynamic model.
+
+@item
+The server unit is a GNAT implementation unit from the @code{Ada}, @code{GNAT},
+@code{Interfaces}, or @code{System} hierarchies.
+
+@item
+The server unit has pragma @code{Pure} or @code{Preelaborate}.
+
+@item
+The client unit has an explicit @code{Elaborate_All} pragma for the server
+unit.
+@end itemize
+@end itemize
+
+These rules ensure that elaboration checks are not omitted. If the rules are
+violated, the binder emits a warning:
+
+@quotation
+
+@example
+warning: "x.ads" has dynamic elaboration checks and with's
+warning: "y.ads" which has static elaboration checks
+@end example
+@end quotation
+
+The warnings can be suppressed by binder switch @code{-ws}.
+
+@node ABE Diagnostics,SPARK Diagnostics,Mixing Elaboration Models,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat abe-diagnostics}@anchor{224}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{225}
+@section ABE Diagnostics
+
+
+GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
+that invoke internal targets, regardless of whether the dynamic, SPARK, or
+static model is in effect.
+
+Note that GNAT emits warnings rather than hard errors whenever it encounters an
+elaboration problem. This is because the elaboration model in effect may be too
+conservative, or a particular scenario may not be invoked due conditional
+execution. The warnings can be suppressed selectively with @code{pragma Warnings
+(Off)} or globally with compiler switch @code{-gnatwL}.
+
+A `guaranteed ABE' arises when the body of a target is not elaborated early
+enough, and causes `all' scenarios that directly invoke the target to fail.
+
+@quotation
+
+@example
+package body Guaranteed_ABE is
+ function ABE return Integer;
+
+ Val : constant Integer := ABE;
+
+ function ABE return Integer is
+ begin
+ ...
+ end ABE;
+end Guaranteed_ABE;
+@end example
+@end quotation
+
+In the example above, the elaboration of @code{Guaranteed_ABE}’s body elaborates
+the declaration of @code{Val}. This invokes function @code{ABE}, however the body of
+@code{ABE} has not been elaborated yet. GNAT emits the following diagnostic:
+
+@quotation
+
+@example
+4. Val : constant Integer := ABE;
+ |
+ >>> warning: cannot call "ABE" before body seen
+ >>> warning: Program_Error will be raised at run time
+@end example
+@end quotation
+
+A `conditional ABE' arises when the body of a target is not elaborated early
+enough, and causes `some' scenarios that directly invoke the target to fail.
+
+@quotation
+
+@example
+ 1. package body Conditional_ABE is
+ 2. procedure Force_Body is null;
+ 3.
+ 4. generic
+ 5. with function Func return Integer;
+ 6. package Gen is
+ 7. Val : constant Integer := Func;
+ 8. end Gen;
+ 9.
+10. function ABE return Integer;
+11.
+12. function Cause_ABE return Boolean is
+13. package Inst is new Gen (ABE);
+14. begin
+15. ...
+16. end Cause_ABE;
+17.
+18. Val : constant Boolean := Cause_ABE;
+19.
+20. function ABE return Integer is
+21. begin
+22. ...
+23. end ABE;
+24.
+25. Safe : constant Boolean := Cause_ABE;
+26. end Conditional_ABE;
+@end example
+@end quotation
+
+In the example above, the elaboration of package body @code{Conditional_ABE}
+elaborates the declaration of @code{Val}. This invokes function @code{Cause_ABE},
+which instantiates generic unit @code{Gen} as @code{Inst}. The elaboration of
+@code{Inst} invokes function @code{ABE}, however the body of @code{ABE} has not been
+elaborated yet. GNAT emits the following diagnostic:
+
+@quotation
+
+@example
+13. package Inst is new Gen (ABE);
+ |
+ >>> warning: in instantiation at line 7
+ >>> warning: cannot call "ABE" before body seen
+ >>> warning: Program_Error may be raised at run time
+ >>> warning: body of unit "Conditional_ABE" elaborated
+ >>> warning: function "Cause_ABE" called at line 18
+ >>> warning: function "ABE" called at line 7, instance at line 13
+@end example
+@end quotation
+
+Note that the same ABE problem does not occur with the elaboration of
+declaration @code{Safe} because the body of function @code{ABE} has already been
+elaborated at that point.
+
+@node SPARK Diagnostics,Elaboration Circularities,ABE Diagnostics,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{226}@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-diagnostics}@anchor{227}
+@section SPARK Diagnostics
+
+
+GNAT enforces the SPARK rules of elaboration as defined in the SPARK Reference
+Manual section 7.7 when compiler switch @code{-gnatd.v} is in effect. Note
+that GNAT emits hard errors whenever it encounters a violation of the SPARK
+rules.
+
+@quotation
+
+@example
+1. with Server;
+2. package body SPARK_Diagnostics with SPARK_Mode is
+3. Val : constant Integer := Server.Func;
+ |
+ >>> call to "Func" during elaboration in SPARK
+ >>> unit "SPARK_Diagnostics" requires pragma "Elaborate_All" for "Server"
+ >>> body of unit "SPARK_Model" elaborated
+ >>> function "Func" called at line 3
+
+4. end SPARK_Diagnostics;
+@end example
+@end quotation
+
+@node Elaboration Circularities,Resolving Elaboration Circularities,SPARK Diagnostics,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{228}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{229}
+@section Elaboration Circularities
+
+
+An `elaboration circularity' occurs whenever the elaboration of a set of
+units enters a deadlocked state, where each unit is waiting for another unit
+to be elaborated. This situation may be the result of improper use of `with'
+clauses, elaboration-control pragmas, or invocations in elaboration code.
+
+The following example exhibits an elaboration circularity.
+
+@quotation
+
+@example
+with B; pragma Elaborate (B);
+package A is
+end A;
+@end example
+
+@example
+package B is
+ procedure Force_Body;
+end B;
+@end example
+
+@example
+with C;
+package body B is
+ procedure Force_Body is null;
+
+ Elab : constant Integer := C.Func;
+end B;
+@end example
+
+@example
+package C is
+ function Func return Integer;
+end C;
+@end example
+
+@example
+with A;
+package body C is
+ function Func return Integer is
+ begin
+ ...
+ end Func;
+end C;
+@end example
+@end quotation
+
+The binder emits the following diagnostic:
+
+@quotation
+
+@example
+error: Elaboration circularity detected
+info:
+info: Reason:
+info:
+info: unit "a (spec)" depends on its own elaboration
+info:
+info: Circularity:
+info:
+info: unit "a (spec)" has with clause and pragma Elaborate for unit "b (spec)"
+info: unit "b (body)" is in the closure of pragma Elaborate
+info: unit "b (body)" invokes a construct of unit "c (body)" at elaboration time
+info: unit "c (body)" has with clause for unit "a (spec)"
+info:
+info: Suggestions:
+info:
+info: remove pragma Elaborate for unit "b (body)" in unit "a (spec)"
+info: use the dynamic elaboration model (compiler switch -gnatE)
+@end example
+@end quotation
+
+The diagnostic consist of the following sections:
+
+
+@itemize *
+
+@item
+Reason
+
+This section provides a short explanation describing why the set of units
+could not be ordered.
+
+@item
+Circularity
+
+This section enumerates the units comprising the deadlocked set, along with
+their interdependencies.
+
+@item
+Suggestions
+
+This section enumerates various tactics for eliminating the circularity.
+@end itemize
+
+@node Resolving Elaboration Circularities,Elaboration-related Compiler Switches,Elaboration Circularities,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{22a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{22b}
+@section Resolving Elaboration Circularities
+
+
+The most desirable option from the point of view of long-term maintenance is to
+rearrange the program so that the elaboration problems are avoided. One useful
+technique is to place the elaboration code into separate child packages.
+Another is to move some of the initialization code to explicitly invoked
+subprograms, where the program controls the order of initialization explicitly.
+Although this is the most desirable option, it may be impractical and involve
+too much modification, especially in the case of complex legacy code.
+
+When faced with an elaboration circularity, the programmer should also consider
+the tactics given in the suggestions section of the circularity diagnostic.
+Depending on the units involved in the circularity, their `with' clauses,
+purity, preelaborability, presence of elaboration-control pragmas and
+invocations at elaboration time, the binder may suggest one or more of the
+following tactics to eliminate the circularity:
+
+
+@itemize *
+
+@item
+Pragma Elaborate elimination
+
+@example
+remove pragma Elaborate for unit "..." in unit "..."
+@end example
+
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate}:
+
+
+@itemize -
+
+@item
+Prevents a set of units from being elaborated.
+
+@item
+The removal of the pragma will not eliminate the semantic effects of the
+pragma. In other words, the argument of the pragma will still be elaborated
+prior to the unit containing the pragma.
+
+@item
+The removal of the pragma will enable the successful ordering of the units.
+@end itemize
+
+The programmer should remove the pragma as advised, and rebuild the program.
+
+@item
+Pragma Elaborate_All elimination
+
+@example
+remove pragma Elaborate_All for unit "..." in unit "..."
+@end example
+
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate_All}:
+
+
+@itemize -
+
+@item
+Prevents a set of units from being elaborated.
+
+@item
+The removal of the pragma will not eliminate the semantic effects of the
+pragma. In other words, the argument of the pragma along with its `with'
+closure will still be elaborated prior to the unit containing the pragma.
+
+@item
+The removal of the pragma will enable the successful ordering of the units.
+@end itemize
+
+The programmer should remove the pragma as advised, and rebuild the program.
+
+@item
+Pragma Elaborate_All downgrade
+
+@example
+change pragma Elaborate_All for unit "..." to Elaborate in unit "..."
+@end example
+
+This tactic is always suggested with the pragma @code{Elaborate_All} elimination
+tactic. It offers a different alternative of guaranteeing that the argument
+of the pragma will still be elaborated prior to the unit containing the
+pragma.
+
+The programmer should update the pragma as advised, and rebuild the program.
+
+@item
+Pragma Elaborate_Body elimination
+
+@example
+remove pragma Elaborate_Body in unit "..."
+@end example
+
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate_Body}:
+
+
+@itemize -
+
+@item
+Prevents a set of units from being elaborated.
+
+@item
+The removal of the pragma will enable the successful ordering of the units.
+@end itemize
+
+Note that the binder cannot determine whether the pragma is required for
+other purposes, such as guaranteeing the initialization of a variable
+declared in the spec by elaboration code in the body.
+
+The programmer should remove the pragma as advised, and rebuild the program.
+
+@item
+Use of pragma Restrictions
+
+@example
+use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code)
+@end example
+
+This tactic is suggested when the binder has determined that a task
+activation at elaboration time:
+
+
+@itemize -
+
+@item
+Prevents a set of units from being elaborated.
+@end itemize
+
+Note that the binder cannot determine with certainty whether the task will
+block at elaboration time.
+
+The programmer should create a configuration file, place the pragma within,
+update the general compilation arguments, and rebuild the program.
+
+@item
+Use of dynamic elaboration model
+
+@example
+use the dynamic elaboration model (compiler switch -gnatE)
+@end example
+
+This tactic is suggested when the binder has determined that an invocation at
+elaboration time:
+
+
+@itemize -
+
+@item
+Prevents a set of units from being elaborated.
+
+@item
+The use of the dynamic model will enable the successful ordering of the
+units.
+@end itemize
+
+The programmer has two options:
+
+
+@itemize -
+
+@item
+Determine the units involved in the invocation using the detailed
+invocation information, and add compiler switch @code{-gnatE} to the
+compilation arguments of selected files only. This approach will yield
+safer elaboration orders compared to the other option because it will
+minimize the opportunities presented to the dynamic model for ignoring
+invocations.
+
+@item
+Add compiler switch @code{-gnatE} to the general compilation arguments.
+@end itemize
+
+@item
+Use of detailed invocation information
+
+@example
+use detailed invocation information (compiler switch -gnatd_F)
+@end example
+
+This tactic is always suggested with the use of the dynamic model tactic. It
+causes the circularity section of the circularity diagnostic to describe the
+flow of elaboration code from a unit to a unit, enumerating all such paths in
+the process.
+
+The programmer should analyze this information to determine which units
+should be compiled with the dynamic model.
+
+@item
+Forced-dependency elimination
+
+@example
+remove the dependency of unit "..." on unit "..." from the argument of switch -f
+@end example
+
+This tactic is suggested when the binder has determined that a dependency
+present in the forced-elaboration-order file indicated by binder switch
+@code{-f}:
+
+
+@itemize -
+
+@item
+Prevents a set of units from being elaborated.
+
+@item
+The removal of the dependency will enable the successful ordering of the
+units.
+@end itemize
+
+The programmer should edit the forced-elaboration-order file, remove the
+dependency, and rebind the program.
+
+@item
+All forced-dependency elimination
+
+@example
+remove switch -f
+@end example
+
+This tactic is suggested in case editing the forced-elaboration-order file is
+not an option.
+
+The programmer should remove binder switch @code{-f} from the binder
+arguments, and rebind.
+
+@item
+Multiple-circularities diagnostic
+
+@example
+diagnose all circularities (binder switch -d_C)
+@end example
+
+By default, the binder will diagnose only the highest-precedence circularity.
+If the program contains multiple circularities, the binder will suggest the
+use of binder switch @code{-d_C} in order to obtain the diagnostics of all
+circularities.
+
+The programmer should add binder switch @code{-d_C} to the binder
+arguments, and rebind.
+@end itemize
+
+If none of the tactics suggested by the binder eliminate the elaboration
+circularity, the programmer should consider using one of the legacy elaboration
+models, in the following order:
+
+
+@itemize *
+
+@item
+Use the pre-20.x legacy elaboration-order model, with binder switch
+@code{-H}.
+
+@item
+Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
+switch @code{-gnatH} and binder switch @code{-H}.
+
+@item
+Use the relaxed static-elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
+
+@item
+Use the relaxed dynamic-elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
+@code{-H}.
+@end itemize
+
+@node Elaboration-related Compiler Switches,Summary of Procedures for Elaboration Control,Resolving Elaboration Circularities,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-related-compiler-switches}@anchor{22c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{22d}
+@section Elaboration-related Compiler Switches
+
+
+GNAT has several switches that affect the elaboration model and consequently
+the elaboration order chosen by the binder.
+
+@geindex -gnatE (gnat)
+
+
+@table @asis
+
+@item @code{-gnatE}
+
+Dynamic elaboration checking mode enabled
+
+When this switch is in effect, GNAT activates the dynamic model.
+@end table
+
+@geindex -gnatel (gnat)
+
+
+@table @asis
+
+@item @code{-gnatel}
+
+Turn on info messages on generated Elaborate[_All] pragmas
+
+This switch is only applicable to the pre-20.x legacy elaboration models.
+The post-20.x elaboration model no longer relies on implicitly generated
+@code{Elaborate} and @code{Elaborate_All} pragmas to order units.
+
+When this switch is in effect, GNAT will emit the following supplementary
+information depending on the elaboration model in effect.
+
+
+@itemize -
+
+@item
+`Dynamic model'
+
+GNAT will indicate missing @code{Elaborate} and @code{Elaborate_All} pragmas for
+all library-level scenarios within the partition.
+
+@item
+`Static model'
+
+GNAT will indicate all scenarios invoked during elaboration. In addition,
+it will provide detailed traceback when an implicit @code{Elaborate} or
+@code{Elaborate_All} pragma is generated.
+
+@item
+`SPARK model'
+
+GNAT will indicate how an elaboration requirement is met by the context of
+a unit. This diagnostic requires compiler switch @code{-gnatd.v}.
+
+@example
+1. with Server; pragma Elaborate_All (Server);
+2. package Client with SPARK_Mode is
+3. Val : constant Integer := Server.Func;
+ |
+ >>> info: call to "Func" during elaboration in SPARK
+ >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1
+
+4. end Client;
+@end example
+@end itemize
+@end table
+
+@geindex -gnatH (gnat)
+
+
+@table @asis
+
+@item @code{-gnatH}
+
+Legacy elaboration checking mode enabled
+
+When this switch is in effect, GNAT will utilize the pre-18.x elaboration
+model.
+@end table
+
+@geindex -gnatJ (gnat)
+
+
+@table @asis
+
+@item @code{-gnatJ}
+
+Relaxed elaboration checking mode enabled
+
+When this switch is in effect, GNAT will not process certain scenarios,
+resulting in a more permissive elaboration model. Note that this may
+eliminate some diagnostics and run-time checks.
+@end table
+
+@geindex -gnatw.f (gnat)
+
+
+@table @asis
+
+@item @code{-gnatw.f}
+
+Turn on warnings for suspicious Subp’Access
+
+When this switch is in effect, GNAT will treat @code{'Access} of an entry,
+operator, or subprogram as a potential call to the target and issue warnings:
+
+@example
+ 1. package body Attribute_Call is
+ 2. function Func return Integer;
+ 3. type Func_Ptr is access function return Integer;
+ 4.
+ 5. Ptr : constant Func_Ptr := Func'Access;
+ |
+ >>> warning: "Access" attribute of "Func" before body seen
+ >>> warning: possible Program_Error on later references
+ >>> warning: body of unit "Attribute_Call" elaborated
+ >>> warning: "Access" of "Func" taken at line 5
+
+ 6.
+ 7. function Func return Integer is
+ 8. begin
+ 9. ...
+10. end Func;
+11. end Attribute_Call;
+@end example
+
+In the example above, the elaboration of declaration @code{Ptr} is assigned
+@code{Func'Access} before the body of @code{Func} has been elaborated.
+@end table
+
+@geindex -gnatwl (gnat)
+
+
+@table @asis
+
+@item @code{-gnatwl}
+
+Turn on warnings for elaboration problems
+
+When this switch is in effect, GNAT emits diagnostics in the form of warnings
+concerning various elaboration problems. The warnings are enabled by default.
+The switch is provided in case all warnings are suppressed, but elaboration
+warnings are still desired.
+
+@item @code{-gnatwL}
+
+Turn off warnings for elaboration problems
+
+When this switch is in effect, GNAT no longer emits any diagnostics in the
+form of warnings. Selective suppression of elaboration problems is possible
+using @code{pragma Warnings (Off)}.
+
+@example
+ 1. package body Selective_Suppression is
+ 2. function ABE return Integer;
+ 3.
+ 4. Val_1 : constant Integer := ABE;
+ |
+ >>> warning: cannot call "ABE" before body seen
+ >>> warning: Program_Error will be raised at run time
+
+ 5.
+ 6. pragma Warnings (Off);
+ 7. Val_2 : constant Integer := ABE;
+ 8. pragma Warnings (On);
+ 9.
+10. function ABE return Integer is
+11. begin
+12. ...
+13. end ABE;
+14. end Selective_Suppression;
+@end example
+
+Note that suppressing elaboration warnings does not eliminate run-time
+checks. The example above will still fail at run time with an ABE.
+@end table
+
+@node Summary of Procedures for Elaboration Control,Inspecting the Chosen Elaboration Order,Elaboration-related Compiler Switches,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{22f}
+@section Summary of Procedures for Elaboration Control
+
+
+A programmer should first compile the program with the default options, using
+none of the binder or compiler switches. If the binder succeeds in finding an
+elaboration order, then apart from possible cases involving dispatching calls
+and access-to-subprogram types, the program is free of elaboration errors.
+
+If it is important for the program to be portable to compilers other than GNAT,
+then the programmer should use compiler switch @code{-gnatel} and consider
+the messages about missing or implicitly created @code{Elaborate} and
+@code{Elaborate_All} pragmas.
+
+If the binder reports an elaboration circularity, the programmer has several
+options:
+
+
+@itemize *
+
+@item
+Ensure that elaboration warnings are enabled. This will allow the static
+model to output trace information of elaboration issues. The trace
+information could shed light on previously unforeseen dependencies, as well
+as their origins. Elaboration warnings are enabled with compiler switch
+@code{-gnatwl}.
+
+@item
+Cosider the tactics given in the suggestions section of the circularity
+diagnostic.
+
+@item
+If none of the steps outlined above resolve the circularity, use a more
+permissive elaboration model, in the following order:
+
+
+@itemize -
+
+@item
+Use the pre-20.x legacy elaboration-order model, with binder switch
+@code{-H}.
+
+@item
+Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
+switch @code{-gnatH} and binder switch @code{-H}.
+
+@item
+Use the relaxed static elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
+
+@item
+Use the relaxed dynamic elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
+@code{-H}.
+@end itemize
+@end itemize
+
+@node Inspecting the Chosen Elaboration Order,,Summary of Procedures for Elaboration Control,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{230}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{231}
+@section Inspecting the Chosen Elaboration Order
+
+
+To see the elaboration order chosen by the binder, inspect the contents of file
+@cite{b~xxx.adb}. On certain targets, this file appears as @cite{b_xxx.adb}. The
+elaboration order appears as a sequence of calls to @code{Elab_Body} and
+@code{Elab_Spec}, interspersed with assignments to @cite{Exxx} which indicates that a
+particular unit is elaborated. For example:
+
+@quotation
+
+@example
+System.Soft_Links'Elab_Body;
+E14 := True;
+System.Secondary_Stack'Elab_Body;
+E18 := True;
+System.Exception_Table'Elab_Body;
+E24 := True;
+Ada.Io_Exceptions'Elab_Spec;
+E67 := True;
+Ada.Tags'Elab_Spec;
+Ada.Streams'Elab_Spec;
+E43 := True;
+Interfaces.C'Elab_Spec;
+E69 := True;
+System.Finalization_Root'Elab_Spec;
+E60 := True;
+System.Os_Lib'Elab_Body;
+E71 := True;
+System.Finalization_Implementation'Elab_Spec;
+System.Finalization_Implementation'Elab_Body;
+E62 := True;
+Ada.Finalization'Elab_Spec;
+E58 := True;
+Ada.Finalization.List_Controller'Elab_Spec;
+E76 := True;
+System.File_Control_Block'Elab_Spec;
+E74 := True;
+System.File_Io'Elab_Body;
+E56 := True;
+Ada.Tags'Elab_Body;
+E45 := True;
+Ada.Text_Io'Elab_Spec;
+Ada.Text_Io'Elab_Body;
+E07 := True;
+@end example
+@end quotation
+
+Note also binder switch @code{-l}, which outputs the chosen elaboration
+order and provides a more readable form of the above:
+
+@quotation
+
+@example
+ada (spec)
+interfaces (spec)
+system (spec)
+system.case_util (spec)
+system.case_util (body)
+system.concat_2 (spec)
+system.concat_2 (body)
+system.concat_3 (spec)
+system.concat_3 (body)
+system.htable (spec)
+system.parameters (spec)
+system.parameters (body)
+system.crtl (spec)
+interfaces.c_streams (spec)
+interfaces.c_streams (body)
+system.restrictions (spec)
+system.restrictions (body)
+system.standard_library (spec)
+system.exceptions (spec)
+system.exceptions (body)
+system.storage_elements (spec)
+system.storage_elements (body)
+system.secondary_stack (spec)
+system.stack_checking (spec)
+system.stack_checking (body)
+system.string_hash (spec)
+system.string_hash (body)
+system.htable (body)
+system.strings (spec)
+system.strings (body)
+system.traceback (spec)
+system.traceback (body)
+system.traceback_entries (spec)
+system.traceback_entries (body)
+ada.exceptions (spec)
+ada.exceptions.last_chance_handler (spec)
+system.soft_links (spec)
+system.soft_links (body)
+ada.exceptions.last_chance_handler (body)
+system.secondary_stack (body)
+system.exception_table (spec)
+system.exception_table (body)
+ada.io_exceptions (spec)
+ada.tags (spec)
+ada.streams (spec)
+interfaces.c (spec)
+interfaces.c (body)
+system.finalization_root (spec)
+system.finalization_root (body)
+system.memory (spec)
+system.memory (body)
+system.standard_library (body)
+system.os_lib (spec)
+system.os_lib (body)
+system.unsigned_types (spec)
+system.stream_attributes (spec)
+system.stream_attributes (body)
+system.finalization_implementation (spec)
+system.finalization_implementation (body)
+ada.finalization (spec)
+ada.finalization (body)
+ada.finalization.list_controller (spec)
+ada.finalization.list_controller (body)
+system.file_control_block (spec)
+system.file_io (spec)
+system.file_io (body)
+system.val_uns (spec)
+system.val_util (spec)
+system.val_util (body)
+system.val_uns (body)
+system.wch_con (spec)
+system.wch_con (body)
+system.wch_cnv (spec)
+system.wch_jis (spec)
+system.wch_jis (body)
+system.wch_cnv (body)
+system.wch_stw (spec)
+system.wch_stw (body)
+ada.tags (body)
+ada.exceptions (body)
+ada.text_io (spec)
+ada.text_io (body)
+text_io (spec)
+gdbstr (body)
+@end example
+@end quotation
+
+@node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top
+@anchor{gnat_ugn/inline_assembler doc}@anchor{232}@anchor{gnat_ugn/inline_assembler id1}@anchor{233}@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}
+@chapter Inline Assembler
+
+
+@geindex Inline Assembler
+
+If you need to write low-level software that interacts directly
+with the hardware, Ada provides two ways to incorporate assembly
+language code into your program. First, you can import and invoke
+external routines written in assembly language, an Ada feature fully
+supported by GNAT. However, for small sections of code it may be simpler
+or more efficient to include assembly language statements directly
+in your Ada source program, using the facilities of the implementation-defined
+package @code{System.Machine_Code}, which incorporates the gcc
+Inline Assembler. The Inline Assembler approach offers a number of advantages,
+including the following:
+
+
+@itemize *
+
+@item
+No need to use non-Ada tools
+
+@item
+Consistent interface over different targets
+
+@item
+Automatic usage of the proper calling conventions
+
+@item
+Access to Ada constants and variables
+
+@item
+Definition of intrinsic routines
+
+@item
+Possibility of inlining a subprogram comprising assembler code
+
+@item
+Code optimizer can take Inline Assembler code into account
+@end itemize
+
+This appendix presents a series of examples to show you how to use
+the Inline Assembler. Although it focuses on the Intel x86,
+the general approach applies also to other processors.
+It is assumed that you are familiar with Ada
+and with assembly language programming.
+
+@menu
+* Basic Assembler Syntax::
+* A Simple Example of Inline Assembler::
+* Output Variables in Inline Assembler::
+* Input Variables in Inline Assembler::
+* Inlining Inline Assembler Code::
+* Other Asm Functionality::
+
+@end menu
+
+@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler
+@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{234}@anchor{gnat_ugn/inline_assembler id2}@anchor{235}
+@section Basic Assembler Syntax
+
+
+The assembler used by GNAT and gcc is based not on the Intel assembly
+language, but rather on a language that descends from the AT&T Unix
+assembler @code{as} (and which is often referred to as ‘AT&T syntax’).
+The following table summarizes the main features of @code{as} syntax
+and points out the differences from the Intel conventions.
+See the gcc @code{as} and @code{gas} (an @code{as} macro
+pre-processor) documentation for further information.
+
+
+@display
+`Register names'@w{ }
+@display
+gcc / @code{as}: Prefix with ‘%’; for example @code{%eax}@w{ }
+Intel: No extra punctuation; for example @code{eax}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Immediate operand'@w{ }
+@display
+gcc / @code{as}: Prefix with ‘$’; for example @code{$4}@w{ }
+Intel: No extra punctuation; for example @code{4}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Address'@w{ }
+@display
+gcc / @code{as}: Prefix with ‘$’; for example @code{$loc}@w{ }
+Intel: No extra punctuation; for example @code{loc}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Memory contents'@w{ }
+@display
+gcc / @code{as}: No extra punctuation; for example @code{loc}@w{ }
+Intel: Square brackets; for example @code{[loc]}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Register contents'@w{ }
+@display
+gcc / @code{as}: Parentheses; for example @code{(%eax)}@w{ }
+Intel: Square brackets; for example @code{[eax]}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Hexadecimal numbers'@w{ }
+@display
+gcc / @code{as}: Leading ‘0x’ (C language syntax); for example @code{0xA0}@w{ }
+Intel: Trailing ‘h’; for example @code{A0h}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Operand size'@w{ }
+@display
+gcc / @code{as}: Explicit in op code; for example @code{movw} to move a 16-bit word@w{ }
+Intel: Implicit, deduced by assembler; for example @code{mov}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Instruction repetition'@w{ }
+@display
+gcc / @code{as}: Split into two lines; for example@w{ }
+@display
+@code{rep}@w{ }
+@code{stosl}@w{ }
+@end display
+Intel: Keep on one line; for example @code{rep stosl}@w{ }
+@end display
+@end display
+
+
+
+
+@display
+`Order of operands'@w{ }
+@display
+gcc / @code{as}: Source first; for example @code{movw $4, %eax}@w{ }
+Intel: Destination first; for example @code{mov eax, 4}@w{ }
+@end display
+@end display
+
+
+
+@node A Simple Example of Inline Assembler,Output Variables in Inline Assembler,Basic Assembler Syntax,Inline Assembler
+@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{236}@anchor{gnat_ugn/inline_assembler id3}@anchor{237}
+@section A Simple Example of Inline Assembler
+
+
+The following example will generate a single assembly language statement,
+@code{nop}, which does nothing. Despite its lack of run-time effect,
+the example will be useful in illustrating the basics of
+the Inline Assembler facility.
+
+@quotation
+
+@example
+with System.Machine_Code; use System.Machine_Code;
+procedure Nothing is
+begin
+ Asm ("nop");
+end Nothing;
+@end example
+@end quotation
+
+@code{Asm} is a procedure declared in package @code{System.Machine_Code};
+here it takes one parameter, a `template string' that must be a static
+expression and that will form the generated instruction.
+@code{Asm} may be regarded as a compile-time procedure that parses
+the template string and additional parameters (none here),
+from which it generates a sequence of assembly language instructions.
+
+The examples in this chapter will illustrate several of the forms
+for invoking @code{Asm}; a complete specification of the syntax
+is found in the @code{Machine_Code_Insertions} section of the
+@cite{GNAT Reference Manual}.
+
+Under the standard GNAT conventions, the @code{Nothing} procedure
+should be in a file named @code{nothing.adb}.
+You can build the executable in the usual way:
+
+@quotation
+
+@example
+$ gnatmake nothing
+@end example
+@end quotation
+
+However, the interesting aspect of this example is not its run-time behavior
+but rather the generated assembly code.
+To see this output, invoke the compiler as follows:
+
+@quotation
+
+@example
+$ gcc -c -S -fomit-frame-pointer -gnatp nothing.adb
+@end example
+@end quotation
+
+where the options are:
+
+
+@itemize *
+
+@item
+
+@table @asis
+
+@item @code{-c}
+
+compile only (no bind or link)
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-S}
+
+generate assembler listing
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-fomit-frame-pointer}
+
+do not set up separate stack frames
+@end table
+
+@item
+
+@table @asis
+
+@item @code{-gnatp}
+
+do not add runtime checks
+@end table
+@end itemize
+
+This gives a human-readable assembler version of the code. The resulting
+file will have the same name as the Ada source file, but with a @code{.s}
+extension. In our example, the file @code{nothing.s} has the following
+contents:
+
+@quotation
+
+@example
+.file "nothing.adb"
+gcc2_compiled.:
+___gnu_compiled_ada:
+.text
+ .align 4
+.globl __ada_nothing
+__ada_nothing:
+#APP
+ nop
+#NO_APP
+ jmp L1
+ .align 2,0x90
+L1:
+ ret
+@end example
+@end quotation
+
+The assembly code you included is clearly indicated by
+the compiler, between the @code{#APP} and @code{#NO_APP}
+delimiters. The character before the ‘APP’ and ‘NOAPP’
+can differ on different targets. For example, GNU/Linux uses ‘#APP’ while
+on NT you will see ‘/APP’.
+
+If you make a mistake in your assembler code (such as using the
+wrong size modifier, or using a wrong operand for the instruction) GNAT
+will report this error in a temporary file, which will be deleted when
+the compilation is finished. Generating an assembler file will help
+in such cases, since you can assemble this file separately using the
+@code{as} assembler that comes with gcc.
+
+Assembling the file using the command
+
+@quotation
+
+@example
+$ as nothing.s
+@end example
+@end quotation
+
+will give you error messages whose lines correspond to the assembler
+input file, so you can easily find and correct any mistakes you made.
+If there are no errors, @code{as} will generate an object file
+@code{nothing.out}.
+
+@node Output Variables in Inline Assembler,Input Variables in Inline Assembler,A Simple Example of Inline Assembler,Inline Assembler
+@anchor{gnat_ugn/inline_assembler id4}@anchor{238}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{239}
+@section Output Variables in Inline Assembler
+
+
+The examples in this section, showing how to access the processor flags,
+illustrate how to specify the destination operands for assembly language
+statements.
+
+@quotation
+
+@example
+with Interfaces; use Interfaces;
+with Ada.Text_IO; use Ada.Text_IO;
+with System.Machine_Code; use System.Machine_Code;
+procedure Get_Flags is
+ Flags : Unsigned_32;
+ use ASCII;
+begin
+ Asm ("pushfl" & LF & HT & -- push flags on stack
+ "popl %%eax" & LF & HT & -- load eax with flags
+ "movl %%eax, %0", -- store flags in variable
+ Outputs => Unsigned_32'Asm_Output ("=g", Flags));
+ Put_Line ("Flags register:" & Flags'Img);
+end Get_Flags;
+@end example
+@end quotation
+
+In order to have a nicely aligned assembly listing, we have separated
+multiple assembler statements in the Asm template string with linefeed
+(ASCII.LF) and horizontal tab (ASCII.HT) characters.
+The resulting section of the assembly output file is:
+
+@quotation
+
+@example
+#APP
+ pushfl
+ popl %eax
+ movl %eax, -40(%ebp)
+#NO_APP
+@end example
+@end quotation
+
+It would have been legal to write the Asm invocation as:
+
+@quotation
+
+@example
+Asm ("pushfl popl %%eax movl %%eax, %0")
+@end example
+@end quotation
+
+but in the generated assembler file, this would come out as:
+
+@quotation
+
+@example
+#APP
+ pushfl popl %eax movl %eax, -40(%ebp)
+#NO_APP
+@end example
+@end quotation
+
+which is not so convenient for the human reader.
+
+We use Ada comments
+at the end of each line to explain what the assembler instructions
+actually do. This is a useful convention.
+
+When writing Inline Assembler instructions, you need to precede each register
+and variable name with a percent sign. Since the assembler already requires
+a percent sign at the beginning of a register name, you need two consecutive
+percent signs for such names in the Asm template string, thus @code{%%eax}.
+In the generated assembly code, one of the percent signs will be stripped off.
+
+Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output
+variables: operands you later define using @code{Input} or @code{Output}
+parameters to @code{Asm}.
+An output variable is illustrated in
+the third statement in the Asm template string:
+
+@quotation
+
+@example
+movl %%eax, %0
+@end example
+@end quotation
+
+The intent is to store the contents of the eax register in a variable that can
+be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not
+necessarily work, since the compiler might optimize by using a register
+to hold Flags, and the expansion of the @code{movl} instruction would not be
+aware of this optimization. The solution is not to store the result directly
+but rather to advise the compiler to choose the correct operand form;
+that is the purpose of the @code{%0} output variable.
+
+Information about the output variable is supplied in the @code{Outputs}
+parameter to @code{Asm}:
+
+@quotation
+
+@example
+Outputs => Unsigned_32'Asm_Output ("=g", Flags));
+@end example
+@end quotation
+
+The output is defined by the @code{Asm_Output} attribute of the target type;
+the general format is
+
+@quotation
+
+@example
+Type'Asm_Output (constraint_string, variable_name)
+@end example
+@end quotation
+
+The constraint string directs the compiler how
+to store/access the associated variable. In the example
+
+@quotation
+
+@example
+Unsigned_32'Asm_Output ("=m", Flags);
+@end example
+@end quotation
+
+the @code{"m"} (memory) constraint tells the compiler that the variable
+@code{Flags} should be stored in a memory variable, thus preventing
+the optimizer from keeping it in a register. In contrast,
+
+@quotation
+
+@example
+Unsigned_32'Asm_Output ("=r", Flags);
+@end example
+@end quotation
+
+uses the @code{"r"} (register) constraint, telling the compiler to
+store the variable in a register.
+
+If the constraint is preceded by the equal character ‘=’, it tells
+the compiler that the variable will be used to store data into it.
+
+In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint,
+allowing the optimizer to choose whatever it deems best.
+
+There are a fairly large number of constraints, but the ones that are
+most useful (for the Intel x86 processor) are the following:
+
+@quotation
+
+
+@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
+
+`='
+
+@tab
+
+output constraint
+
+@item
+
+`g'
+
+@tab
+
+global (i.e., can be stored anywhere)
+
+@item
+
+`m'
+
+@tab
+
+in memory
+
+@item
+
+`I'
+
+@tab
+
+a constant
+
+@item
+
+`a'
+
+@tab
+
+use eax
+
+@item
+
+`b'
+
+@tab
+
+use ebx
+
+@item
+
+`c'
+
+@tab
+
+use ecx
+
+@item
+
+`d'
+
+@tab
+
+use edx
+
+@item
+
+`S'
+
+@tab
+
+use esi
+
+@item
+
+`D'
+
+@tab
+
+use edi
+
+@item
+
+`r'
+
+@tab
+
+use one of eax, ebx, ecx or edx
+
+@item
+
+`q'
+
+@tab
+
+use one of eax, ebx, ecx, edx, esi or edi
+
+@end multitable
+
+@end quotation
+
+The full set of constraints is described in the gcc and @code{as}
+documentation; note that it is possible to combine certain constraints
+in one constraint string.
+
+You specify the association of an output variable with an assembler operand
+through the @code{%@var{n}} notation, where `n' is a non-negative
+integer. Thus in
+
+@quotation
+
+@example
+Asm ("pushfl" & LF & HT & -- push flags on stack
+ "popl %%eax" & LF & HT & -- load eax with flags
+ "movl %%eax, %0", -- store flags in variable
+ Outputs => Unsigned_32'Asm_Output ("=g", Flags));
+@end example
+@end quotation
+
+@code{%0} will be replaced in the expanded code by the appropriate operand,
+whatever
+the compiler decided for the @code{Flags} variable.
+
+In general, you may have any number of output variables:
+
+
+@itemize *
+
+@item
+Count the operands starting at 0; thus @code{%0}, @code{%1}, etc.
+
+@item
+Specify the @code{Outputs} parameter as a parenthesized comma-separated list
+of @code{Asm_Output} attributes
+@end itemize
+
+For example:
+
+@quotation
+
+@example
+Asm ("movl %%eax, %0" & LF & HT &
+ "movl %%ebx, %1" & LF & HT &
+ "movl %%ecx, %2",
+ Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A
+ Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B
+ Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C
+@end example
+@end quotation
+
+where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables
+in the Ada program.
+
+As a variation on the @code{Get_Flags} example, we can use the constraints
+string to direct the compiler to store the eax register into the @code{Flags}
+variable, instead of including the store instruction explicitly in the
+@code{Asm} template string:
+
+@quotation
+
+@example
+with Interfaces; use Interfaces;
+with Ada.Text_IO; use Ada.Text_IO;
+with System.Machine_Code; use System.Machine_Code;
+procedure Get_Flags_2 is
+ Flags : Unsigned_32;
+ use ASCII;
+begin
+ Asm ("pushfl" & LF & HT & -- push flags on stack
+ "popl %%eax", -- save flags in eax
+ Outputs => Unsigned_32'Asm_Output ("=a", Flags));
+ Put_Line ("Flags register:" & Flags'Img);
+end Get_Flags_2;
+@end example
+@end quotation
+
+The @code{"a"} constraint tells the compiler that the @code{Flags}
+variable will come from the eax register. Here is the resulting code:
+
+@quotation
+
+@example
+#APP
+ pushfl
+ popl %eax
+#NO_APP
+ movl %eax,-40(%ebp)
+@end example
+@end quotation
+
+The compiler generated the store of eax into Flags after
+expanding the assembler code.
+
+Actually, there was no need to pop the flags into the eax register;
+more simply, we could just pop the flags directly into the program variable:
+
+@quotation
+
+@example
+with Interfaces; use Interfaces;
+with Ada.Text_IO; use Ada.Text_IO;
+with System.Machine_Code; use System.Machine_Code;
+procedure Get_Flags_3 is
+ Flags : Unsigned_32;
+ use ASCII;
+begin
+ Asm ("pushfl" & LF & HT & -- push flags on stack
+ "pop %0", -- save flags in Flags
+ Outputs => Unsigned_32'Asm_Output ("=g", Flags));
+ Put_Line ("Flags register:" & Flags'Img);
+end Get_Flags_3;
+@end example
+@end quotation
+
+@node Input Variables in Inline Assembler,Inlining Inline Assembler Code,Output Variables in Inline Assembler,Inline Assembler
+@anchor{gnat_ugn/inline_assembler id5}@anchor{23a}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{23b}
+@section Input Variables in Inline Assembler
+
+
+The example in this section illustrates how to specify the source operands
+for assembly language statements.
+The program simply increments its input value by 1:
+
+@quotation
+
+@example
+with Interfaces; use Interfaces;
+with Ada.Text_IO; use Ada.Text_IO;
+with System.Machine_Code; use System.Machine_Code;
+procedure Increment is
+
+ function Incr (Value : Unsigned_32) return Unsigned_32 is
+ Result : Unsigned_32;
+ begin
+ Asm ("incl %0",
+ Outputs => Unsigned_32'Asm_Output ("=a", Result),
+ Inputs => Unsigned_32'Asm_Input ("a", Value));
+ return Result;
+ end Incr;
+
+ Value : Unsigned_32;
+
+begin
+ Value := 5;
+ Put_Line ("Value before is" & Value'Img);
+ Value := Incr (Value);
+ Put_Line ("Value after is" & Value'Img);
+end Increment;
+@end example
+@end quotation
+
+The @code{Outputs} parameter to @code{Asm} specifies
+that the result will be in the eax register and that it is to be stored
+in the @code{Result} variable.
+
+The @code{Inputs} parameter looks much like the @code{Outputs} parameter,
+but with an @code{Asm_Input} attribute.
+The @code{"="} constraint, indicating an output value, is not present.
+
+You can have multiple input variables, in the same way that you can have more
+than one output variable.
+
+The parameter count (%0, %1) etc, still starts at the first output statement,
+and continues with the input statements.
+
+Just as the @code{Outputs} parameter causes the register to be stored into the
+target variable after execution of the assembler statements, so does the
+@code{Inputs} parameter cause its variable to be loaded into the register
+before execution of the assembler statements.
+
+Thus the effect of the @code{Asm} invocation is:
+
+
+@itemize *
+
+@item
+load the 32-bit value of @code{Value} into eax
+
+@item
+execute the @code{incl %eax} instruction
+
+@item
+store the contents of eax into the @code{Result} variable
+@end itemize
+
+The resulting assembler file (with @code{-O2} optimization) contains:
+
+@quotation
+
+@example
+_increment__incr.1:
+ subl $4,%esp
+ movl 8(%esp),%eax
+#APP
+ incl %eax
+#NO_APP
+ movl %eax,%edx
+ movl %ecx,(%esp)
+ addl $4,%esp
+ ret
+@end example
+@end quotation
+
+@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler
+@anchor{gnat_ugn/inline_assembler id6}@anchor{23c}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{23d}
+@section Inlining Inline Assembler Code
+
+
+For a short subprogram such as the @code{Incr} function in the previous
+section, the overhead of the call and return (creating / deleting the stack
+frame) can be significant, compared to the amount of code in the subprogram
+body. A solution is to apply Ada’s @code{Inline} pragma to the subprogram,
+which directs the compiler to expand invocations of the subprogram at the
+point(s) of call, instead of setting up a stack frame for out-of-line calls.
+Here is the resulting program:
+
+@quotation
+
+@example
+with Interfaces; use Interfaces;
+with Ada.Text_IO; use Ada.Text_IO;
+with System.Machine_Code; use System.Machine_Code;
+procedure Increment_2 is
+
+ function Incr (Value : Unsigned_32) return Unsigned_32 is
+ Result : Unsigned_32;
+ begin
+ Asm ("incl %0",
+ Outputs => Unsigned_32'Asm_Output ("=a", Result),
+ Inputs => Unsigned_32'Asm_Input ("a", Value));
+ return Result;
+ end Incr;
+ pragma Inline (Increment);
+
+ Value : Unsigned_32;
+
+begin
+ Value := 5;
+ Put_Line ("Value before is" & Value'Img);
+ Value := Increment (Value);
+ Put_Line ("Value after is" & Value'Img);
+end Increment_2;
+@end example
+@end quotation
+
+Compile the program with both optimization (@code{-O2}) and inlining
+(@code{-gnatn}) enabled.
+
+The @code{Incr} function is still compiled as usual, but at the
+point in @code{Increment} where our function used to be called:
+
+@quotation
+
+@example
+pushl %edi
+call _increment__incr.1
+@end example
+@end quotation
+
+the code for the function body directly appears:
+
+@quotation
+
+@example
+movl %esi,%eax
+#APP
+ incl %eax
+#NO_APP
+ movl %eax,%edx
+@end example
+@end quotation
+
+thus saving the overhead of stack frame setup and an out-of-line call.
+
+@node Other Asm Functionality,,Inlining Inline Assembler Code,Inline Assembler
+@anchor{gnat_ugn/inline_assembler id7}@anchor{23e}@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{23f}
+@section Other @code{Asm} Functionality
+
+
+This section describes two important parameters to the @code{Asm}
+procedure: @code{Clobber}, which identifies register usage;
+and @code{Volatile}, which inhibits unwanted optimizations.
+
+@menu
+* The Clobber Parameter::
+* The Volatile Parameter::
+
+@end menu
+
+@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality
+@anchor{gnat_ugn/inline_assembler id8}@anchor{240}@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{241}
+@subsection The @code{Clobber} Parameter
+
+
+One of the dangers of intermixing assembly language and a compiled language
+such as Ada is that the compiler needs to be aware of which registers are
+being used by the assembly code. In some cases, such as the earlier examples,
+the constraint string is sufficient to indicate register usage (e.g.,
+@code{"a"} for
+the eax register). But more generally, the compiler needs an explicit
+identification of the registers that are used by the Inline Assembly
+statements.
+
+Using a register that the compiler doesn’t know about
+could be a side effect of an instruction (like @code{mull}
+storing its result in both eax and edx).
+It can also arise from explicit register usage in your
+assembly code; for example:
+
+@quotation
+
+@example
+Asm ("movl %0, %%ebx" & LF & HT &
+ "movl %%ebx, %1",
+ Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
+ Inputs => Unsigned_32'Asm_Input ("g", Var_In));
+@end example
+@end quotation
+
+where the compiler (since it does not analyze the @code{Asm} template string)
+does not know you are using the ebx register.
+
+In such cases you need to supply the @code{Clobber} parameter to @code{Asm},
+to identify the registers that will be used by your assembly code:
+
+@quotation
+
+@example
+Asm ("movl %0, %%ebx" & LF & HT &
+ "movl %%ebx, %1",
+ Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
+ Inputs => Unsigned_32'Asm_Input ("g", Var_In),
+ Clobber => "ebx");
+@end example
+@end quotation
+
+The Clobber parameter is a static string expression specifying the
+register(s) you are using. Note that register names are `not' prefixed
+by a percent sign. Also, if more than one register is used then their names
+are separated by commas; e.g., @code{"eax, ebx"}
+
+The @code{Clobber} parameter has several additional uses:
+
+
+@itemize *
+
+@item
+Use ‘register’ name @code{cc} to indicate that flags might have changed
+
+@item
+Use ‘register’ name @code{memory} if you changed a memory location
+@end itemize
+
+@node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality
+@anchor{gnat_ugn/inline_assembler id9}@anchor{242}@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{243}
+@subsection The @code{Volatile} Parameter
+
+
+@geindex Volatile parameter
+
+Compiler optimizations in the presence of Inline Assembler may sometimes have
+unwanted effects. For example, when an @code{Asm} invocation with an input
+variable is inside a loop, the compiler might move the loading of the input
+variable outside the loop, regarding it as a one-time initialization.
+
+If this effect is not desired, you can disable such optimizations by setting
+the @code{Volatile} parameter to @code{True}; for example:
+
+@quotation
+
+@example
+Asm ("movl %0, %%ebx" & LF & HT &
+ "movl %%ebx, %1",
+ Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
+ Inputs => Unsigned_32'Asm_Input ("g", Var_In),
+ Clobber => "ebx",
+ Volatile => True);
+@end example
+@end quotation
+
+By default, @code{Volatile} is set to @code{False} unless there is no
+@code{Outputs} parameter.
+
+Although setting @code{Volatile} to @code{True} prevents unwanted
+optimizations, it will also disable other optimizations that might be
+important for efficiency. In general, you should set @code{Volatile}
+to @code{True} only if the compiler’s optimizations have created
+problems.
+
+@node GNU Free Documentation License,Index,Inline Assembler,Top
+@anchor{share/gnu_free_documentation_license doc}@anchor{244}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{245}
+@chapter GNU Free Documentation License
+
+
+Version 1.3, 3 November 2008
+
+Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc
+@indicateurl{https://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+`Preamble'
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document “free” in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of “copyleft”, which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+`1. APPLICABILITY AND DEFINITIONS'
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The `Document', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as “`you'”. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A “`Modified Version'” of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A “`Secondary Section'” is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document’s overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The “`Invariant Sections'” are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The “`Cover Texts'” are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A “`Transparent'” copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not “Transparent” is called `Opaque'.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification. Examples of
+transparent image formats include PNG, XCF and JPG. Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The “`Title Page'” means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, “Title Page” means
+the text near the most prominent appearance of the work’s title,
+preceding the beginning of the body of the text.
+
+The “`publisher'” means any person or entity that distributes
+copies of the Document to the public.
+
+A section “`Entitled XYZ'” means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as “`Acknowledgements'”,
+“`Dedications'”, “`Endorsements'”, or “`History'”.)
+To “`Preserve the Title'”
+of such a section when you modify the Document means that it remains a
+section “Entitled XYZ” according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+`2. VERBATIM COPYING'
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+`3. COPYING IN QUANTITY'
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document’s license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+`4. MODIFICATIONS'
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+
+@enumerate A
+
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document’s license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled “History”, Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled “History” in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the “History” section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled “Acknowledgements” or “Dedications”,
+Preserve the Title of the section, and preserve in the section all
+the substance and tone of each of the contributor acknowledgements
+and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled “Endorsements”. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled “Endorsements”
+or to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version’s license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled “Endorsements”, provided it contains
+nothing but endorsements of your Modified Version by various
+parties—for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+`5. COMBINING DOCUMENTS'
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled “History”
+in the various original documents, forming one section Entitled
+“History”; likewise combine any sections Entitled “Acknowledgements”,
+and any sections Entitled “Dedications”. You must delete all sections
+Entitled “Endorsements”.
+
+`6. COLLECTIONS OF DOCUMENTS'
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+`7. AGGREGATION WITH INDEPENDENT WORKS'
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an “aggregate” if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation’s users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document’s Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+`8. TRANSLATION'
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled “Acknowledgements”,
+“Dedications”, or “History”, the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+`9. TERMINATION'
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+`10. FUTURE REVISIONS OF THIS LICENSE'
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@indicateurl{https://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License “or any later version” applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy’s public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+`11. RELICENSING'
+
+“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+“Massive Multiauthor Collaboration” (or “MMC”) contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+“Incorporate” means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is “eligible for relicensing” if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+`ADDENDUM: How to use this License for your documents'
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@quotation
+
+Copyright © YEAR YOUR NAME.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled “GNU
+Free Documentation License”.
+@end quotation
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the “with … Texts.” line with this:
+
+@quotation
+
+with the Invariant Sections being LIST THEIR TITLES, with the
+Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+@end quotation
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@node Index,,GNU Free Documentation License,Top
+@unnumbered Index
+
+
+@printindex ge
+
+@anchor{cf}@w{ }
+@anchor{gnat_ugn/gnat_utility_programs switches-related-to-project-files}@w{ }
+
+@c %**end of body
+@bye
projects / thirdparty / gcc.git / commitdiff
