blob: 129da895e09f3bb25cf3e2b0920dc26737d51165 [file] [log] [blame]
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gnat_rm.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 4.0.2.@*
@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
@definfoenclose strong,`,'
@definfoenclose emph,`,'
@c %**end of header
@copying
@quotation
GNAT Reference Manual , Oct 25, 2021
AdaCore
Copyright @copyright{} 2008-2021, 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}
@emph{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 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 Compiler_Unit::
* Pragma Compiler_Unit_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 Lock_Free::
* 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_Image::
* 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_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_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.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads.
* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads.
* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads.
* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads.
* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads.
* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads.
* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads.
* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads.
* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads.
* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma 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.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.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::
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 @emph{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
@emph{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 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 Compiler_Unit::
* Pragma Compiler_Unit_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 [=> boolean_EXPRESSION]
| Async_Writers [=> boolean_EXPRESSION]
| Effective_Reads [=> boolean_EXPRESSION]
| Effective_Writes [=> boolean_EXPRESSION]
others => 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 Aggregate_Individually_Assign,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 Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2012,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{25}
@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{26}
@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{27}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{28}
@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{29}
@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 @emph{-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{2a}
@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{2b}
@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 @emph{-gnata} switch on the
command line.
If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default,
however, if the @emph{-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{2c}
@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{2d}
@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{2e}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{2f}
@section Pragma Async_Readers
Syntax:
@example
pragma Async_Readers [ (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{30}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{31}
@section Pragma Async_Writers
Syntax:
@example
pragma Async_Writers [ (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{32}
@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{33}
@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{34}
@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 @emph{-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{35}
@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 @emph{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 @emph{-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{36}
@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{37}
@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
@emph{-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{38}
@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{39}
@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{3a}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3b}
@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 Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3c}
@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 @emph{-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 @emph{-gnatwe} with
Compile_Time_Warning resulted in a fatal error. Now the compiler always emits
a warning. You can use @ref{3a,,Pragma Compile_Time_Error} to force the generation of
an error.
@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3d}
@section Pragma Compiler_Unit
Syntax:
@example
pragma Compiler_Unit;
@end example
This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is
retained so that old versions of the GNAT run-time that use this pragma can
be compiled with newer versions of the compiler.
@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{3e}
@section Pragma Compiler_Unit_Warning
Syntax:
@example
pragma Compiler_Unit_Warning;
@end example
This pragma is intended only for internal use in the GNAT run-time library.
It indicates that the unit is used as part of the compiler build. The effect
is to generate warnings for the use of constructs (for example, conditional
expressions) that would cause trouble when bootstrapping using an older
version of GNAT. For the exact list of restrictions, see the compiler sources
and references to Check_Compiler_Unit.
@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3f}
@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{40}
@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{41}
@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 @emph{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 @emph{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 @emph{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 @emph{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{42}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{43}
@section Pragma Constant_After_Elaboration
Syntax:
@example
pragma Constant_After_Elaboration [ (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{44}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{45}
@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{46}
@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{47}
@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{48,,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{49}
@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
@strong{function} @code{Fname} @strong{return} T`
@item
@strong{function} @code{Fname} @strong{return} T’Class
@item
@strong{function} @code{Fname} (…) @strong{return} T`
@item
@strong{function} @code{Fname} (…) @strong{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{48,,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{4a}
@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 compoatibility 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{48,,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{4b}
@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{48,,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{4c}
@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{4d}
@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{4e}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4f}
@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{50}
@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 @emph{-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{51}
@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{52}
@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 @emph{L} have @cite{Low_Order_First} scalar
storage order, and record types with names starting with @emph{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{53}
@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{54}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{55}
@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{56}
@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{57}
@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{58}
@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{59}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{5a}
@section Pragma Effective_Reads
Syntax:
@example
pragma Effective_Reads [ (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{5b}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5c}
@section Pragma Effective_Writes
Syntax:
@example
pragma Effective_Writes [ (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{5d}
@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 @emph{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{5e}
@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:
o Within @code{U}, or
o Within a generic package that is instantiated in @code{U}, or
o As an instance of generic subprogram instantiated in @code{U}.
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{5f}
@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{60}
@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{61}
@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{62}
@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{63}
@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{64}
@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_@emph{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.@emph{xxx}} where @emph{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_@emph{xxx}} where
@code{Aux_@emph{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 @emph{-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{65}
@section Pragma Extensions_Allowed
@geindex Ada Extensions
@geindex GNAT Extensions
Syntax:
@example
pragma Extensions_Allowed (On | Off);
@end example
This configuration pragma enables or disables the implementation
extension mode (the use of Off as a parameter cancels the effect
of the @emph{-gnatX} command switch).
In extension mode, the latest version of the Ada language is
implemented (currently Ada 2022), and in addition a number
of GNAT specific extensions are recognized as follows:
@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.
@item
@code{'Reduce} attribute
This attribute part of the Ada 202x language definition is provided for
now under -gnatX to confirm and potentially refine its usage and syntax.
@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