| \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 , Sep 28, 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 |
| overlaps the corresponding set of a later alternative, then the first |
| set shall be a proper subset of the second (and the later alternative |
| will not be executed if the earlier alternative “matches”). All possible |
| values of the composite type shall be covered. The composite type of the |
| selector shall be a nonlimited untagged (but possibly discriminated) |
| record type, all of whose subcomponent subtypes are either static discrete |
| subtypes or record types that meet the same restrictions. |
| |
| Support for casing on arrays (and on records that contain arrays) is |
| currently subject to some restrictions. Non-positional |
| array aggregates are not supported as (or within) case choices. Likewise |
| for array type and subtype names. The current implementation exceeds |
| compile-time capacity limits in some annoyingly common scenarios; the |
| message generated in such cases is usually “Capacity exceeded in compiling |
| case statement with composite selector type”. |
| |
| In addition, pattern bindings are supported. This is a mechanism |
| for binding a name to a component of a matching value for use within |
| an alternative of a case statement. For a component association |
| that occurs within a case choice, the expression may be followed by |
| “is <identifier>”. In the special case of a “box” component association, |
| the identifier may instead be provided within the box. Either of these |
| indicates that the given identifer denotes (a constant view of) the matching |
| subcomponent of the case selector. Binding is not yet supported for arrays |
| or subcomponents thereof. |
| |
| Consider this example (which uses type Rec from the previous example): |
| |
| @example |
| procedure Caser_2 (X : Rec) is |
| begin |
| case X is |
| when (F1 => Positive is Abc, F2 => Positive) => |
| Do_This (Abc) |
| when (F1 => Natural is N1, F2 => <N2>) | |
| (F1 => <N2>, F2 => Natural is N1) => |
| Do_That (Param_1 => N1, Param_2 => N2); |
| when others => |
| Do_The_Other_Thing; |
| end case; |
| end Caser_2; |
| @end example |
| |
| This example is the same as the previous one with respect to |
| determining whether Do_This, Do_That, or Do_The_Other_Thing will |
| be called. But for this version, Do_This takes a parameter and Do_That |
| takes two parameters. If Do_This is called, the actual parameter in the |
| call will be X.F1. |
| |
| If Do_That is called, the situation is more complex because there are two |
| choices for that alternative. If Do_That is called because the first choice |
| matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero |
| or negative), then the actual parameters of the call will be (in order) |
| X.F1 and X.F2. If Do_That is called because the second choice matched (and |
| the first one did not), then the actual parameters will be reversed. |
| |
| Within the choice list for single alternative, each choice must |
| define the same set of bindings and the component subtypes for |
| for a given identifer must all statically match. Currently, the case |
| of a binding for a nondiscrete component is not implemented. |
| |
| @item |
| Fixed lower bounds for array types and subtypes |
| |
| Unconstrained array types and subtypes can be specified with a lower bound |
| that is fixed to a certain value, by writing an index range that uses the |
| syntax “<lower-bound-expression> .. <>”. This guarantees that all objects |
| of the type or subtype will have the specified lower bound. |
| |
| For example, a matrix type with fixed lower bounds of zero for each |
| dimension can be declared by the following: |
| |
| @example |
| type Matrix is |
| array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; |
| @end example |
| |
| Objects of type Matrix declared with an index constraint must have index |
| ranges starting at zero: |
| |
| @example |
| M1 : Matrix (0 .. 9, 0 .. 19); |
| M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE |
| @end example |
| |
| Similarly, a subtype of String can be declared that specifies the lower |
| bound of objects of that subtype to be 1: |
| |
| @quotation |
| |
| @example |
| subtype String_1 is String (1 .. <>); |
| @end example |
| @end quotation |
| |
| If a string slice is passed to a formal of subtype String_1 in a call to |
| a subprogram S, the slice’s bounds will “slide” so that the lower bound |
| is 1. Within S, the lower bound of the formal is known to be 1, so, unlike |
| a normal unconstrained String formal, there is no need to worry about |
| accounting for other possible lower-bound values. Sliding of bounds also |
| occurs in other contexts, such as for object declarations with an |
| unconstrained subtype with fixed lower bound, as well as in subtype |
| conversions. |
| |
| Use of this feature increases safety by simplifying code, and can also |
| improve the efficiency of indexing operations, since the compiler statically |
| knows the lower bound of unconstrained array formals when the formal’s |
| subtype has index ranges with static fixed lower bounds. |
| |
| @item |
| Prefixed-view notation for calls to primitive subprograms of untagged types |
| |
| Since Ada 2005, calls to primitive subprograms of a tagged type that |
| have a “prefixed view” (see RM 4.1.3(9.2)) have been allowed to be |
| written using the form of a selected_component, with the first actual |
| parameter given as the prefix and the name of the subprogram as a |
| selector. This prefixed-view notation for calls is extended so as to |
| also allow such syntax for calls to primitive subprograms of untagged |
| types. The primitives of an untagged type T that have a prefixed view |
| are those where the first formal parameter of the subprogram either |
| is of type T or is an anonymous access parameter whose designated type |
| is T. For a type that has a component that happens to have the same |
| simple name as one of the type’s primitive subprograms, where the |
| component is visible at the point of a selected_component using that |
| name, preference is given to the component in a selected_component |
| (as is currently the case for tagged types with such component names). |
| @end itemize |
| |
| @node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{66}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{67} |
| @section Pragma Extensions_Visible |
| |
| |
| Syntax: |
| |
| @example |
| pragma Extensions_Visible [ (boolean_EXPRESSION) ]; |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} |
| in the SPARK 2014 Reference Manual, section 6.1.7. |
| |
| @node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{68} |
| @section Pragma External |
| |
| |
| Syntax: |
| |
| @example |
| pragma External ( |
| [ Convention =>] convention_IDENTIFIER, |
| [ Entity =>] LOCAL_NAME |
| [, [External_Name =>] static_string_EXPRESSION ] |
| [, [Link_Name =>] static_string_EXPRESSION ]); |
| @end example |
| |
| This pragma is identical in syntax and semantics to pragma |
| @code{Export} as defined in the Ada Reference Manual. It is |
| provided for compatibility with some Ada 83 compilers that |
| used this pragma for exactly the same purposes as pragma |
| @code{Export} before the latter was standardized. |
| |
| @node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{69} |
| @section Pragma External_Name_Casing |
| |
| |
| @geindex Dec Ada 83 casing compatibility |
| |
| @geindex External Names |
| @geindex casing |
| |
| @geindex Casing of External names |
| |
| Syntax: |
| |
| @example |
| pragma External_Name_Casing ( |
| Uppercase | Lowercase |
| [, Uppercase | Lowercase | As_Is]); |
| @end example |
| |
| This pragma provides control over the casing of external names associated |
| with Import and Export pragmas. There are two cases to consider: |
| |
| |
| @itemize * |
| |
| @item |
| Implicit external names |
| |
| Implicit external names are derived from identifiers. The most common case |
| arises when a standard Ada Import or Export pragma is used with only two |
| arguments, as in: |
| |
| @example |
| pragma Import (C, C_Routine); |
| @end example |
| |
| Since Ada is a case-insensitive language, the spelling of the identifier in |
| the Ada source program does not provide any information on the desired |
| casing of the external name, and so a convention is needed. In GNAT the |
| default treatment is that such names are converted to all lower case |
| letters. This corresponds to the normal C style in many environments. |
| The first argument of pragma @code{External_Name_Casing} can be used to |
| control this treatment. If @code{Uppercase} is specified, then the name |
| will be forced to all uppercase letters. If @code{Lowercase} is specified, |
| then the normal default of all lower case letters will be used. |
| |
| This same implicit treatment is also used in the case of extended DEC Ada 83 |
| compatible Import and Export pragmas where an external name is explicitly |
| specified using an identifier rather than a string. |
| |
| @item |
| Explicit external names |
| |
| Explicit external names are given as string literals. The most common case |
| arises when a standard Ada Import or Export pragma is used with three |
| arguments, as in: |
| |
| @example |
| pragma Import (C, C_Routine, "C_routine"); |
| @end example |
| |
| In this case, the string literal normally provides the exact casing required |
| for the external name. The second argument of pragma |
| @code{External_Name_Casing} may be used to modify this behavior. |
| If @code{Uppercase} is specified, then the name |
| will be forced to all uppercase letters. If @code{Lowercase} is specified, |
| then the name will be forced to all lowercase letters. A specification of |
| @code{As_Is} provides the normal default behavior in which the casing is |
| taken from the string provided. |
| @end itemize |
| |
| This pragma may appear anywhere that a pragma is valid. In particular, it |
| can be used as a configuration pragma in the @code{gnat.adc} file, in which |
| case it applies to all subsequent compilations, or it can be used as a program |
| unit pragma, in which case it only applies to the current unit, or it can |
| be used more locally to control individual Import/Export pragmas. |
| |
| It was primarily intended for use with OpenVMS systems, where many |
| compilers convert all symbols to upper case by default. For interfacing to |
| such compilers (e.g., the DEC C compiler), it may be convenient to use |
| the pragma: |
| |
| @example |
| pragma External_Name_Casing (Uppercase, Uppercase); |
| @end example |
| |
| to enforce the upper casing of all external symbols. |
| |
| @node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6a} |
| @section Pragma Fast_Math |
| |
| |
| Syntax: |
| |
| @example |
| pragma Fast_Math; |
| @end example |
| |
| This is a configuration pragma which activates a mode in which speed is |
| considered more important for floating-point operations than absolutely |
| accurate adherence to the requirements of the standard. Currently the |
| following operations are affected: |
| |
| |
| @table @asis |
| |
| @item @emph{Complex Multiplication} |
| |
| The normal simple formula for complex multiplication can result in intermediate |
| overflows for numbers near the end of the range. The Ada standard requires that |
| this situation be detected and corrected by scaling, but in Fast_Math mode such |
| cases will simply result in overflow. Note that to take advantage of this you |
| must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} |
| under control of the pragma, rather than use the preinstantiated versions. |
| @end table |
| |
| @node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6b}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6c} |
| @section Pragma Favor_Top_Level |
| |
| |
| Syntax: |
| |
| @example |
| pragma Favor_Top_Level (type_NAME); |
| @end example |
| |
| The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram |
| type. This pragma is an efficiency hint to the compiler, regarding the use of |
| @code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. |
| The pragma means that nested subprograms are not used with this type, or are |
| rare, so that the generated code should be efficient in the top-level case. |
| When this pragma is used, dynamically generated trampolines may be used on some |
| targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. |
| |
| @node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6d} |
| @section Pragma Finalize_Storage_Only |
| |
| |
| Syntax: |
| |
| @example |
| pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); |
| @end example |
| |
| The argument of pragma @code{Finalize_Storage_Only} must denote a local type which |
| is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The |
| pragma suppresses the call to @code{Finalize} for declared library-level objects |
| of the argument type. This is mostly useful for types where finalization is |
| only used to deal with storage reclamation since in most environments it is |
| not necessary to reclaim memory just before terminating execution, hence the |
| name. Note that this pragma does not suppress Finalize calls for library-level |
| heap-allocated objects (see pragma @code{No_Heap_Finalization}). |
| |
| @node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6e} |
| @section Pragma Float_Representation |
| |
| |
| Syntax: |
| |
| @example |
| pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); |
| |
| FLOAT_REP ::= VAX_Float | IEEE_Float |
| @end example |
| |
| In the one argument form, this pragma is a configuration pragma which |
| allows control over the internal representation chosen for the predefined |
| floating point types declared in the packages @code{Standard} and |
| @code{System}. This pragma is only provided for compatibility and has no effect. |
| |
| The two argument form specifies the representation to be used for |
| the specified floating-point type. The argument must |
| be @code{IEEE_Float} to specify the use of IEEE format, as follows: |
| |
| |
| @itemize * |
| |
| @item |
| For a digits value of 6, 32-bit IEEE short format will be used. |
| |
| @item |
| For a digits value of 15, 64-bit IEEE long format will be used. |
| |
| @item |
| No other value of digits is permitted. |
| @end itemize |
| |
| @node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6f}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{70} |
| @section Pragma Ghost |
| |
| |
| Syntax: |
| |
| @example |
| pragma Ghost [ (boolean_EXPRESSION) ]; |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK |
| 2014 Reference Manual, section 6.9. |
| |
| @node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{72} |
| @section Pragma Global |
| |
| |
| Syntax: |
| |
| @example |
| pragma Global (GLOBAL_SPECIFICATION); |
| |
| GLOBAL_SPECIFICATION ::= |
| null |
| | (GLOBAL_LIST) |
| | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) |
| |
| MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST |
| |
| MODE_SELECTOR ::= In_Out | Input | Output | Proof_In |
| GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) |
| GLOBAL_ITEM ::= NAME |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Global} in the |
| SPARK 2014 Reference Manual, section 6.1.4. |
| |
| @node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{73} |
| @section Pragma Ident |
| |
| |
| Syntax: |
| |
| @example |
| pragma Ident (static_string_EXPRESSION); |
| @end example |
| |
| This pragma is identical in effect to pragma @code{Comment}. It is provided |
| for compatibility with other Ada compilers providing this pragma. |
| |
| @node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{74} |
| @section Pragma Ignore_Pragma |
| |
| |
| Syntax: |
| |
| @example |
| pragma Ignore_Pragma (pragma_IDENTIFIER); |
| @end example |
| |
| This is a configuration pragma |
| that takes a single argument that is a simple identifier. Any subsequent |
| use of a pragma whose pragma identifier matches this argument will be |
| silently ignored. This may be useful when legacy code or code intended |
| for compilation with some other compiler contains pragmas that match the |
| name, but not the exact implementation, of a GNAT pragma. The use of this |
| pragma allows such pragmas to be ignored, which may be useful in CodePeer |
| mode, or during porting of legacy code. |
| |
| @node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{75} |
| @section Pragma Implementation_Defined |
| |
| |
| Syntax: |
| |
| @example |
| pragma Implementation_Defined (local_NAME); |
| @end example |
| |
| This pragma marks a previously declared entity as implementation-defined. |
| For an overloaded entity, applies to the most recent homonym. |
| |
| @example |
| pragma Implementation_Defined; |
| @end example |
| |
| The form with no arguments appears anywhere within a scope, most |
| typically a package spec, and indicates that all entities that are |
| defined within the package spec are Implementation_Defined. |
| |
| This pragma is used within the GNAT runtime library to identify |
| implementation-defined entities introduced in language-defined units, |
| for the purpose of implementing the No_Implementation_Identifiers |
| restriction. |
| |
| @node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{76} |
| @section Pragma Implemented |
| |
| |
| Syntax: |
| |
| @example |
| pragma Implemented (procedure_LOCAL_NAME, implementation_kind); |
| |
| implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any |
| @end example |
| |
| This is an Ada 2012 representation pragma which applies to protected, task |
| and synchronized interface primitives. The use of pragma Implemented provides |
| a way to impose a static requirement on the overriding operation by adhering |
| to one of the three implementation kinds: entry, protected procedure or any of |
| the above. This pragma is available in all earlier versions of Ada as an |
| implementation-defined pragma. |
| |
| @example |
| type Synch_Iface is synchronized interface; |
| procedure Prim_Op (Obj : in out Iface) is abstract; |
| pragma Implemented (Prim_Op, By_Protected_Procedure); |
| |
| protected type Prot_1 is new Synch_Iface with |
| procedure Prim_Op; -- Legal |
| end Prot_1; |
| |
| protected type Prot_2 is new Synch_Iface with |
| entry Prim_Op; -- Illegal |
| end Prot_2; |
| |
| task type Task_Typ is new Synch_Iface with |
| entry Prim_Op; -- Illegal |
| end Task_Typ; |
| @end example |
| |
| When applied to the procedure_or_entry_NAME of a requeue statement, pragma |
| Implemented determines the runtime behavior of the requeue. Implementation kind |
| By_Entry guarantees that the action of requeueing will proceed from an entry to |
| another entry. Implementation kind By_Protected_Procedure transforms the |
| requeue into a dispatching call, thus eliminating the chance of blocking. Kind |
| By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on |
| the target’s overriding subprogram kind. |
| |
| @node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{77} |
| @section Pragma Implicit_Packing |
| |
| |
| @geindex Rational Profile |
| |
| Syntax: |
| |
| @example |
| pragma Implicit_Packing; |
| @end example |
| |
| This is a configuration pragma that requests implicit packing for packed |
| arrays for which a size clause is given but no explicit pragma Pack or |
| specification of Component_Size is present. It also applies to records |
| where no record representation clause is present. Consider this example: |
| |
| @example |
| type R is array (0 .. 7) of Boolean; |
| for R'Size use 8; |
| @end example |
| |
| In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause |
| does not change the layout of a composite object. So the Size clause in the |
| above example is normally rejected, since the default layout of the array uses |
| 8-bit components, and thus the array requires a minimum of 64 bits. |
| |
| If this declaration is compiled in a region of code covered by an occurrence |
| of the configuration pragma Implicit_Packing, then the Size clause in this |
| and similar examples will cause implicit packing and thus be accepted. For |
| this implicit packing to occur, the type in question must be an array of small |
| components whose size is known at compile time, and the Size clause must |
| specify the exact size that corresponds to the number of elements in the array |
| multiplied by the size in bits of the component type (both single and |
| multi-dimensioned arrays can be controlled with this pragma). |
| |
| @geindex Array packing |
| |
| Similarly, the following example shows the use in the record case |
| |
| @example |
| type r is record |
| a, b, c, d, e, f, g, h : boolean; |
| chr : character; |
| end record; |
| for r'size use 16; |
| @end example |
| |
| Without a pragma Pack, each Boolean field requires 8 bits, so the |
| minimum size is 72 bits, but with a pragma Pack, 16 bits would be |
| sufficient. The use of pragma Implicit_Packing allows this record |
| declaration to compile without an explicit pragma Pack. |
| |
| @node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{78} |
| @section Pragma Import_Function |
| |
| |
| Syntax: |
| |
| @example |
| pragma Import_Function ( |
| [Internal =>] LOCAL_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Result_Type =>] SUBTYPE_MARK] |
| [, [Mechanism =>] MECHANISM] |
| [, [Result_Mechanism =>] MECHANISM_NAME]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= |
| Value |
| | Reference |
| @end example |
| |
| This pragma is used in conjunction with a pragma @code{Import} to |
| specify additional information for an imported function. The pragma |
| @code{Import} (or equivalent pragma @code{Interface}) must precede the |
| @code{Import_Function} pragma and both must appear in the same |
| declarative part as the function specification. |
| |
| The @code{Internal} argument must uniquely designate |
| the function to which the |
| pragma applies. If more than one function name exists of this name in |
| the declarative part you must use the @code{Parameter_Types} and |
| @code{Result_Type} parameters to achieve the required unique |
| designation. Subtype marks in these parameters must exactly match the |
| subtypes in the corresponding function specification, using positional |
| notation to match parameters with subtype marks. |
| The form with an @code{'Access} attribute can be used to match an |
| anonymous access parameter. |
| |
| You may optionally use the @code{Mechanism} and @code{Result_Mechanism} |
| parameters to specify passing mechanisms for the |
| parameters and result. If you specify a single mechanism name, it |
| applies to all parameters. Otherwise you may specify a mechanism on a |
| parameter by parameter basis using either positional or named |
| notation. If the mechanism is not specified, the default mechanism |
| is used. |
| |
| @node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{79} |
| @section Pragma Import_Object |
| |
| |
| Syntax: |
| |
| @example |
| pragma Import_Object |
| [Internal =>] LOCAL_NAME |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Size =>] EXTERNAL_SYMBOL]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end example |
| |
| This pragma designates an object as imported, and apart from the |
| extended rules for external symbols, is identical in effect to the use of |
| the normal @code{Import} pragma applied to an object. Unlike the |
| subprogram case, you need not use a separate @code{Import} pragma, |
| although you may do so (and probably should do so from a portability |
| point of view). @code{size} is syntax checked, but otherwise ignored by |
| GNAT. |
| |
| @node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7a} |
| @section Pragma Import_Procedure |
| |
| |
| Syntax: |
| |
| @example |
| pragma Import_Procedure ( |
| [Internal =>] LOCAL_NAME |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Mechanism =>] MECHANISM]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= Value | Reference |
| @end example |
| |
| This pragma is identical to @code{Import_Function} except that it |
| applies to a procedure rather than a function and the parameters |
| @code{Result_Type} and @code{Result_Mechanism} are not permitted. |
| |
| @node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7b} |
| @section Pragma Import_Valued_Procedure |
| |
| |
| Syntax: |
| |
| @example |
| pragma Import_Valued_Procedure ( |
| [Internal =>] LOCAL_NAME |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Mechanism =>] MECHANISM]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= Value | Reference |
| @end example |
| |
| This pragma is identical to @code{Import_Procedure} except that the |
| first parameter of @code{LOCAL_NAME}, which must be present, must be of |
| mode @code{out}, and externally the subprogram is treated as a function |
| with this parameter as the result of the function. The purpose of this |
| capability is to allow the use of @code{out} and @code{in out} |
| parameters in interfacing to external functions (which are not permitted |
| in Ada functions). You may optionally use the @code{Mechanism} |
| parameters to specify passing mechanisms for the parameters. |
| If you specify a single mechanism name, it applies to all parameters. |
| Otherwise you may specify a mechanism on a parameter by parameter |
| basis using either positional or named notation. If the mechanism is not |
| specified, the default mechanism is used. |
| |
| Note that it is important to use this pragma in conjunction with a separate |
| pragma Import that specifies the desired convention, since otherwise the |
| default convention is Ada, which is almost certainly not what is required. |
| |
| @node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7c} |
| @section Pragma Independent |
| |
| |
| Syntax: |
| |
| @example |
| pragma Independent (Local_NAME); |
| @end example |
| |
| This pragma is standard in Ada 2012 mode (which also provides an aspect |
| of the same name). It is also available as an implementation-defined |
| pragma in all earlier versions. It specifies that the |
| designated object or all objects of the designated type must be |
| independently addressable. This means that separate tasks can safely |
| manipulate such objects. For example, if two components of a record are |
| independent, then two separate tasks may access these two components. |
| This may place |
| constraints on the representation of the object (for instance prohibiting |
| tight packing). |
| |
| @node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7d} |
| @section Pragma Independent_Components |
| |
| |
| Syntax: |
| |
| @example |
| pragma Independent_Components (Local_NAME); |
| @end example |
| |
| This pragma is standard in Ada 2012 mode (which also provides an aspect |
| of the same name). It is also available as an implementation-defined |
| pragma in all earlier versions. It specifies that the components of the |
| designated object, or the components of each object of the designated |
| type, must be |
| independently addressable. This means that separate tasks can safely |
| manipulate separate components in the composite object. This may place |
| constraints on the representation of the object (for instance prohibiting |
| tight packing). |
| |
| @node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7e}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7f} |
| @section Pragma Initial_Condition |
| |
| |
| Syntax: |
| |
| @example |
| pragma Initial_Condition (boolean_EXPRESSION); |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} |
| in the SPARK 2014 Reference Manual, section 7.1.6. |
| |
| @node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{80} |
| @section Pragma Initialize_Scalars |
| |
| |
| @geindex debugging with Initialize_Scalars |
| |
| Syntax: |
| |
| @example |
| pragma Initialize_Scalars |
| [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; |
| |
| TYPE_VALUE_PAIR ::= |
| SCALAR_TYPE => static_EXPRESSION |
| |
| SCALAR_TYPE := |
| Short_Float |
| | Float |
| | Long_Float |
| | Long_Long_Flat |
| | Signed_8 |
| | Signed_16 |
| | Signed_32 |
| | Signed_64 |
| | Unsigned_8 |
| | Unsigned_16 |
| | Unsigned_32 |
| | Unsigned_64 |
| @end example |
| |
| This pragma is similar to @code{Normalize_Scalars} conceptually but has two |
| important differences. |
| |
| First, there is no requirement for the pragma to be used uniformly in all units |
| of a partition. In particular, it is fine to use this just for some or all of |
| the application units of a partition, without needing to recompile the run-time |
| library. In the case where some units are compiled with the pragma, and some |
| without, then a declaration of a variable where the type is defined in package |
| Standard or is locally declared will always be subject to initialization, as |
| will any declaration of a scalar variable. For composite variables, whether the |
| variable is initialized may also depend on whether the package in which the |
| type of the variable is declared is compiled with the pragma. |
| |
| The other important difference is that the programmer can control the value |
| used for initializing scalar objects. This effect can be achieved in several |
| different ways: |
| |
| |
| @itemize * |
| |
| @item |
| At compile time, the programmer can specify the invalid value for a |
| particular family of scalar types using the optional arguments of the pragma. |
| |
| The compile-time approach is intended to optimize the generated code for the |
| pragma, by possibly using fast operations such as @code{memset}. Note that such |
| optimizations require using values where the bytes all have the same binary |
| representation. |
| |
| @item |
| At bind time, the programmer has several options: |
| |
| |
| @itemize * |
| |
| @item |
| Initialization with invalid values (similar to Normalize_Scalars, though |
| for Initialize_Scalars it is not always possible to determine the invalid |
| values in complex cases like signed component fields with nonstandard |
| sizes). |
| |
| @item |
| Initialization with high values. |
| |
| @item |
| Initialization with low values. |
| |
| @item |
| Initialization with a specific bit pattern. |
| @end itemize |
| |
| See the GNAT User’s Guide for binder options for specifying these cases. |
| |
| The bind-time approach is intended to provide fast turnaround for testing |
| with different values, without having to recompile the program. |
| |
| @item |
| At execution time, the programmer can specify the invalid values using an |
| environment variable. See the GNAT User’s Guide for details. |
| |
| The execution-time approach is intended to provide fast turnaround for |
| testing with different values, without having to recompile and rebind the |
| program. |
| @end itemize |
| |
| Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction |
| with the enhanced validity checking that is now provided in GNAT, which checks |
| for invalid values under more conditions. Using this feature (see description |
| of the @emph{-gnatV} flag in the GNAT User’s Guide) in conjunction with pragma |
| @code{Initialize_Scalars} provides a powerful new tool to assist in the detection |
| of problems caused by uninitialized variables. |
| |
| Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the |
| generated code. This may cause your code to be substantially larger. It may |
| also cause an increase in the amount of stack required, so it is probably a |
| good idea to turn on stack checking (see description of stack checking in the |
| GNAT User’s Guide) when using this pragma. |
| |
| @node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{81}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{82} |
| @section Pragma Initializes |
| |
| |
| Syntax: |
| |
| @example |
| pragma Initializes (INITIALIZATION_LIST); |
| |
| INITIALIZATION_LIST ::= |
| null |
| | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) |
| |
| INITIALIZATION_ITEM ::= name [=> INPUT_LIST] |
| |
| INPUT_LIST ::= |
| null |
| | INPUT |
| | (INPUT @{, INPUT@}) |
| |
| INPUT ::= name |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Initializes} in the |
| SPARK 2014 Reference Manual, section 7.1.5. |
| |
| @node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{84} |
| @section Pragma Inline_Always |
| |
| |
| Syntax: |
| |
| @example |
| pragma Inline_Always (NAME [, NAME]); |
| @end example |
| |
| Similar to pragma @code{Inline} except that inlining is unconditional. |
| Inline_Always instructs the compiler to inline every direct call to the |
| subprogram or else to emit a compilation error, independently of any |
| option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level. |
| It is an error to take the address or access of @code{NAME}. It is also an error to |
| apply this pragma to a primitive operation of a tagged type. Thanks to such |
| restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. |
| |
| @node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{85} |
| @section Pragma Inline_Generic |
| |
| |
| Syntax: |
| |
| @example |
| pragma Inline_Generic (GNAME @{, GNAME@}); |
| |
| GNAME ::= generic_unit_NAME | generic_instance_NAME |
| @end example |
| |
| This pragma is provided for compatibility with Dec Ada 83. It has |
| no effect in GNAT (which always inlines generics), other |
| than to check that the given names are all names of generic units or |
| generic instances. |
| |
| @node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{86} |
| @section Pragma Interface |
| |
| |
| Syntax: |
| |
| @example |
| pragma Interface ( |
| [Convention =>] convention_identifier, |
| [Entity =>] local_NAME |
| [, [External_Name =>] static_string_expression] |
| [, [Link_Name =>] static_string_expression]); |
| @end example |
| |
| This pragma is identical in syntax and semantics to |
| the standard Ada pragma @code{Import}. It is provided for compatibility |
| with Ada 83. The definition is upwards compatible both with pragma |
| @code{Interface} as defined in the Ada 83 Reference Manual, and also |
| with some extended implementations of this pragma in certain Ada 83 |
| implementations. The only difference between pragma @code{Interface} |
| and pragma @code{Import} is that there is special circuitry to allow |
| both pragmas to appear for the same subprogram entity (normally it |
| is illegal to have multiple @code{Import} pragmas. This is useful in |
| maintaining Ada 83/Ada 95 compatibility and is compatible with other |
| Ada 83 compilers. |
| |
| @node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{87} |
| @section Pragma Interface_Name |
| |
| |
| Syntax: |
| |
| @example |
| pragma Interface_Name ( |
| [Entity =>] LOCAL_NAME |
| [, [External_Name =>] static_string_EXPRESSION] |
| [, [Link_Name =>] static_string_EXPRESSION]); |
| @end example |
| |
| This pragma provides an alternative way of specifying the interface name |
| for an interfaced subprogram, and is provided for compatibility with Ada |
| 83 compilers that use the pragma for this purpose. You must provide at |
| least one of @code{External_Name} or @code{Link_Name}. |
| |
| @node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{88} |
| @section Pragma Interrupt_Handler |
| |
| |
| Syntax: |
| |
| @example |
| pragma Interrupt_Handler (procedure_LOCAL_NAME); |
| @end example |
| |
| This program unit pragma is supported for parameterless protected procedures |
| as described in Annex C of the Ada Reference Manual. |
| |
| @node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{89} |
| @section Pragma Interrupt_State |
| |
| |
| Syntax: |
| |
| @example |
| pragma Interrupt_State |
| ([Name =>] value, |
| [State =>] SYSTEM | RUNTIME | USER); |
| @end example |
| |
| Normally certain interrupts are reserved to the implementation. Any attempt |
| to attach an interrupt causes Program_Error to be raised, as described in |
| RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in |
| many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is |
| reserved to the implementation, so that @code{Ctrl-C} can be used to |
| interrupt execution. Additionally, signals such as @code{SIGSEGV}, |
| @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific |
| Ada exceptions, or used to implement run-time functions such as the |
| @code{abort} statement and stack overflow checking. |
| |
| Pragma @code{Interrupt_State} provides a general mechanism for overriding |
| such uses of interrupts. It subsumes the functionality of pragma |
| @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not |
| available on Windows. On all other platforms than VxWorks, |
| it applies to signals; on VxWorks, it applies to vectored hardware interrupts |
| and may be used to mark interrupts required by the board support package |
| as reserved. |
| |
| Interrupts can be in one of three states: |
| |
| |
| @itemize * |
| |
| @item |
| System |
| |
| The interrupt is reserved (no Ada handler can be installed), and the |
| Ada run-time may not install a handler. As a result you are guaranteed |
| standard system default action if this interrupt is raised. This also allows |
| installing a low level handler via C APIs such as sigaction(), outside |
| of Ada control. |
| |
| @item |
| Runtime |
| |
| The interrupt is reserved (no Ada handler can be installed). The run time |
| is allowed to install a handler for internal control purposes, but is |
| not required to do so. |
| |
| @item |
| User |
| |
| The interrupt is unreserved. The user may install an Ada handler via |
| Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide |
| some other action. |
| @end itemize |
| |
| These states are the allowed values of the @code{State} parameter of the |
| pragma. The @code{Name} parameter is a value of the type |
| @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in |
| @code{Ada.Interrupts.Names}. |
| |
| This is a configuration pragma, and the binder will check that there |
| are no inconsistencies between different units in a partition in how a |
| given interrupt is specified. It may appear anywhere a pragma is legal. |
| |
| The effect is to move the interrupt to the specified state. |
| |
| By declaring interrupts to be SYSTEM, you guarantee the standard system |
| action, such as a core dump. |
| |
| By declaring interrupts to be USER, you guarantee that you can install |
| a handler. |
| |
| Note that certain signals on many operating systems cannot be caught and |
| handled by applications. In such cases, the pragma is ignored. See the |
| operating system documentation, or the value of the array @code{Reserved} |
| declared in the spec of package @code{System.OS_Interface}. |
| |
| Overriding the default state of signals used by the Ada runtime may interfere |
| with an application’s runtime behavior in the cases of the synchronous signals, |
| and in the case of the signal used to implement the @code{abort} statement. |
| |
| @node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{8a}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8b} |
| @section Pragma Invariant |
| |
| |
| Syntax: |
| |
| @example |
| pragma Invariant |
| ([Entity =>] private_type_LOCAL_NAME, |
| [Check =>] EXPRESSION |
| [,[Message =>] String_Expression]); |
| @end example |
| |
| This pragma provides exactly the same capabilities as the Type_Invariant aspect |
| defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The |
| Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it |
| requires the use of the aspect syntax, which is not available except in 2012 |
| mode, it is not possible to use the Type_Invariant aspect in earlier versions |
| of Ada. However the Invariant pragma may be used in any version of Ada. Also |
| note that the aspect Invariant is a synonym in GNAT for the aspect |
| Type_Invariant, but there is no pragma Type_Invariant. |
| |
| The pragma must appear within the visible part of the package specification, |
| after the type to which its Entity argument appears. As with the Invariant |
| aspect, the Check expression is not analyzed until the end of the visible |
| part of the package, so it may contain forward references. The Message |
| argument, if present, provides the exception message used if the invariant |
| is violated. If no Message parameter is provided, a default message that |
| identifies the line on which the pragma appears is used. |
| |
| It is permissible to have multiple Invariants for the same type entity, in |
| which case they are and’ed together. It is permissible to use this pragma |
| in Ada 2012 mode, but you cannot have both an invariant aspect and an |
| invariant pragma for the same entity. |
| |
| For further details on the use of this pragma, see the Ada 2012 documentation |
| of the Type_Invariant aspect. |
| |
| @node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8c} |
| @section Pragma Keep_Names |
| |
| |
| Syntax: |
| |
| @example |
| pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); |
| @end example |
| |
| The @code{LOCAL_NAME} argument |
| must refer to an enumeration first subtype |
| in the current declarative part. The effect is to retain the enumeration |
| literal names for use by @code{Image} and @code{Value} even if a global |
| @code{Discard_Names} pragma applies. This is useful when you want to |
| generally suppress enumeration literal names and for example you therefore |
| use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you |
| want to retain the names for specific enumeration types. |
| |
| @node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8d} |
| @section Pragma License |
| |
| |
| @geindex License checking |
| |
| Syntax: |
| |
| @example |
| pragma License (Unrestricted | GPL | Modified_GPL | Restricted); |
| @end example |
| |
| This pragma is provided to allow automated checking for appropriate license |
| conditions with respect to the standard and modified GPL. A pragma |
| @code{License}, which is a configuration pragma that typically appears at |
| the start of a source file or in a separate @code{gnat.adc} file, specifies |
| the licensing conditions of a unit as follows: |
| |
| |
| @itemize * |
| |
| @item |
| Unrestricted |
| This is used for a unit that can be freely used with no license restrictions. |
| Examples of such units are public domain units, and units from the Ada |
| Reference Manual. |
| |
| @item |
| GPL |
| This is used for a unit that is licensed under the unmodified GPL, and which |
| therefore cannot be @code{with}ed by a restricted unit. |
| |
| @item |
| Modified_GPL |
| This is used for a unit licensed under the GNAT modified GPL that includes |
| a special exception paragraph that specifically permits the inclusion of |
| the unit in programs without requiring the entire program to be released |
| under the GPL. |
| |
| @item |
| Restricted |
| This is used for a unit that is restricted in that it is not permitted to |
| depend on units that are licensed under the GPL. Typical examples are |
| proprietary code that is to be released under more restrictive license |
| conditions. Note that restricted units are permitted to @code{with} units |
| which are licensed under the modified GPL (this is the whole point of the |
| modified GPL). |
| @end itemize |
| |
| Normally a unit with no @code{License} pragma is considered to have an |
| unknown license, and no checking is done. However, standard GNAT headers |
| are recognized, and license information is derived from them as follows. |
| |
| A GNAT license header starts with a line containing 78 hyphens. The following |
| comment text is searched for the appearance of any of the following strings. |
| |
| If the string ‘GNU General Public License’ is found, then the unit is assumed |
| to have GPL license, unless the string ‘As a special exception’ follows, in |
| which case the license is assumed to be modified GPL. |
| |
| If one of the strings |
| ‘This specification is adapted from the Ada Semantic Interface’ or |
| ‘This specification is derived from the Ada Reference Manual’ is found |
| then the unit is assumed to be unrestricted. |
| |
| These default actions means that a program with a restricted license pragma |
| will automatically get warnings if a GPL unit is inappropriately |
| @code{with}ed. For example, the program: |
| |
| @example |
| with Sem_Ch3; |
| with GNAT.Sockets; |
| procedure Secret_Stuff is |
| ... |
| end Secret_Stuff |
| @end example |
| |
| if compiled with pragma @code{License} (@code{Restricted}) in a |
| @code{gnat.adc} file will generate the warning: |
| |
| @example |
| 1. with Sem_Ch3; |
| | |
| >>> license of withed unit "Sem_Ch3" is incompatible |
| |
| 2. with GNAT.Sockets; |
| 3. procedure Secret_Stuff is |
| @end example |
| |
| Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT |
| compiler and is licensed under the |
| GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT |
| run time, and is therefore licensed under the modified GPL. |
| |
| @node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8e} |
| @section Pragma Link_With |
| |
| |
| Syntax: |
| |
| @example |
| pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); |
| @end example |
| |
| This pragma is provided for compatibility with certain Ada 83 compilers. |
| It has exactly the same effect as pragma @code{Linker_Options} except |
| that spaces occurring within one of the string expressions are treated |
| as separators. For example, in the following case: |
| |
| @example |
| pragma Link_With ("-labc -ldef"); |
| @end example |
| |
| results in passing the strings @code{-labc} and @code{-ldef} as two |
| separate arguments to the linker. In addition pragma Link_With allows |
| multiple arguments, with the same effect as successive pragmas. |
| |
| @node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8f} |
| @section Pragma Linker_Alias |
| |
| |
| Syntax: |
| |
| @example |
| pragma Linker_Alias ( |
| [Entity =>] LOCAL_NAME, |
| [Target =>] static_string_EXPRESSION); |
| @end example |
| |
| @code{LOCAL_NAME} must refer to an object that is declared at the library |
| level. This pragma establishes the given entity as a linker alias for the |
| given target. It is equivalent to @code{__attribute__((alias))} in GNU C |
| and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol |
| @code{static_string_EXPRESSION} in the object file, that is to say no space |
| is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved |
| to the same address as @code{static_string_EXPRESSION} by the linker. |
| |
| The actual linker name for the target must be used (e.g., the fully |
| encoded name with qualification in Ada, or the mangled name in C++), |
| or it must be declared using the C convention with @code{pragma Import} |
| or @code{pragma Export}. |
| |
| Not all target machines support this pragma. On some of them it is accepted |
| only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. |
| |
| @example |
| -- Example of the use of pragma Linker_Alias |
| |
| package p is |
| i : Integer := 1; |
| pragma Export (C, i); |
| |
| new_name_for_i : Integer; |
| pragma Linker_Alias (new_name_for_i, "i"); |
| end p; |
| @end example |
| |
| @node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{90} |
| @section Pragma Linker_Constructor |
| |
| |
| Syntax: |
| |
| @example |
| pragma Linker_Constructor (procedure_LOCAL_NAME); |
| @end example |
| |
| @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
| is declared at the library level. A procedure to which this pragma is |
| applied will be treated as an initialization routine by the linker. |
| It is equivalent to @code{__attribute__((constructor))} in GNU C and |
| causes @code{procedure_LOCAL_NAME} to be invoked before the entry point |
| of the executable is called (or immediately after the shared library is |
| loaded if the procedure is linked in a shared library), in particular |
| before the Ada run-time environment is set up. |
| |
| Because of these specific contexts, the set of operations such a procedure |
| can perform is very limited and the type of objects it can manipulate is |
| essentially restricted to the elementary types. In particular, it must only |
| contain code to which pragma Restrictions (No_Elaboration_Code) applies. |
| |
| This pragma is used by GNAT to implement auto-initialization of shared Stand |
| Alone Libraries, which provides a related capability without the restrictions |
| listed above. Where possible, the use of Stand Alone Libraries is preferable |
| to the use of this pragma. |
| |
| @node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{91} |
| @section Pragma Linker_Destructor |
| |
| |
| Syntax: |
| |
| @example |
| pragma Linker_Destructor (procedure_LOCAL_NAME); |
| @end example |
| |
| @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
| is declared at the library level. A procedure to which this pragma is |
| applied will be treated as a finalization routine by the linker. |
| It is equivalent to @code{__attribute__((destructor))} in GNU C and |
| causes @code{procedure_LOCAL_NAME} to be invoked after the entry point |
| of the executable has exited (or immediately before the shared library |
| is unloaded if the procedure is linked in a shared library), in particular |
| after the Ada run-time environment is shut down. |
| |
| See @code{pragma Linker_Constructor} for the set of restrictions that apply |
| because of these specific contexts. |
| |
| @node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{92}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{93} |
| @section Pragma Linker_Section |
| |
| |
| Syntax: |
| |
| @example |
| pragma Linker_Section ( |
| [Entity =>] LOCAL_NAME, |
| [Section =>] static_string_EXPRESSION); |
| @end example |
| |
| @code{LOCAL_NAME} must refer to an object, type, or subprogram that is |
| declared at the library level. This pragma specifies the name of the |
| linker section for the given entity. It is equivalent to |
| @code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to |
| be placed in the @code{static_string_EXPRESSION} section of the |
| executable (assuming the linker doesn’t rename the section). |
| GNAT also provides an implementation defined aspect of the same name. |
| |
| In the case of specifying this aspect for a type, the effect is to |
| specify the corresponding section for all library-level objects of |
| the type that do not have an explicit linker section set. Note that |
| this only applies to whole objects, not to components of composite objects. |
| |
| In the case of a subprogram, the linker section applies to all previously |
| declared matching overloaded subprograms in the current declarative part |
| which do not already have a linker section assigned. The linker section |
| aspect is useful in this case for specifying different linker sections |
| for different elements of such an overloaded set. |
| |
| Note that an empty string specifies that no linker section is specified. |
| This is not quite the same as omitting the pragma or aspect, since it |
| can be used to specify that one element of an overloaded set of subprograms |
| has the default linker section, or that one object of a type for which a |
| linker section is specified should has the default linker section. |
| |
| The compiler normally places library-level entities in standard sections |
| depending on the class: procedures and functions generally go in the |
| @code{.text} section, initialized variables in the @code{.data} section |
| and uninitialized variables in the @code{.bss} section. |
| |
| Other, special sections may exist on given target machines to map special |
| hardware, for example I/O ports or flash memory. This pragma is a means to |
| defer the final layout of the executable to the linker, thus fully working |
| at the symbolic level with the compiler. |
| |
| Some file formats do not support arbitrary sections so not all target |
| machines support this pragma. The use of this pragma may cause a program |
| execution to be erroneous if it is used to place an entity into an |
| inappropriate section (e.g., a modified variable into the @code{.text} |
| section). See also @code{pragma Persistent_BSS}. |
| |
| @example |
| -- Example of the use of pragma Linker_Section |
| |
| package IO_Card is |
| Port_A : Integer; |
| pragma Volatile (Port_A); |
| pragma Linker_Section (Port_A, ".bss.port_a"); |
| |
| Port_B : Integer; |
| pragma Volatile (Port_B); |
| pragma Linker_Section (Port_B, ".bss.port_b"); |
| |
| type Port_Type is new Integer with Linker_Section => ".bss"; |
| PA : Port_Type with Linker_Section => ".bss.PA"; |
| PB : Port_Type; -- ends up in linker section ".bss" |
| |
| procedure Q with Linker_Section => "Qsection"; |
| end IO_Card; |
| @end example |
| |
| @node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{95} |
| @section Pragma Lock_Free |
| |
| |
| Syntax: |
| This pragma may be specified for protected types or objects. It specifies that |
| the implementation of protected operations must be implemented without locks. |
| Compilation fails if the compiler cannot generate lock-free code for the |
| operations. |
| |
| The current conditions required to support this pragma are: |
| |
| |
| @itemize * |
| |
| @item |
| Protected type declarations may not contain entries |
| |
| @item |
| Protected subprogram declarations may not have nonelementary parameters |
| @end itemize |
| |
| In addition, each protected subprogram body must satisfy: |
| |
| |
| @itemize * |
| |
| @item |
| May reference only one protected component |
| |
| @item |
| May not reference nonconstant entities outside the protected subprogram |
| scope. |
| |
| @item |
| May not contain address representation items, allocators, or quantified |
| expressions. |
| |
| @item |
| May not contain delay, goto, loop, or procedure-call statements. |
| |
| @item |
| May not contain exported and imported entities |
| |
| @item |
| May not dereferenced access values |
| |
| @item |
| Function calls and attribute references must be static |
| @end itemize |
| |
| @node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{96} |
| @section Pragma Loop_Invariant |
| |
| |
| Syntax: |
| |
| @example |
| pragma Loop_Invariant ( boolean_EXPRESSION ); |
| @end example |
| |
| The effect of this pragma is similar to that of pragma @code{Assert}, |
| except that in an @code{Assertion_Policy} pragma, the identifier |
| @code{Loop_Invariant} is used to control whether it is ignored or checked |
| (or disabled). |
| |
| @code{Loop_Invariant} can only appear as one of the items in the sequence |
| of statements of a loop body, or nested inside block statements that |
| appear in the sequence of statements of a loop body. |
| The intention is that it be used to |
| represent a “loop invariant” assertion, i.e. something that is true each |
| time through the loop, and which can be used to show that the loop is |
| achieving its purpose. |
| |
| Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that |
| apply to the same loop should be grouped in the same sequence of |
| statements. |
| |
| To aid in writing such invariants, the special attribute @code{Loop_Entry} |
| may be used to refer to the value of an expression on entry to the loop. This |
| attribute can only be used within the expression of a @code{Loop_Invariant} |
| pragma. For full details, see documentation of attribute @code{Loop_Entry}. |
| |
| @node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{97} |
| @section Pragma Loop_Optimize |
| |
| |
| Syntax: |
| |
| @example |
| pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); |
| |
| OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector |
| @end example |
| |
| This pragma must appear immediately within a loop statement. It allows the |
| programmer to specify optimization hints for the enclosing loop. The hints |
| are not mutually exclusive and can be freely mixed, but not all combinations |
| will yield a sensible outcome. |
| |
| There are five supported optimization hints for a loop: |
| |
| |
| @itemize * |
| |
| @item |
| Ivdep |
| |
| The programmer asserts that there are no loop-carried dependencies |
| which would prevent consecutive iterations of the loop from being |
| executed simultaneously. |
| |
| @item |
| No_Unroll |
| |
| The loop must not be unrolled. This is a strong hint: the compiler will not |
| unroll a loop marked with this hint. |
| |
| @item |
| Unroll |
| |
| The loop should be unrolled. This is a weak hint: the compiler will try to |
| apply unrolling to this loop preferably to other optimizations, notably |
| vectorization, but there is no guarantee that the loop will be unrolled. |
| |
| @item |
| No_Vector |
| |
| The loop must not be vectorized. This is a strong hint: the compiler will not |
| vectorize a loop marked with this hint. |
| |
| @item |
| Vector |
| |
| The loop should be vectorized. This is a weak hint: the compiler will try to |
| apply vectorization to this loop preferably to other optimizations, notably |
| unrolling, but there is no guarantee that the loop will be vectorized. |
| @end itemize |
| |
| These hints do not remove the need to pass the appropriate switches to the |
| compiler in order to enable the relevant optimizations, that is to say |
| @emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for |
| vectorization. |
| |
| @node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{98} |
| @section Pragma Loop_Variant |
| |
| |
| Syntax: |
| |
| @example |
| pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); |
| LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION |
| CHANGE_DIRECTION ::= Increases | Decreases |
| @end example |
| |
| @code{Loop_Variant} can only appear as one of the items in the sequence |
| of statements of a loop body, or nested inside block statements that |
| appear in the sequence of statements of a loop body. |
| It allows the specification of quantities which must always |
| decrease or increase in successive iterations of the loop. In its simplest |
| form, just one expression is specified, whose value must increase or decrease |
| on each iteration of the loop. |
| |
| In a more complex form, multiple arguments can be given which are intepreted |
| in a nesting lexicographic manner. For example: |
| |
| @example |
| pragma Loop_Variant (Increases => X, Decreases => Y); |
| @end example |
| |
| specifies that each time through the loop either X increases, or X stays |
| the same and Y decreases. A @code{Loop_Variant} pragma ensures that the |
| loop is making progress. It can be useful in helping to show informally |
| or prove formally that the loop always terminates. |
| |
| @code{Loop_Variant} is an assertion whose effect can be controlled using |
| an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The |
| policy can be @code{Check} to enable the loop variant check, @code{Ignore} |
| to ignore the check (in which case the pragma has no effect on the program), |
| or @code{Disable} in which case the pragma is not even checked for correct |
| syntax. |
| |
| Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that |
| apply to the same loop should be grouped in the same sequence of |
| statements. |
| |
| The @code{Loop_Entry} attribute may be used within the expressions of the |
| @code{Loop_Variant} pragma to refer to values on entry to the loop. |
| |
| @node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{99} |
| @section Pragma Machine_Attribute |
| |
| |
| Syntax: |
| |
| @example |
| pragma Machine_Attribute ( |
| [Entity =>] LOCAL_NAME, |
| [Attribute_Name =>] static_string_EXPRESSION |
| [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); |
| @end example |
| |
| Machine-dependent attributes can be specified for types and/or |
| declarations. This pragma is semantically equivalent to |
| @code{__attribute__((@emph{attribute_name}))} (if @code{info} is not |
| specified) or @code{__attribute__((@emph{attribute_name(info})))} |
| or @code{__attribute__((@emph{attribute_name(info,…})))} in GNU C, |
| where @emph{attribute_name} is recognized by the compiler middle-end |
| or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note |
| that a string literal for the optional parameter @code{info} or the |
| following ones is transformed by default into an identifier, |
| which may make this pragma unusable for some attributes. |
| For further information see @cite{GNU Compiler Collection (GCC) Internals}. |
| |
| @node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9a} |
| @section Pragma Main |
| |
| |
| Syntax: |
| |
| @example |
| pragma Main |
| (MAIN_OPTION [, MAIN_OPTION]); |
| |
| MAIN_OPTION ::= |
| [Stack_Size =>] static_integer_EXPRESSION |
| | [Task_Stack_Size_Default =>] static_integer_EXPRESSION |
| | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION |
| @end example |
| |
| This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
| no effect in GNAT, other than being syntax checked. |
| |
| @node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9b} |
| @section Pragma Main_Storage |
| |
| |
| Syntax: |
| |
| @example |
| pragma Main_Storage |
| (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); |
| |
| MAIN_STORAGE_OPTION ::= |
| [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION |
| | [TOP_GUARD =>] static_SIMPLE_EXPRESSION |
| @end example |
| |
| This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
| no effect in GNAT, other than being syntax checked. |
| |
| @node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9c}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9d} |
| @section Pragma Max_Queue_Length |
| |
| |
| Syntax: |
| |
| @example |
| pragma Max_Entry_Queue (static_integer_EXPRESSION); |
| @end example |
| |
| This pragma is used to specify the maximum callers per entry queue for |
| individual protected entries and entry families. It accepts a single |
| integer (-1 or more) as a parameter and must appear after the declaration of an |
| entry. |
| |
| A value of -1 represents no additional restriction on queue length. |
| |
| @node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9e} |
| @section Pragma No_Body |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Body; |
| @end example |
| |
| There are a number of cases in which a package spec does not require a body, |
| and in fact a body is not permitted. GNAT will not permit the spec to be |
| compiled if there is a body around. The pragma No_Body allows you to provide |
| a body file, even in a case where no body is allowed. The body file must |
| contain only comments and a single No_Body pragma. This is recognized by |
| the compiler as indicating that no body is logically present. |
| |
| This is particularly useful during maintenance when a package is modified in |
| such a way that a body needed before is no longer needed. The provision of a |
| dummy body with a No_Body pragma ensures that there is no interference from |
| earlier versions of the package body. |
| |
| @node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9f}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a0} |
| @section Pragma No_Caching |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Caching [ (boolean_EXPRESSION) ]; |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{No_Caching} in |
| the SPARK 2014 Reference Manual, section 7.1.2. |
| |
| @node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a1} |
| @section Pragma No_Component_Reordering |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; |
| @end example |
| |
| @code{type_LOCAL_NAME} must refer to a record type declaration in the current |
| declarative part. The effect is to preclude any reordering of components |
| for the layout of the record, i.e. the record is laid out by the compiler |
| in the order in which the components are declared textually. The form with |
| no argument is a configuration pragma which applies to all record types |
| declared in units to which the pragma applies and there is a requirement |
| that this pragma be used consistently within a partition. |
| |
| @node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a2}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a3} |
| @section Pragma No_Elaboration_Code_All |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Elaboration_Code_All [(program_unit_NAME)]; |
| @end example |
| |
| This is a program unit pragma (there is also an equivalent aspect of the |
| same name) that establishes the restriction @code{No_Elaboration_Code} for |
| the current unit and any extended main source units (body and subunits). |
| It also has the effect of enforcing a transitive application of this |
| aspect, so that if any unit is implicitly or explicitly with’ed by the |
| current unit, it must also have the No_Elaboration_Code_All aspect set. |
| It may be applied to package or subprogram specs or their generic versions. |
| |
| @node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a4} |
| @section Pragma No_Heap_Finalization |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; |
| @end example |
| |
| Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a |
| type-specific pragma. |
| |
| In its configuration form, the pragma must appear within a configuration file |
| such as gnat.adc, without an argument. The pragma suppresses the call to |
| @code{Finalize} for heap-allocated objects created through library-level named |
| access-to-object types in cases where the designated type requires finalization |
| actions. |
| |
| In its type-specific form, the argument of the pragma must denote a |
| library-level named access-to-object type. The pragma suppresses the call to |
| @code{Finalize} for heap-allocated objects created through the specific access type |
| in cases where the designated type requires finalization actions. |
| |
| It is still possible to finalize such heap-allocated objects by explicitly |
| deallocating them. |
| |
| A library-level named access-to-object type declared within a generic unit will |
| lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not |
| appear at the library level. |
| |
| @node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a5}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a6} |
| @section Pragma No_Inline |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Inline (NAME @{, NAME@}); |
| @end example |
| |
| This pragma suppresses inlining for the callable entity or the instances of |
| the generic subprogram designated by @code{NAME}, including inlining that |
| results from the use of pragma @code{Inline}. This pragma is always active, |
| in particular it is not subject to the use of option @emph{-gnatn} or |
| @emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and |
| pragma @code{Inline_Always} for the same @code{NAME}. |
| |
| @node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a7} |
| @section Pragma No_Return |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); |
| @end example |
| |
| Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure |
| declarations in the current declarative part. A procedure to which this |
| pragma is applied may not contain any explicit @code{return} statements. |
| In addition, if the procedure contains any implicit returns from falling |
| off the end of a statement sequence, then execution of that implicit |
| return will cause Program_Error to be raised. |
| |
| One use of this pragma is to identify procedures whose only purpose is to raise |
| an exception. Another use of this pragma is to suppress incorrect warnings |
| about missing returns in functions, where the last statement of a function |
| statement sequence is a call to such a procedure. |
| |
| Note that in Ada 2005 mode, this pragma is part of the language. It is |
| available in all earlier versions of Ada as an implementation-defined |
| pragma. |
| |
| @node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a8} |
| @section Pragma No_Strict_Aliasing |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; |
| @end example |
| |
| @code{type_LOCAL_NAME} must refer to an access type |
| declaration in the current declarative part. The effect is to inhibit |
| strict aliasing optimization for the given type. The form with no |
| arguments is a configuration pragma which applies to all access types |
| declared in units to which the pragma applies. For a detailed |
| description of the strict aliasing optimization, and the situations |
| in which it must be suppressed, see the section on Optimization and Strict Aliasing |
| in the @cite{GNAT User’s Guide}. |
| |
| This pragma currently has no effects on access to unconstrained array types. |
| |
| @node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a9}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{aa} |
| @section Pragma No_Tagged_Streams |
| |
| |
| Syntax: |
| |
| @example |
| pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; |
| @end example |
| |
| Normally when a tagged type is introduced using a full type declaration, |
| part of the processing includes generating stream access routines to be |
| used by stream attributes referencing the type (or one of its subtypes |
| or derived types). This can involve the generation of significant amounts |
| of code which is wasted space if stream routines are not needed for the |
| type in question. |
| |
| The @code{No_Tagged_Streams} pragma causes the generation of these stream |
| routines to be skipped, and any attempt to use stream operations on |
| types subject to this pragma will be statically rejected as illegal. |
| |
| There are two forms of the pragma. The form with no arguments must appear |
| in a declarative sequence or in the declarations of a package spec. This |
| pragma affects all subsequent root tagged types declared in the declaration |
| sequence, and specifies that no stream routines be generated. The form with |
| an argument (for which there is also a corresponding aspect) specifies a |
| single root tagged type for which stream routines are not to be generated. |
| |
| Once the pragma has been given for a particular root tagged type, all subtypes |
| and derived types of this type inherit the pragma automatically, so the effect |
| applies to a complete hierarchy (this is necessary to deal with the class-wide |
| dispatching versions of the stream routines). |
| |
| When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously |
| applied to a tagged type its Expanded_Name and External_Tag are initialized |
| with empty strings. This is useful to avoid exposing entity names at binary |
| level but has a negative impact on the debuggability of tagged types. |
| |
| @node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ab} |
| @section Pragma Normalize_Scalars |
| |
| |
| Syntax: |
| |
| @example |
| pragma Normalize_Scalars; |
| @end example |
| |
| This is a language defined pragma which is fully implemented in GNAT. The |
| effect is to cause all scalar objects that are not otherwise initialized |
| to be initialized. The initial values are implementation dependent and |
| are as follows: |
| |
| |
| @table @asis |
| |
| @item @emph{Standard.Character} |
| |
| Objects whose root type is Standard.Character are initialized to |
| Character’Last unless the subtype range excludes NUL (in which case |
| NUL is used). This choice will always generate an invalid value if |
| one exists. |
| |
| @item @emph{Standard.Wide_Character} |
| |
| Objects whose root type is Standard.Wide_Character are initialized to |
| Wide_Character’Last unless the subtype range excludes NUL (in which case |
| NUL is used). This choice will always generate an invalid value if |
| one exists. |
| |
| @item @emph{Standard.Wide_Wide_Character} |
| |
| Objects whose root type is Standard.Wide_Wide_Character are initialized to |
| the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in |
| which case NUL is used). This choice will always generate an invalid value if |
| one exists. |
| |
| @item @emph{Integer types} |
| |
| Objects of an integer type are treated differently depending on whether |
| negative values are present in the subtype. If no negative values are |
| present, then all one bits is used as the initial value except in the |
| special case where zero is excluded from the subtype, in which case |
| all zero bits are used. This choice will always generate an invalid |
| value if one exists. |
| |
| For subtypes with negative values present, the largest negative number |
| is used, except in the unusual case where this largest negative number |
| is in the subtype, and the largest positive number is not, in which case |
| the largest positive value is used. This choice will always generate |
| an invalid value if one exists. |
| |
| @item @emph{Floating-Point Types} |
| |
| Objects of all floating-point types are initialized to all 1-bits. For |
| standard IEEE format, this corresponds to a NaN (not a number) which is |
| indeed an invalid value. |
| |
| @item @emph{Fixed-Point Types} |
| |
| Objects of all fixed-point types are treated as described above for integers, |
| with the rules applying to the underlying integer value used to represent |
| the fixed-point value. |
| |
| @item @emph{Modular types} |
| |
| Objects of a modular type are initialized to all one bits, except in |
| the special case where zero is excluded from the subtype, in which |
| case all zero bits are used. This choice will always generate an |
| invalid value if one exists. |
| |
| @item @emph{Enumeration types} |
| |
| Objects of an enumeration type are initialized to all one-bits, i.e., to |
| the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal |
| whose Pos value is zero, in which case a code of zero is used. This choice |
| will always generate an invalid value if one exists. |
| @end table |
| |
| @node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ac}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ad} |
| @section Pragma Obsolescent |
| |
| |
| Syntax: |
| |
| @example |
| pragma Obsolescent; |
| |
| pragma Obsolescent ( |
| [Message =>] static_string_EXPRESSION |
| [,[Version =>] Ada_05]]); |
| |
| pragma Obsolescent ( |
| [Entity =>] NAME |
| [,[Message =>] static_string_EXPRESSION |
| [,[Version =>] Ada_05]] ); |
| @end example |
| |
| This pragma can occur immediately following a declaration of an entity, |
| including the case of a record component. If no Entity argument is present, |
| then this declaration is the one to which the pragma applies. If an Entity |
| parameter is present, it must either match the name of the entity in this |
| declaration, or alternatively, the pragma can immediately follow an enumeration |
| type declaration, where the Entity argument names one of the enumeration |
| literals. |
| |
| This pragma is used to indicate that the named entity |
| is considered obsolescent and should not be used. Typically this is |
| used when an API must be modified by eventually removing or modifying |
| existing subprograms or other entities. The pragma can be used at an |
| intermediate stage when the entity is still present, but will be |
| removed later. |
| |
| The effect of this pragma is to output a warning message on a reference to |
| an entity thus marked that the subprogram is obsolescent if the appropriate |
| warning option in the compiler is activated. If the @code{Message} parameter is |
| present, then a second warning message is given containing this text. In |
| addition, a reference to the entity is considered to be a violation of pragma |
| @code{Restrictions (No_Obsolescent_Features)}. |
| |
| This pragma can also be used as a program unit pragma for a package, |
| in which case the entity name is the name of the package, and the |
| pragma indicates that the entire package is considered |
| obsolescent. In this case a client @code{with}ing such a package |
| violates the restriction, and the @code{with} clause is |
| flagged with warnings if the warning option is set. |
| |
| If the @code{Version} parameter is present (which must be exactly |
| the identifier @code{Ada_05}, no other argument is allowed), then the |
| indication of obsolescence applies only when compiling in Ada 2005 |
| mode. This is primarily intended for dealing with the situations |
| in the predefined library where subprograms or packages |
| have become defined as obsolescent in Ada 2005 |
| (e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. |
| |
| The following examples show typical uses of this pragma: |
| |
| @example |
| package p is |
| pragma Obsolescent (p, Message => "use pp instead of p"); |
| end p; |
| |
| package q is |
| procedure q2; |
| pragma Obsolescent ("use q2new instead"); |
| |
| type R is new integer; |
| pragma Obsolescent |
| (Entity => R, |
| Message => "use RR in Ada 2005", |
| Version => Ada_05); |
| |
| type M is record |
| F1 : Integer; |
| F2 : Integer; |
| pragma Obsolescent; |
| F3 : Integer; |
| end record; |
| |
| type E is (a, bc, 'd', quack); |
| pragma Obsolescent (Entity => bc) |
| pragma Obsolescent (Entity => 'd') |
| |
| function "+" |
| (a, b : character) return character; |
| pragma Obsolescent (Entity => "+"); |
| end; |
| @end example |
| |
| Note that, as for all pragmas, if you use a pragma argument identifier, |
| then all subsequent parameters must also use a pragma argument identifier. |
| So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} |
| argument is present, it must be preceded by @code{Message =>}. |
| |
| @node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ae} |
| @section Pragma Optimize_Alignment |
| |
| |
| @geindex Alignment |
| @geindex default settings |
| |
| Syntax: |
| |
| @example |
| pragma Optimize_Alignment (TIME | SPACE | OFF); |
| @end example |
| |
| This is a configuration pragma which affects the choice of default alignments |
| for types and objects where no alignment is explicitly specified. There is a |
| time/space trade-off in the selection of these values. Large alignments result |
| in more efficient code, at the expense of larger data space, since sizes have |
| to be increased to match these alignments. Smaller alignments save space, but |
| the access code is slower. The normal choice of default alignments for types |
| and individual alignment promotions for objects (which is what you get if you |
| do not use this pragma, or if you use an argument of OFF), tries to balance |
| these two requirements. |
| |
| Specifying SPACE causes smaller default alignments to be chosen in two cases. |
| First any packed record is given an alignment of 1. Second, if a size is given |
| for the type, then the alignment is chosen to avoid increasing this size. For |
| example, consider: |
| |
| @example |
| type R is record |
| X : Integer; |
| Y : Character; |
| end record; |
| |
| for R'Size use 5*8; |
| @end example |
| |
| In the default mode, this type gets an alignment of 4, so that access to the |
| Integer field X are efficient. But this means that objects of the type end up |
| with a size of 8 bytes. This is a valid choice, since sizes of objects are |
| allowed to be bigger than the size of the type, but it can waste space if for |
| example fields of type R appear in an enclosing record. If the above type is |
| compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. |
| |
| However, there is one case in which SPACE is ignored. If a variable length |
| record (that is a discriminated record with a component which is an array |
| whose length depends on a discriminant), has a pragma Pack, then it is not |
| in general possible to set the alignment of such a record to one, so the |
| pragma is ignored in this case (with a warning). |
| |
| Specifying SPACE also disables alignment promotions for standalone objects, |
| which occur when the compiler increases the alignment of a specific object |
| without changing the alignment of its type. |
| |
| Specifying SPACE also disables component reordering in unpacked record types, |
| which can result in larger sizes in order to meet alignment requirements. |
| |
| Specifying TIME causes larger default alignments to be chosen in the case of |
| small types with sizes that are not a power of 2. For example, consider: |
| |
| @example |
| type R is record |
| A : Character; |
| B : Character; |
| C : Boolean; |
| end record; |
| |
| pragma Pack (R); |
| for R'Size use 17; |
| @end example |
| |
| The default alignment for this record is normally 1, but if this type is |
| compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set |
| to 4, which wastes space for objects of the type, since they are now 4 bytes |
| long, but results in more efficient access when the whole record is referenced. |
| |
| As noted above, this is a configuration pragma, and there is a requirement |
| that all units in a partition be compiled with a consistent setting of the |
| optimization setting. This would normally be achieved by use of a configuration |
| pragma file containing the appropriate setting. The exception to this rule is |
| that units with an explicit configuration pragma in the same file as the source |
| unit are excluded from the consistency check, as are all predefined units. The |
| latter are compiled by default in pragma Optimize_Alignment (Off) mode if no |
| pragma appears at the start of the file. |
| |
| @node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{af} |
| @section Pragma Ordered |
| |
| |
| Syntax: |
| |
| @example |
| pragma Ordered (enumeration_first_subtype_LOCAL_NAME); |
| @end example |
| |
| Most enumeration types are from a conceptual point of view unordered. |
| For example, consider: |
| |
| @example |
| type Color is (Red, Blue, Green, Yellow); |
| @end example |
| |
| By Ada semantics @code{Blue > Red} and @code{Green > Blue}, |
| but really these relations make no sense; the enumeration type merely |
| specifies a set of possible colors, and the order is unimportant. |
| |
| For unordered enumeration types, it is generally a good idea if |
| clients avoid comparisons (other than equality or inequality) and |
| explicit ranges. (A @emph{client} is a unit where the type is referenced, |
| other than the unit where the type is declared, its body, and its subunits.) |
| For example, if code buried in some client says: |
| |
| @example |
| if Current_Color < Yellow then ... |
| if Current_Color in Blue .. Green then ... |
| @end example |
| |
| then the client code is relying on the order, which is undesirable. |
| It makes the code hard to read and creates maintenance difficulties if |
| entries have to be added to the enumeration type. Instead, |
| the code in the client should list the possibilities, or an |
| appropriate subtype should be declared in the unit that declares |
| the original enumeration type. E.g., the following subtype could |
| be declared along with the type @code{Color}: |
| |
| @example |
| subtype RBG is Color range Red .. Green; |
| @end example |
| |
| and then the client could write: |
| |
| @example |
| if Current_Color in RBG then ... |
| if Current_Color = Blue or Current_Color = Green then ... |
| @end example |
| |
| However, some enumeration types are legitimately ordered from a conceptual |
| point of view. For example, if you declare: |
| |
| @example |
| type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); |
| @end example |
| |
| then the ordering imposed by the language is reasonable, and |
| clients can depend on it, writing for example: |
| |
| @example |
| if D in Mon .. Fri then ... |
| if D < Wed then ... |
| @end example |
| |
| The pragma @emph{Ordered} is provided to mark enumeration types that |
| are conceptually ordered, alerting the reader that clients may depend |
| on the ordering. GNAT provides a pragma to mark enumerations as ordered |
| rather than one to mark them as unordered, since in our experience, |
| the great majority of enumeration types are conceptually unordered. |
| |
| The types @code{Boolean}, @code{Character}, @code{Wide_Character}, |
| and @code{Wide_Wide_Character} |
| are considered to be ordered types, so each is declared with a |
| pragma @code{Ordered} in package @code{Standard}. |
| |
| Normally pragma @code{Ordered} serves only as documentation and a guide for |
| coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that |
| requests warnings for inappropriate uses (comparisons and explicit |
| subranges) for unordered types. If this switch is used, then any |
| enumeration type not marked with pragma @code{Ordered} will be considered |
| as unordered, and will generate warnings for inappropriate uses. |
| |
| Note that generic types are not considered ordered or unordered (since the |
| template can be instantiated for both cases), so we never generate warnings |
| for the case of generic enumerated types. |
| |
| For additional information please refer to the description of the |
| @emph{-gnatw.u} switch in the GNAT User’s Guide. |
| |
| @node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b0} |
| @section Pragma Overflow_Mode |
| |
| |
| Syntax: |
| |
| @example |
| pragma Overflow_Mode |
| ( [General =>] MODE |
| [,[Assertions =>] MODE]); |
| |
| MODE ::= STRICT | MINIMIZED | ELIMINATED |
| @end example |
| |
| This pragma sets the current overflow mode to the given setting. For details |
| of the meaning of these modes, please refer to the |
| ‘Overflow Check Handling in GNAT’ appendix in the |
| GNAT User’s Guide. If only the @code{General} parameter is present, |
| the given mode applies to all expressions. If both parameters are present, |
| the @code{General} mode applies to expressions outside assertions, and |
| the @code{Eliminated} mode applies to expressions within assertions. |
| |
| The case of the @code{MODE} parameter is ignored, |
| so @code{MINIMIZED}, @code{Minimized} and |
| @code{minimized} all have the same effect. |
| |
| The @code{Overflow_Mode} pragma has the same scoping and placement |
| rules as pragma @code{Suppress}, so it can occur either as a |
| configuration pragma, specifying a default for the whole |
| program, or in a declarative scope, where it applies to the |
| remaining declarations and statements in that scope. |
| |
| The pragma @code{Suppress (Overflow_Check)} suppresses |
| overflow checking, but does not affect the overflow mode. |
| |
| The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) |
| overflow checking, but does not affect the overflow mode. |
| |
| @node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b1} |
| @section Pragma Overriding_Renamings |
| |
| |
| @geindex Rational profile |
| |
| @geindex Rational compatibility |
| |
| Syntax: |
| |
| @example |
| pragma Overriding_Renamings; |
| @end example |
| |
| This is a GNAT configuration pragma to simplify porting |
| legacy code accepted by the Rational |
| Ada compiler. In the presence of this pragma, a renaming declaration that |
| renames an inherited operation declared in the same scope is legal if selected |
| notation is used as in: |
| |
| @example |
| pragma Overriding_Renamings; |
| ... |
| package R is |
| function F (..); |
| ... |
| function F (..) renames R.F; |
| end R; |
| @end example |
| |
| even though |
| RM 8.3 (15) stipulates that an overridden operation is not visible within the |
| declaration of the overriding operation. |
| |
| @node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b2} |
| @section Pragma Partition_Elaboration_Policy |
| |
| |
| Syntax: |
| |
| @example |
| pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); |
| |
| POLICY_IDENTIFIER ::= Concurrent | Sequential |
| @end example |
| |
| This pragma is standard in Ada 2005, but is available in all earlier |
| versions of Ada as an implementation-defined pragma. |
| See Ada 2012 Reference Manual for details. |
| |
| @node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b3}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b4} |
| @section Pragma Part_Of |
| |
| |
| Syntax: |
| |
| @example |
| pragma Part_Of (ABSTRACT_STATE); |
| |
| ABSTRACT_STATE ::= NAME |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the |
| SPARK 2014 Reference Manual, section 7.2.6. |
| |
| @node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b5} |
| @section Pragma Passive |
| |
| |
| Syntax: |
| |
| @example |
| pragma Passive [(Semaphore | No)]; |
| @end example |
| |
| Syntax checked, but otherwise ignored by GNAT. This is recognized for |
| compatibility with DEC Ada 83 implementations, where it is used within a |
| task definition to request that a task be made passive. If the argument |
| @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 |
| treats the pragma as an assertion that the containing task is passive |
| and that optimization of context switch with this task is permitted and |
| desired. If the argument @code{No} is present, the task must not be |
| optimized. GNAT does not attempt to optimize any tasks in this manner |
| (since protected objects are available in place of passive tasks). |
| |
| For more information on the subject of passive tasks, see the section |
| ‘Passive Task Optimization’ in the GNAT Users Guide. |
| |
| @node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b6}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b7} |
| @section Pragma Persistent_BSS |
| |
| |
| Syntax: |
| |
| @example |
| pragma Persistent_BSS [(LOCAL_NAME)] |
| @end example |
| |
| This pragma allows selected objects to be placed in the @code{.persistent_bss} |
| section. On some targets the linker and loader provide for special |
| treatment of this section, allowing a program to be reloaded without |
| affecting the contents of this data (hence the name persistent). |
| |
| There are two forms of usage. If an argument is given, it must be the |
| local name of a library-level object, with no explicit initialization |
| and whose type is potentially persistent. If no argument is given, then |
| the pragma is a configuration pragma, and applies to all library-level |
| objects with no explicit initialization of potentially persistent types. |
| |
| A potentially persistent type is a scalar type, or an untagged, |
| non-discriminated record, all of whose components have no explicit |
| initialization and are themselves of a potentially persistent type, |
| or an array, all of whose constraints are static, and whose component |
| type is potentially persistent. |
| |
| If this pragma is used on a target where this feature is not supported, |
| then the pragma will be ignored. See also @code{pragma Linker_Section}. |
| |
| @node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b8} |
| @section Pragma Post |
| |
| |
| @geindex Post |
| |
| @geindex Checks |
| @geindex postconditions |
| |
| Syntax: |
| |
| @example |
| pragma Post (Boolean_Expression); |
| @end example |
| |
| The @code{Post} pragma is intended to be an exact replacement for |
| the language-defined |
| @code{Post} aspect, and shares its restrictions and semantics. |
| It must appear either immediately following the corresponding |
| subprogram declaration (only other pragmas may intervene), or |
| if there is no separate subprogram declaration, then it can |
| appear at the start of the declarations in a subprogram body |
| (preceded only by other pragmas). |
| |
| @node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b9} |
| @section Pragma Postcondition |
| |
| |
| @geindex Postcondition |
| |
| @geindex Checks |
| @geindex postconditions |
| |
| Syntax: |
| |
| @example |
| pragma Postcondition ( |
| [Check =>] Boolean_Expression |
| [,[Message =>] String_Expression]); |
| @end example |
| |
| The @code{Postcondition} pragma allows specification of automatic |
| postcondition checks for subprograms. These checks are similar to |
| assertions, but are automatically inserted just prior to the return |
| statements of the subprogram with which they are associated (including |
| implicit returns at the end of procedure bodies and associated |
| exception handlers). |
| |
| In addition, the boolean expression which is the condition which |
| must be true may contain references to function’Result in the case |
| of a function to refer to the returned value. |
| |
| @code{Postcondition} pragmas may appear either immediately following the |
| (separate) declaration of a subprogram, or at the start of the |
| declarations of a subprogram body. Only other pragmas may intervene |
| (that is appear between the subprogram declaration and its |
| postconditions, or appear before the postcondition in the |
| declaration sequence in a subprogram body). In the case of a |
| postcondition appearing after a subprogram declaration, the |
| formal arguments of the subprogram are visible, and can be |
| referenced in the postcondition expressions. |
| |
| The postconditions are collected and automatically tested just |
| before any return (implicit or explicit) in the subprogram body. |
| A postcondition is only recognized if postconditions are active |
| at the time the pragma is encountered. The compiler switch @emph{gnata} |
| turns on all postconditions by default, and pragma @code{Check_Policy} |
| with an identifier of @code{Postcondition} can also be used to |
| control whether postconditions are active. |
| |
| The general approach is that postconditions are placed in the spec |
| if they represent functional aspects which make sense to the client. |
| For example we might have: |
| |
| @example |
| function Direction return Integer; |
| pragma Postcondition |
| (Direction'Result = +1 |
| or else |
| Direction'Result = -1); |
| @end example |
| |
| which serves to document that the result must be +1 or -1, and |
| will test that this is the case at run time if postcondition |
| checking is active. |
| |
| Postconditions within the subprogram body can be used to |
| check that some internal aspect of the implementation, |
| not visible to the client, is operating as expected. |
| For instance if a square root routine keeps an internal |
| counter of the number of times it is called, then we |
| might have the following postcondition: |
| |
| @example |
| Sqrt_Calls : Natural := 0; |
| |
| function Sqrt (Arg : Float) return Float is |
| pragma Postcondition |
| (Sqrt_Calls = Sqrt_Calls'Old + 1); |
| ... |
| end Sqrt |
| @end example |
| |
| As this example, shows, the use of the @code{Old} attribute |
| is often useful in postconditions to refer to the state on |
| entry to the subprogram. |
| |
| Note that postconditions are only checked on normal returns |
| from the subprogram. If an abnormal return results from |
| raising an exception, then the postconditions are not checked. |
| |
| If a postcondition fails, then the exception |
| @code{System.Assertions.Assert_Failure} is raised. If |
| a message argument was supplied, then the given string |
| will be used as the exception message. If no message |
| argument was supplied, then the default message has |
| the form “Postcondition failed at file_name:line”. The |
| exception is raised in the context of the subprogram |
| body, so it is possible to catch postcondition failures |
| within the subprogram body itself. |
| |
| Within a package spec, normal visibility rules |
| in Ada would prevent forward references within a |
| postcondition pragma to functions defined later in |
| the same package. This would introduce undesirable |
| ordering constraints. To avoid this problem, all |
| postcondition pragmas are analyzed at the end of |
| the package spec, allowing forward references. |
| |
| The following example shows that this even allows |
| mutually recursive postconditions as in: |
| |
| @example |
| package Parity_Functions is |
| function Odd (X : Natural) return Boolean; |
| pragma Postcondition |
| (Odd'Result = |
| (x = 1 |
| or else |
| (x /= 0 and then Even (X - 1)))); |
| |
| function Even (X : Natural) return Boolean; |
| pragma Postcondition |
| (Even'Result = |
| (x = 0 |
| or else |
| (x /= 1 and then Odd (X - 1)))); |
| |
| end Parity_Functions; |
| @end example |
| |
| There are no restrictions on the complexity or form of |
| conditions used within @code{Postcondition} pragmas. |
| The following example shows that it is even possible |
| to verify performance behavior. |
| |
| @example |
| package Sort is |
| |
| Performance : constant Float; |
| -- Performance constant set by implementation |
| -- to match target architecture behavior. |
| |
| procedure Treesort (Arg : String); |
| -- Sorts characters of argument using N*logN sort |
| pragma Postcondition |
| (Float (Clock - Clock'Old) <= |
| Float (Arg'Length) * |
| log (Float (Arg'Length)) * |
| Performance); |
| end Sort; |
| @end example |
| |
| Note: postcondition pragmas associated with subprograms that are |
| marked as Inline_Always, or those marked as Inline with front-end |
| inlining (-gnatN option set) are accepted and legality-checked |
| by the compiler, but are ignored at run-time even if postcondition |
| checking is enabled. |
| |
| Note that pragma @code{Postcondition} differs from the language-defined |
| @code{Post} aspect (and corresponding @code{Post} pragma) in allowing |
| multiple occurrences, allowing occurences in the body even if there |
| is a separate spec, and allowing a second string parameter, and the |
| use of the pragma identifier @code{Check}. Historically, pragma |
| @code{Postcondition} was implemented prior to the development of |
| Ada 2012, and has been retained in its original form for |
| compatibility purposes. |
| |
| @node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{ba} |
| @section Pragma Post_Class |
| |
| |
| @geindex Post |
| |
| @geindex Checks |
| @geindex postconditions |
| |
| Syntax: |
| |
| @example |
| pragma Post_Class (Boolean_Expression); |
| @end example |
| |
| The @code{Post_Class} pragma is intended to be an exact replacement for |
| the language-defined |
| @code{Post'Class} aspect, and shares its restrictions and semantics. |
| It must appear either immediately following the corresponding |
| subprogram declaration (only other pragmas may intervene), or |
| if there is no separate subprogram declaration, then it can |
| appear at the start of the declarations in a subprogram body |
| (preceded only by other pragmas). |
| |
| Note: This pragma is called @code{Post_Class} rather than |
| @code{Post'Class} because the latter would not be strictly |
| conforming to the allowed syntax for pragmas. The motivation |
| for provinding pragmas equivalent to the aspects is to allow a program |
| to be written using the pragmas, and then compiled if necessary |
| using an Ada compiler that does not recognize the pragmas or |
| aspects, but is prepared to ignore the pragmas. The assertion |
| policy that controls this pragma is @code{Post'Class}, not |
| @code{Post_Class}. |
| |
| @node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{bb} |
| @section Pragma Pre |
| |
| |
| @geindex Pre |
| |
| @geindex Checks |
| @geindex preconditions |
| |
| Syntax: |
| |
| @example |
| pragma Pre (Boolean_Expression); |
| @end example |
| |
| The @code{Pre} pragma is intended to be an exact replacement for |
| the language-defined |
| @code{Pre} aspect, and shares its restrictions and semantics. |
| It must appear either immediately following the corresponding |
| subprogram declaration (only other pragmas may intervene), or |
| if there is no separate subprogram declaration, then it can |
| appear at the start of the declarations in a subprogram body |
| (preceded only by other pragmas). |
| |
| @node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bc} |
| @section Pragma Precondition |
| |
| |
| @geindex Preconditions |
| |
| @geindex Checks |
| @geindex preconditions |
| |
| Syntax: |
| |
| @example |
| pragma Precondition ( |
| [Check =>] Boolean_Expression |
| [,[Message =>] String_Expression]); |
| @end example |
| |
| The @code{Precondition} pragma is similar to @code{Postcondition} |
| except that the corresponding checks take place immediately upon |
| entry to the subprogram, and if a precondition fails, the exception |
| is raised in the context of the caller, and the attribute ‘Result |
| cannot be used within the precondition expression. |
| |
| Otherwise, the placement and visibility rules are identical to those |
| described for postconditions. The following is an example of use |
| within a package spec: |
| |
| @example |
| package Math_Functions is |
| ... |
| function Sqrt (Arg : Float) return Float; |
| pragma Precondition (Arg >= 0.0) |
| ... |
| end Math_Functions; |
| @end example |
| |
| @code{Precondition} pragmas may appear either immediately following the |
| (separate) declaration of a subprogram, or at the start of the |
| declarations of a subprogram body. Only other pragmas may intervene |
| (that is appear between the subprogram declaration and its |
| postconditions, or appear before the postcondition in the |
| declaration sequence in a subprogram body). |
| |
| Note: precondition pragmas associated with subprograms that are |
| marked as Inline_Always, or those marked as Inline with front-end |
| inlining (-gnatN option set) are accepted and legality-checked |
| by the compiler, but are ignored at run-time even if precondition |
| checking is enabled. |
| |
| Note that pragma @code{Precondition} differs from the language-defined |
| @code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing |
| multiple occurrences, allowing occurences in the body even if there |
| is a separate spec, and allowing a second string parameter, and the |
| use of the pragma identifier @code{Check}. Historically, pragma |
| @code{Precondition} was implemented prior to the development of |
| Ada 2012, and has been retained in its original form for |
| compatibility purposes. |
| |
| @node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{bd}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{be} |
| @section Pragma Predicate |
| |
| |
| Syntax: |
| |
| @example |
| pragma Predicate |
| ([Entity =>] type_LOCAL_NAME, |
| [Check =>] EXPRESSION); |
| @end example |
| |
| This pragma (available in all versions of Ada in GNAT) encompasses both |
| the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in |
| Ada 2012. A predicate is regarded as static if it has an allowed form |
| for @code{Static_Predicate} and is otherwise treated as a |
| @code{Dynamic_Predicate}. Otherwise, predicates specified by this |
| pragma behave exactly as described in the Ada 2012 reference manual. |
| For example, if we have |
| |
| @example |
| type R is range 1 .. 10; |
| subtype S is R; |
| pragma Predicate (Entity => S, Check => S not in 4 .. 6); |
| subtype Q is R |
| pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); |
| @end example |
| |
| the effect is identical to the following Ada 2012 code: |
| |
| @example |
| type R is range 1 .. 10; |
| subtype S is R with |
| Static_Predicate => S not in 4 .. 6; |
| subtype Q is R with |
| Dynamic_Predicate => F(Q) or G(Q); |
| @end example |
| |
| Note that there are no pragmas @code{Dynamic_Predicate} |
| or @code{Static_Predicate}. That is |
| because these pragmas would affect legality and semantics of |
| the program and thus do not have a neutral effect if ignored. |
| The motivation behind providing pragmas equivalent to |
| corresponding aspects is to allow a program to be written |
| using the pragmas, and then compiled with a compiler that |
| will ignore the pragmas. That doesn’t work in the case of |
| static and dynamic predicates, since if the corresponding |
| pragmas are ignored, then the behavior of the program is |
| fundamentally changed (for example a membership test |
| @code{A in B} would not take into account a predicate |
| defined for subtype B). When following this approach, the |
| use of predicates should be avoided. |
| |
| @node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{bf} |
| @section Pragma Predicate_Failure |
| |
| |
| Syntax: |
| |
| @example |
| pragma Predicate_Failure |
| ([Entity =>] type_LOCAL_NAME, |
| [Message =>] String_Expression); |
| @end example |
| |
| The @code{Predicate_Failure} pragma is intended to be an exact replacement for |
| the language-defined |
| @code{Predicate_Failure} aspect, and shares its restrictions and semantics. |
| |
| @node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c0} |
| @section Pragma Preelaborable_Initialization |
| |
| |
| Syntax: |
| |
| @example |
| pragma Preelaborable_Initialization (DIRECT_NAME); |
| @end example |
| |
| This pragma is standard in Ada 2005, but is available in all earlier |
| versions of Ada as an implementation-defined pragma. |
| See Ada 2012 Reference Manual for details. |
| |
| @node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c1} |
| @section Pragma Prefix_Exception_Messages |
| |
| |
| @geindex Prefix_Exception_Messages |
| |
| @geindex exception |
| |
| @geindex Exception_Message |
| |
| Syntax: |
| |
| @example |
| pragma Prefix_Exception_Messages; |
| @end example |
| |
| This is an implementation-defined configuration pragma that affects the |
| behavior of raise statements with a message given as a static string |
| constant (typically a string literal). In such cases, the string will |
| be automatically prefixed by the name of the enclosing entity (giving |
| the package and subprogram containing the raise statement). This helps |
| to identify where messages are coming from, and this mode is automatic |
| for the run-time library. |
| |
| The pragma has no effect if the message is computed with an expression other |
| than a static string constant, since the assumption in this case is that |
| the program computes exactly the string it wants. If you still want the |
| prefixing in this case, you can always call |
| @code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. |
| |
| @node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c2} |
| @section Pragma Pre_Class |
| |
| |
| @geindex Pre_Class |
| |
| @geindex Checks |
| @geindex preconditions |
| |
| Syntax: |
| |
| @example |
| pragma Pre_Class (Boolean_Expression); |
| @end example |
| |
| The @code{Pre_Class} pragma is intended to be an exact replacement for |
| the language-defined |
| @code{Pre'Class} aspect, and shares its restrictions and semantics. |
| It must appear either immediately following the corresponding |
| subprogram declaration (only other pragmas may intervene), or |
| if there is no separate subprogram declaration, then it can |
| appear at the start of the declarations in a subprogram body |
| (preceded only by other pragmas). |
| |
| Note: This pragma is called @code{Pre_Class} rather than |
| @code{Pre'Class} because the latter would not be strictly |
| conforming to the allowed syntax for pragmas. The motivation |
| for providing pragmas equivalent to the aspects is to allow a program |
| to be written using the pragmas, and then compiled if necessary |
| using an Ada compiler that does not recognize the pragmas or |
| aspects, but is prepared to ignore the pragmas. The assertion |
| policy that controls this pragma is @code{Pre'Class}, not |
| @code{Pre_Class}. |
| |
| @node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c3} |
| @section Pragma Priority_Specific_Dispatching |
| |
| |
| Syntax: |
| |
| @example |
| pragma Priority_Specific_Dispatching ( |
| POLICY_IDENTIFIER, |
| first_priority_EXPRESSION, |
| last_priority_EXPRESSION) |
| |
| POLICY_IDENTIFIER ::= |
| EDF_Across_Priorities | |
| FIFO_Within_Priorities | |
| Non_Preemptive_Within_Priorities | |
| Round_Robin_Within_Priorities |
| @end example |
| |
| This pragma is standard in Ada 2005, but is available in all earlier |
| versions of Ada as an implementation-defined pragma. |
| See Ada 2012 Reference Manual for details. |
| |
| @node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c4} |
| @section Pragma Profile |
| |
| |
| Syntax: |
| |
| @example |
| pragma Profile (Ravenscar | Restricted | Rational | Jorvik | |
| GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); |
| @end example |
| |
| This pragma is standard in Ada 2005, but is available in all earlier |
| versions of Ada as an implementation-defined pragma. This is a |
| configuration pragma that establishes a set of configuration pragmas |
| that depend on the argument. @code{Ravenscar} is standard in Ada 2005. |
| @code{Jorvik} is standard in Ada 202x. |
| The other possibilities (@code{Restricted}, @code{Rational}, |
| @code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) |
| are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. |
| |
| The set of configuration pragmas is defined in the following sections. |
| |
| |
| @itemize * |
| |
| @item |
| Pragma Profile (Ravenscar) |
| |
| The @code{Ravenscar} profile is standard in Ada 2005, |
| but is available in all earlier |
| versions of Ada as an implementation-defined pragma. This profile |
| establishes the following set of configuration pragmas: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Task_Dispatching_Policy (FIFO_Within_Priorities)} |
| |
| [RM D.2.2] Tasks are dispatched following a preemptive |
| priority-ordered scheduling policy. |
| |
| @item |
| @code{Locking_Policy (Ceiling_Locking)} |
| |
| [RM D.3] While tasks and interrupts execute a protected action, they inherit |
| the ceiling priority of the corresponding protected object. |
| |
| @item |
| @code{Detect_Blocking} |
| |
| This pragma forces the detection of potentially blocking operations within a |
| protected operation, and to raise Program_Error if that happens. |
| @end itemize |
| |
| plus the following set of restrictions: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Max_Entry_Queue_Length => 1} |
| |
| No task can be queued on a protected entry. |
| |
| @item |
| @code{Max_Protected_Entries => 1} |
| |
| @item |
| @code{Max_Task_Entries => 0} |
| |
| No rendezvous statements are allowed. |
| |
| @item |
| @code{No_Abort_Statements} |
| |
| @item |
| @code{No_Dynamic_Attachment} |
| |
| @item |
| @code{No_Dynamic_Priorities} |
| |
| @item |
| @code{No_Implicit_Heap_Allocations} |
| |
| @item |
| @code{No_Local_Protected_Objects} |
| |
| @item |
| @code{No_Local_Timing_Events} |
| |
| @item |
| @code{No_Protected_Type_Allocators} |
| |
| @item |
| @code{No_Relative_Delay} |
| |
| @item |
| @code{No_Requeue_Statements} |
| |
| @item |
| @code{No_Select_Statements} |
| |
| @item |
| @code{No_Specific_Termination_Handlers} |
| |
| @item |
| @code{No_Task_Allocators} |
| |
| @item |
| @code{No_Task_Hierarchy} |
| |
| @item |
| @code{No_Task_Termination} |
| |
| @item |
| @code{Simple_Barriers} |
| @end itemize |
| |
| The Ravenscar profile also includes the following restrictions that specify |
| that there are no semantic dependencies on the corresponding predefined |
| packages: |
| |
| |
| @itemize * |
| |
| @item |
| @code{No_Dependence => Ada.Asynchronous_Task_Control} |
| |
| @item |
| @code{No_Dependence => Ada.Calendar} |
| |
| @item |
| @code{No_Dependence => Ada.Execution_Time.Group_Budget} |
| |
| @item |
| @code{No_Dependence => Ada.Execution_Time.Timers} |
| |
| @item |
| @code{No_Dependence => Ada.Task_Attributes} |
| |
| @item |
| @code{No_Dependence => System.Multiprocessors.Dispatching_Domains} |
| @end itemize |
| |
| This set of configuration pragmas and restrictions correspond to the |
| definition of the ‘Ravenscar Profile’ for limited tasking, devised and |
| published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. |
| A description is also available at |
| @indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. |
| |
| The original definition of the profile was revised at subsequent IRTAW |
| meetings. It has been included in the ISO |
| @cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, |
| and was made part of the Ada 2005 standard. |
| The formal definition given by |
| the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and |
| AI-305) available at |
| @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and |
| @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. |
| |
| The above set is a superset of the restrictions provided by pragma |
| @code{Profile (Restricted)}, it includes six additional restrictions |
| (@code{Simple_Barriers}, @code{No_Select_Statements}, |
| @code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, |
| @code{No_Relative_Delay} and @code{No_Task_Termination}). This means |
| that pragma @code{Profile (Ravenscar)}, like the pragma |
| @code{Profile (Restricted)}, |
| automatically causes the use of a simplified, |
| more efficient version of the tasking run-time library. |
| |
| @item |
| Pragma Profile (Jorvik) |
| |
| @code{Jorvik} is the new profile added to the Ada 202x draft standard, |
| previously implemented under the name @code{GNAT_Extended_Ravenscar}. |
| |
| The @code{No_Implicit_Heap_Allocations} restriction has been replaced |
| by @code{No_Implicit_Task_Allocations} and |
| @code{No_Implicit_Protected_Object_Allocations}. |
| |
| The @code{Simple_Barriers} restriction has been replaced by |
| @code{Pure_Barriers}. |
| |
| The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and |
| @code{No_Relative_Delay} restrictions have been removed. |
| |
| Details on the rationale for @code{Jorvik} and implications for use may be |
| found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, |
| T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, |
| Number 10300. |
| |
| @item |
| Pragma Profile (GNAT_Ravenscar_EDF) |
| |
| This profile corresponds to the Ravenscar profile but using |
| EDF_Across_Priority as the Task_Scheduling_Policy. |
| |
| @item |
| Pragma Profile (Restricted) |
| |
| This profile corresponds to the GNAT restricted run time. It |
| establishes the following set of restrictions: |
| |
| |
| @itemize * |
| |
| @item |
| @code{No_Abort_Statements} |
| |
| @item |
| @code{No_Entry_Queue} |
| |
| @item |
| @code{No_Task_Hierarchy} |
| |
| @item |
| @code{No_Task_Allocators} |
| |
| @item |
| @code{No_Dynamic_Priorities} |
| |
| @item |
| @code{No_Terminate_Alternatives} |
| |
| @item |
| @code{No_Dynamic_Attachment} |
| |
| @item |
| @code{No_Protected_Type_Allocators} |
| |
| @item |
| @code{No_Local_Protected_Objects} |
| |
| @item |
| @code{No_Requeue_Statements} |
| |
| @item |
| @code{No_Task_Attributes_Package} |
| |
| @item |
| @code{Max_Asynchronous_Select_Nesting = 0} |
| |
| @item |
| @code{Max_Task_Entries = 0} |
| |
| @item |
| @code{Max_Protected_Entries = 1} |
| |
| @item |
| @code{Max_Select_Alternatives = 0} |
| @end itemize |
| |
| This set of restrictions causes the automatic selection of a simplified |
| version of the run time that provides improved performance for the |
| limited set of tasking functionality permitted by this set of restrictions. |
| |
| @item |
| Pragma Profile (Rational) |
| |
| The Rational profile is intended to facilitate porting legacy code that |
| compiles with the Rational APEX compiler, even when the code includes non- |
| conforming Ada constructs. The profile enables the following three pragmas: |
| |
| |
| @itemize * |
| |
| @item |
| @code{pragma Implicit_Packing} |
| |
| @item |
| @code{pragma Overriding_Renamings} |
| |
| @item |
| @code{pragma Use_VADS_Size} |
| @end itemize |
| @end itemize |
| |
| @node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c5} |
| @section Pragma Profile_Warnings |
| |
| |
| Syntax: |
| |
| @example |
| pragma Profile_Warnings (Ravenscar | Restricted | Rational); |
| @end example |
| |
| This is an implementation-defined pragma that is similar in |
| effect to @code{pragma Profile} except that instead of |
| generating @code{Restrictions} pragmas, it generates |
| @code{Restriction_Warnings} pragmas. The result is that |
| violations of the profile generate warning messages instead |
| of error messages. |
| |
| @node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c6} |
| @section Pragma Propagate_Exceptions |
| |
| |
| @geindex Interfacing to C++ |
| |
| Syntax: |
| |
| @example |
| pragma Propagate_Exceptions; |
| @end example |
| |
| This pragma is now obsolete and, other than generating a warning if warnings |
| on obsolescent features are enabled, is ignored. |
| It is retained for compatibility |
| purposes. It used to be used in connection with optimization of |
| a now-obsolete mechanism for implementation of exceptions. |
| |
| @node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c7} |
| @section Pragma Provide_Shift_Operators |
| |
| |
| @geindex Shift operators |
| |
| Syntax: |
| |
| @example |
| pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); |
| @end example |
| |
| This pragma can be applied to a first subtype local name that specifies |
| either an unsigned or signed type. It has the effect of providing the |
| five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, |
| Rotate_Left and Rotate_Right) for the given type. It is similar to |
| including the function declarations for these five operators, together |
| with the pragma Import (Intrinsic, …) statements. |
| |
| @node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c8} |
| @section Pragma Psect_Object |
| |
| |
| Syntax: |
| |
| @example |
| pragma Psect_Object ( |
| [Internal =>] LOCAL_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Size =>] EXTERNAL_SYMBOL]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end example |
| |
| This pragma is identical in effect to pragma @code{Common_Object}. |
| |
| @node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{c9}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{ca} |
| @section Pragma Pure_Function |
| |
| |
| Syntax: |
| |
| @example |
| pragma Pure_Function ([Entity =>] function_LOCAL_NAME); |
| @end example |
| |
| This pragma appears in the same declarative part as a function |
| declaration (or a set of function declarations if more than one |
| overloaded declaration exists, in which case the pragma applies |
| to all entities). It specifies that the function @code{Entity} is |
| to be considered pure for the purposes of code generation. This means |
| that the compiler can assume that there are no side effects, and |
| in particular that two calls with identical arguments produce the |
| same result. It also means that the function can be used in an |
| address clause. |
| |
| Note that, quite deliberately, there are no static checks to try |
| to ensure that this promise is met, so @code{Pure_Function} can be used |
| with functions that are conceptually pure, even if they do modify |
| global variables. For example, a square root function that is |
| instrumented to count the number of times it is called is still |
| conceptually pure, and can still be optimized, even though it |
| modifies a global variable (the count). Memo functions are another |
| example (where a table of previous calls is kept and consulted to |
| avoid re-computation). |
| |
| Note also that the normal rules excluding optimization of subprograms |
| in pure units (when parameter types are descended from System.Address, |
| or when the full view of a parameter type is limited), do not apply |
| for the Pure_Function case. If you explicitly specify Pure_Function, |
| the compiler may optimize away calls with identical arguments, and |
| if that results in unexpected behavior, the proper action is not to |
| use the pragma for subprograms that are not (conceptually) pure. |
| |
| Note: Most functions in a @code{Pure} package are automatically pure, and |
| there is no need to use pragma @code{Pure_Function} for such functions. One |
| exception is any function that has at least one formal of type |
| @code{System.Address} or a type derived from it. Such functions are not |
| considered pure by default, since the compiler assumes that the |
| @code{Address} parameter may be functioning as a pointer and that the |
| referenced data may change even if the address value does not. |
| Similarly, imported functions are not considered to be pure by default, |
| since there is no way of checking that they are in fact pure. The use |
| of pragma @code{Pure_Function} for such a function will override these default |
| assumption, and cause the compiler to treat a designated subprogram as pure |
| in these cases. |
| |
| Note: If pragma @code{Pure_Function} is applied to a renamed function, it |
| applies to the underlying renamed function. This can be used to |
| disambiguate cases of overloading where some but not all functions |
| in a set of overloaded functions are to be designated as pure. |
| |
| If pragma @code{Pure_Function} is applied to a library-level function, the |
| function is also considered pure from an optimization point of view, but the |
| unit is not a Pure unit in the categorization sense. So for example, a function |
| thus marked is free to @code{with} non-pure units. |
| |
| @node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{cb} |
| @section Pragma Rational |
| |
| |
| Syntax: |
| |
| @example |
| pragma Rational; |
| @end example |
| |
| This pragma is considered obsolescent, but is retained for |
| compatibility purposes. It is equivalent to: |
| |
| @example |
| pragma Profile (Rational); |
| @end example |
| |
| @node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cc} |
| @section Pragma Ravenscar |
| |
| |
| Syntax: |
| |
| @example |
| pragma Ravenscar; |
| @end example |
| |
| This pragma is considered obsolescent, but is retained for |
| compatibility purposes. It is equivalent to: |
| |
| @example |
| pragma Profile (Ravenscar); |
| @end example |
| |
| which is the preferred method of setting the @code{Ravenscar} profile. |
| |
| @node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cd}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{ce} |
| @section Pragma Refined_Depends |
| |
| |
| Syntax: |
| |
| @example |
| pragma Refined_Depends (DEPENDENCY_RELATION); |
| |
| DEPENDENCY_RELATION ::= |
| null |
| | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) |
| |
| DEPENDENCY_CLAUSE ::= |
| OUTPUT_LIST =>[+] INPUT_LIST |
| | NULL_DEPENDENCY_CLAUSE |
| |
| NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST |
| |
| OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) |
| |
| INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) |
| |
| OUTPUT ::= NAME | FUNCTION_RESULT |
| INPUT ::= NAME |
| |
| where FUNCTION_RESULT is a function Result attribute_reference |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in |
| the SPARK 2014 Reference Manual, section 6.1.5. |
| |
| @node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d0} |
| @section Pragma Refined_Global |
| |
| |
| Syntax: |
| |
| @example |
| pragma Refined_Global (GLOBAL_SPECIFICATION); |
| |
| GLOBAL_SPECIFICATION ::= |
| null |
| | (GLOBAL_LIST) |
| | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) |
| |
| MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST |
| |
| MODE_SELECTOR ::= In_Out | Input | Output | Proof_In |
| GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) |
| GLOBAL_ITEM ::= NAME |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in |
| the SPARK 2014 Reference Manual, section 6.1.4. |
| |
| @node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d1}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d2} |
| @section Pragma Refined_Post |
| |
| |
| Syntax: |
| |
| @example |
| pragma Refined_Post (boolean_EXPRESSION); |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in |
| the SPARK 2014 Reference Manual, section 7.2.7. |
| |
| @node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d3}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d4} |
| @section Pragma Refined_State |
| |
| |
| Syntax: |
| |
| @example |
| pragma Refined_State (REFINEMENT_LIST); |
| |
| REFINEMENT_LIST ::= |
| (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) |
| |
| REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST |
| |
| CONSTITUENT_LIST ::= |
| null |
| | CONSTITUENT |
| | (CONSTITUENT @{, CONSTITUENT@}) |
| |
| CONSTITUENT ::= object_NAME | state_NAME |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Refined_State} in |
| the SPARK 2014 Reference Manual, section 7.2.2. |
| |
| @node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d5} |
| @section Pragma Relative_Deadline |
| |
| |
| Syntax: |
| |
| @example |
| pragma Relative_Deadline (time_span_EXPRESSION); |
| @end example |
| |
| This pragma is standard in Ada 2005, but is available in all earlier |
| versions of Ada as an implementation-defined pragma. |
| See Ada 2012 Reference Manual for details. |
| |
| @node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d6}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d7} |
| @section Pragma Remote_Access_Type |
| |
| |
| Syntax: |
| |
| @example |
| pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); |
| @end example |
| |
| This pragma appears in the formal part of a generic declaration. |
| It specifies an exception to the RM rule from E.2.2(17/2), which forbids |
| the use of a remote access to class-wide type as actual for a formal |
| access type. |
| |
| When this pragma applies to a formal access type @code{Entity}, that |
| type is treated as a remote access to class-wide type in the generic. |
| It must be a formal general access type, and its designated type must |
| be the class-wide type of a formal tagged limited private type from the |
| same generic declaration. |
| |
| In the generic unit, the formal type is subject to all restrictions |
| pertaining to remote access to class-wide types. At instantiation, the |
| actual type must be a remote access to class-wide type. |
| |
| @node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{d8} |
| @section Pragma Rename_Pragma |
| |
| |
| @geindex Pragmas |
| @geindex synonyms |
| |
| Syntax: |
| |
| @example |
| pragma Rename_Pragma ( |
| [New_Name =>] IDENTIFIER, |
| [Renamed =>] pragma_IDENTIFIER); |
| @end example |
| |
| This pragma provides a mechanism for supplying new names for existing |
| pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for |
| the Renamed pragma. For example, suppose you have code that was originally |
| developed on a compiler that supports Inline_Only as an implementation defined |
| pragma. And suppose the semantics of pragma Inline_Only are identical to (or at |
| least very similar to) the GNAT implementation defined pragma |
| Inline_Always. You could globally replace Inline_Only with Inline_Always. |
| |
| However, to avoid that source modification, you could instead add a |
| configuration pragma: |
| |
| @example |
| pragma Rename_Pragma ( |
| New_Name => Inline_Only, |
| Renamed => Inline_Always); |
| @end example |
| |
| Then GNAT will treat “pragma Inline_Only …” as if you had written |
| “pragma Inline_Always …”. |
| |
| Pragma Inline_Only will not necessarily mean the same thing as the other Ada |
| compiler; it’s up to you to make sure the semantics are close enough. |
| |
| @node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d9} |
| @section Pragma Restricted_Run_Time |
| |
| |
| Syntax: |
| |
| @example |
| pragma Restricted_Run_Time; |
| @end example |
| |
| This pragma is considered obsolescent, but is retained for |
| compatibility purposes. It is equivalent to: |
| |
| @example |
| pragma Profile (Restricted); |
| @end example |
| |
| which is the preferred method of setting the restricted run time |
| profile. |
| |
| @node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{da} |
| @section Pragma Restriction_Warnings |
| |
| |
| Syntax: |
| |
| @example |
| pragma Restriction_Warnings |
| (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); |
| @end example |
| |
| This pragma allows a series of restriction identifiers to be |
| specified (the list of allowed identifiers is the same as for |
| pragma @code{Restrictions}). For each of these identifiers |
| the compiler checks for violations of the restriction, but |
| generates a warning message rather than an error message |
| if the restriction is violated. |
| |
| One use of this is in situations where you want to know |
| about violations of a restriction, but you want to ignore some of |
| these violations. Consider this example, where you want to set |
| Ada_95 mode and enable style checks, but you want to know about |
| any other use of implementation pragmas: |
| |
| @example |
| pragma Restriction_Warnings (No_Implementation_Pragmas); |
| pragma Warnings (Off, "violation of No_Implementation_Pragmas"); |
| pragma Ada_95; |
| pragma Style_Checks ("2bfhkM160"); |
| pragma Warnings (On, "violation of No_Implementation_Pragmas"); |
| @end example |
| |
| By including the above lines in a configuration pragmas file, |
| the Ada_95 and Style_Checks pragmas are accepted without |
| generating a warning, but any other use of implementation |
| defined pragmas will cause a warning to be generated. |
| |
| @node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{db} |
| @section Pragma Reviewable |
| |
| |
| Syntax: |
| |
| @example |
| pragma Reviewable; |
| @end example |
| |
| This pragma is an RM-defined standard pragma, but has no effect on the |
| program being compiled, or on the code generated for the program. |
| |
| To obtain the required output specified in RM H.3.1, the compiler must be |
| run with various special switches as follows: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Where compiler-generated run-time checks remain} |
| |
| The switch @emph{-gnatGL} |
| may be used to list the expanded code in pseudo-Ada form. |
| Runtime checks show up in the listing either as explicit |
| checks or operators marked with @{@} to indicate a check is present. |
| |
| @item |
| @emph{An identification of known exceptions at compile time} |
| |
| If the program is compiled with @emph{-gnatwa}, |
| the compiler warning messages will indicate all cases where the compiler |
| detects that an exception is certain to occur at run time. |
| |
| @item |
| @emph{Possible reads of uninitialized variables} |
| |
| The compiler warns of many such cases, but its output is incomplete. |
| @end itemize |
| |
| |
| A supplemental static analysis tool |
| may be used to obtain a comprehensive list of all |
| possible points at which uninitialized data may be read. |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Where run-time support routines are implicitly invoked} |
| |
| In the output from @emph{-gnatGL}, |
| run-time calls are explicitly listed as calls to the relevant |
| run-time routine. |
| |
| @item |
| @emph{Object code listing} |
| |
| This may be obtained either by using the @emph{-S} switch, |
| or the objdump utility. |
| |
| @item |
| @emph{Constructs known to be erroneous at compile time} |
| |
| These are identified by warnings issued by the compiler (use @emph{-gnatwa}). |
| |
| @item |
| @emph{Stack usage information} |
| |
| Static stack usage data (maximum per-subprogram) can be obtained via the |
| @emph{-fstack-usage} switch to the compiler. |
| Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch |
| to gnatbind |
| @end itemize |
| |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Object code listing of entire partition} |
| |
| This can be obtained by compiling the partition with @emph{-S}, |
| or by applying objdump |
| to all the object files that are part of the partition. |
| |
| @item |
| @emph{A description of the run-time model} |
| |
| The full sources of the run-time are available, and the documentation of |
| these routines describes how these run-time routines interface to the |
| underlying operating system facilities. |
| |
| @item |
| @emph{Control and data-flow information} |
| @end itemize |
| |
| |
| A supplemental static analysis tool |
| may be used to obtain complete control and data-flow information, as well as |
| comprehensive messages identifying possible problems based on this |
| information. |
| |
| @node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{dc}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dd} |
| @section Pragma Secondary_Stack_Size |
| |
| |
| Syntax: |
| |
| @example |
| pragma Secondary_Stack_Size (integer_EXPRESSION); |
| @end example |
| |
| This pragma appears within the task definition of a single task declaration |
| or a task type declaration (like pragma @code{Storage_Size}) and applies to all |
| task objects of that type. The argument specifies the size of the secondary |
| stack to be used by these task objects, and must be of an integer type. The |
| secondary stack is used to handle functions that return a variable-sized |
| result, for example a function returning an unconstrained String. |
| |
| Note this pragma only applies to targets using fixed secondary stacks, like |
| VxWorks 653 and bare board targets, where a fixed block for the |
| secondary stack is allocated from the primary stack of the task. By default, |
| these targets assign a percentage of the primary stack for the secondary stack, |
| as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, |
| an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. |
| |
| For most targets, the pragma does not apply as the secondary stack grows on |
| demand: allocated as a chain of blocks in the heap. The default size of these |
| blocks can be modified via the @code{-D} binder option as described in |
| @cite{GNAT User’s Guide}. |
| |
| Note that no check is made to see if the secondary stack can fit inside the |
| primary stack. |
| |
| Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} |
| is in effect. |
| |
| @node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{de} |
| @section Pragma Share_Generic |
| |
| |
| Syntax: |
| |
| @example |
| pragma Share_Generic (GNAME @{, GNAME@}); |
| |
| GNAME ::= generic_unit_NAME | generic_instance_NAME |
| @end example |
| |
| This pragma is provided for compatibility with Dec Ada 83. It has |
| no effect in GNAT (which does not implement shared generics), other |
| than to check that the given names are all names of generic units or |
| generic instances. |
| |
| @node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{df}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e0} |
| @section Pragma Shared |
| |
| |
| This pragma is provided for compatibility with Ada 83. The syntax and |
| semantics are identical to pragma Atomic. |
| |
| @node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e1} |
| @section Pragma Short_Circuit_And_Or |
| |
| |
| Syntax: |
| |
| @example |
| pragma Short_Circuit_And_Or; |
| @end example |
| |
| This configuration pragma causes any occurrence of the AND operator applied to |
| operands of type Standard.Boolean to be short-circuited (i.e. the AND operator |
| is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This |
| may be useful in the context of certification protocols requiring the use of |
| short-circuited logical operators. If this configuration pragma occurs locally |
| within the file being compiled, it applies only to the file being compiled. |
| There is no requirement that all units in a partition use this option. |
| |
| @node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e2} |
| @section Pragma Short_Descriptors |
| |
| |
| Syntax: |
| |
| @example |
| pragma Short_Descriptors |
| @end example |
| |
| This pragma is provided for compatibility with other Ada implementations. It |
| is recognized but ignored by all current versions of GNAT. |
| |
| @node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e3}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e4} |
| @section Pragma Simple_Storage_Pool_Type |
| |
| |
| @geindex Storage pool |
| @geindex simple |
| |
| @geindex Simple storage pool |
| |
| Syntax: |
| |
| @example |
| pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); |
| @end example |
| |
| A type can be established as a ‘simple storage pool type’ by applying |
| the representation pragma @code{Simple_Storage_Pool_Type} to the type. |
| A type named in the pragma must be a library-level immutably limited record |
| type or limited tagged type declared immediately within a package declaration. |
| The type can also be a limited private type whose full type is allowed as |
| a simple storage pool type. |
| |
| For a simple storage pool type @code{SSP}, nonabstract primitive subprograms |
| @code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that |
| are subtype conformant with the following subprogram declarations: |
| |
| @example |
| procedure Allocate |
| (Pool : in out SSP; |
| Storage_Address : out System.Address; |
| Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; |
| Alignment : System.Storage_Elements.Storage_Count); |
| |
| procedure Deallocate |
| (Pool : in out SSP; |
| Storage_Address : System.Address; |
| Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; |
| Alignment : System.Storage_Elements.Storage_Count); |
| |
| function Storage_Size (Pool : SSP) |
| return System.Storage_Elements.Storage_Count; |
| @end example |
| |
| Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and |
| @code{Storage_Size} are optional. If @code{Deallocate} is not declared, then |
| applying an unchecked deallocation has no effect other than to set its actual |
| parameter to null. If @code{Storage_Size} is not declared, then the |
| @code{Storage_Size} attribute applied to an access type associated with |
| a pool object of type SSP returns zero. Additional operations can be declared |
| for a simple storage pool type (such as for supporting a mark/release |
| storage-management discipline). |
| |
| An object of a simple storage pool type can be associated with an access |
| type by specifying the attribute |
| @ref{e5,,Simple_Storage_Pool}. For example: |
| |
| @example |
| My_Pool : My_Simple_Storage_Pool_Type; |
| |
| type Acc is access My_Data_Type; |
| |
| for Acc'Simple_Storage_Pool use My_Pool; |
| @end example |
| |
| See attribute @ref{e5,,Simple_Storage_Pool} |
| for further details. |
| |
| @node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e6}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e7} |
| @section Pragma Source_File_Name |
| |
| |
| Syntax: |
| |
| @example |
| pragma Source_File_Name ( |
| [Unit_Name =>] unit_NAME, |
| Spec_File_Name => STRING_LITERAL, |
| [Index => INTEGER_LITERAL]); |
| |
| pragma Source_File_Name ( |
| [Unit_Name =>] unit_NAME, |
| Body_File_Name => STRING_LITERAL, |
| [Index => INTEGER_LITERAL]); |
| @end example |
| |
| Use this to override the normal naming convention. It is a configuration |
| pragma, and so has the usual applicability of configuration pragmas |
| (i.e., it applies to either an entire partition, or to all units in a |
| compilation, or to a single unit, depending on how it is used. |
| @code{unit_name} is mapped to @code{file_name_literal}. The identifier for |
| the second argument is required, and indicates whether this is the file |
| name for the spec or for the body. |
| |
| The optional Index argument should be used when a file contains multiple |
| units, and when you do not want to use @code{gnatchop} to separate then |
| into multiple files (which is the recommended procedure to limit the |
| number of recompilations that are needed when some sources change). |
| For instance, if the source file @code{source.ada} contains |
| |
| @example |
| package B is |
| ... |
| end B; |
| |
| with B; |
| procedure A is |
| begin |
| .. |
| end A; |
| @end example |
| |
| you could use the following configuration pragmas: |
| |
| @example |
| pragma Source_File_Name |
| (B, Spec_File_Name => "source.ada", Index => 1); |
| pragma Source_File_Name |
| (A, Body_File_Name => "source.ada", Index => 2); |
| @end example |
| |
| Note that the @code{gnatname} utility can also be used to generate those |
| configuration pragmas. |
| |
| Another form of the @code{Source_File_Name} pragma allows |
| the specification of patterns defining alternative file naming schemes |
| to apply to all files. |
| |
| @example |
| pragma Source_File_Name |
| ( [Spec_File_Name =>] STRING_LITERAL |
| [,[Casing =>] CASING_SPEC] |
| [,[Dot_Replacement =>] STRING_LITERAL]); |
| |
| pragma Source_File_Name |
| ( [Body_File_Name =>] STRING_LITERAL |
| [,[Casing =>] CASING_SPEC] |
| [,[Dot_Replacement =>] STRING_LITERAL]); |
| |
| pragma Source_File_Name |
| ( [Subunit_File_Name =>] STRING_LITERAL |
| [,[Casing =>] CASING_SPEC] |
| [,[Dot_Replacement =>] STRING_LITERAL]); |
| |
| CASING_SPEC ::= Lowercase | Uppercase | Mixedcase |
| @end example |
| |
| The first argument is a pattern that contains a single asterisk indicating |
| the point at which the unit name is to be inserted in the pattern string |
| to form the file name. The second argument is optional. If present it |
| specifies the casing of the unit name in the resulting file name string. |
| The default is lower case. Finally the third argument allows for systematic |
| replacement of any dots in the unit name by the specified string literal. |
| |
| Note that Source_File_Name pragmas should not be used if you are using |
| project files. The reason for this rule is that the project manager is not |
| aware of these pragmas, and so other tools that use the projet file would not |
| be aware of the intended naming conventions. If you are using project files, |
| file naming is controlled by Source_File_Name_Project pragmas, which are |
| usually supplied automatically by the project manager. A pragma |
| Source_File_Name cannot appear after a @ref{e8,,Pragma Source_File_Name_Project}. |
| |
| For more details on the use of the @code{Source_File_Name} pragma, see the |
| sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} |
| in the @cite{GNAT User’s Guide}. |
| |
| @node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e9}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e8} |
| @section Pragma Source_File_Name_Project |
| |
| |
| This pragma has the same syntax and semantics as pragma Source_File_Name. |
| It is only allowed as a stand-alone configuration pragma. |
| It cannot appear after a @ref{e7,,Pragma Source_File_Name}, and |
| most importantly, once pragma Source_File_Name_Project appears, |
| no further Source_File_Name pragmas are allowed. |
| |
| The intention is that Source_File_Name_Project pragmas are always |
| generated by the Project Manager in a manner consistent with the naming |
| specified in a project file, and when naming is controlled in this manner, |
| it is not permissible to attempt to modify this naming scheme using |
| Source_File_Name or Source_File_Name_Project pragmas (which would not be |
| known to the project manager). |
| |
| @node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ea} |
| @section Pragma Source_Reference |
| |
| |
| Syntax: |
| |
| @example |
| pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); |
| @end example |
| |
| This pragma must appear as the first line of a source file. |
| @code{integer_literal} is the logical line number of the line following |
| the pragma line (for use in error messages and debugging |
| information). @code{string_literal} is a static string constant that |
| specifies the file name to be used in error messages and debugging |
| information. This is most notably used for the output of @code{gnatchop} |
| with the @emph{-r} switch, to make sure that the original unchopped |
| source file is the one referred to. |
| |
| The second argument must be a string literal, it cannot be a static |
| string expression other than a string literal. This is because its value |
| is needed for error messages issued by all phases of the compiler. |
| |
| @node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{eb}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{ec} |
| @section Pragma SPARK_Mode |
| |
| |
| Syntax: |
| |
| @example |
| pragma SPARK_Mode [(On | Off)] ; |
| @end example |
| |
| In general a program can have some parts that are in SPARK 2014 (and |
| follow all the rules in the SPARK Reference Manual), and some parts |
| that are full Ada 2012. |
| |
| The SPARK_Mode pragma is used to identify which parts are in SPARK |
| 2014 (by default programs are in full Ada). The SPARK_Mode pragma can |
| be used in the following places: |
| |
| |
| @itemize * |
| |
| @item |
| As a configuration pragma, in which case it sets the default mode for |
| all units compiled with this pragma. |
| |
| @item |
| Immediately following a library-level subprogram spec |
| |
| @item |
| Immediately within a library-level package body |
| |
| @item |
| Immediately following the @code{private} keyword of a library-level |
| package spec |
| |
| @item |
| Immediately following the @code{begin} keyword of a library-level |
| package body |
| |
| @item |
| Immediately within a library-level subprogram body |
| @end itemize |
| |
| Normally a subprogram or package spec/body inherits the current mode |
| that is active at the point it is declared. But this can be overridden |
| by pragma within the spec or body as above. |
| |
| The basic consistency rule is that you can’t turn SPARK_Mode back |
| @code{On}, once you have explicitly (with a pragma) turned if |
| @code{Off}. So the following rules apply: |
| |
| If a subprogram spec has SPARK_Mode @code{Off}, then the body must |
| also have SPARK_Mode @code{Off}. |
| |
| For a package, we have four parts: |
| |
| |
| @itemize * |
| |
| @item |
| the package public declarations |
| |
| @item |
| the package private part |
| |
| @item |
| the body of the package |
| |
| @item |
| the elaboration code after @code{begin} |
| @end itemize |
| |
| For a package, the rule is that if you explicitly turn SPARK_Mode |
| @code{Off} for any part, then all the following parts must have |
| SPARK_Mode @code{Off}. Note that this may require repeating a pragma |
| SPARK_Mode (@code{Off}) in the body. For example, if we have a |
| configuration pragma SPARK_Mode (@code{On}) that turns the mode on by |
| default everywhere, and one particular package spec has pragma |
| SPARK_Mode (@code{Off}), then that pragma will need to be repeated in |
| the package body. |
| |
| @node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ed} |
| @section Pragma Static_Elaboration_Desired |
| |
| |
| Syntax: |
| |
| @example |
| pragma Static_Elaboration_Desired; |
| @end example |
| |
| This pragma is used to indicate that the compiler should attempt to initialize |
| statically the objects declared in the library unit to which the pragma applies, |
| when these objects are initialized (explicitly or implicitly) by an aggregate. |
| In the absence of this pragma, aggregates in object declarations are expanded |
| into assignments and loops, even when the aggregate components are static |
| constants. When the aggregate is present the compiler builds a static expression |
| that requires no run-time code, so that the initialized object can be placed in |
| read-only data space. If the components are not static, or the aggregate has |
| more that 100 components, the compiler emits a warning that the pragma cannot |
| be obeyed. (See also the restriction No_Implicit_Loops, which supports static |
| construction of larger aggregates with static components that include an others |
| choice.) |
| |
| @node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ee} |
| @section Pragma Stream_Convert |
| |
| |
| Syntax: |
| |
| @example |
| pragma Stream_Convert ( |
| [Entity =>] type_LOCAL_NAME, |
| [Read =>] function_NAME, |
| [Write =>] function_NAME); |
| @end example |
| |
| This pragma provides an efficient way of providing user-defined stream |
| attributes. Not only is it simpler to use than specifying the attributes |
| directly, but more importantly, it allows the specification to be made in such |
| a way that the predefined unit Ada.Streams is not loaded unless it is actually |
| needed (i.e. unless the stream attributes are actually used); the use of |
| the Stream_Convert pragma adds no overhead at all, unless the stream |
| attributes are actually used on the designated type. |
| |
| The first argument specifies the type for which stream functions are |
| provided. The second parameter provides a function used to read values |
| of this type. It must name a function whose argument type may be any |
| subtype, and whose returned type must be the type given as the first |
| argument to the pragma. |
| |
| The meaning of the @code{Read} parameter is that if a stream attribute directly |
| or indirectly specifies reading of the type given as the first parameter, |
| then a value of the type given as the argument to the Read function is |
| read from the stream, and then the Read function is used to convert this |
| to the required target type. |
| |
| Similarly the @code{Write} parameter specifies how to treat write attributes |
| that directly or indirectly apply to the type given as the first parameter. |
| It must have an input parameter of the type specified by the first parameter, |
| and the return type must be the same as the input type of the Read function. |
| The effect is to first call the Write function to convert to the given stream |
| type, and then write the result type to the stream. |
| |
| The Read and Write functions must not be overloaded subprograms. If necessary |
| renamings can be supplied to meet this requirement. |
| The usage of this attribute is best illustrated by a simple example, taken |
| from the GNAT implementation of package Ada.Strings.Unbounded: |
| |
| @example |
| function To_Unbounded (S : String) return Unbounded_String |
| renames To_Unbounded_String; |
| |
| pragma Stream_Convert |
| (Unbounded_String, To_Unbounded, To_String); |
| @end example |
| |
| The specifications of the referenced functions, as given in the Ada |
| Reference Manual are: |
| |
| @example |
| function To_Unbounded_String (Source : String) |
| return Unbounded_String; |
| |
| function To_String (Source : Unbounded_String) |
| return String; |
| @end example |
| |
| The effect is that if the value of an unbounded string is written to a stream, |
| then the representation of the item in the stream is in the same format that |
| would be used for @code{Standard.String'Output}, and this same representation |
| is expected when a value of this type is read from the stream. Note that the |
| value written always includes the bounds, even for Unbounded_String’Write, |
| since Unbounded_String is not an array type. |
| |
| Note that the @code{Stream_Convert} pragma is not effective in the case of |
| a derived type of a non-limited tagged type. If such a type is specified then |
| the pragma is silently ignored, and the default implementation of the stream |
| attributes is used instead. |
| |
| @node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ef} |
| @section Pragma Style_Checks |
| |
| |
| Syntax: |
| |
| @example |
| pragma Style_Checks (string_LITERAL | ALL_CHECKS | |
| On | Off [, LOCAL_NAME]); |
| @end example |
| |
| This pragma is used in conjunction with compiler switches to control the |
| built in style checking provided by GNAT. The compiler switches, if set, |
| provide an initial setting for the switches, and this pragma may be used |
| to modify these settings, or the settings may be provided entirely by |
| the use of the pragma. This pragma can be used anywhere that a pragma |
| is legal, including use as a configuration pragma (including use in |
| the @code{gnat.adc} file). |
| |
| The form with a string literal specifies which style options are to be |
| activated. These are additive, so they apply in addition to any previously |
| set style check options. The codes for the options are the same as those |
| used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. |
| For example the following two methods can be used to enable |
| layout checking: |
| |
| |
| @itemize * |
| |
| @item |
| @example |
| pragma Style_Checks ("l"); |
| @end example |
| |
| @item |
| @example |
| gcc -c -gnatyl ... |
| @end example |
| @end itemize |
| |
| The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent |
| to the use of the @code{gnaty} switch with no options. |
| See the @cite{GNAT User’s Guide} for details.) |
| |
| Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). |
| In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check |
| options (i.e. equivalent to @code{-gnatyg}). |
| |
| The forms with @code{Off} and @code{On} |
| can be used to temporarily disable style checks |
| as shown in the following example: |
| |
| @example |
| pragma Style_Checks ("k"); -- requires keywords in lower case |
| pragma Style_Checks (Off); -- turn off style checks |
| NULL; -- this will not generate an error message |
| pragma Style_Checks (On); -- turn style checks back on |
| NULL; -- this will generate an error message |
| @end example |
| |
| Finally the two argument form is allowed only if the first argument is |
| @code{On} or @code{Off}. The effect is to turn of semantic style checks |
| for the specified entity, as shown in the following example: |
| |
| @example |
| pragma Style_Checks ("r"); -- require consistency of identifier casing |
| Arg : Integer; |
| Rf1 : Integer := ARG; -- incorrect, wrong case |
| pragma Style_Checks (Off, Arg); |
| Rf2 : Integer := ARG; -- OK, no error |
| @end example |
| |
| @node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f0} |
| @section Pragma Subtitle |
| |
| |
| Syntax: |
| |
| @example |
| pragma Subtitle ([Subtitle =>] STRING_LITERAL); |
| @end example |
| |
| This pragma is recognized for compatibility with other Ada compilers |
| but is ignored by GNAT. |
| |
| @node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f1} |
| @section Pragma Suppress |
| |
| |
| Syntax: |
| |
| @example |
| pragma Suppress (Identifier [, [On =>] Name]); |
| @end example |
| |
| This is a standard pragma, and supports all the check names required in |
| the RM. It is included here because GNAT recognizes some additional check |
| names that are implementation defined (as permitted by the RM): |
| |
| |
| @itemize * |
| |
| @item |
| @code{Alignment_Check} can be used to suppress alignment checks |
| on addresses used in address clauses. Such checks can also be suppressed |
| by suppressing range checks, but the specific use of @code{Alignment_Check} |
| allows suppression of alignment checks without suppressing other range checks. |
| Note that @code{Alignment_Check} is suppressed by default on machines (such as |
| the x86) with non-strict alignment. |
| |
| @item |
| @code{Atomic_Synchronization} can be used to suppress the special memory |
| synchronization instructions that are normally generated for access to |
| @code{Atomic} variables to ensure correct synchronization between tasks |
| that use such variables for synchronization purposes. |
| |
| @item |
| @code{Duplicated_Tag_Check} Can be used to suppress the check that is generated |
| for a duplicated tag value when a tagged type is declared. |
| |
| @item |
| @code{Container_Checks} Can be used to suppress all checks within Ada.Containers |
| and instances of its children, including Tampering_Check. |
| |
| @item |
| @code{Tampering_Check} Can be used to suppress tampering check in the containers. |
| |
| @item |
| @code{Predicate_Check} can be used to control whether predicate checks are |
| active. It is applicable only to predicates for which the policy is |
| @code{Check}. Unlike @code{Assertion_Policy}, which determines if a given |
| predicate is ignored or checked for the whole program, the use of |
| @code{Suppress} and @code{Unsuppress} with this check name allows a given |
| predicate to be turned on and off at specific points in the program. |
| |
| @item |
| @code{Validity_Check} can be used specifically to control validity checks. |
| If @code{Suppress} is used to suppress validity checks, then no validity |
| checks are performed, including those specified by the appropriate compiler |
| switch or the @code{Validity_Checks} pragma. |
| |
| @item |
| Additional check names previously introduced by use of the @code{Check_Name} |
| pragma are also allowed. |
| @end itemize |
| |
| Note that pragma Suppress gives the compiler permission to omit |
| checks, but does not require the compiler to omit checks. The compiler |
| will generate checks if they are essentially free, even when they are |
| suppressed. In particular, if the compiler can prove that a certain |
| check will necessarily fail, it will generate code to do an |
| unconditional ‘raise’, even if checks are suppressed. The compiler |
| warns in this case. |
| |
| Of course, run-time checks are omitted whenever the compiler can prove |
| that they will not fail, whether or not checks are suppressed. |
| |
| @node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f2} |
| @section Pragma Suppress_All |
| |
| |
| Syntax: |
| |
| @example |
| pragma Suppress_All; |
| @end example |
| |
| This pragma can appear anywhere within a unit. |
| The effect is to apply @code{Suppress (All_Checks)} to the unit |
| in which it appears. This pragma is implemented for compatibility with DEC |
| Ada 83 usage where it appears at the end of a unit, and for compatibility |
| with Rational Ada, where it appears as a program unit pragma. |
| The use of the standard Ada pragma @code{Suppress (All_Checks)} |
| as a normal configuration pragma is the preferred usage in GNAT. |
| |
| @node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f3}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f4} |
| @section Pragma Suppress_Debug_Info |
| |
| |
| Syntax: |
| |
| @example |
| pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); |
| @end example |
| |
| This pragma can be used to suppress generation of debug information |
| for the specified entity. It is intended primarily for use in debugging |
| the debugger, and navigating around debugger problems. |
| |
| @node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f5} |
| @section Pragma Suppress_Exception_Locations |
| |
| |
| Syntax: |
| |
| @example |
| pragma Suppress_Exception_Locations; |
| @end example |
| |
| In normal mode, a raise statement for an exception by default generates |
| an exception message giving the file name and line number for the location |
| of the raise. This is useful for debugging and logging purposes, but this |
| entails extra space for the strings for the messages. The configuration |
| pragma @code{Suppress_Exception_Locations} can be used to suppress the |
| generation of these strings, with the result that space is saved, but the |
| exception message for such raises is null. This configuration pragma may |
| appear in a global configuration pragma file, or in a specific unit as |
| usual. It is not required that this pragma be used consistently within |
| a partition, so it is fine to have some units within a partition compiled |
| with this pragma and others compiled in normal mode without it. |
| |
| @node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f6}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f7} |
| @section Pragma Suppress_Initialization |
| |
| |
| @geindex Suppressing initialization |
| |
| @geindex Initialization |
| @geindex suppression of |
| |
| Syntax: |
| |
| @example |
| pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); |
| @end example |
| |
| Here variable_or_subtype_Name is the name introduced by a type declaration |
| or subtype declaration or the name of a variable introduced by an |
| object declaration. |
| |
| In the case of a type or subtype |
| this pragma suppresses any implicit or explicit initialization |
| for all variables of the given type or subtype, |
| including initialization resulting from the use of pragmas |
| Normalize_Scalars or Initialize_Scalars. |
| |
| This is considered a representation item, so it cannot be given after |
| the type is frozen. It applies to all subsequent object declarations, |
| and also any allocator that creates objects of the type. |
| |
| If the pragma is given for the first subtype, then it is considered |
| to apply to the base type and all its subtypes. If the pragma is given |
| for other than a first subtype, then it applies only to the given subtype. |
| The pragma may not be given after the type is frozen. |
| |
| Note that this includes eliminating initialization of discriminants |
| for discriminated types, and tags for tagged types. In these cases, |
| you will have to use some non-portable mechanism (e.g. address |
| overlays or unchecked conversion) to achieve required initialization |
| of these fields before accessing any object of the corresponding type. |
| |
| For the variable case, implicit initialization for the named variable |
| is suppressed, just as though its subtype had been given in a pragma |
| Suppress_Initialization, as described above. |
| |
| @node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f8} |
| @section Pragma Task_Name |
| |
| |
| Syntax |
| |
| @example |
| pragma Task_Name (string_EXPRESSION); |
| @end example |
| |
| This pragma appears within a task definition (like pragma |
| @code{Priority}) and applies to the task in which it appears. The |
| argument must be of type String, and provides a name to be used for |
| the task instance when the task is created. Note that this expression |
| is not required to be static, and in particular, it can contain |
| references to task discriminants. This facility can be used to |
| provide different names for different tasks as they are created, |
| as illustrated in the example below. |
| |
| The task name is recorded internally in the run-time structures |
| and is accessible to tools like the debugger. In addition the |
| routine @code{Ada.Task_Identification.Image} will return this |
| string, with a unique task address appended. |
| |
| @example |
| -- Example of the use of pragma Task_Name |
| |
| with Ada.Task_Identification; |
| use Ada.Task_Identification; |
| with Text_IO; use Text_IO; |
| procedure t3 is |
| |
| type Astring is access String; |
| |
| task type Task_Typ (Name : access String) is |
| pragma Task_Name (Name.all); |
| end Task_Typ; |
| |
| task body Task_Typ is |
| Nam : constant String := Image (Current_Task); |
| begin |
| Put_Line ("-->" & Nam (1 .. 14) & "<--"); |
| end Task_Typ; |
| |
| type Ptr_Task is access Task_Typ; |
| Task_Var : Ptr_Task; |
| |
| begin |
| Task_Var := |
| new Task_Typ (new String'("This is task 1")); |
| Task_Var := |
| new Task_Typ (new String'("This is task 2")); |
| end; |
| @end example |
| |
| @node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f9} |
| @section Pragma Task_Storage |
| |
| |
| Syntax: |
| |
| @example |
| pragma Task_Storage ( |
| [Task_Type =>] LOCAL_NAME, |
| [Top_Guard =>] static_integer_EXPRESSION); |
| @end example |
| |
| This pragma specifies the length of the guard area for tasks. The guard |
| area is an additional storage area allocated to a task. A value of zero |
| means that either no guard area is created or a minimal guard area is |
| created, depending on the target. This pragma can appear anywhere a |
| @code{Storage_Size} attribute definition clause is allowed for a task |
| type. |
| |
| @node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fb} |
| @section Pragma Test_Case |
| |
| |
| @geindex Test cases |
| |
| Syntax: |
| |
| @example |
| pragma Test_Case ( |
| [Name =>] static_string_Expression |
| ,[Mode =>] (Nominal | Robustness) |
| [, Requires => Boolean_Expression] |
| [, Ensures => Boolean_Expression]); |
| @end example |
| |
| The @code{Test_Case} pragma allows defining fine-grain specifications |
| for use by testing tools. |
| The compiler checks the validity of the @code{Test_Case} pragma, but its |
| presence does not lead to any modification of the code generated by the |
| compiler. |
| |
| @code{Test_Case} pragmas may only appear immediately following the |
| (separate) declaration of a subprogram in a package declaration, inside |
| a package spec unit. Only other pragmas may intervene (that is appear |
| between the subprogram declaration and a test case). |
| |
| The compiler checks that boolean expressions given in @code{Requires} and |
| @code{Ensures} are valid, where the rules for @code{Requires} are the |
| same as the rule for an expression in @code{Precondition} and the rules |
| for @code{Ensures} are the same as the rule for an expression in |
| @code{Postcondition}. In particular, attributes @code{'Old} and |
| @code{'Result} can only be used within the @code{Ensures} |
| expression. The following is an example of use within a package spec: |
| |
| @example |
| package Math_Functions is |
| ... |
| function Sqrt (Arg : Float) return Float; |
| pragma Test_Case (Name => "Test 1", |
| Mode => Nominal, |
| Requires => Arg < 10000.0, |
| Ensures => Sqrt'Result < 10.0); |
| ... |
| end Math_Functions; |
| @end example |
| |
| The meaning of a test case is that there is at least one context where |
| @code{Requires} holds such that, if the associated subprogram is executed in |
| that context, then @code{Ensures} holds when the subprogram returns. |
| Mode @code{Nominal} indicates that the input context should also satisfy the |
| precondition of the subprogram, and the output context should also satisfy its |
| postcondition. Mode @code{Robustness} indicates that the precondition and |
| postcondition of the subprogram should be ignored for this test case. |
| |
| @node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fc}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fd} |
| @section Pragma Thread_Local_Storage |
| |
| |
| @geindex Task specific storage |
| |
| @geindex TLS (Thread Local Storage) |
| |
| @geindex Task_Attributes |
| |
| Syntax: |
| |
| @example |
| pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); |
| @end example |
| |
| This pragma specifies that the specified entity, which must be |
| a variable declared in a library-level package, is to be marked as |
| “Thread Local Storage” (@code{TLS}). On systems supporting this (which |
| include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each |
| thread (and hence each Ada task) to see a distinct copy of the variable. |
| |
| The variable must not have default initialization, and if there is |
| an explicit initialization, it must be either @code{null} for an |
| access variable, a static expression for a scalar variable, or a fully |
| static aggregate for a composite type, that is to say, an aggregate all |
| of whose components are static, and which does not include packed or |
| discriminated components. |
| |
| This provides a low-level mechanism similar to that provided by |
| the @code{Ada.Task_Attributes} package, but much more efficient |
| and is also useful in writing interface code that will interact |
| with foreign threads. |
| |
| If this pragma is used on a system where @code{TLS} is not supported, |
| then an error message will be generated and the program will be rejected. |
| |
| @node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fe} |
| @section Pragma Time_Slice |
| |
| |
| Syntax: |
| |
| @example |
| pragma Time_Slice (static_duration_EXPRESSION); |
| @end example |
| |
| For implementations of GNAT on operating systems where it is possible |
| to supply a time slice value, this pragma may be used for this purpose. |
| It is ignored if it is used in a system that does not allow this control, |
| or if it appears in other than the main program unit. |
| |
| @node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{ff} |
| @section Pragma Title |
| |
| |
| Syntax: |
| |
| @example |
| pragma Title (TITLING_OPTION [, TITLING OPTION]); |
| |
| TITLING_OPTION ::= |
| [Title =>] STRING_LITERAL, |
| | [Subtitle =>] STRING_LITERAL |
| @end example |
| |
| Syntax checked but otherwise ignored by GNAT. This is a listing control |
| pragma used in DEC Ada 83 implementations to provide a title and/or |
| subtitle for the program listing. The program listing generated by GNAT |
| does not have titles or subtitles. |
| |
| Unlike other pragmas, the full flexibility of named notation is allowed |
| for this pragma, i.e., the parameters may be given in any order if named |
| notation is used, and named and positional notation can be mixed |
| following the normal rules for procedure calls in Ada. |
| |
| @node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{100} |
| @section Pragma Type_Invariant |
| |
| |
| Syntax: |
| |
| @example |
| pragma Type_Invariant |
| ([Entity =>] type_LOCAL_NAME, |
| [Check =>] EXPRESSION); |
| @end example |
| |
| The @code{Type_Invariant} pragma is intended to be an exact |
| replacement for the language-defined @code{Type_Invariant} |
| aspect, and shares its restrictions and semantics. It differs |
| from the language defined @code{Invariant} pragma in that it |
| does not permit a string parameter, and it is |
| controlled by the assertion identifier @code{Type_Invariant} |
| rather than @code{Invariant}. |
| |
| @node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{101}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{102} |
| @section Pragma Type_Invariant_Class |
| |
| |
| Syntax: |
| |
| @example |
| pragma Type_Invariant_Class |
| ([Entity =>] type_LOCAL_NAME, |
| [Check =>] EXPRESSION); |
| @end example |
| |
| The @code{Type_Invariant_Class} pragma is intended to be an exact |
| replacement for the language-defined @code{Type_Invariant'Class} |
| aspect, and shares its restrictions and semantics. |
| |
| Note: This pragma is called @code{Type_Invariant_Class} rather than |
| @code{Type_Invariant'Class} because the latter would not be strictly |
| conforming to the allowed syntax for pragmas. The motivation |
| for providing pragmas equivalent to the aspects is to allow a program |
| to be written using the pragmas, and then compiled if necessary |
| using an Ada compiler that does not recognize the pragmas or |
| aspects, but is prepared to ignore the pragmas. The assertion |
| policy that controls this pragma is @code{Type_Invariant'Class}, |
| not @code{Type_Invariant_Class}. |
| |
| @node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{103} |
| @section Pragma Unchecked_Union |
| |
| |
| @geindex Unions in C |
| |
| Syntax: |
| |
| @example |
| pragma Unchecked_Union (first_subtype_LOCAL_NAME); |
| @end example |
| |
| This pragma is used to specify a representation of a record type that is |
| equivalent to a C union. It was introduced as a GNAT implementation defined |
| pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this |
| pragma, making it language defined, and GNAT fully implements this extended |
| version in all language modes (Ada 83, Ada 95, and Ada 2005). For full |
| details, consult the Ada 2012 Reference Manual, section B.3.3. |
| |
| @node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{104} |
| @section Pragma Unevaluated_Use_Of_Old |
| |
| |
| @geindex Attribute Old |
| |
| @geindex Attribute Loop_Entry |
| |
| @geindex Unevaluated_Use_Of_Old |
| |
| Syntax: |
| |
| @example |
| pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); |
| @end example |
| |
| This pragma controls the processing of attributes Old and Loop_Entry. |
| If either of these attributes is used in a potentially unevaluated |
| expression (e.g. the then or else parts of an if expression), then |
| normally this usage is considered illegal if the prefix of the attribute |
| is other than an entity name. The language requires this |
| behavior for Old, and GNAT copies the same rule for Loop_Entry. |
| |
| The reason for this rule is that otherwise, we can have a situation |
| where we save the Old value, and this results in an exception, even |
| though we might not evaluate the attribute. Consider this example: |
| |
| @example |
| package UnevalOld is |
| K : Character; |
| procedure U (A : String; C : Boolean) -- ERROR |
| with Post => (if C then A(1)'Old = K else True); |
| end; |
| @end example |
| |
| If procedure U is called with a string with a lower bound of 2, and |
| C false, then an exception would be raised trying to evaluate A(1) |
| on entry even though the value would not be actually used. |
| |
| Although the rule guarantees against this possibility, it is sometimes |
| too restrictive. For example if we know that the string has a lower |
| bound of 1, then we will never raise an exception. |
| The pragma @code{Unevaluated_Use_Of_Old} can be |
| used to modify this behavior. If the argument is @code{Error} then an |
| error is given (this is the default RM behavior). If the argument is |
| @code{Warn} then the usage is allowed as legal but with a warning |
| that an exception might be raised. If the argument is @code{Allow} |
| then the usage is allowed as legal without generating a warning. |
| |
| This pragma may appear as a configuration pragma, or in a declarative |
| part or package specification. In the latter case it applies to |
| uses up to the end of the corresponding statement sequence or |
| sequence of package declarations. |
| |
| @node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{105} |
| @section Pragma Unimplemented_Unit |
| |
| |
| Syntax: |
| |
| @example |
| pragma Unimplemented_Unit; |
| @end example |
| |
| If this pragma occurs in a unit that is processed by the compiler, GNAT |
| aborts with the message @code{xxx not implemented}, where |
| @code{xxx} is the name of the current compilation unit. This pragma is |
| intended to allow the compiler to handle unimplemented library units in |
| a clean manner. |
| |
| The abort only happens if code is being generated. Thus you can use |
| specs of unimplemented packages in syntax or semantic checking mode. |
| |
| @node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{106}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{107} |
| @section Pragma Universal_Aliasing |
| |
| |
| Syntax: |
| |
| @example |
| pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; |
| @end example |
| |
| @code{type_LOCAL_NAME} must refer to a type declaration in the current |
| declarative part. The effect is to inhibit strict type-based aliasing |
| optimization for the given type. In other words, the effect is as though |
| access types designating this type were subject to pragma No_Strict_Aliasing. |
| For a detailed description of the strict aliasing optimization, and the |
| situations in which it must be suppressed, see the section on |
| @code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}. |
| |
| @node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{109} |
| @section Pragma Unmodified |
| |
| |
| @geindex Warnings |
| @geindex unmodified |
| |
| Syntax: |
| |
| @example |
| pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); |
| @end example |
| |
| This pragma signals that the assignable entities (variables, |
| @code{out} parameters, @code{in out} parameters) whose names are listed are |
| deliberately not assigned in the current source unit. This |
| suppresses warnings about the |
| entities being referenced but not assigned, and in addition a warning will be |
| generated if one of these entities is in fact assigned in the |
| same unit as the pragma (or in the corresponding body, or one |
| of its subunits). |
| |
| This is particularly useful for clearly signaling that a particular |
| parameter is not modified, even though the spec suggests that it might |
| be. |
| |
| For the variable case, warnings are never given for unreferenced variables |
| whose name contains one of the substrings |
| @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names |
| are typically to be used in cases where such warnings are expected. |
| Thus it is never necessary to use @code{pragma Unmodified} for such |
| variables, though it is harmless to do so. |
| |
| @node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10b} |
| @section Pragma Unreferenced |
| |
| |
| @geindex Warnings |
| @geindex unreferenced |
| |
| Syntax: |
| |
| @example |
| pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); |
| pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); |
| @end example |
| |
| This pragma signals that the entities whose names are listed are |
| deliberately not referenced in the current source unit after the |
| occurrence of the pragma. This |
| suppresses warnings about the |
| entities being unreferenced, and in addition a warning will be |
| generated if one of these entities is in fact subsequently referenced in the |
| same unit as the pragma (or in the corresponding body, or one |
| of its subunits). |
| |
| This is particularly useful for clearly signaling that a particular |
| parameter is not referenced in some particular subprogram implementation |
| and that this is deliberate. It can also be useful in the case of |
| objects declared only for their initialization or finalization side |
| effects. |
| |
| If @code{LOCAL_NAME} identifies more than one matching homonym in the |
| current scope, then the entity most recently declared is the one to which |
| the pragma applies. Note that in the case of accept formals, the pragma |
| Unreferenced may appear immediately after the keyword @code{do} which |
| allows the indication of whether or not accept formals are referenced |
| or not to be given individually for each accept statement. |
| |
| The left hand side of an assignment does not count as a reference for the |
| purpose of this pragma. Thus it is fine to assign to an entity for which |
| pragma Unreferenced is given. |
| |
| Note that if a warning is desired for all calls to a given subprogram, |
| regardless of whether they occur in the same unit as the subprogram |
| declaration, then this pragma should not be used (calls from another |
| unit would not be flagged); pragma Obsolescent can be used instead |
| for this purpose, see @ref{ad,,Pragma Obsolescent}. |
| |
| The second form of pragma @code{Unreferenced} is used within a context |
| clause. In this case the arguments must be unit names of units previously |
| mentioned in @code{with} clauses (similar to the usage of pragma |
| @code{Elaborate_All}. The effect is to suppress warnings about unreferenced |
| units and unreferenced entities within these units. |
| |
| For the variable case, warnings are never given for unreferenced variables |
| whose name contains one of the substrings |
| @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names |
| are typically to be used in cases where such warnings are expected. |
| Thus it is never necessary to use @code{pragma Unreferenced} for such |
| variables, though it is harmless to do so. |
| |
| @node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10d} |
| @section Pragma Unreferenced_Objects |
| |
| |
| @geindex Warnings |
| @geindex unreferenced |
| |
| Syntax: |
| |
| @example |
| pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); |
| @end example |
| |
| This pragma signals that for the types or subtypes whose names are |
| listed, objects which are declared with one of these types or subtypes may |
| not be referenced, and if no references appear, no warnings are given. |
| |
| This is particularly useful for objects which are declared solely for their |
| initialization and finalization effect. Such variables are sometimes referred |
| to as RAII variables (Resource Acquisition Is Initialization). Using this |
| pragma on the relevant type (most typically a limited controlled type), the |
| compiler will automatically suppress unwanted warnings about these variables |
| not being referenced. |
| |
| @node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10e} |
| @section Pragma Unreserve_All_Interrupts |
| |
| |
| Syntax: |
| |
| @example |
| pragma Unreserve_All_Interrupts; |
| @end example |
| |
| Normally certain interrupts are reserved to the implementation. Any attempt |
| to attach an interrupt causes Program_Error to be raised, as described in |
| RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in |
| many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is |
| reserved to the implementation, so that @code{Ctrl-C} can be used to |
| interrupt execution. |
| |
| If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in |
| a program, then all such interrupts are unreserved. This allows the |
| program to handle these interrupts, but disables their standard |
| functions. For example, if this pragma is used, then pressing |
| @code{Ctrl-C} will not automatically interrupt execution. However, |
| a program can then handle the @code{SIGINT} interrupt as it chooses. |
| |
| For a full list of the interrupts handled in a specific implementation, |
| see the source code for the spec of @code{Ada.Interrupts.Names} in |
| file @code{a-intnam.ads}. This is a target dependent file that contains the |
| list of interrupts recognized for a given target. The documentation in |
| this file also specifies what interrupts are affected by the use of |
| the @code{Unreserve_All_Interrupts} pragma. |
| |
| For a more general facility for controlling what interrupts can be |
| handled, see pragma @code{Interrupt_State}, which subsumes the functionality |
| of the @code{Unreserve_All_Interrupts} pragma. |
| |
| @node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10f} |
| @section Pragma Unsuppress |
| |
| |
| Syntax: |
| |
| @example |
| pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); |
| @end example |
| |
| This pragma undoes the effect of a previous pragma @code{Suppress}. If |
| there is no corresponding pragma @code{Suppress} in effect, it has no |
| effect. The range of the effect is the same as for pragma |
| @code{Suppress}. The meaning of the arguments is identical to that used |
| in pragma @code{Suppress}. |
| |
| One important application is to ensure that checks are on in cases where |
| code depends on the checks for its correct functioning, so that the code |
| will compile correctly even if the compiler switches are set to suppress |
| checks. For example, in a program that depends on external names of tagged |
| types and wants to ensure that the duplicated tag check occurs even if all |
| run-time checks are suppressed by a compiler switch, the following |
| configuration pragma will ensure this test is not suppressed: |
| |
| @example |
| pragma Unsuppress (Duplicated_Tag_Check); |
| @end example |
| |
| This pragma is standard in Ada 2005. It is available in all earlier versions |
| of Ada as an implementation-defined pragma. |
| |
| Note that in addition to the checks defined in the Ada RM, GNAT recogizes a |
| number of implementation-defined check names. See the description of pragma |
| @code{Suppress} for full details. |
| |
| @node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{110} |
| @section Pragma Use_VADS_Size |
| |
| |
| @geindex Size |
| @geindex VADS compatibility |
| |
| @geindex Rational profile |
| |
| Syntax: |
| |
| @example |
| pragma Use_VADS_Size; |
| @end example |
| |
| This is a configuration pragma. In a unit to which it applies, any use |
| of the ‘Size attribute is automatically interpreted as a use of the |
| ‘VADS_Size attribute. Note that this may result in incorrect semantic |
| processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in |
| the handling of existing code which depends on the interpretation of Size |
| as implemented in the VADS compiler. See description of the VADS_Size |
| attribute for further details. |
| |
| @node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{111}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{112} |
| @section Pragma Unused |
| |
| |
| @geindex Warnings |
| @geindex unused |
| |
| Syntax: |
| |
| @example |
| pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); |
| @end example |
| |
| This pragma signals that the assignable entities (variables, |
| @code{out} parameters, and @code{in out} parameters) whose names are listed |
| deliberately do not get assigned or referenced in the current source unit |
| after the occurrence of the pragma in the current source unit. This |
| suppresses warnings about the entities that are unreferenced and/or not |
| assigned, and, in addition, a warning will be generated if one of these |
| entities gets assigned or subsequently referenced in the same unit as the |
| pragma (in the corresponding body or one of its subunits). |
| |
| This is particularly useful for clearly signaling that a particular |
| parameter is not modified or referenced, even though the spec suggests |
| that it might be. |
| |
| For the variable case, warnings are never given for unreferenced |
| variables whose name contains one of the substrings |
| @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names |
| are typically to be used in cases where such warnings are expected. |
| Thus it is never necessary to use @code{pragma Unmodified} for such |
| variables, though it is harmless to do so. |
| |
| @node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{113} |
| @section Pragma Validity_Checks |
| |
| |
| Syntax: |
| |
| @example |
| pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); |
| @end example |
| |
| This pragma is used in conjunction with compiler switches to control the |
| built-in validity checking provided by GNAT. The compiler switches, if set |
| provide an initial setting for the switches, and this pragma may be used |
| to modify these settings, or the settings may be provided entirely by |
| the use of the pragma. This pragma can be used anywhere that a pragma |
| is legal, including use as a configuration pragma (including use in |
| the @code{gnat.adc} file). |
| |
| The form with a string literal specifies which validity options are to be |
| activated. The validity checks are first set to include only the default |
| reference manual settings, and then a string of letters in the string |
| specifies the exact set of options required. The form of this string |
| is exactly as described for the @emph{-gnatVx} compiler switch (see the |
| GNAT User’s Guide for details). For example the following two |
| methods can be used to enable validity checking for mode @code{in} and |
| @code{in out} subprogram parameters: |
| |
| |
| @itemize * |
| |
| @item |
| @example |
| pragma Validity_Checks ("im"); |
| @end example |
| |
| @item |
| @example |
| $ gcc -c -gnatVim ... |
| @end example |
| @end itemize |
| |
| The form ALL_CHECKS activates all standard checks (its use is equivalent |
| to the use of the @code{gnatVa} switch). |
| |
| The forms with @code{Off} and @code{On} can be used to temporarily disable |
| validity checks as shown in the following example: |
| |
| @example |
| pragma Validity_Checks ("c"); -- validity checks for copies |
| pragma Validity_Checks (Off); -- turn off validity checks |
| A := B; -- B will not be validity checked |
| pragma Validity_Checks (On); -- turn validity checks back on |
| A := C; -- C will be validity checked |
| @end example |
| |
| @node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{114}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{115} |
| @section Pragma Volatile |
| |
| |
| Syntax: |
| |
| @example |
| pragma Volatile (LOCAL_NAME); |
| @end example |
| |
| This pragma is defined by the Ada Reference Manual, and the GNAT |
| implementation is fully conformant with this definition. The reason it |
| is mentioned in this section is that a pragma of the same name was supplied |
| in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 |
| implementation of pragma Volatile is upwards compatible with the |
| implementation in DEC Ada 83. |
| |
| @node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{116}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{117} |
| @section Pragma Volatile_Full_Access |
| |
| |
| Syntax: |
| |
| @example |
| pragma Volatile_Full_Access (LOCAL_NAME); |
| @end example |
| |
| This is similar in effect to pragma Volatile, except that any reference to the |
| object is guaranteed to be done only with instructions that read or write all |
| the bits of the object. Furthermore, if the object is of a composite type, |
| then any reference to a subcomponent of the object is guaranteed to read |
| and/or write all the bits of the object. |
| |
| The intention is that this be suitable for use with memory-mapped I/O devices |
| on some machines. Note that there are two important respects in which this is |
| different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} |
| object is not a sequential action in the RM 9.10 sense and, therefore, does |
| not create a synchronization point. Second, in the case of @code{pragma Atomic}, |
| there is no guarantee that all the bits will be accessed if the reference |
| is not to the whole object; the compiler is allowed (and generally will) |
| access only part of the object in this case. |
| |
| @node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{118}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{119} |
| @section Pragma Volatile_Function |
| |
| |
| Syntax: |
| |
| @example |
| pragma Volatile_Function [ (boolean_EXPRESSION) ]; |
| @end example |
| |
| For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} |
| in the SPARK 2014 Reference Manual, section 7.1.2. |
| |
| @node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11a} |
| @section Pragma Warning_As_Error |
| |
| |
| Syntax: |
| |
| @example |
| pragma Warning_As_Error (static_string_EXPRESSION); |
| @end example |
| |
| This configuration pragma allows the programmer to specify a set |
| of warnings that will be treated as errors. Any warning that |
| matches the pattern given by the pragma argument will be treated |
| as an error. This gives more precise control than -gnatwe, |
| which treats warnings as errors. |
| |
| This pragma can apply to regular warnings (messages enabled by -gnatw) |
| and to style warnings (messages that start with “(style)”, |
| enabled by -gnaty). |
| |
| The pattern may contain asterisks, which match zero or more characters |
| in the message. For example, you can use @code{pragma Warning_As_Error |
| ("bits of*unused")} to treat the warning message @code{warning: 960 bits of |
| "a" unused} as an error. All characters other than asterisk are treated |
| as literal characters in the match. The match is case insensitive; for |
| example XYZ matches xyz. |
| |
| Note that the pattern matches if it occurs anywhere within the warning |
| message string (it is not necessary to put an asterisk at the start and |
| the end of the message, since this is implied). |
| |
| Another possibility for the static_string_EXPRESSION which works whether |
| or not error tags are enabled (@emph{-gnatw.d}) is to use a single |
| @emph{-gnatw} tag string, enclosed in brackets, |
| as shown in the example below, to treat one category of warnings as errors. |
| Note that if you want to treat multiple categories of warnings as errors, |
| you can use multiple pragma Warning_As_Error. |
| |
| The above use of patterns to match the message applies only to warning |
| messages generated by the front end. This pragma can also be applied to |
| warnings provided by the back end and mentioned in @ref{11b,,Pragma Warnings}. |
| By using a single full @emph{-Wxxx} switch in the pragma, such warnings |
| can also be treated as errors. |
| |
| The pragma can appear either in a global configuration pragma file |
| (e.g. @code{gnat.adc}), or at the start of a file. Given a global |
| configuration pragma file containing: |
| |
| @example |
| pragma Warning_As_Error ("[-gnatwj]"); |
| @end example |
| |
| which will treat all obsolescent feature warnings as errors, the |
| following program compiles as shown (compile options here are |
| @emph{-gnatwa.d -gnatl -gnatj55}). |
| |
| @example |
| 1. pragma Warning_As_Error ("*never assigned*"); |
| 2. function Warnerr return String is |
| 3. X : Integer; |
| | |
| >>> error: variable "X" is never read and |
| never assigned [-gnatwv] [warning-as-error] |
| |
| 4. Y : Integer; |
| | |
| >>> warning: variable "Y" is assigned but |
| never read [-gnatwu] |
| |
| 5. begin |
| 6. Y := 0; |
| 7. return %ABC%; |
| | |
| >>> error: use of "%" is an obsolescent |
| feature (RM J.2(4)), use """ instead |
| [-gnatwj] [warning-as-error] |
| |
| 8. end; |
| |
| 8 lines: No errors, 3 warnings (2 treated as errors) |
| @end example |
| |
| Note that this pragma does not affect the set of warnings issued in |
| any way, it merely changes the effect of a matching warning if one |
| is produced as a result of other warnings options. As shown in this |
| example, if the pragma results in a warning being treated as an error, |
| the tag is changed from “warning:” to “error:” and the string |
| “[warning-as-error]” is appended to the end of the message. |
| |
| @node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11c}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11b} |
| @section Pragma Warnings |
| |
| |
| Syntax: |
| |
| @example |
| pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); |
| |
| DETAILS ::= On | Off |
| DETAILS ::= On | Off, local_NAME |
| DETAILS ::= static_string_EXPRESSION |
| DETAILS ::= On | Off, static_string_EXPRESSION |
| |
| TOOL_NAME ::= GNAT | GNATprove |
| |
| REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} |
| @end example |
| |
| Note: in Ada 83 mode, a string literal may be used in place of a static string |
| expression (which does not exist in Ada 83). |
| |
| Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the |
| second form is always understood. If the intention is to use |
| the fourth form, then you can write @code{NAME & ""} to force the |
| intepretation as a @emph{static_string_EXPRESSION}. |
| |
| Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted |
| that way. The use of the @code{TOOL_NAME} argument is relevant only to users |
| of SPARK and GNATprove, see last part of this section for details. |
| |
| Normally warnings are enabled, with the output being controlled by |
| the command line switch. Warnings (@code{Off}) turns off generation of |
| warnings until a Warnings (@code{On}) is encountered or the end of the |
| current unit. If generation of warnings is turned off using this |
| pragma, then some or all of the warning messages are suppressed, |
| regardless of the setting of the command line switches. |
| |
| The @code{Reason} parameter may optionally appear as the last argument |
| in any of the forms of this pragma. It is intended purely for the |
| purposes of documenting the reason for the @code{Warnings} pragma. |
| The compiler will check that the argument is a static string but |
| otherwise ignore this argument. Other tools may provide specialized |
| processing for this string. |
| |
| The form with a single argument (or two arguments if Reason present), |
| where the first argument is @code{ON} or @code{OFF} |
| may be used as a configuration pragma. |
| |
| If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for |
| the specified entity. This suppression is effective from the point where |
| it occurs till the end of the extended scope of the variable (similar to |
| the scope of @code{Suppress}). This form cannot be used as a configuration |
| pragma. |
| |
| In the case where the first argument is other than @code{ON} or |
| @code{OFF}, |
| the third form with a single static_string_EXPRESSION argument (and possible |
| reason) provides more precise |
| control over which warnings are active. The string is a list of letters |
| specifying which warnings are to be activated and which deactivated. The |
| code for these letters is the same as the string used in the command |
| line switch controlling warnings. For a brief summary, use the gnatmake |
| command with no arguments, which will generate usage information containing |
| the list of warnings switches supported. For |
| full details see the section on @code{Warning Message Control} in the |
| @cite{GNAT User’s Guide}. |
| This form can also be used as a configuration pragma. |
| |
| The warnings controlled by the @code{-gnatw} switch are generated by the |
| front end of the compiler. The GCC back end can provide additional warnings |
| and they are controlled by the @code{-W} switch. Such warnings can be |
| identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the |
| message which designates the @code{-W@emph{xxx}} switch that controls the message. |
| The form with a single @emph{static_string_EXPRESSION} argument also works for these |
| warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this |
| case. The above reference lists a few examples of these additional warnings. |
| |
| The specified warnings will be in effect until the end of the program |
| or another pragma @code{Warnings} is encountered. The effect of the pragma is |
| cumulative. Initially the set of warnings is the standard default set |
| as possibly modified by compiler switches. Then each pragma Warning |
| modifies this set of warnings as specified. This form of the pragma may |
| also be used as a configuration pragma. |
| |
| The fourth form, with an @code{On|Off} parameter and a string, is used to |
| control individual messages, based on their text. The string argument |
| is a pattern that is used to match against the text of individual |
| warning messages (not including the initial “warning: ” tag). |
| |
| The pattern may contain asterisks, which match zero or more characters in |
| the message. For example, you can use |
| @code{pragma Warnings (Off, "bits of*unused")} to suppress the warning |
| message @code{warning: 960 bits of "a" unused}. No other regular |
| expression notations are permitted. All characters other than asterisk in |
| these three specific cases are treated as literal characters in the match. |
| The match is case insensitive, for example XYZ matches xyz. |
| |
| Note that the pattern matches if it occurs anywhere within the warning |
| message string (it is not necessary to put an asterisk at the start and |
| the end of the message, since this is implied). |
| |
| The above use of patterns to match the message applies only to warning |
| messages generated by the front end. This form of the pragma with a string |
| argument can also be used to control warnings provided by the back end and |
| mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma, |
| such warnings can be turned on and off. |
| |
| There are two ways to use the pragma in this form. The OFF form can be used |
| as a configuration pragma. The effect is to suppress all warnings (if any) |
| that match the pattern string throughout the compilation (or match the |
| -W switch in the back end case). |
| |
| The second usage is to suppress a warning locally, and in this case, two |
| pragmas must appear in sequence: |
| |
| @example |
| pragma Warnings (Off, Pattern); |
| ... code where given warning is to be suppressed |
| pragma Warnings (On, Pattern); |
| @end example |
| |
| In this usage, the pattern string must match in the Off and On |
| pragmas, and (if @emph{-gnatw.w} is given) at least one matching |
| warning must be suppressed. |
| |
| Note: if the ON form is not found, then the effect of the OFF form extends |
| until the end of the file (pragma Warnings is purely textual, so its effect |
| does not stop at the end of the enclosing scope). |
| |
| Note: to write a string that will match any warning, use the string |
| @code{"***"}. It will not work to use a single asterisk or two |
| asterisks since this looks like an operator name. This form with three |
| asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching |
| @code{pragma Warnings (On, "***")} will be required. This can be |
| helpful in avoiding forgetting to turn warnings back on. |
| |
| Note: the debug flag @code{-gnatd.i} can be |
| used to cause the compiler to entirely ignore all WARNINGS pragmas. This can |
| be useful in checking whether obsolete pragmas in existing programs are hiding |
| real problems. |
| |
| Note: pragma Warnings does not affect the processing of style messages. See |
| separate entry for pragma Style_Checks for control of style messages. |
| |
| Users of the formal verification tool GNATprove for the SPARK subset of Ada may |
| use the version of the pragma with a @code{TOOL_NAME} parameter. |
| |
| If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the |
| compiler or @code{GNATprove} for the formal verification tool. A given tool only |
| takes into account pragma Warnings that do not specify a tool name, or that |
| specify the matching tool name. This makes it possible to disable warnings |
| selectively for each tool, and as a consequence to detect useless pragma |
| Warnings with switch @code{-gnatw.w}. |
| |
| @node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11d} |
| @section Pragma Weak_External |
| |
| |
| Syntax: |
| |
| @example |
| pragma Weak_External ([Entity =>] LOCAL_NAME); |
| @end example |
| |
| @code{LOCAL_NAME} must refer to an object that is declared at the library |
| level. This pragma specifies that the given entity should be marked as a |
| weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} |
| in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead |
| of a regular symbol, that is to say a symbol that does not have to be |
| resolved by the linker if used in conjunction with a pragma Import. |
| |
| When a weak symbol is not resolved by the linker, its address is set to |
| zero. This is useful in writing interfaces to external modules that may |
| or may not be linked in the final executable, for example depending on |
| configuration settings. |
| |
| If a program references at run time an entity to which this pragma has been |
| applied, and the corresponding symbol was not resolved at link time, then |
| the execution of the program is erroneous. It is not erroneous to take the |
| Address of such an entity, for example to guard potential references, |
| as shown in the example below. |
| |
| Some file formats do not support weak symbols so not all target machines |
| support this pragma. |
| |
| @example |
| -- Example of the use of pragma Weak_External |
| |
| package External_Module is |
| key : Integer; |
| pragma Import (C, key); |
| pragma Weak_External (key); |
| function Present return boolean; |
| end External_Module; |
| |
| with System; use System; |
| package body External_Module is |
| function Present return boolean is |
| begin |
| return key'Address /= System.Null_Address; |
| end Present; |
| end External_Module; |
| @end example |
| |
| @node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas |
| @anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11e} |
| @section Pragma Wide_Character_Encoding |
| |
| |
| Syntax: |
| |
| @example |
| pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); |
| @end example |
| |
| This pragma specifies the wide character encoding to be used in program |
| source text appearing subsequently. It is a configuration pragma, but may |
| also be used at any point that a pragma is allowed, and it is permissible |
| to have more than one such pragma in a file, allowing multiple encodings |
| to appear within the same file. |
| |
| However, note that the pragma cannot immediately precede the relevant |
| wide character, because then the previous encoding will still be in |
| effect, causing “illegal character” errors. |
| |
| The argument can be an identifier or a character literal. In the identifier |
| case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, |
| @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal |
| case it is correspondingly one of the characters @code{h}, @code{u}, |
| @code{s}, @code{e}, @code{8}, or @code{b}. |
| |
| Note that when the pragma is used within a file, it affects only the |
| encoding within that file, and does not affect withed units, specs, |
| or subunits. |
| |
| @node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top |
| @anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{120}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{121} |
| @chapter Implementation Defined Aspects |
| |
| |
| Ada defines (throughout the Ada 2012 reference manual, summarized |
| in Annex K) a set of aspects that can be specified for certain entities. |
| These language defined aspects are implemented in GNAT in Ada 2012 mode |
| and work as described in the Ada 2012 Reference Manual. |
| |
| In addition, Ada 2012 allows implementations to define additional aspects |
| whose meaning is defined by the implementation. GNAT provides |
| a number of these implementation-defined aspects which can be used |
| to extend and enhance the functionality of the compiler. This section of |
| the GNAT reference manual describes these additional aspects. |
| |
| Note that any program using these aspects may not be portable to |
| other compilers (although GNAT implements this set of aspects on all |
| platforms). Therefore if portability to other compilers is an important |
| consideration, you should minimize the use of these aspects. |
| |
| Note that for many of these aspects, the effect is essentially similar |
| to the use of a pragma or attribute specification with the same name |
| applied to the entity. For example, if we write: |
| |
| @example |
| type R is range 1 .. 100 |
| with Value_Size => 10; |
| @end example |
| |
| then the effect is the same as: |
| |
| @example |
| type R is range 1 .. 100; |
| for R'Value_Size use 10; |
| @end example |
| |
| and if we write: |
| |
| @example |
| type R is new Integer |
| with Shared => True; |
| @end example |
| |
| then the effect is the same as: |
| |
| @example |
| type R is new Integer; |
| pragma Shared (R); |
| @end example |
| |
| In the documentation below, such cases are simply marked |
| as being boolean aspects equivalent to the corresponding pragma |
| or attribute definition clause. |
| |
| @menu |
| * Aspect Abstract_State:: |
| * Aspect Annotate:: |
| * Aspect Async_Readers:: |
| * Aspect Async_Writers:: |
| * Aspect Constant_After_Elaboration:: |
| * Aspect Contract_Cases:: |
| * Aspect Depends:: |
| * Aspect Default_Initial_Condition:: |
| * Aspect Dimension:: |
| * Aspect Dimension_System:: |
| * Aspect Disable_Controlled:: |
| * Aspect Effective_Reads:: |
| * Aspect Effective_Writes:: |
| * Aspect Extensions_Visible:: |
| * Aspect Favor_Top_Level:: |
| * Aspect Ghost:: |
| * Aspect Global:: |
| * Aspect Initial_Condition:: |
| * Aspect Initializes:: |
| * Aspect Inline_Always:: |
| * Aspect Invariant:: |
| * Aspect Invariant’Class:: |
| * Aspect Iterable:: |
| * Aspect Linker_Section:: |
| * Aspect Lock_Free:: |
| * Aspect Max_Queue_Length:: |
| * Aspect No_Caching:: |
| * Aspect No_Elaboration_Code_All:: |
| * Aspect No_Inline:: |
| * Aspect No_Tagged_Streams:: |
| * Aspect No_Task_Parts:: |
| * Aspect Object_Size:: |
| * Aspect Obsolescent:: |
| * Aspect Part_Of:: |
| * Aspect Persistent_BSS:: |
| * Aspect Predicate:: |
| * Aspect Pure_Function:: |
| * Aspect Refined_Depends:: |
| * Aspect Refined_Global:: |
| * Aspect Refined_Post:: |
| * Aspect Refined_State:: |
| * Aspect Relaxed_Initialization:: |
| * Aspect Remote_Access_Type:: |
| * Aspect Secondary_Stack_Size:: |
| * Aspect Scalar_Storage_Order:: |
| * Aspect Shared:: |
| * Aspect Simple_Storage_Pool:: |
| * Aspect Simple_Storage_Pool_Type:: |
| * Aspect SPARK_Mode:: |
| * Aspect Suppress_Debug_Info:: |
| * Aspect Suppress_Initialization:: |
| * Aspect Test_Case:: |
| * Aspect Thread_Local_Storage:: |
| * Aspect Universal_Aliasing:: |
| * Aspect Unmodified:: |
| * Aspect Unreferenced:: |
| * Aspect Unreferenced_Objects:: |
| * Aspect Value_Size:: |
| * Aspect Volatile_Full_Access:: |
| * Aspect Volatile_Function:: |
| * Aspect Warnings:: |
| |
| @end menu |
| |
| @node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{122} |
| @section Aspect Abstract_State |
| |
| |
| @geindex Abstract_State |
| |
| This aspect is equivalent to @ref{1e,,pragma Abstract_State}. |
| |
| @node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{123} |
| @section Aspect Annotate |
| |
| |
| @geindex Annotate |
| |
| There are three forms of this aspect (where ID is an identifier, |
| and ARG is a general expression), |
| corresponding to @ref{28,,pragma Annotate}. |
| |
| |
| @table @asis |
| |
| @item @emph{Annotate => ID} |
| |
| Equivalent to @code{pragma Annotate (ID, Entity => Name);} |
| |
| @item @emph{Annotate => (ID)} |
| |
| Equivalent to @code{pragma Annotate (ID, Entity => Name);} |
| |
| @item @emph{Annotate => (ID ,ID @{, ARG@})} |
| |
| Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} |
| @end table |
| |
| @node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{124} |
| @section Aspect Async_Readers |
| |
| |
| @geindex Async_Readers |
| |
| This boolean aspect is equivalent to @ref{2f,,pragma Async_Readers}. |
| |
| @node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{125} |
| @section Aspect Async_Writers |
| |
| |
| @geindex Async_Writers |
| |
| This boolean aspect is equivalent to @ref{31,,pragma Async_Writers}. |
| |
| @node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{126} |
| @section Aspect Constant_After_Elaboration |
| |
| |
| @geindex Constant_After_Elaboration |
| |
| This aspect is equivalent to @ref{43,,pragma Constant_After_Elaboration}. |
| |
| @node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{127} |
| @section Aspect Contract_Cases |
| |
| |
| @geindex Contract_Cases |
| |
| This aspect is equivalent to @ref{45,,pragma Contract_Cases}, the sequence |
| of clauses being enclosed in parentheses so that syntactically it is an |
| aggregate. |
| |
| @node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{128} |
| @section Aspect Depends |
| |
| |
| @geindex Depends |
| |
| This aspect is equivalent to @ref{55,,pragma Depends}. |
| |
| @node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{129} |
| @section Aspect Default_Initial_Condition |
| |
| |
| @geindex Default_Initial_Condition |
| |
| This aspect is equivalent to @ref{4f,,pragma Default_Initial_Condition}. |
| |
| @node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12a} |
| @section Aspect Dimension |
| |
| |
| @geindex Dimension |
| |
| The @code{Dimension} aspect is used to specify the dimensions of a given |
| subtype of a dimensioned numeric type. The aspect also specifies a symbol |
| used when doing formatted output of dimensioned quantities. The syntax is: |
| |
| @example |
| with Dimension => |
| ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) |
| |
| SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL |
| |
| DIMENSION_VALUE ::= |
| RATIONAL |
| | others => RATIONAL |
| | DISCRETE_CHOICE_LIST => RATIONAL |
| |
| RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] |
| @end example |
| |
| This aspect can only be applied to a subtype whose parent type has |
| a @code{Dimension_System} aspect. The aspect must specify values for |
| all dimensions of the system. The rational values are the powers of the |
| corresponding dimensions that are used by the compiler to verify that |
| physical (numeric) computations are dimensionally consistent. For example, |
| the computation of a force must result in dimensions (L => 1, M => 1, T => -2). |
| For further examples of the usage |
| of this aspect, see package @code{System.Dim.Mks}. |
| Note that when the dimensioned type is an integer type, then any |
| dimension value must be an integer literal. |
| |
| @node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12b} |
| @section Aspect Dimension_System |
| |
| |
| @geindex Dimension_System |
| |
| The @code{Dimension_System} aspect is used to define a system of |
| dimensions that will be used in subsequent subtype declarations with |
| @code{Dimension} aspects that reference this system. The syntax is: |
| |
| @example |
| with Dimension_System => (DIMENSION @{, DIMENSION@}); |
| |
| DIMENSION ::= ([Unit_Name =>] IDENTIFIER, |
| [Unit_Symbol =>] SYMBOL, |
| [Dim_Symbol =>] SYMBOL) |
| |
| SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL |
| @end example |
| |
| This aspect is applied to a type, which must be a numeric derived type |
| (typically a floating-point type), that |
| will represent values within the dimension system. Each @code{DIMENSION} |
| corresponds to one particular dimension. A maximum of 7 dimensions may |
| be specified. @code{Unit_Name} is the name of the dimension (for example |
| @code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities |
| of this dimension (for example @code{m} for @code{Meter}). |
| @code{Dim_Symbol} gives |
| the identification within the dimension system (typically this is a |
| single letter, e.g. @code{L} standing for length for unit name @code{Meter}). |
| The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. |
| The @code{Dim_Symbol} is used in error messages when numeric operations have |
| inconsistent dimensions. |
| |
| GNAT provides the standard definition of the International MKS system in |
| the run-time package @code{System.Dim.Mks}. You can easily define |
| similar packages for cgs units or British units, and define conversion factors |
| between values in different systems. The MKS system is characterized by the |
| following aspect: |
| |
| @example |
| type Mks_Type is new Long_Long_Float with |
| Dimension_System => ( |
| (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), |
| (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), |
| (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), |
| (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), |
| (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), |
| (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), |
| (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); |
| @end example |
| |
| Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to |
| represent a theta character (avoiding the use of extended Latin-1 |
| characters in this context). |
| |
| See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users |
| Guide for detailed examples of use of the dimension system. |
| |
| @node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12c} |
| @section Aspect Disable_Controlled |
| |
| |
| @geindex Disable_Controlled |
| |
| The aspect @code{Disable_Controlled} is defined for controlled record types. If |
| active, this aspect causes suppression of all related calls to @code{Initialize}, |
| @code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, |
| where for example you might want a record to be controlled or not depending on |
| whether some run-time check is enabled or suppressed. |
| |
| @node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12d} |
| @section Aspect Effective_Reads |
| |
| |
| @geindex Effective_Reads |
| |
| This aspect is equivalent to @ref{5a,,pragma Effective_Reads}. |
| |
| @node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12e} |
| @section Aspect Effective_Writes |
| |
| |
| @geindex Effective_Writes |
| |
| This aspect is equivalent to @ref{5c,,pragma Effective_Writes}. |
| |
| @node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12f} |
| @section Aspect Extensions_Visible |
| |
| |
| @geindex Extensions_Visible |
| |
| This aspect is equivalent to @ref{67,,pragma Extensions_Visible}. |
| |
| @node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{130} |
| @section Aspect Favor_Top_Level |
| |
| |
| @geindex Favor_Top_Level |
| |
| This boolean aspect is equivalent to @ref{6c,,pragma Favor_Top_Level}. |
| |
| @node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{131} |
| @section Aspect Ghost |
| |
| |
| @geindex Ghost |
| |
| This aspect is equivalent to @ref{70,,pragma Ghost}. |
| |
| @node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{132} |
| @section Aspect Global |
| |
| |
| @geindex Global |
| |
| This aspect is equivalent to @ref{72,,pragma Global}. |
| |
| @node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{133} |
| @section Aspect Initial_Condition |
| |
| |
| @geindex Initial_Condition |
| |
| This aspect is equivalent to @ref{7f,,pragma Initial_Condition}. |
| |
| @node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{134} |
| @section Aspect Initializes |
| |
| |
| @geindex Initializes |
| |
| This aspect is equivalent to @ref{82,,pragma Initializes}. |
| |
| @node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{135} |
| @section Aspect Inline_Always |
| |
| |
| @geindex Inline_Always |
| |
| This boolean aspect is equivalent to @ref{84,,pragma Inline_Always}. |
| |
| @node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{136} |
| @section Aspect Invariant |
| |
| |
| @geindex Invariant |
| |
| This aspect is equivalent to @ref{8b,,pragma Invariant}. It is a |
| synonym for the language defined aspect @code{Type_Invariant} except |
| that it is separately controllable using pragma @code{Assertion_Policy}. |
| |
| @node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{137} |
| @section Aspect Invariant’Class |
| |
| |
| @geindex Invariant'Class |
| |
| This aspect is equivalent to @ref{102,,pragma Type_Invariant_Class}. It is a |
| synonym for the language defined aspect @code{Type_Invariant'Class} except |
| that it is separately controllable using pragma @code{Assertion_Policy}. |
| |
| @node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{138} |
| @section Aspect Iterable |
| |
| |
| @geindex Iterable |
| |
| This aspect provides a light-weight mechanism for loops and quantified |
| expressions over container types, without the overhead imposed by the tampering |
| checks of standard Ada 2012 iterators. The value of the aspect is an aggregate |
| with six named components, of which the last three are optional: @code{First}, |
| @code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. |
| When only the first three components are specified, only the |
| @code{for .. in} form of iteration over cursors is available. When @code{Element} |
| is specified, both this form and the @code{for .. of} form of iteration over |
| elements are available. If the last two components are specified, reverse |
| iterations over the container can be specified (analogous to what can be done |
| over predefined containers that support the @code{Reverse_Iterator} interface). |
| The following is a typical example of use: |
| |
| @example |
| type List is private with |
| Iterable => (First => First_Cursor, |
| Next => Advance, |
| Has_Element => Cursor_Has_Element, |
| [Element => Get_Element]); |
| @end example |
| |
| |
| @itemize * |
| |
| @item |
| The value denoted by @code{First} must denote a primitive operation of the |
| container type that returns a @code{Cursor}, which must a be a type declared in |
| the container package or visible from it. For example: |
| @end itemize |
| |
| @example |
| function First_Cursor (Cont : Container) return Cursor; |
| @end example |
| |
| |
| @itemize * |
| |
| @item |
| The value of @code{Next} is a primitive operation of the container type that takes |
| both a container and a cursor and yields a cursor. For example: |
| @end itemize |
| |
| @example |
| function Advance (Cont : Container; Position : Cursor) return Cursor; |
| @end example |
| |
| |
| @itemize * |
| |
| @item |
| The value of @code{Has_Element} is a primitive operation of the container type |
| that takes both a container and a cursor and yields a boolean. For example: |
| @end itemize |
| |
| @example |
| function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; |
| @end example |
| |
| |
| @itemize * |
| |
| @item |
| The value of @code{Element} is a primitive operation of the container type that |
| takes both a container and a cursor and yields an @code{Element_Type}, which must |
| be a type declared in the container package or visible from it. For example: |
| @end itemize |
| |
| @example |
| function Get_Element (Cont : Container; Position : Cursor) return Element_Type; |
| @end example |
| |
| This aspect is used in the GNAT-defined formal container packages. |
| |
| @node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{139} |
| @section Aspect Linker_Section |
| |
| |
| @geindex Linker_Section |
| |
| This aspect is equivalent to @ref{93,,pragma Linker_Section}. |
| |
| @node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{13a} |
| @section Aspect Lock_Free |
| |
| |
| @geindex Lock_Free |
| |
| This boolean aspect is equivalent to @ref{95,,pragma Lock_Free}. |
| |
| @node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13b} |
| @section Aspect Max_Queue_Length |
| |
| |
| @geindex Max_Queue_Length |
| |
| This aspect is equivalent to @ref{9d,,pragma Max_Queue_Length}. |
| |
| @node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13c} |
| @section Aspect No_Caching |
| |
| |
| @geindex No_Caching |
| |
| This boolean aspect is equivalent to @ref{a0,,pragma No_Caching}. |
| |
| @node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13d} |
| @section Aspect No_Elaboration_Code_All |
| |
| |
| @geindex No_Elaboration_Code_All |
| |
| This aspect is equivalent to @ref{a3,,pragma No_Elaboration_Code_All} |
| for a program unit. |
| |
| @node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13e} |
| @section Aspect No_Inline |
| |
| |
| @geindex No_Inline |
| |
| This boolean aspect is equivalent to @ref{a6,,pragma No_Inline}. |
| |
| @node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13f} |
| @section Aspect No_Tagged_Streams |
| |
| |
| @geindex No_Tagged_Streams |
| |
| This aspect is equivalent to @ref{aa,,pragma No_Tagged_Streams} with an |
| argument specifying a root tagged type (thus this aspect can only be |
| applied to such a type). |
| |
| @node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{140} |
| @section Aspect No_Task_Parts |
| |
| |
| @geindex No_Task_Parts |
| |
| Applies to a type. If True, requires that the type and any descendants |
| do not have any task parts. The rules for this aspect are the same as |
| for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), |
| replacing “controlled” with “task”. |
| |
| If No_Task_Parts is True for a type T, then the compiler can optimize |
| away certain tasking-related code that would otherwise be needed |
| for T’Class, because descendants of T might contain tasks. |
| |
| @node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{141} |
| @section Aspect Object_Size |
| |
| |
| @geindex Object_Size |
| |
| This aspect is equivalent to @ref{142,,attribute Object_Size}. |
| |
| @node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{143} |
| @section Aspect Obsolescent |
| |
| |
| @geindex Obsolsecent |
| |
| This aspect is equivalent to @ref{ad,,pragma Obsolescent}. Note that the |
| evaluation of this aspect happens at the point of occurrence, it is not |
| delayed until the freeze point. |
| |
| @node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{144} |
| @section Aspect Part_Of |
| |
| |
| @geindex Part_Of |
| |
| This aspect is equivalent to @ref{b4,,pragma Part_Of}. |
| |
| @node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{145} |
| @section Aspect Persistent_BSS |
| |
| |
| @geindex Persistent_BSS |
| |
| This boolean aspect is equivalent to @ref{b7,,pragma Persistent_BSS}. |
| |
| @node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{146} |
| @section Aspect Predicate |
| |
| |
| @geindex Predicate |
| |
| This aspect is equivalent to @ref{be,,pragma Predicate}. It is thus |
| similar to the language defined aspects @code{Dynamic_Predicate} |
| and @code{Static_Predicate} except that whether the resulting |
| predicate is static or dynamic is controlled by the form of the |
| expression. It is also separately controllable using pragma |
| @code{Assertion_Policy}. |
| |
| @node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{147} |
| @section Aspect Pure_Function |
| |
| |
| @geindex Pure_Function |
| |
| This boolean aspect is equivalent to @ref{ca,,pragma Pure_Function}. |
| |
| @node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{148} |
| @section Aspect Refined_Depends |
| |
| |
| @geindex Refined_Depends |
| |
| This aspect is equivalent to @ref{ce,,pragma Refined_Depends}. |
| |
| @node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{149} |
| @section Aspect Refined_Global |
| |
| |
| @geindex Refined_Global |
| |
| This aspect is equivalent to @ref{d0,,pragma Refined_Global}. |
| |
| @node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14a} |
| @section Aspect Refined_Post |
| |
| |
| @geindex Refined_Post |
| |
| This aspect is equivalent to @ref{d2,,pragma Refined_Post}. |
| |
| @node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14b} |
| @section Aspect Refined_State |
| |
| |
| @geindex Refined_State |
| |
| This aspect is equivalent to @ref{d4,,pragma Refined_State}. |
| |
| @node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14c} |
| @section Aspect Relaxed_Initialization |
| |
| |
| @geindex Refined_Initialization |
| |
| For the syntax and semantics of this aspect, see the SPARK 2014 Reference |
| Manual, section 6.10. |
| |
| @node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14d} |
| @section Aspect Remote_Access_Type |
| |
| |
| @geindex Remote_Access_Type |
| |
| This aspect is equivalent to @ref{d7,,pragma Remote_Access_Type}. |
| |
| @node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14e} |
| @section Aspect Secondary_Stack_Size |
| |
| |
| @geindex Secondary_Stack_Size |
| |
| This aspect is equivalent to @ref{dd,,pragma Secondary_Stack_Size}. |
| |
| @node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14f} |
| @section Aspect Scalar_Storage_Order |
| |
| |
| @geindex Scalar_Storage_Order |
| |
| This aspect is equivalent to a @ref{150,,attribute Scalar_Storage_Order}. |
| |
| @node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{151} |
| @section Aspect Shared |
| |
| |
| @geindex Shared |
| |
| This boolean aspect is equivalent to @ref{e0,,pragma Shared} |
| and is thus a synonym for aspect @code{Atomic}. |
| |
| @node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{152} |
| @section Aspect Simple_Storage_Pool |
| |
| |
| @geindex Simple_Storage_Pool |
| |
| This aspect is equivalent to @ref{e5,,attribute Simple_Storage_Pool}. |
| |
| @node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{153} |
| @section Aspect Simple_Storage_Pool_Type |
| |
| |
| @geindex Simple_Storage_Pool_Type |
| |
| This boolean aspect is equivalent to @ref{e4,,pragma Simple_Storage_Pool_Type}. |
| |
| @node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{154} |
| @section Aspect SPARK_Mode |
| |
| |
| @geindex SPARK_Mode |
| |
| This aspect is equivalent to @ref{ec,,pragma SPARK_Mode} and |
| may be specified for either or both of the specification and body |
| of a subprogram or package. |
| |
| @node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{155} |
| @section Aspect Suppress_Debug_Info |
| |
| |
| @geindex Suppress_Debug_Info |
| |
| This boolean aspect is equivalent to @ref{f4,,pragma Suppress_Debug_Info}. |
| |
| @node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{156} |
| @section Aspect Suppress_Initialization |
| |
| |
| @geindex Suppress_Initialization |
| |
| This boolean aspect is equivalent to @ref{f7,,pragma Suppress_Initialization}. |
| |
| @node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{157} |
| @section Aspect Test_Case |
| |
| |
| @geindex Test_Case |
| |
| This aspect is equivalent to @ref{fb,,pragma Test_Case}. |
| |
| @node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{158} |
| @section Aspect Thread_Local_Storage |
| |
| |
| @geindex Thread_Local_Storage |
| |
| This boolean aspect is equivalent to @ref{fd,,pragma Thread_Local_Storage}. |
| |
| @node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{159} |
| @section Aspect Universal_Aliasing |
| |
| |
| @geindex Universal_Aliasing |
| |
| This boolean aspect is equivalent to @ref{107,,pragma Universal_Aliasing}. |
| |
| @node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{15a} |
| @section Aspect Unmodified |
| |
| |
| @geindex Unmodified |
| |
| This boolean aspect is equivalent to @ref{109,,pragma Unmodified}. |
| |
| @node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15b} |
| @section Aspect Unreferenced |
| |
| |
| @geindex Unreferenced |
| |
| This boolean aspect is equivalent to @ref{10b,,pragma Unreferenced}. |
| |
| When using the @code{-gnat2022} switch, this aspect is also supported on formal |
| parameters, which is in particular the only form possible for expression |
| functions. |
| |
| @node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15c} |
| @section Aspect Unreferenced_Objects |
| |
| |
| @geindex Unreferenced_Objects |
| |
| This boolean aspect is equivalent to @ref{10d,,pragma Unreferenced_Objects}. |
| |
| @node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15d} |
| @section Aspect Value_Size |
| |
| |
| @geindex Value_Size |
| |
| This aspect is equivalent to @ref{15e,,attribute Value_Size}. |
| |
| @node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15f} |
| @section Aspect Volatile_Full_Access |
| |
| |
| @geindex Volatile_Full_Access |
| |
| This boolean aspect is equivalent to @ref{117,,pragma Volatile_Full_Access}. |
| |
| @node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{160} |
| @section Aspect Volatile_Function |
| |
| |
| @geindex Volatile_Function |
| |
| This boolean aspect is equivalent to @ref{119,,pragma Volatile_Function}. |
| |
| @node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects |
| @anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{161} |
| @section Aspect Warnings |
| |
| |
| @geindex Warnings |
| |
| This aspect is equivalent to the two argument form of @ref{11b,,pragma Warnings}, |
| where the first argument is @code{ON} or @code{OFF} and the second argument |
| is the entity. |
| |
| @node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top |
| @anchor{gnat_rm/implementation_defined_attributes doc}@anchor{162}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{163}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8} |
| @chapter Implementation Defined Attributes |
| |
| |
| Ada defines (throughout the Ada reference manual, |
| summarized in Annex K), |
| a set of attributes that provide useful additional functionality in all |
| areas of the language. These language defined attributes are implemented |
| in GNAT and work as described in the Ada Reference Manual. |
| |
| In addition, Ada allows implementations to define additional |
| attributes whose meaning is defined by the implementation. GNAT provides |
| a number of these implementation-dependent attributes which can be used |
| to extend and enhance the functionality of the compiler. This section of |
| the GNAT reference manual describes these additional attributes. It also |
| describes additional implementation-dependent features of standard |
| language-defined attributes. |
| |
| Note that any program using these attributes may not be portable to |
| other compilers (although GNAT implements this set of attributes on all |
| platforms). Therefore if portability to other compilers is an important |
| consideration, you should minimize the use of these attributes. |
| |
| @menu |
| * Attribute Abort_Signal:: |
| * Attribute Address_Size:: |
| * Attribute Asm_Input:: |
| * Attribute Asm_Output:: |
| * Attribute Atomic_Always_Lock_Free:: |
| * Attribute Bit:: |
| * Attribute Bit_Position:: |
| * Attribute Code_Address:: |
| * Attribute Compiler_Version:: |
| * Attribute Constrained:: |
| * Attribute Default_Bit_Order:: |
| * Attribute Default_Scalar_Storage_Order:: |
| * Attribute Deref:: |
| * Attribute Descriptor_Size:: |
| * Attribute Elaborated:: |
| * Attribute Elab_Body:: |
| * Attribute Elab_Spec:: |
| * Attribute Elab_Subp_Body:: |
| * Attribute Emax:: |
| * Attribute Enabled:: |
| * Attribute Enum_Rep:: |
| * Attribute Enum_Val:: |
| * Attribute Epsilon:: |
| * Attribute Fast_Math:: |
| * Attribute Finalization_Size:: |
| * Attribute Fixed_Value:: |
| * Attribute From_Any:: |
| * Attribute Has_Access_Values:: |
| * Attribute Has_Discriminants:: |
| * Attribute Has_Tagged_Values:: |
| * Attribute Img:: |
| * Attribute Initialized:: |
| * Attribute Integer_Value:: |
| * Attribute Invalid_Value:: |
| * Attribute Iterable:: |
| * Attribute Large:: |
| * Attribute Library_Level:: |
| * Attribute 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:: |
| |
| @end menu |
| |
| @node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{164} |
| @section Attribute Abort_Signal |
| |
| |
| @geindex Abort_Signal |
| |
| @code{Standard'Abort_Signal} (@code{Standard} is the only allowed |
| prefix) provides the entity for the special exception used to signal |
| task abort or asynchronous transfer of control. Normally this attribute |
| should only be used in the tasking runtime (it is highly peculiar, and |
| completely outside the normal semantics of Ada, for a user program to |
| intercept the abort exception). |
| |
| @node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{165} |
| @section Attribute Address_Size |
| |
| |
| @geindex Size of `@w{`}Address`@w{`} |
| |
| @geindex Address_Size |
| |
| @code{Standard'Address_Size} (@code{Standard} is the only allowed |
| prefix) is a static constant giving the number of bits in an |
| @code{Address}. It is the same value as System.Address’Size, |
| but has the advantage of being static, while a direct |
| reference to System.Address’Size is nonstatic because Address |
| is a private type. |
| |
| @node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{166} |
| @section Attribute Asm_Input |
| |
| |
| @geindex Asm_Input |
| |
| The @code{Asm_Input} attribute denotes a function that takes two |
| parameters. The first is a string, the second is an expression of the |
| type designated by the prefix. The first (string) argument is required |
| to be a static expression, and is the constraint for the parameter, |
| (e.g., what kind of register is required). The second argument is the |
| value to be used as the input argument. The possible values for the |
| constant are the same as those used in the RTL, and are dependent on |
| the configuration file used to built the GCC back end. |
| @ref{167,,Machine Code Insertions} |
| |
| @node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{168} |
| @section Attribute Asm_Output |
| |
| |
| @geindex Asm_Output |
| |
| The @code{Asm_Output} attribute denotes a function that takes two |
| parameters. The first is a string, the second is the name of a variable |
| of the type designated by the attribute prefix. The first (string) |
| argument is required to be a static expression and designates the |
| constraint for the parameter (e.g., what kind of register is |
| required). The second argument is the variable to be updated with the |
| result. The possible values for constraint are the same as those used in |
| the RTL, and are dependent on the configuration file used to build the |
| GCC back end. If there are no output operands, then this argument may |
| either be omitted, or explicitly given as @code{No_Output_Operands}. |
| @ref{167,,Machine Code Insertions} |
| |
| @node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{169} |
| @section Attribute Atomic_Always_Lock_Free |
| |
| |
| @geindex Atomic_Always_Lock_Free |
| |
| The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. |
| The result is a Boolean value which is True if the type has discriminants, |
| and False otherwise. The result indicate whether atomic operations are |
| supported by the target for the given type. |
| |
| @node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{16a} |
| @section Attribute Bit |
| |
| |
| @geindex Bit |
| |
| @code{obj'Bit}, where @code{obj} is any object, yields the bit |
| offset within the storage unit (byte) that contains the first bit of |
| storage allocated for the object. The value of this attribute is of the |
| type @emph{universal_integer} and is always a nonnegative number smaller |
| than @code{System.Storage_Unit}. |
| |
| For an object that is a variable or a constant allocated in a register, |
| the value is zero. (The use of this attribute does not force the |
| allocation of a variable to memory). |
| |
| For an object that is a formal parameter, this attribute applies |
| to either the matching actual parameter or to a copy of the |
| matching actual parameter. |
| |
| For an access object the value is zero. Note that |
| @code{obj.all'Bit} is subject to an @code{Access_Check} for the |
| designated object. Similarly for a record component |
| @code{X.C'Bit} is subject to a discriminant check and |
| @code{X(I).Bit} and @code{X(I1..I2)'Bit} |
| are subject to index checks. |
| |
| This attribute is designed to be compatible with the DEC Ada 83 definition |
| and implementation of the @code{Bit} attribute. |
| |
| @node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16b} |
| @section Attribute Bit_Position |
| |
| |
| @geindex Bit_Position |
| |
| @code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one |
| of the fields of the record type, yields the bit |
| offset within the record contains the first bit of |
| storage allocated for the object. The value of this attribute is of the |
| type @emph{universal_integer}. The value depends only on the field |
| @code{C} and is independent of the alignment of |
| the containing record @code{R}. |
| |
| @node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16c} |
| @section Attribute Code_Address |
| |
| |
| @geindex Code_Address |
| |
| @geindex Subprogram address |
| |
| @geindex Address of subprogram code |
| |
| The @code{'Address} |
| attribute may be applied to subprograms in Ada 95 and Ada 2005, but the |
| intended effect seems to be to provide |
| an address value which can be used to call the subprogram by means of |
| an address clause as in the following example: |
| |
| @example |
| procedure K is ... |
| |
| procedure L; |
| for L'Address use K'Address; |
| pragma Import (Ada, L); |
| @end example |
| |
| A call to @code{L} is then expected to result in a call to @code{K}. |
| In Ada 83, where there were no access-to-subprogram values, this was |
| a common work-around for getting the effect of an indirect call. |
| GNAT implements the above use of @code{Address} and the technique |
| illustrated by the example code works correctly. |
| |
| However, for some purposes, it is useful to have the address of the start |
| of the generated code for the subprogram. On some architectures, this is |
| not necessarily the same as the @code{Address} value described above. |
| For example, the @code{Address} value may reference a subprogram |
| descriptor rather than the subprogram itself. |
| |
| The @code{'Code_Address} attribute, which can only be applied to |
| subprogram entities, always returns the address of the start of the |
| generated code of the specified subprogram, which may or may not be |
| the same value as is returned by the corresponding @code{'Address} |
| attribute. |
| |
| @node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16d} |
| @section Attribute Compiler_Version |
| |
| |
| @geindex Compiler_Version |
| |
| @code{Standard'Compiler_Version} (@code{Standard} is the only allowed |
| prefix) yields a static string identifying the version of the compiler |
| being used to compile the unit containing the attribute reference. |
| |
| @node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16e} |
| @section Attribute Constrained |
| |
| |
| @geindex Constrained |
| |
| In addition to the usage of this attribute in the Ada RM, GNAT |
| also permits the use of the @code{'Constrained} attribute |
| in a generic template |
| for any type, including types without discriminants. The value of this |
| attribute in the generic instance when applied to a scalar type or a |
| record type without discriminants is always @code{True}. This usage is |
| compatible with older Ada compilers, including notably DEC Ada. |
| |
| @node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16f} |
| @section Attribute Default_Bit_Order |
| |
| |
| @geindex Big endian |
| |
| @geindex Little endian |
| |
| @geindex Default_Bit_Order |
| |
| @code{Standard'Default_Bit_Order} (@code{Standard} is the only |
| allowed prefix), provides the value @code{System.Default_Bit_Order} |
| as a @code{Pos} value (0 for @code{High_Order_First}, 1 for |
| @code{Low_Order_First}). This is used to construct the definition of |
| @code{Default_Bit_Order} in package @code{System}. |
| |
| @node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{170} |
| @section Attribute Default_Scalar_Storage_Order |
| |
| |
| @geindex Big endian |
| |
| @geindex Little endian |
| |
| @geindex Default_Scalar_Storage_Order |
| |
| @code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only |
| allowed prefix), provides the current value of the default scalar storage |
| order (as specified using pragma @code{Default_Scalar_Storage_Order}, or |
| equal to @code{Default_Bit_Order} if unspecified) as a |
| @code{System.Bit_Order} value. This is a static attribute. |
| |
| @node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{171} |
| @section Attribute Deref |
| |
| |
| @geindex Deref |
| |
| The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields |
| the variable of type @code{typ} that is located at the given address. It is similar |
| to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to |
| a named access-to-@cite{typ} type, except that it yields a variable, so it can be |
| used on the left side of an assignment. |
| |
| @node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{172} |
| @section Attribute Descriptor_Size |
| |
| |
| @geindex Descriptor |
| |
| @geindex Dope vector |
| |
| @geindex Descriptor_Size |
| |
| Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the |
| descriptor allocated for a type. The result is non-zero only for unconstrained |
| array types and the returned value is of type universal integer. In GNAT, an |
| array descriptor contains bounds information and is located immediately before |
| the first element of the array. |
| |
| @example |
| type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; |
| Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); |
| @end example |
| |
| The attribute takes into account any padding due to the alignment of the |
| component type. In the example above, the descriptor contains two values |
| of type @code{Short_Short_Integer} representing the low and high bound. But, |
| since @code{Positive} has an alignment of 4, the size of the descriptor is |
| @code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, |
| which yields a size of 32 bits, i.e. including 16 bits of padding. |
| |
| @node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{173} |
| @section Attribute Elaborated |
| |
| |
| @geindex Elaborated |
| |
| The prefix of the @code{'Elaborated} attribute must be a unit name. The |
| value is a Boolean which indicates whether or not the given unit has been |
| elaborated. This attribute is primarily intended for internal use by the |
| generated code for dynamic elaboration checking, but it can also be used |
| in user programs. The value will always be True once elaboration of all |
| units has been completed. An exception is for units which need no |
| elaboration, the value is always False for such units. |
| |
| @node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{174} |
| @section Attribute Elab_Body |
| |
| |
| @geindex Elab_Body |
| |
| This attribute can only be applied to a program unit name. It returns |
| the entity for the corresponding elaboration procedure for elaborating |
| the body of the referenced unit. This is used in the main generated |
| elaboration procedure by the binder and is not normally used in any |
| other context. However, there may be specialized situations in which it |
| is useful to be able to call this elaboration procedure from Ada code, |
| e.g., if it is necessary to do selective re-elaboration to fix some |
| error. |
| |
| @node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{175} |
| @section Attribute Elab_Spec |
| |
| |
| @geindex Elab_Spec |
| |
| This attribute can only be applied to a program unit name. It returns |
| the entity for the corresponding elaboration procedure for elaborating |
| the spec of the referenced unit. This is used in the main |
| generated elaboration procedure by the binder and is not normally used |
| in any other context. However, there may be specialized situations in |
| which it is useful to be able to call this elaboration procedure from |
| Ada code, e.g., if it is necessary to do selective re-elaboration to fix |
| some error. |
| |
| @node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{176} |
| @section Attribute Elab_Subp_Body |
| |
| |
| @geindex Elab_Subp_Body |
| |
| This attribute can only be applied to a library level subprogram |
| name and is only allowed in CodePeer mode. It returns the entity |
| for the corresponding elaboration procedure for elaborating the body |
| of the referenced subprogram unit. This is used in the main generated |
| elaboration procedure by the binder in CodePeer mode only and is unrecognized |
| otherwise. |
| |
| @node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{177} |
| @section Attribute Emax |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Emax |
| |
| The @code{Emax} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{178} |
| @section Attribute Enabled |
| |
| |
| @geindex Enabled |
| |
| The @code{Enabled} attribute allows an application program to check at compile |
| time to see if the designated check is currently enabled. The prefix is a |
| simple identifier, referencing any predefined check name (other than |
| @code{All_Checks}) or a check name introduced by pragma Check_Name. If |
| no argument is given for the attribute, the check is for the general state |
| of the check, if an argument is given, then it is an entity name, and the |
| check indicates whether an @code{Suppress} or @code{Unsuppress} has been |
| given naming the entity (if not, then the argument is ignored). |
| |
| Note that instantiations inherit the check status at the point of the |
| instantiation, so a useful idiom is to have a library package that |
| introduces a check name with @code{pragma Check_Name}, and then contains |
| generic packages or subprograms which use the @code{Enabled} attribute |
| to see if the check is enabled. A user of this package can then issue |
| a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating |
| the package or subprogram, controlling whether the check will be present. |
| |
| @node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{179} |
| @section Attribute Enum_Rep |
| |
| |
| @geindex Representation of enums |
| |
| @geindex Enum_Rep |
| |
| Note that this attribute is now standard in Ada 202x and is available |
| as an implementation defined attribute for earlier Ada versions. |
| |
| For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a |
| function with the following spec: |
| |
| @example |
| function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; |
| @end example |
| |
| It is also allowable to apply @code{Enum_Rep} directly to an object of an |
| enumeration type or to a non-overloaded enumeration |
| literal. In this case @code{S'Enum_Rep} is equivalent to |
| @code{typ'Enum_Rep(S)} where @code{typ} is the type of the |
| enumeration literal or object. |
| |
| The function returns the representation value for the given enumeration |
| value. This will be equal to value of the @code{Pos} attribute in the |
| absence of an enumeration representation clause. This is a static |
| attribute (i.e., the result is static if the argument is static). |
| |
| @code{S'Enum_Rep} can also be used with integer types and objects, |
| in which case it simply returns the integer value. The reason for this |
| is to allow it to be used for @code{(<>)} discrete formal arguments in |
| a generic unit that can be instantiated with either enumeration types |
| or integer types. Note that if @code{Enum_Rep} is used on a modular |
| type whose upper bound exceeds the upper bound of the largest signed |
| integer type, and the argument is a variable, so that the universal |
| integer calculation is done at run time, then the call to @code{Enum_Rep} |
| may raise @code{Constraint_Error}. |
| |
| @node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{17a} |
| @section Attribute Enum_Val |
| |
| |
| @geindex Representation of enums |
| |
| @geindex Enum_Val |
| |
| Note that this attribute is now standard in Ada 202x and is available |
| as an implementation defined attribute for earlier Ada versions. |
| |
| For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a |
| function with the following spec: |
| |
| @example |
| function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; |
| @end example |
| |
| The function returns the enumeration value whose representation matches the |
| argument, or raises Constraint_Error if no enumeration literal of the type |
| has the matching value. |
| This will be equal to value of the @code{Val} attribute in the |
| absence of an enumeration representation clause. This is a static |
| attribute (i.e., the result is static if the argument is static). |
| |
| @node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17b} |
| @section Attribute Epsilon |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Epsilon |
| |
| The @code{Epsilon} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17c} |
| @section Attribute Fast_Math |
| |
| |
| @geindex Fast_Math |
| |
| @code{Standard'Fast_Math} (@code{Standard} is the only allowed |
| prefix) yields a static Boolean value that is True if pragma |
| @code{Fast_Math} is active, and False otherwise. |
| |
| @node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17d} |
| @section Attribute Finalization_Size |
| |
| |
| @geindex Finalization_Size |
| |
| The prefix of attribute @code{Finalization_Size} must be an object or |
| a non-class-wide type. This attribute returns the size of any hidden data |
| reserved by the compiler to handle finalization-related actions. The type of |
| the attribute is @emph{universal_integer}. |
| |
| @code{Finalization_Size} yields a value of zero for a type with no controlled |
| parts, an object whose type has no controlled parts, or an object of a |
| class-wide type whose tag denotes a type with no controlled parts. |
| |
| Note that only heap-allocated objects contain finalization data. |
| |
| @node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17e} |
| @section Attribute Fixed_Value |
| |
| |
| @geindex Fixed_Value |
| |
| For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a |
| function with the following specification: |
| |
| @example |
| function S'Fixed_Value (Arg : <Universal_Integer>) return S; |
| @end example |
| |
| The value returned is the fixed-point value @code{V} such that: |
| |
| @example |
| V = Arg * S'Small |
| @end example |
| |
| The effect is thus similar to first converting the argument to the |
| integer type used to represent @code{S}, and then doing an unchecked |
| conversion to the fixed-point type. The difference is |
| that there are full range checks, to ensure that the result is in range. |
| This attribute is primarily intended for use in implementation of the |
| input-output functions for fixed-point values. |
| |
| @node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17f} |
| @section Attribute From_Any |
| |
| |
| @geindex From_Any |
| |
| This internal attribute is used for the generation of remote subprogram |
| stubs in the context of the Distributed Systems Annex. |
| |
| @node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{180} |
| @section Attribute Has_Access_Values |
| |
| |
| @geindex Access values |
| @geindex testing for |
| |
| @geindex Has_Access_Values |
| |
| The prefix of the @code{Has_Access_Values} attribute is a type. The result |
| is a Boolean value which is True if the is an access type, or is a composite |
| type with a component (at any nesting depth) that is an access type, and is |
| False otherwise. |
| The intended use of this attribute is in conjunction with generic |
| definitions. If the attribute is applied to a generic private type, it |
| indicates whether or not the corresponding actual type has access values. |
| |
| @node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{181} |
| @section Attribute Has_Discriminants |
| |
| |
| @geindex Discriminants |
| @geindex testing for |
| |
| @geindex Has_Discriminants |
| |
| The prefix of the @code{Has_Discriminants} attribute is a type. The result |
| is a Boolean value which is True if the type has discriminants, and False |
| otherwise. The intended use of this attribute is in conjunction with generic |
| definitions. If the attribute is applied to a generic private type, it |
| indicates whether or not the corresponding actual type has discriminants. |
| |
| @node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{182} |
| @section Attribute Has_Tagged_Values |
| |
| |
| @geindex Tagged values |
| @geindex testing for |
| |
| @geindex Has_Tagged_Values |
| |
| The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a |
| Boolean value which is True if the type is a composite type (array or record) |
| that is either a tagged type or has a subcomponent that is tagged, and is False |
| otherwise. The intended use of this attribute is in conjunction with generic |
| definitions. If the attribute is applied to a generic private type, it |
| indicates whether or not the corresponding actual type has access values. |
| |
| @node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{183} |
| @section Attribute Img |
| |
| |
| @geindex Img |
| |
| The @code{Img} attribute differs from @code{Image} in that, while both can be |
| applied directly to an object, @code{Img} cannot be applied to types. |
| |
| Example usage of the attribute: |
| |
| @example |
| Put_Line ("X = " & X'Img); |
| @end example |
| |
| which has the same meaning as the more verbose: |
| |
| @example |
| Put_Line ("X = " & T'Image (X)); |
| @end example |
| |
| where @code{T} is the (sub)type of the object @code{X}. |
| |
| Note that technically, in analogy to @code{Image}, |
| @code{X'Img} returns a parameterless function |
| that returns the appropriate string when called. This means that |
| @code{X'Img} can be renamed as a function-returning-string, or used |
| in an instantiation as a function parameter. |
| |
| @node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{184} |
| @section Attribute Initialized |
| |
| |
| @geindex Initialized |
| |
| For the syntax and semantics of this attribute, see the SPARK 2014 Reference |
| Manual, section 6.10. |
| |
| @node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{185} |
| @section Attribute Integer_Value |
| |
| |
| @geindex Integer_Value |
| |
| For every integer type @code{S}, @code{S'Integer_Value} denotes a |
| function with the following spec: |
| |
| @example |
| function S'Integer_Value (Arg : <Universal_Fixed>) return S; |
| @end example |
| |
| The value returned is the integer value @code{V}, such that: |
| |
| @example |
| Arg = V * T'Small |
| @end example |
| |
| where @code{T} is the type of @code{Arg}. |
| The effect is thus similar to first doing an unchecked conversion from |
| the fixed-point type to its corresponding implementation type, and then |
| converting the result to the target integer type. The difference is |
| that there are full range checks, to ensure that the result is in range. |
| This attribute is primarily intended for use in implementation of the |
| standard input-output functions for fixed-point values. |
| |
| @node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{186} |
| @section Attribute Invalid_Value |
| |
| |
| @geindex Invalid_Value |
| |
| For every scalar type S, S’Invalid_Value returns an undefined value of the |
| type. If possible this value is an invalid representation for the type. The |
| value returned is identical to the value used to initialize an otherwise |
| uninitialized value of the type if pragma Initialize_Scalars is used, |
| including the ability to modify the value with the binder -Sxx flag and |
| relevant environment variables at run time. |
| |
| @node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{187} |
| @section Attribute Iterable |
| |
| |
| @geindex Iterable |
| |
| Equivalent to Aspect Iterable. |
| |
| @node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{188} |
| @section Attribute Large |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Large |
| |
| The @code{Large} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{189} |
| @section Attribute Library_Level |
| |
| |
| @geindex Library_Level |
| |
| @code{P'Library_Level}, where P is an entity name, |
| returns a Boolean value which is True if the entity is declared |
| at the library level, and False otherwise. Note that within a |
| generic instantition, the name of the generic unit denotes the |
| instance, which means that this attribute can be used to test |
| if a generic is instantiated at the library level, as shown |
| in this example: |
| |
| @example |
| generic |
| ... |
| package Gen is |
| pragma Compile_Time_Error |
| (not Gen'Library_Level, |
| "Gen can only be instantiated at library level"); |
| ... |
| end Gen; |
| @end example |
| |
| @node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{18a} |
| @section Attribute Lock_Free |
| |
| |
| @geindex Lock_Free |
| |
| @code{P'Lock_Free}, where P is a protected object, returns True if a |
| pragma @code{Lock_Free} applies to P. |
| |
| @node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18b} |
| @section Attribute Loop_Entry |
| |
| |
| @geindex Loop_Entry |
| |
| Syntax: |
| |
| @example |
| X'Loop_Entry [(loop_name)] |
| @end example |
| |
| The @code{Loop_Entry} attribute is used to refer to the value that an |
| expression had upon entry to a given loop in much the same way that the |
| @code{Old} attribute in a subprogram postcondition can be used to refer |
| to the value an expression had upon entry to the subprogram. The |
| relevant loop is either identified by the given loop name, or it is the |
| innermost enclosing loop when no loop name is given. |
| |
| A @code{Loop_Entry} attribute can only occur within a |
| @code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of |
| @code{Loop_Entry} is to compare the current value of objects with their |
| initial value at loop entry, in a @code{Loop_Invariant} pragma. |
| |
| The effect of using @code{X'Loop_Entry} is the same as declaring |
| a constant initialized with the initial value of @code{X} at loop |
| entry. This copy is not performed if the loop is not entered, or if the |
| corresponding pragmas are ignored or disabled. |
| |
| @node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18c} |
| @section Attribute Machine_Size |
| |
| |
| @geindex Machine_Size |
| |
| This attribute is identical to the @code{Object_Size} attribute. It is |
| provided for compatibility with the DEC Ada 83 attribute of this name. |
| |
| @node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18d} |
| @section Attribute Mantissa |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Mantissa |
| |
| The @code{Mantissa} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18e}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18f} |
| @section Attribute Maximum_Alignment |
| |
| |
| @geindex Alignment |
| @geindex maximum |
| |
| @geindex Maximum_Alignment |
| |
| @code{Standard'Maximum_Alignment} (@code{Standard} is the only |
| allowed prefix) provides the maximum useful alignment value for the |
| target. This is a static value that can be used to specify the alignment |
| for an object, guaranteeing that it is properly aligned in all |
| cases. |
| |
| @node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{190} |
| @section Attribute Max_Integer_Size |
| |
| |
| @geindex Max_Integer_Size |
| |
| @code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed |
| prefix) provides the size of the largest supported integer type for |
| the target. The result is a static constant. |
| |
| @node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{191} |
| @section Attribute Mechanism_Code |
| |
| |
| @geindex Return values |
| @geindex passing mechanism |
| |
| @geindex Parameters |
| @geindex passing mechanism |
| |
| @geindex Mechanism_Code |
| |
| @code{func'Mechanism_Code} yields an integer code for the |
| mechanism used for the result of function @code{func}, and |
| @code{subprog'Mechanism_Code (n)} yields the mechanism |
| used for formal parameter number @emph{n} (a static integer value, with 1 |
| meaning the first parameter) of subprogram @code{subprog}. The code returned is: |
| |
| |
| @table @asis |
| |
| @item @emph{1} |
| |
| by copy (value) |
| |
| @item @emph{2} |
| |
| by reference |
| @end table |
| |
| @node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{192} |
| @section Attribute Null_Parameter |
| |
| |
| @geindex Zero address |
| @geindex passing |
| |
| @geindex Null_Parameter |
| |
| A reference @code{T'Null_Parameter} denotes an imaginary object of |
| type or subtype @code{T} allocated at machine address zero. The attribute |
| is allowed only as the default expression of a formal parameter, or as |
| an actual expression of a subprogram call. In either case, the |
| subprogram must be imported. |
| |
| The identity of the object is represented by the address zero in the |
| argument list, independent of the passing mechanism (explicit or |
| default). |
| |
| This capability is needed to specify that a zero address should be |
| passed for a record or other composite object passed by reference. |
| There is no way of indicating this without the @code{Null_Parameter} |
| attribute. |
| |
| @node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{142}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{193} |
| @section Attribute Object_Size |
| |
| |
| @geindex Size |
| @geindex used for objects |
| |
| @geindex Object_Size |
| |
| The size of an object is not necessarily the same as the size of the type |
| of an object. This is because by default object sizes are increased to be |
| a multiple of the alignment of the object. For example, |
| @code{Natural'Size} is |
| 31, but by default objects of type @code{Natural} will have a size of 32 bits. |
| Similarly, a record containing an integer and a character: |
| |
| @example |
| type Rec is record |
| I : Integer; |
| C : Character; |
| end record; |
| @end example |
| |
| will have a size of 40 (that is @code{Rec'Size} will be 40). The |
| alignment will be 4, because of the |
| integer field, and so the default size of record objects for this type |
| will be 64 (8 bytes). |
| |
| If the alignment of the above record is specified to be 1, then the |
| object size will be 40 (5 bytes). This is true by default, and also |
| an object size of 40 can be explicitly specified in this case. |
| |
| A consequence of this capability is that different object sizes can be |
| given to subtypes that would otherwise be considered in Ada to be |
| statically matching. But it makes no sense to consider such subtypes |
| as statically matching. Consequently, GNAT adds a rule |
| to the static matching rules that requires object sizes to match. |
| Consider this example: |
| |
| @example |
| 1. procedure BadAVConvert is |
| 2. type R is new Integer; |
| 3. subtype R1 is R range 1 .. 10; |
| 4. subtype R2 is R range 1 .. 10; |
| 5. for R1'Object_Size use 8; |
| 6. for R2'Object_Size use 16; |
| 7. type R1P is access all R1; |
| 8. type R2P is access all R2; |
| 9. R1PV : R1P := new R1'(4); |
| 10. R2PV : R2P; |
| 11. begin |
| 12. R2PV := R2P (R1PV); |
| | |
| >>> target designated subtype not compatible with |
| type "R1" defined at line 3 |
| |
| 13. end; |
| @end example |
| |
| In the absence of lines 5 and 6, |
| types @code{R1} and @code{R2} statically match and |
| hence the conversion on line 12 is legal. But since lines 5 and 6 |
| cause the object sizes to differ, GNAT considers that types |
| @code{R1} and @code{R2} are not statically matching, and line 12 |
| generates the diagnostic shown above. |
| |
| Similar additional checks are performed in other contexts requiring |
| statically matching subtypes. |
| |
| @node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{194} |
| @section Attribute Old |
| |
| |
| @geindex Old |
| |
| In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage |
| within @code{Post} aspect), GNAT also permits the use of this attribute |
| in implementation defined pragmas @code{Postcondition}, |
| @code{Contract_Cases} and @code{Test_Case}. Also usages of |
| @code{Old} which would be illegal according to the Ada 2012 RM |
| definition are allowed under control of |
| implementation defined pragma @code{Unevaluated_Use_Of_Old}. |
| |
| @node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{195} |
| @section Attribute Passed_By_Reference |
| |
| |
| @geindex Parameters |
| @geindex when passed by reference |
| |
| @geindex Passed_By_Reference |
| |
| @code{typ'Passed_By_Reference} for any subtype @cite{typ} returns |
| a value of type @code{Boolean} value that is @code{True} if the type is |
| normally passed by reference and @code{False} if the type is normally |
| passed by copy in calls. For scalar types, the result is always @code{False} |
| and is static. For non-scalar types, the result is nonstatic. |
| |
| @node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{196} |
| @section Attribute Pool_Address |
| |
| |
| @geindex Pool_Address |
| |
| @code{X'Pool_Address} for any object @code{X} returns the address |
| of X within its storage pool. This is the same as |
| @code{X'Address}, except that for an unconstrained array whose |
| bounds are allocated just before the first component, |
| @code{X'Pool_Address} returns the address of those bounds, |
| whereas @code{X'Address} returns the address of the first |
| component. |
| |
| Here, we are interpreting ‘storage pool’ broadly to mean |
| @code{wherever the object is allocated}, which could be a |
| user-defined storage pool, |
| the global heap, on the stack, or in a static memory area. |
| For an object created by @code{new}, @code{Ptr.all'Pool_Address} is |
| what is passed to @code{Allocate} and returned from @code{Deallocate}. |
| |
| @node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{197} |
| @section Attribute Range_Length |
| |
| |
| @geindex Range_Length |
| |
| @code{typ'Range_Length} for any discrete type @cite{typ} yields |
| the number of values represented by the subtype (zero for a null |
| range). The result is static for static subtypes. @code{Range_Length} |
| applied to the index subtype of a one dimensional array always gives the |
| same result as @code{Length} applied to the array itself. |
| |
| @node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{198} |
| @section Attribute Restriction_Set |
| |
| |
| @geindex Restriction_Set |
| |
| @geindex Restrictions |
| |
| This attribute allows compile time testing of restrictions that |
| are currently in effect. It is primarily intended for specializing |
| code in the run-time based on restrictions that are active (e.g. |
| don’t need to save fpt registers if restriction No_Floating_Point |
| is known to be in effect), but can be used anywhere. |
| |
| There are two forms: |
| |
| @example |
| System'Restriction_Set (partition_boolean_restriction_NAME) |
| System'Restriction_Set (No_Dependence => library_unit_NAME); |
| @end example |
| |
| In the case of the first form, the only restriction names |
| allowed are parameterless restrictions that are checked |
| for consistency at bind time. For a complete list see the |
| subtype @code{System.Rident.Partition_Boolean_Restrictions}. |
| |
| The result returned is True if the restriction is known to |
| be in effect, and False if the restriction is known not to |
| be in effect. An important guarantee is that the value of |
| a Restriction_Set attribute is known to be consistent throughout |
| all the code of a partition. |
| |
| This is trivially achieved if the entire partition is compiled |
| with a consistent set of restriction pragmas. However, the |
| compilation model does not require this. It is possible to |
| compile one set of units with one set of pragmas, and another |
| set of units with another set of pragmas. It is even possible |
| to compile a spec with one set of pragmas, and then WITH the |
| same spec with a different set of pragmas. Inconsistencies |
| in the actual use of the restriction are checked at bind time. |
| |
| In order to achieve the guarantee of consistency for the |
| Restriction_Set pragma, we consider that a use of the pragma |
| that yields False is equivalent to a violation of the |
| restriction. |
| |
| So for example if you write |
| |
| @example |
| if System'Restriction_Set (No_Floating_Point) then |
| ... |
| else |
| ... |
| end if; |
| @end example |
| |
| And the result is False, so that the else branch is executed, |
| you can assume that this restriction is not set for any unit |
| in the partition. This is checked by considering this use of |
| the restriction pragma to be a violation of the restriction |
| No_Floating_Point. This means that no other unit can attempt |
| to set this restriction (if some unit does attempt to set it, |
| the binder will refuse to bind the partition). |
| |
| Technical note: The restriction name and the unit name are |
| intepreted entirely syntactically, as in the corresponding |
| Restrictions pragma, they are not analyzed semantically, |
| so they do not have a type. |
| |
| @node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{199} |
| @section Attribute Result |
| |
| |
| @geindex Result |
| |
| @code{function'Result} can only be used with in a Postcondition pragma |
| for a function. The prefix must be the name of the corresponding function. This |
| is used to refer to the result of the function in the postcondition expression. |
| For a further discussion of the use of this attribute and examples of its use, |
| see the description of pragma Postcondition. |
| |
| @node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19a} |
| @section Attribute Safe_Emax |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Safe_Emax |
| |
| The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{19b} |
| @section Attribute Safe_Large |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Safe_Large |
| |
| The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19c} |
| @section Attribute Safe_Small |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Safe_Small |
| |
| The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{150}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19d} |
| @section Attribute Scalar_Storage_Order |
| |
| |
| @geindex Endianness |
| |
| @geindex Scalar storage order |
| |
| @geindex Scalar_Storage_Order |
| |
| For every array or record type @code{S}, the representation attribute |
| @code{Scalar_Storage_Order} denotes the order in which storage elements |
| that make up scalar components are ordered within S. The value given must |
| be a static expression of type System.Bit_Order. The following is an example |
| of the use of this feature: |
| |
| @example |
| -- Component type definitions |
| |
| subtype Yr_Type is Natural range 0 .. 127; |
| subtype Mo_Type is Natural range 1 .. 12; |
| subtype Da_Type is Natural range 1 .. 31; |
| |
| -- Record declaration |
| |
| type Date is record |
| Years_Since_1980 : Yr_Type; |
| Month : Mo_Type; |
| Day_Of_Month : Da_Type; |
| end record; |
| |
| -- Record representation clause |
| |
| for Date use record |
| Years_Since_1980 at 0 range 0 .. 6; |
| Month at 0 range 7 .. 10; |
| Day_Of_Month at 0 range 11 .. 15; |
| end record; |
| |
| -- Attribute definition clauses |
| |
| for Date'Bit_Order use System.High_Order_First; |
| for Date'Scalar_Storage_Order use System.High_Order_First; |
| -- If Scalar_Storage_Order is specified, it must be consistent with |
| -- Bit_Order, so it's best to always define the latter explicitly if |
| -- the former is used. |
| @end example |
| |
| Other properties are as for the standard representation attribute @code{Bit_Order} |
| defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. |
| |
| For a record type @code{T}, if @code{T'Scalar_Storage_Order} is |
| specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: |
| this means that if a @code{Scalar_Storage_Order} attribute definition |
| clause is not confirming, then the type’s @code{Bit_Order} shall be |
| specified explicitly and set to the same value. |
| |
| Derived types inherit an explicitly set scalar storage order from their parent |
| types. This may be overridden for the derived type by giving an explicit scalar |
| storage order for it. However, for a record extension, the derived type must |
| have the same scalar storage order as the parent type. |
| |
| A component of a record type that is itself a record or an array and that does |
| not start and end on a byte boundary must have have the same scalar storage |
| order as the record type. A component of a bit-packed array type that is itself |
| a record or an array must have the same scalar storage order as the array type. |
| |
| No component of a type that has an explicit @code{Scalar_Storage_Order} |
| attribute definition may be aliased. |
| |
| A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. |
| with a value equal to @code{System.Default_Bit_Order}) has no effect. |
| |
| If the opposite storage order is specified, then whenever the value of |
| a scalar component of an object of type @code{S} is read, the storage |
| elements of the enclosing machine scalar are first reversed (before |
| retrieving the component value, possibly applying some shift and mask |
| operatings on the enclosing machine scalar), and the opposite operation |
| is done for writes. |
| |
| In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components |
| are relaxed. Instead, the following rules apply: |
| |
| |
| @itemize * |
| |
| @item |
| the underlying storage elements are those at positions |
| @code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} |
| |
| @item |
| the sequence of underlying storage elements shall have |
| a size no greater than the largest machine scalar |
| |
| @item |
| the enclosing machine scalar is defined as the smallest machine |
| scalar starting at a position no greater than |
| @code{position + first_bit / storage_element_size} and covering |
| storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`} |
| |
| @item |
| the position of the component is interpreted relative to that machine |
| scalar. |
| @end itemize |
| |
| If no scalar storage order is specified for a type (either directly, or by |
| inheritance in the case of a derived type), then the default is normally |
| the native ordering of the target, but this default can be overridden using |
| pragma @code{Default_Scalar_Storage_Order}. |
| |
| If a component of @code{T} is itself of a record or array type, the specfied |
| @code{Scalar_Storage_Order} does @emph{not} apply to that nested type: an explicit |
| attribute definition clause must be provided for the component type as well |
| if desired. |
| |
| Representation changes that explicitly or implicitly toggle the scalar storage |
| order are not supported and may result in erroneous execution of the program, |
| except when performed by means of an instance of @code{Ada.Unchecked_Conversion}. |
| |
| In particular, overlays are not supported and a warning is given for them: |
| |
| @example |
| type Rec_LE is record |
| I : Integer; |
| end record; |
| |
| for Rec_LE use record |
| I at 0 range 0 .. 31; |
| end record; |
| |
| for Rec_LE'Bit_Order use System.Low_Order_First; |
| for Rec_LE'Scalar_Storage_Order use System.Low_Order_First; |
| |
| type Rec_BE is record |
| I : Integer; |
| end record; |
| |
| for Rec_BE use record |
| I at 0 range 0 .. 31; |
| end record; |
| |
| for Rec_BE'Bit_Order use System.High_Order_First; |
| for Rec_BE'Scalar_Storage_Order use System.High_Order_First; |
| |
| R_LE : Rec_LE; |
| |
| R_BE : Rec_BE; |
| for R_BE'Address use R_LE'Address; |
| @end example |
| |
| @code{warning: overlay changes scalar storage order [enabled by default]} |
| |
| In most cases, such representation changes ought to be replaced by an |
| instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}. |
| |
| Note that the scalar storage order only affects the in-memory data |
| representation. It has no effect on the representation used by stream |
| attributes. |
| |
| Note that debuggers may be unable to display the correct value of scalar |
| components of a type for which the opposite storage order is specified. |
| |
| @node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e5}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{19e} |
| @section Attribute Simple_Storage_Pool |
| |
| |
| @geindex Storage pool |
| @geindex simple |
| |
| @geindex Simple storage pool |
| |
| @geindex Simple_Storage_Pool |
| |
| For every nonformal, nonderived access-to-object type @code{Acc}, the |
| representation attribute @code{Simple_Storage_Pool} may be specified |
| via an attribute_definition_clause (or by specifying the equivalent aspect): |
| |
| @example |
| My_Pool : My_Simple_Storage_Pool_Type; |
| |
| type Acc is access My_Data_Type; |
| |
| for Acc'Simple_Storage_Pool use My_Pool; |
| @end example |
| |
| The name given in an attribute_definition_clause for the |
| @code{Simple_Storage_Pool} attribute shall denote a variable of |
| a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}). |
| |
| The use of this attribute is only allowed for a prefix denoting a type |
| for which it has been specified. The type of the attribute is the type |
| of the variable specified as the simple storage pool of the access type, |
| and the attribute denotes that variable. |
| |
| It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} |
| for the same access type. |
| |
| If the @code{Simple_Storage_Pool} attribute has been specified for an access |
| type, then applying the @code{Storage_Pool} attribute to the type is flagged |
| with a warning and its evaluation raises the exception @code{Program_Error}. |
| |
| If the Simple_Storage_Pool attribute has been specified for an access |
| type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} |
| returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, |
| which is intended to indicate the number of storage elements reserved for |
| the simple storage pool. If the Storage_Size function has not been defined |
| for the simple storage pool type, then this attribute returns zero. |
| |
| If an access type @code{S} has a specified simple storage pool of type |
| @code{SSP}, then the evaluation of an allocator for that access type calls |
| the primitive @code{Allocate} procedure for type @code{SSP}, passing |
| @code{S'Simple_Storage_Pool} as the pool parameter. The detailed |
| semantics of such allocators is the same as those defined for allocators |
| in section 13.11 of the @cite{Ada Reference Manual}, with the term |
| @emph{simple storage pool} substituted for @emph{storage pool}. |
| |
| If an access type @code{S} has a specified simple storage pool of type |
| @code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} |
| for that access type invokes the primitive @code{Deallocate} procedure |
| for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool |
| parameter. The detailed semantics of such unchecked deallocations is the same |
| as defined in section 13.11.2 of the Ada Reference Manual, except that the |
| term @emph{simple storage pool} is substituted for @emph{storage pool}. |
| |
| @node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{19f} |
| @section Attribute Small |
| |
| |
| @geindex Ada 83 attributes |
| |
| @geindex Small |
| |
| The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for |
| fixed-point types. |
| GNAT also allows this attribute to be applied to floating-point types |
| for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute when applied to floating-point types. |
| |
| @node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{1a0} |
| @section Attribute Small_Denominator |
| |
| |
| @geindex Small |
| |
| @geindex Small_Denominator |
| |
| @code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the |
| denominator in the representation of @code{typ'Small} as a rational number |
| with coprime factors (i.e. as an irreducible fraction). |
| |
| @node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{1a1} |
| @section Attribute Small_Numerator |
| |
| |
| @geindex Small |
| |
| @geindex Small_Numerator |
| |
| @code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the |
| numerator in the representation of @code{typ'Small} as a rational number |
| with coprime factors (i.e. as an irreducible fraction). |
| |
| @node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a2} |
| @section Attribute Storage_Unit |
| |
| |
| @geindex Storage_Unit |
| |
| @code{Standard'Storage_Unit} (@code{Standard} is the only allowed |
| prefix) provides the same value as @code{System.Storage_Unit}. |
| |
| @node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a3} |
| @section Attribute Stub_Type |
| |
| |
| @geindex Stub_Type |
| |
| The GNAT implementation of remote access-to-classwide types is |
| organized as described in AARM section E.4 (20.t): a value of an RACW type |
| (designating a remote object) is represented as a normal access |
| value, pointing to a “stub” object which in turn contains the |
| necessary information to contact the designated remote object. A |
| call on any dispatching operation of such a stub object does the |
| remote call, if necessary, using the information in the stub object |
| to locate the target partition, etc. |
| |
| For a prefix @code{T} that denotes a remote access-to-classwide type, |
| @code{T'Stub_Type} denotes the type of the corresponding stub objects. |
| |
| By construction, the layout of @code{T'Stub_Type} is identical to that of |
| type @code{RACW_Stub_Type} declared in the internal implementation-defined |
| unit @code{System.Partition_Interface}. Use of this attribute will create |
| an implicit dependency on this unit. |
| |
| @node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a4} |
| @section Attribute System_Allocator_Alignment |
| |
| |
| @geindex Alignment |
| @geindex allocator |
| |
| @geindex System_Allocator_Alignment |
| |
| @code{Standard'System_Allocator_Alignment} (@code{Standard} is the only |
| allowed prefix) provides the observable guaranted to be honored by |
| the system allocator (malloc). This is a static value that can be used |
| in user storage pools based on malloc either to reject allocation |
| with alignment too large or to enable a realignment circuitry if the |
| alignment request is larger than this value. |
| |
| @node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a5} |
| @section Attribute Target_Name |
| |
| |
| @geindex Target_Name |
| |
| @code{Standard'Target_Name} (@code{Standard} is the only allowed |
| prefix) provides a static string value that identifies the target |
| for the current compilation. For GCC implementations, this is the |
| standard gcc target name without the terminating slash (for |
| example, GNAT 5.0 on windows yields “i586-pc-mingw32msv”). |
| |
| @node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a6} |
| @section Attribute To_Address |
| |
| |
| @geindex To_Address |
| |
| The @code{System'To_Address} |
| (@code{System} is the only allowed prefix) |
| denotes a function identical to |
| @code{System.Storage_Elements.To_Address} except that |
| it is a static attribute. This means that if its argument is |
| a static expression, then the result of the attribute is a |
| static expression. This means that such an expression can be |
| used in contexts (e.g., preelaborable packages) which require a |
| static expression and where the function call could not be used |
| (since the function call is always nonstatic, even if its |
| argument is static). The argument must be in the range |
| -(2**(m-1)) .. 2**m-1, where m is the memory size |
| (typically 32 or 64). Negative values are intepreted in a |
| modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on |
| a 32 bits machine). |
| |
| @node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a7} |
| @section Attribute To_Any |
| |
| |
| @geindex To_Any |
| |
| This internal attribute is used for the generation of remote subprogram |
| stubs in the context of the Distributed Systems Annex. |
| |
| @node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a8} |
| @section Attribute Type_Class |
| |
| |
| @geindex Type_Class |
| |
| @code{typ'Type_Class} for any type or subtype @cite{typ} yields |
| the value of the type class for the full type of @cite{typ}. If |
| @cite{typ} is a generic formal type, the value is the value for the |
| corresponding actual subtype. The value of this attribute is of type |
| @code{System.Aux_DEC.Type_Class}, which has the following definition: |
| |
| @example |
| type Type_Class is |
| (Type_Class_Enumeration, |
| Type_Class_Integer, |
| Type_Class_Fixed_Point, |
| Type_Class_Floating_Point, |
| Type_Class_Array, |
| Type_Class_Record, |
| Type_Class_Access, |
| Type_Class_Task, |
| Type_Class_Address); |
| @end example |
| |
| Protected types yield the value @code{Type_Class_Task}, which thus |
| applies to all concurrent types. This attribute is designed to |
| be compatible with the DEC Ada 83 attribute of the same name. |
| |
| @node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a9} |
| @section Attribute Type_Key |
| |
| |
| @geindex Type_Key |
| |
| The @code{Type_Key} attribute is applicable to a type or subtype and |
| yields a value of type Standard.String containing encoded information |
| about the type or subtype. This provides improved compatibility with |
| other implementations that support this attribute. |
| |
| @node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1aa} |
| @section Attribute TypeCode |
| |
| |
| @geindex TypeCode |
| |
| This internal attribute is used for the generation of remote subprogram |
| stubs in the context of the Distributed Systems Annex. |
| |
| @node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1ab} |
| @section Attribute Unconstrained_Array |
| |
| |
| @geindex Unconstrained_Array |
| |
| The @code{Unconstrained_Array} attribute can be used with a prefix that |
| denotes any type or subtype. It is a static attribute that yields |
| @code{True} if the prefix designates an unconstrained array, |
| and @code{False} otherwise. In a generic instance, the result is |
| still static, and yields the result of applying this test to the |
| generic actual. |
| |
| @node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1ac} |
| @section Attribute Universal_Literal_String |
| |
| |
| @geindex Named numbers |
| @geindex representation of |
| |
| @geindex Universal_Literal_String |
| |
| The prefix of @code{Universal_Literal_String} must be a named |
| number. The static result is the string consisting of the characters of |
| the number as defined in the original source. This allows the user |
| program to access the actual text of named numbers without intermediate |
| conversions and without the need to enclose the strings in quotes (which |
| would preclude their use as numbers). |
| |
| For example, the following program prints the first 50 digits of pi: |
| |
| @example |
| with Text_IO; use Text_IO; |
| with Ada.Numerics; |
| procedure Pi is |
| begin |
| Put (Ada.Numerics.Pi'Universal_Literal_String); |
| end; |
| @end example |
| |
| @node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1ad} |
| @section Attribute Unrestricted_Access |
| |
| |
| @geindex Access |
| @geindex unrestricted |
| |
| @geindex Unrestricted_Access |
| |
| The @code{Unrestricted_Access} attribute is similar to @code{Access} |
| except that all accessibility and aliased view checks are omitted. This |
| is a user-beware attribute. |
| |
| For objects, it is similar to @code{Address}, for which it is a |
| desirable replacement where the value desired is an access type. |
| In other words, its effect is similar to first applying the |
| @code{Address} attribute and then doing an unchecked conversion to a |
| desired access type. |
| |
| For subprograms, @code{P'Unrestricted_Access} may be used where |
| @code{P'Access} would be illegal, to construct a value of a |
| less-nested named access type that designates a more-nested |
| subprogram. This value may be used in indirect calls, so long as the |
| more-nested subprogram still exists; once the subprogram containing it |
| has returned, such calls are erroneous. For example: |
| |
| @example |
| package body P is |
| |
| type Less_Nested is not null access procedure; |
| Global : Less_Nested; |
| |
| procedure P1 is |
| begin |
| Global.all; |
| end P1; |
| |
| procedure P2 is |
| Local_Var : Integer; |
| |
| procedure More_Nested is |
| begin |
| ... Local_Var ... |
| end More_Nested; |
| begin |
| Global := More_Nested'Unrestricted_Access; |
| P1; |
| end P2; |
| |
| end P; |
| @end example |
| |
| When P1 is called from P2, the call via Global is OK, but if P1 were |
| called after P2 returns, it would be an erroneous use of a dangling |
| pointer. |
| |
| For objects, it is possible to use @code{Unrestricted_Access} for any |
| type. However, if the result is of an access-to-unconstrained array |
| subtype, then the resulting pointer has the same scope as the context |
| of the attribute, and must not be returned to some enclosing scope. |
| For instance, if a function uses @code{Unrestricted_Access} to create |
| an access-to-unconstrained-array and returns that value to the caller, |
| the result will involve dangling pointers. In addition, it is only |
| valid to create pointers to unconstrained arrays using this attribute |
| if the pointer has the normal default ‘fat’ representation where a |
| pointer has two components, one points to the array and one points to |
| the bounds. If a size clause is used to force ‘thin’ representation |
| for a pointer to unconstrained where there is only space for a single |
| pointer, then the resulting pointer is not usable. |
| |
| In the simple case where a direct use of Unrestricted_Access attempts |
| to make a thin pointer for a non-aliased object, the compiler will |
| reject the use as illegal, as shown in the following example: |
| |
| @example |
| with System; use System; |
| procedure SliceUA2 is |
| type A is access all String; |
| for A'Size use Standard'Address_Size; |
| |
| procedure P (Arg : A) is |
| begin |
| null; |
| end P; |
| |
| X : String := "hello world!"; |
| X2 : aliased String := "hello world!"; |
| |
| AV : A := X'Unrestricted_Access; -- ERROR |
| | |
| >>> illegal use of Unrestricted_Access attribute |
| >>> attempt to generate thin pointer to unaliased object |
| |
| begin |
| P (X'Unrestricted_Access); -- ERROR |
| | |
| >>> illegal use of Unrestricted_Access attribute |
| >>> attempt to generate thin pointer to unaliased object |
| |
| P (X(7 .. 12)'Unrestricted_Access); -- ERROR |
| | |
| >>> illegal use of Unrestricted_Access attribute |
| >>> attempt to generate thin pointer to unaliased object |
| |
| P (X2'Unrestricted_Access); -- OK |
| end; |
| @end example |
| |
| but other cases cannot be detected by the compiler, and are |
| considered to be erroneous. Consider the following example: |
| |
| @example |
| with System; use System; |
| with System; use System; |
| procedure SliceUA is |
| type AF is access all String; |
| |
| type A is access all String; |
| for A'Size use Standard'Address_Size; |
| |
| procedure P (Arg : A) is |
| begin |
| if Arg'Length /= 6 then |
| raise Program_Error; |
| end if; |
| end P; |
| |
| X : String := "hello world!"; |
| Y : AF := X (7 .. 12)'Unrestricted_Access; |
| |
| begin |
| P (A (Y)); |
| end; |
| @end example |
| |
| A normal unconstrained array value |
| or a constrained array object marked as aliased has the bounds in memory |
| just before the array, so a thin pointer can retrieve both the data and |
| the bounds. But in this case, the non-aliased object @code{X} does not have the |
| bounds before the string. If the size clause for type @code{A} |
| were not present, then the pointer |
| would be a fat pointer, where one component is a pointer to the bounds, |
| and all would be well. But with the size clause present, the conversion from |
| fat pointer to thin pointer in the call loses the bounds, and so this |
| is erroneous, and the program likely raises a @code{Program_Error} exception. |
| |
| In general, it is advisable to completely |
| avoid mixing the use of thin pointers and the use of |
| @code{Unrestricted_Access} where the designated type is an |
| unconstrained array. The use of thin pointers should be restricted to |
| cases of porting legacy code that implicitly assumes the size of pointers, |
| and such code should not in any case be using this attribute. |
| |
| Another erroneous situation arises if the attribute is |
| applied to a constant. The resulting pointer can be used to access the |
| constant, but the effect of trying to modify a constant in this manner |
| is not well-defined. Consider this example: |
| |
| @example |
| P : constant Integer := 4; |
| type R is access all Integer; |
| RV : R := P'Unrestricted_Access; |
| .. |
| RV.all := 3; |
| @end example |
| |
| Here we attempt to modify the constant P from 4 to 3, but the compiler may |
| or may not notice this attempt, and subsequent references to P may yield |
| either the value 3 or the value 4 or the assignment may blow up if the |
| compiler decides to put P in read-only memory. One particular case where |
| @code{Unrestricted_Access} can be used in this way is to modify the |
| value of an @code{in} parameter: |
| |
| @example |
| procedure K (S : in String) is |
| type R is access all Character; |
| RV : R := S (3)'Unrestricted_Access; |
| begin |
| RV.all := 'a'; |
| end; |
| @end example |
| |
| In general this is a risky approach. It may appear to “work” but such uses of |
| @code{Unrestricted_Access} are potentially non-portable, even from one version |
| of GNAT to another, so are best avoided if possible. |
| |
| @node Attribute Update,Attribute Valid_Image,Attribute Unrestricted_Access,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1ae} |
| @section Attribute Update |
| |
| |
| @geindex Update |
| |
| The @code{Update} attribute creates a copy of an array or record value |
| with one or more modified components. The syntax is: |
| |
| @example |
| PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) |
| PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) |
| PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION |
| @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) |
| |
| MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION |
| INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} |
| INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) |
| @end example |
| |
| where @code{PREFIX} is the name of an array or record object, the |
| association list in parentheses does not contain an @code{others} |
| choice and the box symbol @code{<>} may not appear in any |
| expression. The effect is to yield a copy of the array or record value |
| which is unchanged apart from the components mentioned in the |
| association list, which are changed to the indicated value. The |
| original value of the array or record value is not affected. For |
| example: |
| |
| @example |
| type Arr is Array (1 .. 5) of Integer; |
| ... |
| Avar1 : Arr := (1,2,3,4,5); |
| Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); |
| @end example |
| |
| yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} |
| begin unmodified. Similarly: |
| |
| @example |
| type Rec is A, B, C : Integer; |
| ... |
| Rvar1 : Rec := (A => 1, B => 2, C => 3); |
| Rvar2 : Rec := Rvar1'Update (B => 20); |
| @end example |
| |
| yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), |
| with @code{Rvar1} being unmodifed. |
| Note that the value of the attribute reference is computed |
| completely before it is used. This means that if you write: |
| |
| @example |
| Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); |
| @end example |
| |
| then the value of @code{Avar1} is not modified if @code{Function_Call} |
| raises an exception, unlike the effect of a series of direct assignments |
| to elements of @code{Avar1}. In general this requires that |
| two extra complete copies of the object are required, which should be |
| kept in mind when considering efficiency. |
| |
| The @code{Update} attribute cannot be applied to prefixes of a limited |
| type, and cannot reference discriminants in the case of a record type. |
| The accessibility level of an Update attribute result object is defined |
| as for an aggregate. |
| |
| In the record case, no component can be mentioned more than once. In |
| the array case, two overlapping ranges can appear in the association list, |
| in which case the modifications are processed left to right. |
| |
| Multi-dimensional arrays can be modified, as shown by this example: |
| |
| @example |
| A : array (1 .. 10, 1 .. 10) of Integer; |
| .. |
| A := A'Update ((1, 2) => 20, (3, 4) => 30); |
| @end example |
| |
| which changes element (1,2) to 20 and (3,4) to 30. |
| |
| @node Attribute Valid_Image,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-valid-image}@anchor{1af} |
| @section Attribute Valid_Image |
| |
| |
| @geindex Valid_Image |
| |
| The @code{'Valid_Image} attribute is defined for enumeration types other than |
| those in package Standard. This attribute is a function that takes |
| a String, and returns Boolean. @code{T'Valid_Image (S)} returns True |
| if and only if @code{T'Value (S)} would not raise Constraint_Error. |
| |
| @node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Image,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b0} |
| @section Attribute Valid_Scalars |
| |
| |
| @geindex Valid_Scalars |
| |
| The @code{'Valid_Scalars} attribute is intended to make it easier to check the |
| validity of scalar subcomponents of composite objects. The attribute is defined |
| for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type |
| except for tagged private or @code{Unchecked_Union} types. The value of the |
| attribute is of type @code{Boolean}. |
| |
| @code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of |
| @code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if |
| @code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent |
| to attribute @code{'Valid} for scalar types. |
| |
| It is not specified in what order the subcomponents are checked, nor whether |
| any more are checked after any one of them is determined to be invalid. If the |
| prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated |
| specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then |
| only the subcomponents of @code{T} are checked; in other words, components of |
| extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. |
| |
| The compiler will issue a warning if it can be determined at compile time that |
| the prefix of the attribute has no scalar subcomponents. |
| |
| Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of |
| a large variant record. If the attribute is called in many places in the same |
| program applied to objects of the same type, it can reduce program size to |
| write a function with a single use of the attribute, and then call that |
| function from multiple places. |
| |
| @node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b1} |
| @section Attribute VADS_Size |
| |
| |
| @geindex Size |
| @geindex VADS compatibility |
| |
| @geindex VADS_Size |
| |
| The @code{'VADS_Size} attribute is intended to make it easier to port |
| legacy code which relies on the semantics of @code{'Size} as implemented |
| by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the |
| same semantic interpretation. In particular, @code{'VADS_Size} applied |
| to a predefined or other primitive type with no Size clause yields the |
| Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on |
| typical machines). In addition @code{'VADS_Size} applied to an object |
| gives the result that would be obtained by applying the attribute to |
| the corresponding type. |
| |
| @node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15e}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b2} |
| @section Attribute Value_Size |
| |
| |
| @geindex Size |
| @geindex setting for not-first subtype |
| |
| @geindex Value_Size |
| |
| @code{type'Value_Size} is the number of bits required to represent |
| a value of the given subtype. It is the same as @code{type'Size}, |
| but, unlike @code{Size}, may be set for non-first subtypes. |
| |
| @node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b3} |
| @section Attribute Wchar_T_Size |
| |
| |
| @geindex Wchar_T_Size |
| |
| @code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed |
| prefix) provides the size in bits of the C @code{wchar_t} type |
| primarily for constructing the definition of this type in |
| package @code{Interfaces.C}. The result is a static constant. |
| |
| @node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes |
| @anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b4} |
| @section Attribute Word_Size |
| |
| |
| @geindex Word_Size |
| |
| @code{Standard'Word_Size} (@code{Standard} is the only allowed |
| prefix) provides the value @code{System.Word_Size}. The result is |
| a static constant. |
| |
| @node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1b5}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b6}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9} |
| @chapter Standard and Implementation Defined Restrictions |
| |
| |
| All Ada Reference Manual-defined Restriction identifiers are implemented: |
| |
| |
| @itemize * |
| |
| @item |
| language-defined restrictions (see 13.12.1) |
| |
| @item |
| tasking restrictions (see D.7) |
| |
| @item |
| high integrity restrictions (see H.4) |
| @end itemize |
| |
| GNAT implements additional restriction identifiers. All restrictions, whether |
| language defined or GNAT-specific, are listed in the following. |
| |
| @menu |
| * Partition-Wide Restrictions:: |
| * Program Unit Level Restrictions:: |
| |
| @end menu |
| |
| @node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b7}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b8} |
| @section Partition-Wide Restrictions |
| |
| |
| There are two separate lists of restriction identifiers. The first |
| set requires consistency throughout a partition (in other words, if the |
| restriction identifier is used for any compilation unit in the partition, |
| then all compilation units in the partition must obey the restriction). |
| |
| @menu |
| * Immediate_Reclamation:: |
| * Max_Asynchronous_Select_Nesting:: |
| * Max_Entry_Queue_Length:: |
| * Max_Protected_Entries:: |
| * Max_Select_Alternatives:: |
| * Max_Storage_At_Blocking:: |
| * Max_Task_Entries:: |
| * Max_Tasks:: |
| * No_Abort_Statements:: |
| * No_Access_Parameter_Allocators:: |
| * No_Access_Subprograms:: |
| * No_Allocators:: |
| * No_Anonymous_Allocators:: |
| * No_Asynchronous_Control:: |
| * No_Calendar:: |
| * No_Coextensions:: |
| * No_Default_Initialization:: |
| * No_Delay:: |
| * No_Dependence:: |
| * No_Direct_Boolean_Operators:: |
| * No_Dispatch:: |
| * No_Dispatching_Calls:: |
| * No_Dynamic_Attachment:: |
| * No_Dynamic_Priorities:: |
| * No_Entry_Calls_In_Elaboration_Code:: |
| * No_Enumeration_Maps:: |
| * No_Exception_Handlers:: |
| * No_Exception_Propagation:: |
| * No_Exception_Registration:: |
| * No_Exceptions:: |
| * No_Finalization:: |
| * No_Fixed_Point:: |
| * No_Floating_Point:: |
| * No_Implicit_Conditionals:: |
| * No_Implicit_Dynamic_Code:: |
| * No_Implicit_Heap_Allocations:: |
| * No_Implicit_Protected_Object_Allocations:: |
| * No_Implicit_Task_Allocations:: |
| * No_Initialize_Scalars:: |
| * No_IO:: |
| * No_Local_Allocators:: |
| * No_Local_Protected_Objects:: |
| * No_Local_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:: |
| |
| @end menu |
| |
| @node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b9} |
| @subsection Immediate_Reclamation |
| |
| |
| @geindex Immediate_Reclamation |
| |
| [RM H.4] This restriction ensures that, except for storage occupied by |
| objects created by allocators and not deallocated via unchecked |
| deallocation, any storage reserved at run time for an object is |
| immediately reclaimed when the object no longer exists. |
| |
| @node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1ba} |
| @subsection Max_Asynchronous_Select_Nesting |
| |
| |
| @geindex Max_Asynchronous_Select_Nesting |
| |
| [RM D.7] Specifies the maximum dynamic nesting level of asynchronous |
| selects. Violations of this restriction with a value of zero are |
| detected at compile time. Violations of this restriction with values |
| other than zero cause Storage_Error to be raised. |
| |
| @node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1bb} |
| @subsection Max_Entry_Queue_Length |
| |
| |
| @geindex Max_Entry_Queue_Length |
| |
| [RM D.7] This restriction is a declaration that any protected entry compiled in |
| the scope of the restriction has at most the specified number of |
| tasks waiting on the entry at any one time, and so no queue is required. |
| Note that this restriction is checked at run time. Violation of this |
| restriction results in the raising of Program_Error exception at the point of |
| the call. |
| |
| @geindex Max_Entry_Queue_Depth |
| |
| The restriction @code{Max_Entry_Queue_Depth} is recognized as a |
| synonym for @code{Max_Entry_Queue_Length}. This is retained for historical |
| compatibility purposes (and a warning will be generated for its use if |
| warnings on obsolescent features are activated). |
| |
| @node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1bc} |
| @subsection Max_Protected_Entries |
| |
| |
| @geindex Max_Protected_Entries |
| |
| [RM D.7] Specifies the maximum number of entries per protected type. The |
| bounds of every entry family of a protected unit shall be static, or shall be |
| defined by a discriminant of a subtype whose corresponding bound is static. |
| |
| @node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bd} |
| @subsection Max_Select_Alternatives |
| |
| |
| @geindex Max_Select_Alternatives |
| |
| [RM D.7] Specifies the maximum number of alternatives in a selective accept. |
| |
| @node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1be} |
| @subsection Max_Storage_At_Blocking |
| |
| |
| @geindex Max_Storage_At_Blocking |
| |
| [RM D.7] Specifies the maximum portion (in storage elements) of a task’s |
| Storage_Size that can be retained by a blocked task. A violation of this |
| restriction causes Storage_Error to be raised. |
| |
| @node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1bf} |
| @subsection Max_Task_Entries |
| |
| |
| @geindex Max_Task_Entries |
| |
| [RM D.7] Specifies the maximum number of entries |
| per task. The bounds of every entry family |
| of a task unit shall be static, or shall be |
| defined by a discriminant of a subtype whose |
| corresponding bound is static. |
| |
| @node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c0} |
| @subsection Max_Tasks |
| |
| |
| @geindex Max_Tasks |
| |
| [RM D.7] Specifies the maximum number of task that may be created, not |
| counting the creation of the environment task. Violations of this |
| restriction with a value of zero are detected at compile |
| time. Violations of this restriction with values other than zero cause |
| Storage_Error to be raised. |
| |
| @node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c1} |
| @subsection No_Abort_Statements |
| |
| |
| @geindex No_Abort_Statements |
| |
| [RM D.7] There are no abort_statements, and there are |
| no calls to Task_Identification.Abort_Task. |
| |
| @node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c2} |
| @subsection No_Access_Parameter_Allocators |
| |
| |
| @geindex No_Access_Parameter_Allocators |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of an allocator as the actual parameter to an access |
| parameter. |
| |
| @node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c3} |
| @subsection No_Access_Subprograms |
| |
| |
| @geindex No_Access_Subprograms |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| declarations of access-to-subprogram types. |
| |
| @node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c4} |
| @subsection No_Allocators |
| |
| |
| @geindex No_Allocators |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of an allocator. |
| |
| @node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c5} |
| @subsection No_Anonymous_Allocators |
| |
| |
| @geindex No_Anonymous_Allocators |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of an allocator of anonymous access type. |
| |
| @node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c6} |
| @subsection No_Asynchronous_Control |
| |
| |
| @geindex No_Asynchronous_Control |
| |
| [RM J.13] This restriction ensures at compile time that there are no semantic |
| dependences on the predefined package Asynchronous_Task_Control. |
| |
| @node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c7} |
| @subsection No_Calendar |
| |
| |
| @geindex No_Calendar |
| |
| [GNAT] This restriction ensures at compile time that there are no semantic |
| dependences on package Calendar. |
| |
| @node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c8} |
| @subsection No_Coextensions |
| |
| |
| @geindex No_Coextensions |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| coextensions. See 3.10.2. |
| |
| @node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c9} |
| @subsection No_Default_Initialization |
| |
| |
| @geindex No_Default_Initialization |
| |
| [GNAT] This restriction prohibits any instance of default initialization |
| of variables. The binder implements a consistency rule which prevents |
| any unit compiled without the restriction from with’ing a unit with the |
| restriction (this allows the generation of initialization procedures to |
| be skipped, since you can be sure that no call is ever generated to an |
| initialization procedure in a unit with the restriction active). If used |
| in conjunction with Initialize_Scalars or Normalize_Scalars, the effect |
| is to prohibit all cases of variables declared without a specific |
| initializer (including the case of OUT scalar parameters). |
| |
| @node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1ca} |
| @subsection No_Delay |
| |
| |
| @geindex No_Delay |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| delay statements and no semantic dependences on package Calendar. |
| |
| @node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1cb} |
| @subsection No_Dependence |
| |
| |
| @geindex No_Dependence |
| |
| [RM 13.12.1] This restriction ensures at compile time that there are no |
| dependences on a library unit. |
| |
| @node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1cc} |
| @subsection No_Direct_Boolean_Operators |
| |
| |
| @geindex No_Direct_Boolean_Operators |
| |
| [GNAT] This restriction ensures that no logical operators (and/or/xor) |
| are used on operands of type Boolean (or any type derived from Boolean). |
| This is intended for use in safety critical programs where the certification |
| protocol requires the use of short-circuit (and then, or else) forms for all |
| composite boolean operations. |
| |
| @node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cd} |
| @subsection No_Dispatch |
| |
| |
| @geindex No_Dispatch |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. |
| |
| @node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1ce} |
| @subsection No_Dispatching_Calls |
| |
| |
| @geindex No_Dispatching_Calls |
| |
| [GNAT] This restriction ensures at compile time that the code generated by the |
| compiler involves no dispatching calls. The use of this restriction allows the |
| safe use of record extensions, classwide membership tests and other classwide |
| features not involving implicit dispatching. This restriction ensures that |
| the code contains no indirect calls through a dispatching mechanism. Note that |
| this includes internally-generated calls created by the compiler, for example |
| in the implementation of class-wide objects assignments. The |
| membership test is allowed in the presence of this restriction, because its |
| implementation requires no dispatching. |
| This restriction is comparable to the official Ada restriction |
| @code{No_Dispatch} except that it is a bit less restrictive in that it allows |
| all classwide constructs that do not imply dispatching. |
| The following example indicates constructs that violate this restriction. |
| |
| @example |
| package Pkg is |
| type T is tagged record |
| Data : Natural; |
| end record; |
| procedure P (X : T); |
| |
| type DT is new T with record |
| More_Data : Natural; |
| end record; |
| procedure Q (X : DT); |
| end Pkg; |
| |
| with Pkg; use Pkg; |
| procedure Example is |
| procedure Test (O : T'Class) is |
| N : Natural := O'Size;-- Error: Dispatching call |
| C : T'Class := O; -- Error: implicit Dispatching Call |
| begin |
| if O in DT'Class then -- OK : Membership test |
| Q (DT (O)); -- OK : Type conversion plus direct call |
| else |
| P (O); -- Error: Dispatching call |
| end if; |
| end Test; |
| |
| Obj : DT; |
| begin |
| P (Obj); -- OK : Direct call |
| P (T (Obj)); -- OK : Type conversion plus direct call |
| P (T'Class (Obj)); -- Error: Dispatching call |
| |
| Test (Obj); -- OK : Type conversion |
| |
| if Obj in T'Class then -- OK : Membership test |
| null; |
| end if; |
| end Example; |
| @end example |
| |
| @node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1cf} |
| @subsection No_Dynamic_Attachment |
| |
| |
| @geindex No_Dynamic_Attachment |
| |
| [RM D.7] This restriction ensures that there is no call to any of the |
| operations defined in package Ada.Interrupts |
| (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, |
| Detach_Handler, and Reference). |
| |
| @geindex No_Dynamic_Interrupts |
| |
| The restriction @code{No_Dynamic_Interrupts} is recognized as a |
| synonym for @code{No_Dynamic_Attachment}. This is retained for historical |
| compatibility purposes (and a warning will be generated for its use if |
| warnings on obsolescent features are activated). |
| |
| @node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d0} |
| @subsection No_Dynamic_Priorities |
| |
| |
| @geindex No_Dynamic_Priorities |
| |
| [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. |
| |
| @node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d1} |
| @subsection No_Entry_Calls_In_Elaboration_Code |
| |
| |
| @geindex No_Entry_Calls_In_Elaboration_Code |
| |
| [GNAT] This restriction ensures at compile time that no task or protected entry |
| calls are made during elaboration code. As a result of the use of this |
| restriction, the compiler can assume that no code past an accept statement |
| in a task can be executed at elaboration time. |
| |
| @node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d2} |
| @subsection No_Enumeration_Maps |
| |
| |
| @geindex No_Enumeration_Maps |
| |
| [GNAT] This restriction ensures at compile time that no operations requiring |
| enumeration maps are used (that is Image and Value attributes applied |
| to enumeration types). |
| |
| @node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d3} |
| @subsection No_Exception_Handlers |
| |
| |
| @geindex No_Exception_Handlers |
| |
| [GNAT] This restriction ensures at compile time that there are no explicit |
| exception handlers. It also indicates that no exception propagation will |
| be provided. In this mode, exceptions may be raised but will result in |
| an immediate call to the last chance handler, a routine that the user |
| must define with the following profile: |
| |
| @example |
| procedure Last_Chance_Handler |
| (Source_Location : System.Address; Line : Integer); |
| pragma Export (C, Last_Chance_Handler, |
| "__gnat_last_chance_handler"); |
| @end example |
| |
| The parameter is a C null-terminated string representing a message to be |
| associated with the exception (typically the source location of the raise |
| statement generated by the compiler). The Line parameter when nonzero |
| represents the line number in the source program where the raise occurs. |
| |
| @node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d4} |
| @subsection No_Exception_Propagation |
| |
| |
| @geindex No_Exception_Propagation |
| |
| [GNAT] This restriction guarantees that exceptions are never propagated |
| to an outer subprogram scope. The only case in which an exception may |
| be raised is when the handler is statically in the same subprogram, so |
| that the effect of a raise is essentially like a goto statement. Any |
| other raise statement (implicit or explicit) will be considered |
| unhandled. Exception handlers are allowed, but may not contain an |
| exception occurrence identifier (exception choice). In addition, use of |
| the package GNAT.Current_Exception is not permitted, and reraise |
| statements (raise with no operand) are not permitted. |
| |
| @node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d5} |
| @subsection No_Exception_Registration |
| |
| |
| @geindex No_Exception_Registration |
| |
| [GNAT] This restriction ensures at compile time that no stream operations for |
| types Exception_Id or Exception_Occurrence are used. This also makes it |
| impossible to pass exceptions to or from a partition with this restriction |
| in a distributed environment. If this restriction is active, the generated |
| code is simplified by omitting the otherwise-required global registration |
| of exceptions when they are declared. |
| |
| @node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d6} |
| @subsection No_Exceptions |
| |
| |
| @geindex No_Exceptions |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| raise statements and no exception handlers and also suppresses the |
| generation of language-defined run-time checks. |
| |
| @node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d7} |
| @subsection No_Finalization |
| |
| |
| @geindex No_Finalization |
| |
| [GNAT] This restriction disables the language features described in |
| chapter 7.6 of the Ada 2005 RM as well as all form of code generation |
| performed by the compiler to support these features. The following types |
| are no longer considered controlled when this restriction is in effect: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Ada.Finalization.Controlled} |
| |
| @item |
| @code{Ada.Finalization.Limited_Controlled} |
| |
| @item |
| Derivations from @code{Controlled} or @code{Limited_Controlled} |
| |
| @item |
| Class-wide types |
| |
| @item |
| Protected types |
| |
| @item |
| Task types |
| |
| @item |
| Array and record types with controlled components |
| @end itemize |
| |
| The compiler no longer generates code to initialize, finalize or adjust an |
| object or a nested component, either declared on the stack or on the heap. The |
| deallocation of a controlled object no longer finalizes its contents. |
| |
| @node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d8} |
| @subsection No_Fixed_Point |
| |
| |
| @geindex No_Fixed_Point |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of fixed point types and operations. |
| |
| @node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d9} |
| @subsection No_Floating_Point |
| |
| |
| @geindex No_Floating_Point |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of floating point types and operations. |
| |
| @node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1da} |
| @subsection No_Implicit_Conditionals |
| |
| |
| @geindex No_Implicit_Conditionals |
| |
| [GNAT] This restriction ensures that the generated code does not contain any |
| implicit conditionals, either by modifying the generated code where possible, |
| or by rejecting any construct that would otherwise generate an implicit |
| conditional. Note that this check does not include run time constraint |
| checks, which on some targets may generate implicit conditionals as |
| well. To control the latter, constraint checks can be suppressed in the |
| normal manner. Constructs generating implicit conditionals include comparisons |
| of composite objects and the Max/Min attributes. |
| |
| @node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1db} |
| @subsection No_Implicit_Dynamic_Code |
| |
| |
| @geindex No_Implicit_Dynamic_Code |
| |
| @geindex trampoline |
| |
| [GNAT] This restriction prevents the compiler from building ‘trampolines’. |
| This is a structure that is built on the stack and contains dynamic |
| code to be executed at run time. On some targets, a trampoline is |
| built for the following features: @code{Access}, |
| @code{Unrestricted_Access}, or @code{Address} of a nested subprogram; |
| nested task bodies; primitive operations of nested tagged types. |
| Trampolines do not work on machines that prevent execution of stack |
| data. For example, on windows systems, enabling DEP (data execution |
| protection) will cause trampolines to raise an exception. |
| Trampolines are also quite slow at run time. |
| |
| On many targets, trampolines have been largely eliminated. Look at the |
| version of system.ads for your target — if it has |
| Always_Compatible_Rep equal to False, then trampolines are largely |
| eliminated. In particular, a trampoline is built for the following |
| features: @code{Address} of a nested subprogram; |
| @code{Access} or @code{Unrestricted_Access} of a nested subprogram, |
| but only if pragma Favor_Top_Level applies, or the access type has a |
| foreign-language convention; primitive operations of nested tagged |
| types. |
| |
| @node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1dc} |
| @subsection No_Implicit_Heap_Allocations |
| |
| |
| @geindex No_Implicit_Heap_Allocations |
| |
| [RM D.7] No constructs are allowed to cause implicit heap allocation. |
| |
| @node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1dd} |
| @subsection No_Implicit_Protected_Object_Allocations |
| |
| |
| @geindex No_Implicit_Protected_Object_Allocations |
| |
| [GNAT] No constructs are allowed to cause implicit heap allocation of a |
| protected object. |
| |
| @node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1de} |
| @subsection No_Implicit_Task_Allocations |
| |
| |
| @geindex No_Implicit_Task_Allocations |
| |
| [GNAT] No constructs are allowed to cause implicit heap allocation of a task. |
| |
| @node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1df} |
| @subsection No_Initialize_Scalars |
| |
| |
| @geindex No_Initialize_Scalars |
| |
| [GNAT] This restriction ensures that no unit in the partition is compiled with |
| pragma Initialize_Scalars. This allows the generation of more efficient |
| code, and in particular eliminates dummy null initialization routines that |
| are otherwise generated for some record and array types. |
| |
| @node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e0} |
| @subsection No_IO |
| |
| |
| @geindex No_IO |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| dependences on any of the library units Sequential_IO, Direct_IO, |
| Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. |
| |
| @node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e1} |
| @subsection No_Local_Allocators |
| |
| |
| @geindex No_Local_Allocators |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of an allocator in subprograms, generic subprograms, tasks, |
| and entry bodies. |
| |
| @node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e2} |
| @subsection No_Local_Protected_Objects |
| |
| |
| @geindex No_Local_Protected_Objects |
| |
| [RM D.7] This restriction ensures at compile time that protected objects are |
| only declared at the library level. |
| |
| @node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e3} |
| @subsection No_Local_Timing_Events |
| |
| |
| @geindex No_Local_Timing_Events |
| |
| [RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are |
| declared at the library level. |
| |
| @node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e4} |
| @subsection No_Long_Long_Integers |
| |
| |
| @geindex No_Long_Long_Integers |
| |
| [GNAT] This partition-wide restriction forbids any explicit reference to |
| type Standard.Long_Long_Integer, and also forbids declaring range types whose |
| implicit base type is Long_Long_Integer, and modular types whose size exceeds |
| Long_Integer’Size. |
| |
| @node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e5} |
| @subsection No_Multiple_Elaboration |
| |
| |
| @geindex No_Multiple_Elaboration |
| |
| [GNAT] When this restriction is active and the static elaboration model is |
| used, and -fpreserve-control-flow is not used, the compiler is allowed to |
| suppress the elaboration counter normally associated with the unit, even if |
| the unit has elaboration code. This counter is typically used to check for |
| access before elaboration and to control multiple elaboration attempts. If the |
| restriction is used, then the situations in which multiple elaboration is |
| possible, including non-Ada main programs and Stand Alone libraries, are not |
| permitted and will be diagnosed by the binder. |
| |
| @node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e6} |
| @subsection No_Nested_Finalization |
| |
| |
| @geindex No_Nested_Finalization |
| |
| [RM D.7] All objects requiring finalization are declared at the library level. |
| |
| @node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e7} |
| @subsection No_Protected_Type_Allocators |
| |
| |
| @geindex No_Protected_Type_Allocators |
| |
| [RM D.7] This restriction ensures at compile time that there are no allocator |
| expressions that attempt to allocate protected objects. |
| |
| @node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e8} |
| @subsection No_Protected_Types |
| |
| |
| @geindex No_Protected_Types |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| declarations of protected types or protected objects. |
| |
| @node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e9} |
| @subsection No_Recursion |
| |
| |
| @geindex No_Recursion |
| |
| [RM H.4] A program execution is erroneous if a subprogram is invoked as |
| part of its execution. |
| |
| @node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1ea} |
| @subsection No_Reentrancy |
| |
| |
| @geindex No_Reentrancy |
| |
| [RM H.4] A program execution is erroneous if a subprogram is executed by |
| two tasks at the same time. |
| |
| @node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1eb} |
| @subsection No_Relative_Delay |
| |
| |
| @geindex No_Relative_Delay |
| |
| [RM D.7] This restriction ensures at compile time that there are no delay |
| relative statements and prevents expressions such as @code{delay 1.23;} from |
| appearing in source code. |
| |
| @node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1ec} |
| @subsection No_Requeue_Statements |
| |
| |
| @geindex No_Requeue_Statements |
| |
| [RM D.7] This restriction ensures at compile time that no requeue statements |
| are permitted and prevents keyword @code{requeue} from being used in source |
| code. |
| |
| @geindex No_Requeue |
| |
| The restriction @code{No_Requeue} is recognized as a |
| synonym for @code{No_Requeue_Statements}. This is retained for historical |
| compatibility purposes (and a warning will be generated for its use if |
| warnings on oNobsolescent features are activated). |
| |
| @node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ed} |
| @subsection No_Secondary_Stack |
| |
| |
| @geindex No_Secondary_Stack |
| |
| [GNAT] This restriction ensures at compile time that the generated code |
| does not contain any reference to the secondary stack. The secondary |
| stack is used to implement functions returning unconstrained objects |
| (arrays or records) on some targets. Suppresses the allocation of |
| secondary stacks for tasks (excluding the environment task) at run time. |
| |
| @node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ee} |
| @subsection No_Select_Statements |
| |
| |
| @geindex No_Select_Statements |
| |
| [RM D.7] This restriction ensures at compile time no select statements of any |
| kind are permitted, that is the keyword @code{select} may not appear. |
| |
| @node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ef} |
| @subsection No_Specific_Termination_Handlers |
| |
| |
| @geindex No_Specific_Termination_Handlers |
| |
| [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler |
| or to Ada.Task_Termination.Specific_Handler. |
| |
| @node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f0} |
| @subsection No_Specification_of_Aspect |
| |
| |
| @geindex No_Specification_of_Aspect |
| |
| [RM 13.12.1] This restriction checks at compile time that no aspect |
| specification, attribute definition clause, or pragma is given for a |
| given aspect. |
| |
| @node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f1} |
| @subsection No_Standard_Allocators_After_Elaboration |
| |
| |
| @geindex No_Standard_Allocators_After_Elaboration |
| |
| [RM D.7] Specifies that an allocator using a standard storage pool |
| should never be evaluated at run time after the elaboration of the |
| library items of the partition has completed. Otherwise, Storage_Error |
| is raised. |
| |
| @node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f2} |
| @subsection No_Standard_Storage_Pools |
| |
| |
| @geindex No_Standard_Storage_Pools |
| |
| [GNAT] This restriction ensures at compile time that no access types |
| use the standard default storage pool. Any access type declared must |
| have an explicit Storage_Pool attribute defined specifying a |
| user-defined storage pool. |
| |
| @node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f3} |
| @subsection No_Stream_Optimizations |
| |
| |
| @geindex No_Stream_Optimizations |
| |
| [GNAT] This restriction affects the performance of stream operations on types |
| @code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the |
| compiler uses block reads and writes when manipulating @code{String} objects |
| due to their superior performance. When this restriction is in effect, the |
| compiler performs all IO operations on a per-character basis. |
| |
| @node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f4} |
| @subsection No_Streams |
| |
| |
| @geindex No_Streams |
| |
| [GNAT] This restriction ensures at compile/bind time that there are no |
| stream objects created and no use of stream attributes. |
| This restriction does not forbid dependences on the package |
| @code{Ada.Streams}. So it is permissible to with |
| @code{Ada.Streams} (or another package that does so itself) |
| as long as no actual stream objects are created and no |
| stream attributes are used. |
| |
| Note that the use of restriction allows optimization of tagged types, |
| since they do not need to worry about dispatching stream operations. |
| To take maximum advantage of this space-saving optimization, any |
| unit declaring a tagged type should be compiled with the restriction, |
| though this is not required. |
| |
| @node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f5} |
| @subsection No_Task_Allocators |
| |
| |
| @geindex No_Task_Allocators |
| |
| [RM D.7] There are no allocators for task types |
| or types containing task subcomponents. |
| |
| @node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f6} |
| @subsection No_Task_At_Interrupt_Priority |
| |
| |
| @geindex No_Task_At_Interrupt_Priority |
| |
| [GNAT] This restriction ensures at compile time that there is no |
| Interrupt_Priority aspect or pragma for a task or a task type. As |
| a consequence, the tasks are always created with a priority below |
| that an interrupt priority. |
| |
| @node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f7} |
| @subsection No_Task_Attributes_Package |
| |
| |
| @geindex No_Task_Attributes_Package |
| |
| [GNAT] This restriction ensures at compile time that there are no implicit or |
| explicit dependencies on the package @code{Ada.Task_Attributes}. |
| |
| @geindex No_Task_Attributes |
| |
| The restriction @code{No_Task_Attributes} is recognized as a synonym |
| for @code{No_Task_Attributes_Package}. This is retained for historical |
| compatibility purposes (and a warning will be generated for its use if |
| warnings on obsolescent features are activated). |
| |
| @node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f8} |
| @subsection No_Task_Hierarchy |
| |
| |
| @geindex No_Task_Hierarchy |
| |
| [RM D.7] All (non-environment) tasks depend |
| directly on the environment task of the partition. |
| |
| @node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f9} |
| @subsection No_Task_Termination |
| |
| |
| @geindex No_Task_Termination |
| |
| [RM D.7] Tasks that terminate are erroneous. |
| |
| @node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fa} |
| @subsection No_Tasking |
| |
| |
| @geindex No_Tasking |
| |
| [GNAT] This restriction prevents the declaration of tasks or task types |
| throughout the partition. It is similar in effect to the use of |
| @code{Max_Tasks => 0} except that violations are caught at compile time |
| and cause an error message to be output either by the compiler or |
| binder. |
| |
| @node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fb} |
| @subsection No_Terminate_Alternatives |
| |
| |
| @geindex No_Terminate_Alternatives |
| |
| [RM D.7] There are no selective accepts with terminate alternatives. |
| |
| @node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fc} |
| @subsection No_Unchecked_Access |
| |
| |
| @geindex No_Unchecked_Access |
| |
| [RM H.4] This restriction ensures at compile time that there are no |
| occurrences of the Unchecked_Access attribute. |
| |
| @node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fd} |
| @subsection No_Unchecked_Conversion |
| |
| |
| @geindex No_Unchecked_Conversion |
| |
| [RM J.13] This restriction ensures at compile time that there are no semantic |
| dependences on the predefined generic function Unchecked_Conversion. |
| |
| @node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1fe} |
| @subsection No_Unchecked_Deallocation |
| |
| |
| @geindex No_Unchecked_Deallocation |
| |
| [RM J.13] This restriction ensures at compile time that there are no semantic |
| dependences on the predefined generic procedure Unchecked_Deallocation. |
| |
| @node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1ff} |
| @subsection No_Use_Of_Entity |
| |
| |
| @geindex No_Use_Of_Entity |
| |
| [GNAT] This restriction ensures at compile time that there are no references |
| to the entity given in the form |
| |
| @example |
| No_Use_Of_Entity => Name |
| @end example |
| |
| where @code{Name} is the fully qualified entity, for example |
| |
| @example |
| No_Use_Of_Entity => Ada.Text_IO.Put_Line |
| @end example |
| |
| @node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{200} |
| @subsection Pure_Barriers |
| |
| |
| @geindex Pure_Barriers |
| |
| [GNAT] This restriction ensures at compile time that protected entry |
| barriers are restricted to: |
| |
| |
| @itemize * |
| |
| @item |
| components of the protected object (excluding selection from dereferences), |
| |
| @item |
| constant declarations, |
| |
| @item |
| named numbers, |
| |
| @item |
| enumeration literals, |
| |
| @item |
| integer literals, |
| |
| @item |
| real literals, |
| |
| @item |
| character literals, |
| |
| @item |
| implicitly defined comparison operators, |
| |
| @item |
| uses of the Standard.”not” operator, |
| |
| @item |
| short-circuit operator, |
| |
| @item |
| the Count attribute |
| @end itemize |
| |
| This restriction is a relaxation of the Simple_Barriers restriction, |
| but still ensures absence of side effects, exceptions, and recursion |
| during the evaluation of the barriers. |
| |
| @node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{201} |
| @subsection Simple_Barriers |
| |
| |
| @geindex Simple_Barriers |
| |
| [RM D.7] This restriction ensures at compile time that barriers in entry |
| declarations for protected types are restricted to either static boolean |
| expressions or references to simple boolean variables defined in the private |
| part of the protected type. No other form of entry barriers is permitted. |
| |
| @geindex Boolean_Entry_Barriers |
| |
| The restriction @code{Boolean_Entry_Barriers} is recognized as a |
| synonym for @code{Simple_Barriers}. This is retained for historical |
| compatibility purposes (and a warning will be generated for its use if |
| warnings on obsolescent features are activated). |
| |
| @node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{202} |
| @subsection Static_Priorities |
| |
| |
| @geindex Static_Priorities |
| |
| [GNAT] This restriction ensures at compile time that all priority expressions |
| are static, and that there are no dependences on the package |
| @code{Ada.Dynamic_Priorities}. |
| |
| @node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{203} |
| @subsection Static_Storage_Size |
| |
| |
| @geindex Static_Storage_Size |
| |
| [GNAT] This restriction ensures at compile time that any expression appearing |
| in a Storage_Size pragma or attribute definition clause is static. |
| |
| @node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{204}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{205} |
| @section Program Unit Level Restrictions |
| |
| |
| The second set of restriction identifiers |
| does not require partition-wide consistency. |
| The restriction may be enforced for a single |
| compilation unit without any effect on any of the |
| other compilation units in the partition. |
| |
| @menu |
| * No_Elaboration_Code:: |
| * No_Dynamic_Accessibility_Checks:: |
| * No_Dynamic_Sized_Objects:: |
| * No_Entry_Queue:: |
| * No_Implementation_Aspect_Specifications:: |
| * No_Implementation_Attributes:: |
| * No_Implementation_Identifiers:: |
| * No_Implementation_Pragmas:: |
| * No_Implementation_Restrictions:: |
| * No_Implementation_Units:: |
| * No_Implicit_Aliasing:: |
| * No_Implicit_Loops:: |
| * No_Obsolescent_Features:: |
| * No_Wide_Characters:: |
| * Static_Dispatch_Tables:: |
| * SPARK_05:: |
| |
| @end menu |
| |
| @node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{206} |
| @subsection No_Elaboration_Code |
| |
| |
| @geindex No_Elaboration_Code |
| |
| [GNAT] This restriction ensures at compile time that no elaboration code is |
| generated. Note that this is not the same condition as is enforced |
| by pragma @code{Preelaborate}. There are cases in which pragma |
| @code{Preelaborate} still permits code to be generated (e.g., code |
| to initialize a large array to all zeroes), and there are cases of units |
| which do not meet the requirements for pragma @code{Preelaborate}, |
| but for which no elaboration code is generated. Generally, it is |
| the case that preelaborable units will meet the restrictions, with |
| the exception of large aggregates initialized with an others_clause, |
| and exception declarations (which generate calls to a run-time |
| registry procedure). This restriction is enforced on |
| a unit by unit basis, it need not be obeyed consistently |
| throughout a partition. |
| |
| In the case of aggregates with others, if the aggregate has a dynamic |
| size, there is no way to eliminate the elaboration code (such dynamic |
| bounds would be incompatible with @code{Preelaborate} in any case). If |
| the bounds are static, then use of this restriction actually modifies |
| the code choice of the compiler to avoid generating a loop, and instead |
| generate the aggregate statically if possible, no matter how many times |
| the data for the others clause must be repeatedly generated. |
| |
| It is not possible to precisely document |
| the constructs which are compatible with this restriction, since, |
| unlike most other restrictions, this is not a restriction on the |
| source code, but a restriction on the generated object code. For |
| example, if the source contains a declaration: |
| |
| @example |
| Val : constant Integer := X; |
| @end example |
| |
| where X is not a static constant, it may be possible, depending |
| on complex optimization circuitry, for the compiler to figure |
| out the value of X at compile time, in which case this initialization |
| can be done by the loader, and requires no initialization code. It |
| is not possible to document the precise conditions under which the |
| optimizer can figure this out. |
| |
| Note that this the implementation of this restriction requires full |
| code generation. If it is used in conjunction with “semantics only” |
| checking, then some cases of violations may be missed. |
| |
| When this restriction is active, we are not requesting control-flow |
| preservation with -fpreserve-control-flow, and the static elaboration model is |
| used, the compiler is allowed to suppress the elaboration counter normally |
| associated with the unit. This counter is typically used to check for access |
| before elaboration and to control multiple elaboration attempts. |
| |
| @node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{207} |
| @subsection No_Dynamic_Accessibility_Checks |
| |
| |
| @geindex No_Dynamic_Accessibility_Checks |
| |
| [GNAT] No dynamic accessibility checks are generated when this restriction is |
| in effect. Instead, dangling references are prevented via more conservative |
| compile-time checking. More specifically, existing compile-time checks are |
| enforced but with more conservative assumptions about the accessibility levels |
| of the relevant entities. These conservative assumptions eliminate the need for |
| dynamic accessibility checks. |
| |
| These new rules for computing (at compile-time) the accessibility level of an |
| anonymous access type T are as follows: |
| |
| |
| @itemize * |
| |
| @item |
| If T is a function result type then, from the caller’s perspective, its level |
| is that of the innermost master enclosing the function call. From the callee’s |
| perspective, the level of parameters and local variables of the callee is |
| statically deeper than the level of T. |
| |
| For any other accessibility level L such that the level of parameters and local |
| variables of the callee is statically deeper than L, the level of T (from the |
| callee’s perspective) is also statically deeper than L. |
| |
| @item |
| If T is the type of a formal parameter then, from the caller’s perspective, |
| its level is at least as deep as that of the type of the corresponding actual |
| parameter (whatever that actual parameter might be). From the callee’s |
| perspective, the level of parameters and local variables of the callee is |
| statically deeper than the level of T. |
| |
| @item |
| If T is the type of a discriminant then its level is that of the discriminated |
| type. |
| |
| @item |
| If T is the type of a stand-alone object then its level is the level of the |
| object. |
| |
| @item |
| In all other cases, the level of T is as defined by the existing rules of Ada. |
| @end itemize |
| |
| @node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{208} |
| @subsection No_Dynamic_Sized_Objects |
| |
| |
| @geindex No_Dynamic_Sized_Objects |
| |
| [GNAT] This restriction disallows certain constructs that might lead to the |
| creation of dynamic-sized composite objects (or array or discriminated type). |
| An array subtype indication is illegal if the bounds are not static |
| or references to discriminants of an enclosing type. |
| A discriminated subtype indication is illegal if the type has |
| discriminant-dependent array components or a variant part, and the |
| discriminants are not static. In addition, array and record aggregates are |
| illegal in corresponding cases. Note that this restriction does not forbid |
| access discriminants. It is often a good idea to combine this restriction |
| with No_Secondary_Stack. |
| |
| @node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{209} |
| @subsection No_Entry_Queue |
| |
| |
| @geindex No_Entry_Queue |
| |
| [GNAT] This restriction is a declaration that any protected entry compiled in |
| the scope of the restriction has at most one task waiting on the entry |
| at any one time, and so no queue is required. This restriction is not |
| checked at compile time. A program execution is erroneous if an attempt |
| is made to queue a second task on such an entry. |
| |
| @node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{20a} |
| @subsection No_Implementation_Aspect_Specifications |
| |
| |
| @geindex No_Implementation_Aspect_Specifications |
| |
| [RM 13.12.1] This restriction checks at compile time that no |
| GNAT-defined aspects are present. With this restriction, the only |
| aspects that can be used are those defined in the Ada Reference Manual. |
| |
| @node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{20b} |
| @subsection No_Implementation_Attributes |
| |
| |
| @geindex No_Implementation_Attributes |
| |
| [RM 13.12.1] This restriction checks at compile time that no |
| GNAT-defined attributes are present. With this restriction, the only |
| attributes that can be used are those defined in the Ada Reference |
| Manual. |
| |
| @node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20c} |
| @subsection No_Implementation_Identifiers |
| |
| |
| @geindex No_Implementation_Identifiers |
| |
| [RM 13.12.1] This restriction checks at compile time that no |
| implementation-defined identifiers (marked with pragma Implementation_Defined) |
| occur within language-defined packages. |
| |
| @node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20d} |
| @subsection No_Implementation_Pragmas |
| |
| |
| @geindex No_Implementation_Pragmas |
| |
| [RM 13.12.1] This restriction checks at compile time that no |
| GNAT-defined pragmas are present. With this restriction, the only |
| pragmas that can be used are those defined in the Ada Reference Manual. |
| |
| @node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20e} |
| @subsection No_Implementation_Restrictions |
| |
| |
| @geindex No_Implementation_Restrictions |
| |
| [GNAT] This restriction checks at compile time that no GNAT-defined restriction |
| identifiers (other than @code{No_Implementation_Restrictions} itself) |
| are present. With this restriction, the only other restriction identifiers |
| that can be used are those defined in the Ada Reference Manual. |
| |
| @node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20f} |
| @subsection No_Implementation_Units |
| |
| |
| @geindex No_Implementation_Units |
| |
| [RM 13.12.1] This restriction checks at compile time that there is no |
| mention in the context clause of any implementation-defined descendants |
| of packages Ada, Interfaces, or System. |
| |
| @node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{210} |
| @subsection No_Implicit_Aliasing |
| |
| |
| @geindex No_Implicit_Aliasing |
| |
| [GNAT] This restriction, which is not required to be partition-wide consistent, |
| requires an explicit aliased keyword for an object to which ‘Access, |
| ‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of |
| the ‘Unrestricted_Access attribute for objects. Note: the reason that |
| Unrestricted_Access is forbidden is that it would require the prefix |
| to be aliased, and in such cases, it can always be replaced by |
| the standard attribute Unchecked_Access which is preferable. |
| |
| @node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{211} |
| @subsection No_Implicit_Loops |
| |
| |
| @geindex No_Implicit_Loops |
| |
| [GNAT] This restriction ensures that the generated code of the unit marked |
| with this restriction does not contain any implicit @code{for} loops, either by |
| modifying the generated code where possible, or by rejecting any construct |
| that would otherwise generate an implicit @code{for} loop. If this restriction is |
| active, it is possible to build large array aggregates with all static |
| components without generating an intermediate temporary, and without generating |
| a loop to initialize individual components. Otherwise, a loop is created for |
| arrays larger than about 5000 scalar components. Note that if this restriction |
| is set in the spec of a package, it will not apply to its body. |
| |
| @node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{212} |
| @subsection No_Obsolescent_Features |
| |
| |
| @geindex No_Obsolescent_Features |
| |
| [RM 13.12.1] This restriction checks at compile time that no obsolescent |
| features are used, as defined in Annex J of the Ada Reference Manual. |
| |
| @node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{213} |
| @subsection No_Wide_Characters |
| |
| |
| @geindex No_Wide_Characters |
| |
| [GNAT] This restriction ensures at compile time that no uses of the types |
| @code{Wide_Character} or @code{Wide_String} or corresponding wide |
| wide types |
| appear, and that no wide or wide wide string or character literals |
| appear in the program (that is literals representing characters not in |
| type @code{Character}). |
| |
| @node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{214} |
| @subsection Static_Dispatch_Tables |
| |
| |
| @geindex Static_Dispatch_Tables |
| |
| [GNAT] This restriction checks at compile time that all the artifacts |
| associated with dispatch tables can be placed in read-only memory. |
| |
| @node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions |
| @anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{215} |
| @subsection SPARK_05 |
| |
| |
| @geindex SPARK_05 |
| |
| [GNAT] This restriction no longer has any effect and is superseded by |
| SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that |
| a codebase respects SPARK 2014 restrictions, mark the code with pragma or |
| aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as |
| follows: |
| |
| @example |
| gnatprove -P project.gpr --mode=stone |
| @end example |
| |
| or equivalently: |
| |
| @example |
| gnatprove -P project.gpr --mode=check_all |
| @end example |
| |
| @node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top |
| @anchor{gnat_rm/implementation_advice doc}@anchor{216}@anchor{gnat_rm/implementation_advice id1}@anchor{217}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a} |
| @chapter Implementation Advice |
| |
| |
| The main text of the Ada Reference Manual describes the required |
| behavior of all Ada compilers, and the GNAT compiler conforms to |
| these requirements. |
| |
| In addition, there are sections throughout the Ada Reference Manual headed |
| by the phrase ‘Implementation advice’. These sections are not normative, |
| i.e., they do not specify requirements that all compilers must |
| follow. Rather they provide advice on generally desirable behavior. |
| They are not requirements, because they describe behavior that cannot |
| be provided on all systems, or may be undesirable on some systems. |
| |
| As far as practical, GNAT follows the implementation advice in |
| the Ada Reference Manual. Each such RM section corresponds to a section |
| in this chapter whose title specifies the |
| RM section number and paragraph number and the subject of |
| the advice. The contents of each section consists of the RM text within |
| quotation marks, |
| followed by the GNAT interpretation of the advice. Most often, this simply says |
| ‘followed’, which means that GNAT follows the advice. However, in a |
| number of cases, GNAT deliberately deviates from this advice, in which |
| case the text describes what GNAT does and why. |
| |
| @geindex Error detection |
| |
| @menu |
| * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. |
| * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. |
| * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. |
| * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. |
| * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. |
| * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. |
| * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. |
| * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. |
| * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. |
| * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. |
| * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. |
| * RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. |
| * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. |
| * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. |
| * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. |
| * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. |
| * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. |
| * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. |
| * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. |
| * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. |
| * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. |
| * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. |
| * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. |
| * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. |
| * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. |
| * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. |
| * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. |
| * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. |
| * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. |
| * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. |
| * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. |
| * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. |
| * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. |
| * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. |
| * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. |
| * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. |
| * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. |
| * RM A.18; Containers: RM A 18 Containers. |
| * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. |
| * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. |
| * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. |
| * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. |
| * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. |
| * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. |
| * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. |
| * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. |
| * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. |
| * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. |
| * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. |
| * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. |
| * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. |
| * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. |
| * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. |
| * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. |
| * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. |
| * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. |
| * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. |
| * RM F(7); COBOL Support: RM F 7 COBOL Support. |
| * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. |
| * RM G; Numerics: RM G Numerics. |
| * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. |
| * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. |
| * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. |
| * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. |
| * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. |
| |
| @end menu |
| |
| @node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{218} |
| @section RM 1.1.3(20): Error Detection |
| |
| |
| @quotation |
| |
| “If an implementation detects the use of an unsupported Specialized Needs |
| Annex feature at run time, it should raise @code{Program_Error} if |
| feasible.” |
| @end quotation |
| |
| Not relevant. All specialized needs annex features are either supported, |
| or diagnosed at compile time. |
| |
| @geindex Child Units |
| |
| @node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{219} |
| @section RM 1.1.3(31): Child Units |
| |
| |
| @quotation |
| |
| “If an implementation wishes to provide implementation-defined |
| extensions to the functionality of a language-defined library unit, it |
| should normally do so by adding children to the library unit.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Bounded errors |
| |
| @node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{21a} |
| @section RM 1.1.5(12): Bounded Errors |
| |
| |
| @quotation |
| |
| “If an implementation detects a bounded error or erroneous |
| execution, it should raise @code{Program_Error}.” |
| @end quotation |
| |
| Followed in all cases in which the implementation detects a bounded |
| error or erroneous execution. Not all such situations are detected at |
| runtime. |
| |
| @geindex Pragmas |
| |
| @node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice |
| @anchor{gnat_rm/implementation_advice id2}@anchor{21b}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21c} |
| @section RM 2.8(16): Pragmas |
| |
| |
| @quotation |
| |
| “Normally, implementation-defined pragmas should have no semantic effect |
| for error-free programs; that is, if the implementation-defined pragmas |
| are removed from a working program, the program should still be legal, |
| and should still have the same semantics.” |
| @end quotation |
| |
| The following implementation defined pragmas are exceptions to this |
| rule: |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| Pragma |
| |
| @tab |
| |
| Explanation |
| |
| @item |
| |
| @emph{Abort_Defer} |
| |
| @tab |
| |
| Affects semantics |
| |
| @item |
| |
| @emph{Ada_83} |
| |
| @tab |
| |
| Affects legality |
| |
| @item |
| |
| @emph{Assert} |
| |
| @tab |
| |
| Affects semantics |
| |
| @item |
| |
| @emph{CPP_Class} |
| |
| @tab |
| |
| Affects semantics |
| |
| @item |
| |
| @emph{CPP_Constructor} |
| |
| @tab |
| |
| Affects semantics |
| |
| @item |
| |
| @emph{Debug} |
| |
| @tab |
| |
| Affects semantics |
| |
| @item |
| |
| @emph{Interface_Name} |
| |
| @tab |
| |
| Affects semantics |
| |
| @item |
| |
| @emph{Machine_Attribute} |
| |
| @tab |
| |
| Affects semantics |
| |
| @item |
| |
| @emph{Unimplemented_Unit} |
| |
| @tab |
| |
| Affects legality |
| |
| @item |
| |
| @emph{Unchecked_Union} |
| |
| @tab |
| |
| Affects semantics |
| |
| @end multitable |
| |
| |
| In each of the above cases, it is essential to the purpose of the pragma |
| that this advice not be followed. For details see |
| @ref{7,,Implementation Defined Pragmas}. |
| |
| @node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21d} |
| @section RM 2.8(17-19): Pragmas |
| |
| |
| @quotation |
| |
| “Normally, an implementation should not define pragmas that can |
| make an illegal program legal, except as follows: |
| |
| |
| @itemize * |
| |
| @item |
| A pragma used to complete a declaration, such as a pragma @code{Import}; |
| |
| @item |
| A pragma used to configure the environment by adding, removing, or |
| replacing @code{library_items}.” |
| @end itemize |
| @end quotation |
| |
| See @ref{21c,,RM 2.8(16); Pragmas}. |
| |
| @geindex Character Sets |
| |
| @geindex Alternative Character Sets |
| |
| @node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21e} |
| @section RM 3.5.2(5): Alternative Character Sets |
| |
| |
| @quotation |
| |
| “If an implementation supports a mode with alternative interpretations |
| for @code{Character} and @code{Wide_Character}, the set of graphic |
| characters of @code{Character} should nevertheless remain a proper |
| subset of the set of graphic characters of @code{Wide_Character}. Any |
| character set ‘localizations’ should be reflected in the results of |
| the subprograms defined in the language-defined package |
| @code{Characters.Handling} (see A.3) available in such a mode. In a mode with |
| an alternative interpretation of @code{Character}, the implementation should |
| also support a corresponding change in what is a legal |
| @code{identifier_letter}.” |
| @end quotation |
| |
| Not all wide character modes follow this advice, in particular the JIS |
| and IEC modes reflect standard usage in Japan, and in these encoding, |
| the upper half of the Latin-1 set is not part of the wide-character |
| subset, since the most significant bit is used for wide character |
| encoding. However, this only applies to the external forms. Internally |
| there is no such restriction. |
| |
| @geindex Integer types |
| |
| @node RM 3 5 4 28 Integer Types,RM 3 5 4 29 Integer Types,RM 3 5 2 5 Alternative Character Sets,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21f} |
| @section RM 3.5.4(28): Integer Types |
| |
| |
| @quotation |
| |
| “An implementation should support @code{Long_Integer} in addition to |
| @code{Integer} if the target machine supports 32-bit (or longer) |
| arithmetic. No other named integer subtypes are recommended for package |
| @code{Standard}. Instead, appropriate named integer subtypes should be |
| provided in the library package @code{Interfaces} (see B.2).” |
| @end quotation |
| |
| @code{Long_Integer} is supported. Other standard integer types are supported |
| so this advice is not fully followed. These types |
| are supported for convenient interface to C, and so that all hardware |
| types of the machine are easily available. |
| |
| @node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{220} |
| @section RM 3.5.4(29): Integer Types |
| |
| |
| @quotation |
| |
| “An implementation for a two’s complement machine should support |
| modular types with a binary modulus up to @code{System.Max_Int*2+2}. An |
| implementation should support a non-binary modules up to @code{Integer'Last}.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Enumeration values |
| |
| @node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{221} |
| @section RM 3.5.5(8): Enumeration Values |
| |
| |
| @quotation |
| |
| “For the evaluation of a call on @code{S'Pos} for an enumeration |
| subtype, if the value of the operand does not correspond to the internal |
| code for any enumeration literal of its type (perhaps due to an |
| un-initialized variable), then the implementation should raise |
| @code{Program_Error}. This is particularly important for enumeration |
| types with noncontiguous internal codes specified by an |
| enumeration_representation_clause.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Float types |
| |
| @node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{222} |
| @section RM 3.5.7(17): Float Types |
| |
| |
| @quotation |
| |
| “An implementation should support @code{Long_Float} in addition to |
| @code{Float} if the target machine supports 11 or more digits of |
| precision. No other named floating point subtypes are recommended for |
| package @code{Standard}. Instead, appropriate named floating point subtypes |
| should be provided in the library package @code{Interfaces} (see B.2).” |
| @end quotation |
| |
| @code{Short_Float} and @code{Long_Long_Float} are also provided. The |
| former provides improved compatibility with other implementations |
| supporting this type. The latter corresponds to the highest precision |
| floating-point type supported by the hardware. On most machines, this |
| will be the same as @code{Long_Float}, but on some machines, it will |
| correspond to the IEEE extended form. The notable case is all x86 |
| implementations, where @code{Long_Long_Float} corresponds to the 80-bit |
| extended precision format supported in hardware on this processor. |
| Note that the 128-bit format on SPARC is not supported, since this |
| is a software rather than a hardware format. |
| |
| @geindex Multidimensional arrays |
| |
| @geindex Arrays |
| @geindex multidimensional |
| |
| @node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{223} |
| @section RM 3.6.2(11): Multidimensional Arrays |
| |
| |
| @quotation |
| |
| “An implementation should normally represent multidimensional arrays in |
| row-major order, consistent with the notation used for multidimensional |
| array aggregates (see 4.3.3). However, if a pragma @code{Convention} |
| (@code{Fortran}, …) applies to a multidimensional array type, then |
| column-major order should be used instead (see B.5, @emph{Interfacing with Fortran}).” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Duration'Small |
| |
| @node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{224} |
| @section RM 9.6(30-31): Duration’Small |
| |
| |
| @quotation |
| |
| “Whenever possible in an implementation, the value of @code{Duration'Small} |
| should be no greater than 100 microseconds.” |
| @end quotation |
| |
| Followed. (@code{Duration'Small} = 10**(-9)). |
| |
| @quotation |
| |
| “The time base for @code{delay_relative_statements} should be monotonic; |
| it need not be the same time base as used for @code{Calendar.Clock}.” |
| @end quotation |
| |
| Followed. |
| |
| @node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{225} |
| @section RM 10.2.1(12): Consistent Representation |
| |
| |
| @quotation |
| |
| “In an implementation, a type declared in a pre-elaborated package should |
| have the same representation in every elaboration of a given version of |
| the package, whether the elaborations occur in distinct executions of |
| the same program, or in executions of distinct programs or partitions |
| that include the given version.” |
| @end quotation |
| |
| Followed, except in the case of tagged types. Tagged types involve |
| implicit pointers to a local copy of a dispatch table, and these pointers |
| have representations which thus depend on a particular elaboration of the |
| package. It is not easy to see how it would be possible to follow this |
| advice without severely impacting efficiency of execution. |
| |
| @geindex Exception information |
| |
| @node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{226} |
| @section RM 11.4.1(19): Exception Information |
| |
| |
| @quotation |
| |
| “@code{Exception_Message} by default and @code{Exception_Information} |
| should produce information useful for |
| debugging. @code{Exception_Message} should be short, about one |
| line. @code{Exception_Information} can be long. @code{Exception_Message} |
| should not include the |
| @code{Exception_Name}. @code{Exception_Information} should include both |
| the @code{Exception_Name} and the @code{Exception_Message}.” |
| @end quotation |
| |
| Followed. For each exception that doesn’t have a specified |
| @code{Exception_Message}, the compiler generates one containing the location |
| of the raise statement. This location has the form ‘file_name:line’, where |
| file_name is the short file name (without path information) and line is the line |
| number in the file. Note that in the case of the Zero Cost Exception |
| mechanism, these messages become redundant with the Exception_Information that |
| contains a full backtrace of the calling sequence, so they are disabled. |
| To disable explicitly the generation of the source location message, use the |
| Pragma @code{Discard_Names}. |
| |
| @geindex Suppression of checks |
| |
| @geindex Checks |
| @geindex suppression of |
| |
| @node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{227} |
| @section RM 11.5(28): Suppression of Checks |
| |
| |
| @quotation |
| |
| “The implementation should minimize the code executed for checks that |
| have been suppressed.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Representation clauses |
| |
| @node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{228} |
| @section RM 13.1 (21-24): Representation Clauses |
| |
| |
| @quotation |
| |
| “The recommended level of support for all representation items is |
| qualified as follows: |
| |
| An implementation need not support representation items containing |
| nonstatic expressions, except that an implementation should support a |
| representation item for a given entity if each nonstatic expression in |
| the representation item is a name that statically denotes a constant |
| declared before the entity.” |
| @end quotation |
| |
| Followed. In fact, GNAT goes beyond the recommended level of support |
| by allowing nonstatic expressions in some representation clauses even |
| without the need to declare constants initialized with the values of |
| such expressions. |
| For example: |
| |
| @example |
| X : Integer; |
| Y : Float; |
| for Y'Address use X'Address;>> |
| |
| |
| "An implementation need not support a specification for the `@w{`}Size`@w{`} |
| for a given composite subtype, nor the size or storage place for an |
| object (including a component) of a given composite subtype, unless the |
| constraints on the subtype and its composite subcomponents (if any) are |
| all static constraints." |
| @end example |
| |
| Followed. Size Clauses are not permitted on nonstatic components, as |
| described above. |
| |
| @quotation |
| |
| “An aliased component, or a component whose type is by-reference, should |
| always be allocated at an addressable location.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Packed types |
| |
| @node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{229} |
| @section RM 13.2(6-8): Packed Types |
| |
| |
| @quotation |
| |
| “If a type is packed, then the implementation should try to minimize |
| storage allocated to objects of the type, possibly at the expense of |
| speed of accessing components, subject to reasonable complexity in |
| addressing calculations. |
| |
| The recommended level of support pragma @code{Pack} is: |
| |
| For a packed record type, the components should be packed as tightly as |
| possible subject to the Sizes of the component subtypes, and subject to |
| any @emph{record_representation_clause} that applies to the type; the |
| implementation may, but need not, reorder components or cross aligned |
| word boundaries to improve the packing. A component whose @code{Size} is |
| greater than the word size may be allocated an integral number of words.” |
| @end quotation |
| |
| Followed. Tight packing of arrays is supported for all component sizes |
| up to 64-bits. If the array component size is 1 (that is to say, if |
| the component is a boolean type or an enumeration type with two values) |
| then values of the type are implicitly initialized to zero. This |
| happens both for objects of the packed type, and for objects that have a |
| subcomponent of the packed type. |
| |
| @quotation |
| |
| “An implementation should support Address clauses for imported |
| subprograms.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Address clauses |
| |
| @node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{22a} |
| @section RM 13.3(14-19): Address Clauses |
| |
| |
| @quotation |
| |
| “For an array @code{X}, @code{X'Address} should point at the first |
| component of the array, and not at the array bounds.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “The recommended level of support for the @code{Address} attribute is: |
| |
| @code{X'Address} should produce a useful result if @code{X} is an |
| object that is aliased or of a by-reference type, or is an entity whose |
| @code{Address} has been specified.” |
| @end quotation |
| |
| Followed. A valid address will be produced even if none of those |
| conditions have been met. If necessary, the object is forced into |
| memory to ensure the address is valid. |
| |
| @quotation |
| |
| “An implementation should support @code{Address} clauses for imported |
| subprograms.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “Objects (including subcomponents) that are aliased or of a by-reference |
| type should be allocated on storage element boundaries.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “If the @code{Address} of an object is specified, or it is imported or exported, |
| then the implementation should not perform optimizations based on |
| assumptions of no aliases.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Alignment clauses |
| |
| @node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{22b} |
| @section RM 13.3(29-35): Alignment Clauses |
| |
| |
| @quotation |
| |
| “The recommended level of support for the @code{Alignment} attribute for |
| subtypes is: |
| |
| An implementation should support specified Alignments that are factors |
| and multiples of the number of storage elements per word, subject to the |
| following:” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An implementation need not support specified Alignments for |
| combinations of Sizes and Alignments that cannot be easily |
| loaded and stored by available machine instructions.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An implementation need not support specified Alignments that are |
| greater than the maximum @code{Alignment} the implementation ever returns by |
| default.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “The recommended level of support for the @code{Alignment} attribute for |
| objects is: |
| |
| Same as above, for subtypes, but in addition:” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “For stand-alone library-level objects of statically constrained |
| subtypes, the implementation should support all alignments |
| supported by the target linker. For example, page alignment is likely to |
| be supported for such objects, but not for subtypes.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Size clauses |
| |
| @node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22c} |
| @section RM 13.3(42-43): Size Clauses |
| |
| |
| @quotation |
| |
| “The recommended level of support for the @code{Size} attribute of |
| objects is: |
| |
| A @code{Size} clause should be supported for an object if the specified |
| @code{Size} is at least as large as its subtype’s @code{Size}, and |
| corresponds to a size in storage elements that is a multiple of the |
| object’s @code{Alignment} (if the @code{Alignment} is nonzero).” |
| @end quotation |
| |
| Followed. |
| |
| @node RM 13 3 50-56 Size Clauses,RM 13 3 71-73 Component Size Clauses,RM 13 3 42-43 Size Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22d} |
| @section RM 13.3(50-56): Size Clauses |
| |
| |
| @quotation |
| |
| “If the @code{Size} of a subtype is specified, and allows for efficient |
| independent addressability (see 9.10) on the target architecture, then |
| the @code{Size} of the following objects of the subtype should equal the |
| @code{Size} of the subtype: |
| |
| Aliased objects (including components).” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “@cite{Size} clause on a composite subtype should not affect the |
| internal layout of components.” |
| @end quotation |
| |
| Followed. But note that this can be overridden by use of the implementation |
| pragma Implicit_Packing in the case of packed arrays. |
| |
| @quotation |
| |
| “The recommended level of support for the @code{Size} attribute of subtypes is: |
| |
| The @code{Size} (if not specified) of a static discrete or fixed point |
| subtype should be the number of bits needed to represent each value |
| belonging to the subtype using an unbiased representation, leaving space |
| for a sign bit only if the subtype contains negative values. If such a |
| subtype is a first subtype, then an implementation should support a |
| specified @code{Size} for it that reflects this representation.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “For a subtype implemented with levels of indirection, the @code{Size} |
| should include the size of the pointers, but not the size of what they |
| point at.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Component_Size clauses |
| |
| @node RM 13 3 71-73 Component Size Clauses,RM 13 4 9-10 Enumeration Representation Clauses,RM 13 3 50-56 Size Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22e} |
| @section RM 13.3(71-73): Component Size Clauses |
| |
| |
| @quotation |
| |
| “The recommended level of support for the @code{Component_Size} |
| attribute is: |
| |
| An implementation need not support specified @code{Component_Sizes} that are |
| less than the @code{Size} of the component subtype.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An implementation should support specified Component_Sizes that |
| are factors and multiples of the word size. For such |
| Component_Sizes, the array should contain no gaps between |
| components. For other Component_Sizes (if supported), the array |
| should contain no gaps between components when packing is also |
| specified; the implementation should forbid this combination in cases |
| where it cannot support a no-gaps representation.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Enumeration representation clauses |
| |
| @geindex Representation clauses |
| @geindex enumeration |
| |
| @node RM 13 4 9-10 Enumeration Representation Clauses,RM 13 5 1 17-22 Record Representation Clauses,RM 13 3 71-73 Component Size Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22f} |
| @section RM 13.4(9-10): Enumeration Representation Clauses |
| |
| |
| @quotation |
| |
| “The recommended level of support for enumeration representation clauses |
| is: |
| |
| An implementation need not support enumeration representation clauses |
| for boolean types, but should at minimum support the internal codes in |
| the range @code{System.Min_Int .. System.Max_Int}.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Record representation clauses |
| |
| @geindex Representation clauses |
| @geindex records |
| |
| @node RM 13 5 1 17-22 Record Representation Clauses,RM 13 5 2 5 Storage Place Attributes,RM 13 4 9-10 Enumeration Representation Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{230} |
| @section RM 13.5.1(17-22): Record Representation Clauses |
| |
| |
| @quotation |
| |
| “The recommended level of support for |
| @emph{record_representation_clause}s is: |
| |
| An implementation should support storage places that can be extracted |
| with a load, mask, shift sequence of machine code, and set with a load, |
| shift, mask, store sequence, given the available machine instructions |
| and run-time model.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “A storage place should be supported if its size is equal to the |
| @code{Size} of the component subtype, and it starts and ends on a |
| boundary that obeys the @code{Alignment} of the component subtype.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “If the default bit ordering applies to the declaration of a given type, |
| then for a component whose subtype’s @code{Size} is less than the word |
| size, any storage place that does not cross an aligned word boundary |
| should be supported.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An implementation may reserve a storage place for the tag field of a |
| tagged type, and disallow other components from overlapping that place.” |
| @end quotation |
| |
| Followed. The storage place for the tag field is the beginning of the tagged |
| record, and its size is Address’Size. GNAT will reject an explicit component |
| clause for the tag field. |
| |
| @quotation |
| |
| “An implementation need not support a @emph{component_clause} for a |
| component of an extension part if the storage place is not after the |
| storage places of all components of the parent type, whether or not |
| those storage places had been specified.” |
| @end quotation |
| |
| Followed. The above advice on record representation clauses is followed, |
| and all mentioned features are implemented. |
| |
| @geindex Storage place attributes |
| |
| @node RM 13 5 2 5 Storage Place Attributes,RM 13 5 3 7-8 Bit Ordering,RM 13 5 1 17-22 Record Representation Clauses,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{231} |
| @section RM 13.5.2(5): Storage Place Attributes |
| |
| |
| @quotation |
| |
| “If a component is represented using some form of pointer (such as an |
| offset) to the actual data of the component, and this data is contiguous |
| with the rest of the object, then the storage place attributes should |
| reflect the place of the actual data, not the pointer. If a component is |
| allocated discontinuously from the rest of the object, then a warning |
| should be generated upon reference to one of its storage place |
| attributes.” |
| @end quotation |
| |
| Followed. There are no such components in GNAT. |
| |
| @geindex Bit ordering |
| |
| @node RM 13 5 3 7-8 Bit Ordering,RM 13 7 37 Address as Private,RM 13 5 2 5 Storage Place Attributes,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{232} |
| @section RM 13.5.3(7-8): Bit Ordering |
| |
| |
| @quotation |
| |
| “The recommended level of support for the non-default bit ordering is: |
| |
| If @code{Word_Size} = @code{Storage_Unit}, then the implementation |
| should support the non-default bit ordering in addition to the default |
| bit ordering.” |
| @end quotation |
| |
| Followed. Word size does not equal storage size in this implementation. |
| Thus non-default bit ordering is not supported. |
| |
| @geindex Address |
| @geindex as private type |
| |
| @node RM 13 7 37 Address as Private,RM 13 7 1 16 Address Operations,RM 13 5 3 7-8 Bit Ordering,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{233} |
| @section RM 13.7(37): Address as Private |
| |
| |
| @quotation |
| |
| “@cite{Address} should be of a private type.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Operations |
| @geindex on `@w{`}Address`@w{`} |
| |
| @geindex Address |
| @geindex operations of |
| |
| @node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{234} |
| @section RM 13.7.1(16): Address Operations |
| |
| |
| @quotation |
| |
| “Operations in @code{System} and its children should reflect the target |
| environment semantics as closely as is reasonable. For example, on most |
| machines, it makes sense for address arithmetic to ‘wrap around’. |
| Operations that do not make sense should raise @code{Program_Error}.” |
| @end quotation |
| |
| Followed. Address arithmetic is modular arithmetic that wraps around. No |
| operation raises @code{Program_Error}, since all operations make sense. |
| |
| @geindex Unchecked conversion |
| |
| @node RM 13 9 14-17 Unchecked Conversion,RM 13 11 23-25 Implicit Heap Usage,RM 13 7 1 16 Address Operations,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{235} |
| @section RM 13.9(14-17): Unchecked Conversion |
| |
| |
| @quotation |
| |
| “The @code{Size} of an array object should not include its bounds; hence, |
| the bounds should not be part of the converted data.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “The implementation should not generate unnecessary run-time checks to |
| ensure that the representation of @code{S} is a representation of the |
| target type. It should take advantage of the permission to return by |
| reference when possible. Restrictions on unchecked conversions should be |
| avoided unless required by the target environment.” |
| @end quotation |
| |
| Followed. There are no restrictions on unchecked conversion. A warning is |
| generated if the source and target types do not have the same size since |
| the semantics in this case may be target dependent. |
| |
| @quotation |
| |
| “The recommended level of support for unchecked conversions is: |
| |
| Unchecked conversions should be supported and should be reversible in |
| the cases where this clause defines the result. To enable meaningful use |
| of unchecked conversion, a contiguous representation should be used for |
| elementary subtypes, for statically constrained array subtypes whose |
| component subtype is one of the subtypes described in this paragraph, |
| and for record subtypes without discriminants whose component subtypes |
| are described in this paragraph.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Heap usage |
| @geindex implicit |
| |
| @node RM 13 11 23-25 Implicit Heap Usage,RM 13 11 2 17 Unchecked Deallocation,RM 13 9 14-17 Unchecked Conversion,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{236} |
| @section RM 13.11(23-25): Implicit Heap Usage |
| |
| |
| @quotation |
| |
| “An implementation should document any cases in which it dynamically |
| allocates heap storage for a purpose other than the evaluation of an |
| allocator.” |
| @end quotation |
| |
| Followed, the only other points at which heap storage is dynamically |
| allocated are as follows: |
| |
| |
| @itemize * |
| |
| @item |
| At initial elaboration time, to allocate dynamically sized global |
| objects. |
| |
| @item |
| To allocate space for a task when a task is created. |
| |
| @item |
| To extend the secondary stack dynamically when needed. The secondary |
| stack is used for returning variable length results. |
| @end itemize |
| |
| |
| @quotation |
| |
| “A default (implementation-provided) storage pool for an |
| access-to-constant type should not have overhead to support deallocation of |
| individual objects.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “A storage pool for an anonymous access type should be created at the |
| point of an allocator for the type, and be reclaimed when the designated |
| object becomes inaccessible.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Unchecked deallocation |
| |
| @node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 1 6 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{237} |
| @section RM 13.11.2(17): Unchecked Deallocation |
| |
| |
| @quotation |
| |
| “For a standard storage pool, @code{Free} should actually reclaim the |
| storage.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Stream oriented attributes |
| |
| @node RM 13 13 2 1 6 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{238} |
| @section RM 13.13.2(1.6): Stream Oriented Attributes |
| |
| |
| @quotation |
| |
| “If not specified, the value of Stream_Size for an elementary type |
| should be the number of bits that corresponds to the minimum number of |
| stream elements required by the first subtype of the type, rounded up |
| to the nearest factor or multiple of the word size that is also a |
| multiple of the stream element size.” |
| @end quotation |
| |
| Followed, except that the number of stream elements is 1, 2, 3, 4 or 8. |
| The Stream_Size may be used to override the default choice. |
| |
| The default implementation is based on direct binary representations and is |
| therefore target- and endianness-dependent. To address this issue, GNAT also |
| supplies an alternate implementation of the stream attributes @code{Read} and |
| @code{Write}, which uses the target-independent XDR standard representation for |
| scalar types. This XDR alternative can be enabled via the binder switch -xdr. |
| |
| @geindex XDR representation |
| |
| @geindex Read attribute |
| |
| @geindex Write attribute |
| |
| @geindex Stream oriented attributes |
| |
| @node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 1 6 Stream Oriented Attributes,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{239} |
| @section RM A.1(52): Names of Predefined Numeric Types |
| |
| |
| @quotation |
| |
| “If an implementation provides additional named predefined integer types, |
| then the names should end with @code{Integer} as in |
| @code{Long_Integer}. If an implementation provides additional named |
| predefined floating point types, then the names should end with |
| @code{Float} as in @code{Long_Float}.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Ada.Characters.Handling |
| |
| @node RM A 3 2 49 Ada Characters Handling,RM A 4 4 106 Bounded-Length String Handling,RM A 1 52 Names of Predefined Numeric Types,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{23a} |
| @section RM A.3.2(49): @code{Ada.Characters.Handling} |
| |
| |
| @quotation |
| |
| “If an implementation provides a localized definition of @code{Character} |
| or @code{Wide_Character}, then the effects of the subprograms in |
| @code{Characters.Handling} should reflect the localizations. |
| See also 3.5.2.” |
| @end quotation |
| |
| Followed. GNAT provides no such localized definitions. |
| |
| @geindex Bounded-length strings |
| |
| @node RM A 4 4 106 Bounded-Length String Handling,RM A 5 2 46-47 Random Number Generation,RM A 3 2 49 Ada Characters Handling,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{23b} |
| @section RM A.4.4(106): Bounded-Length String Handling |
| |
| |
| @quotation |
| |
| “Bounded string objects should not be implemented by implicit pointers |
| and dynamic allocation.” |
| @end quotation |
| |
| Followed. No implicit pointers or dynamic allocation are used. |
| |
| @geindex Random number generation |
| |
| @node RM A 5 2 46-47 Random Number Generation,RM A 10 7 23 Get_Immediate,RM A 4 4 106 Bounded-Length String Handling,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23c} |
| @section RM A.5.2(46-47): Random Number Generation |
| |
| |
| @quotation |
| |
| “Any storage associated with an object of type @code{Generator} should be |
| reclaimed on exit from the scope of the object.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “If the generator period is sufficiently long in relation to the number |
| of distinct initiator values, then each possible value of |
| @code{Initiator} passed to @code{Reset} should initiate a sequence of |
| random numbers that does not, in a practical sense, overlap the sequence |
| initiated by any other value. If this is not possible, then the mapping |
| between initiator values and generator states should be a rapidly |
| varying function of the initiator value.” |
| @end quotation |
| |
| Followed. The generator period is sufficiently long for the first |
| condition here to hold true. |
| |
| @geindex Get_Immediate |
| |
| @node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23d} |
| @section RM A.10.7(23): @code{Get_Immediate} |
| |
| |
| @quotation |
| |
| “The @code{Get_Immediate} procedures should be implemented with |
| unbuffered input. For a device such as a keyboard, input should be |
| available if a key has already been typed, whereas for a disk |
| file, input should always be available except at end of file. For a file |
| associated with a keyboard-like device, any line-editing features of the |
| underlying operating system should be disabled during the execution of |
| @code{Get_Immediate}.” |
| @end quotation |
| |
| Followed on all targets except VxWorks. For VxWorks, there is no way to |
| provide this functionality that does not result in the input buffer being |
| flushed before the @code{Get_Immediate} call. A special unit |
| @code{Interfaces.Vxworks.IO} is provided that contains routines to enable |
| this functionality. |
| |
| @geindex Containers |
| |
| @node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{23e} |
| @section RM A.18: @code{Containers} |
| |
| |
| All implementation advice pertaining to Ada.Containers and its |
| child units (that is, all implementation advice occurring within |
| section A.18 and its subsections) is followed except for A.18.24(17): |
| |
| @quotation |
| |
| “Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “ |
| @end quotation |
| |
| The implementations of the two Reference_Preserving_Key functions of |
| the generic package Ada.Containers.Bounded_Ordered_Sets each currently make |
| use of dynamic allocation; other operations on bounded ordered set objects |
| follow the implementation advice. |
| |
| @geindex Export |
| |
| @node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23f} |
| @section RM B.1(39-41): Pragma @code{Export} |
| |
| |
| @quotation |
| |
| “If an implementation supports pragma @code{Export} to a given language, |
| then it should also allow the main subprogram to be written in that |
| language. It should support some mechanism for invoking the elaboration |
| of the Ada library units included in the system, and for invoking the |
| finalization of the environment task. On typical systems, the |
| recommended mechanism is to provide two subprograms whose link names are |
| @code{adainit} and @code{adafinal}. @code{adainit} should contain the |
| elaboration code for library units. @code{adafinal} should contain the |
| finalization code. These subprograms should have no effect the second |
| and subsequent time they are called.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “Automatic elaboration of pre-elaborated packages should be |
| provided when pragma @code{Export} is supported.” |
| @end quotation |
| |
| Followed when the main program is in Ada. If the main program is in a |
| foreign language, then |
| @code{adainit} must be called to elaborate pre-elaborated |
| packages. |
| |
| @quotation |
| |
| “For each supported convention @emph{L} other than @code{Intrinsic}, an |
| implementation should support @code{Import} and @code{Export} pragmas |
| for objects of @emph{L}-compatible types and for subprograms, and pragma |
| @cite{Convention} for @emph{L}-eligible types and for subprograms, |
| presuming the other language has corresponding features. Pragma |
| @code{Convention} need not be supported for scalar types.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Package Interfaces |
| |
| @geindex Interfaces |
| |
| @node RM B 2 12-13 Package Interfaces,RM B 3 63-71 Interfacing with C,RM B 1 39-41 Pragma Export,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{240} |
| @section RM B.2(12-13): Package @code{Interfaces} |
| |
| |
| @quotation |
| |
| “For each implementation-defined convention identifier, there should be a |
| child package of package Interfaces with the corresponding name. This |
| package should contain any declarations that would be useful for |
| interfacing to the language (implementation) represented by the |
| convention. Any declarations useful for interfacing to any language on |
| the given hardware architecture should be provided directly in |
| @code{Interfaces}.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An implementation supporting an interface to C, COBOL, or Fortran should |
| provide the corresponding package or packages described in the following |
| clauses.” |
| @end quotation |
| |
| Followed. GNAT provides all the packages described in this section. |
| |
| @geindex C |
| @geindex interfacing with |
| |
| @node RM B 3 63-71 Interfacing with C,RM B 4 95-98 Interfacing with COBOL,RM B 2 12-13 Package Interfaces,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{241} |
| @section RM B.3(63-71): Interfacing with C |
| |
| |
| @quotation |
| |
| “An implementation should support the following interface correspondences |
| between Ada and C.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada procedure corresponds to a void-returning C function.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada function corresponds to a non-void C function.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada @code{in} scalar parameter is passed as a scalar argument to a C |
| function.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada @code{in} parameter of an access-to-object type with designated |
| type @code{T} is passed as a @code{t*} argument to a C function, |
| where @code{t} is the C type corresponding to the Ada type @code{T}.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} |
| parameter of an elementary type @code{T}, is passed as a @code{t*} |
| argument to a C function, where @code{t} is the C type corresponding to |
| the Ada type @code{T}. In the case of an elementary @code{out} or |
| @code{in out} parameter, a pointer to a temporary copy is used to |
| preserve by-copy semantics.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada parameter of a record type @code{T}, of any mode, is passed as a |
| @code{t*} argument to a C function, where @code{t} is the C |
| structure corresponding to the Ada type @code{T}.” |
| @end quotation |
| |
| Followed. This convention may be overridden by the use of the C_Pass_By_Copy |
| pragma, or Convention, or by explicitly specifying the mechanism for a given |
| call using an extended import or export pragma. |
| |
| @quotation |
| |
| “An Ada parameter of an array type with component type @code{T}, of any |
| mode, is passed as a @code{t*} argument to a C function, where |
| @code{t} is the C type corresponding to the Ada type @code{T}.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada parameter of an access-to-subprogram type is passed as a pointer |
| to a C function whose prototype corresponds to the designated |
| subprogram’s specification.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex COBOL |
| @geindex interfacing with |
| |
| @node RM B 4 95-98 Interfacing with COBOL,RM B 5 22-26 Interfacing with Fortran,RM B 3 63-71 Interfacing with C,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{242} |
| @section RM B.4(95-98): Interfacing with COBOL |
| |
| |
| @quotation |
| |
| “An Ada implementation should support the following interface |
| correspondences between Ada and COBOL.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of |
| the COBOL type corresponding to @code{T}.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of |
| the corresponding COBOL type.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the |
| COBOL type corresponding to the Ada parameter type; for scalars, a local |
| copy is used if necessary to ensure by-copy semantics.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Fortran |
| @geindex interfacing with |
| |
| @node RM B 5 22-26 Interfacing with Fortran,RM C 1 3-5 Access to Machine Operations,RM B 4 95-98 Interfacing with COBOL,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{243} |
| @section RM B.5(22-26): Interfacing with Fortran |
| |
| |
| @quotation |
| |
| “An Ada implementation should support the following interface |
| correspondences between Ada and Fortran:” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada procedure corresponds to a Fortran subroutine.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada function corresponds to a Fortran function.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada parameter of an elementary, array, or record type @code{T} is |
| passed as a @code{T} argument to a Fortran procedure, where @code{T} is |
| the Fortran type corresponding to the Ada type @code{T}, and where the |
| INTENT attribute of the corresponding dummy argument matches the Ada |
| formal parameter mode; the Fortran implementation’s parameter passing |
| conventions are used. For elementary types, a local copy is used if |
| necessary to ensure by-copy semantics.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “An Ada parameter of an access-to-subprogram type is passed as a |
| reference to a Fortran procedure whose interface corresponds to the |
| designated subprogram’s specification.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Machine operations |
| |
| @node RM C 1 3-5 Access to Machine Operations,RM C 1 10-16 Access to Machine Operations,RM B 5 22-26 Interfacing with Fortran,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{244} |
| @section RM C.1(3-5): Access to Machine Operations |
| |
| |
| @quotation |
| |
| “The machine code or intrinsic support should allow access to all |
| operations normally available to assembly language programmers for the |
| target environment, including privileged instructions, if any.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “The interfacing pragmas (see Annex B) should support interface to |
| assembler; the default assembler should be associated with the |
| convention identifier @code{Assembler}.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “If an entity is exported to assembly language, then the implementation |
| should allocate it at an addressable location, and should ensure that it |
| is retained by the linking process, even if not otherwise referenced |
| from the Ada code. The implementation should assume that any call to a |
| machine code or assembler subprogram is allowed to read or update every |
| object that is specified as exported.” |
| @end quotation |
| |
| Followed. |
| |
| @node RM C 1 10-16 Access to Machine Operations,RM C 3 28 Interrupt Support,RM C 1 3-5 Access to Machine Operations,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{245} |
| @section RM C.1(10-16): Access to Machine Operations |
| |
| |
| @quotation |
| |
| “The implementation should ensure that little or no overhead is |
| associated with calling intrinsic and machine-code subprograms.” |
| @end quotation |
| |
| Followed for both intrinsics and machine-code subprograms. |
| |
| @quotation |
| |
| “It is recommended that intrinsic subprograms be provided for convenient |
| access to any machine operations that provide special capabilities or |
| efficiency and that are not otherwise available through the language |
| constructs.” |
| @end quotation |
| |
| Followed. A full set of machine operation intrinsic subprograms is provided. |
| |
| @quotation |
| |
| “Atomic read-modify-write operations—e.g., test and set, compare and |
| swap, decrement and test, enqueue/dequeue.” |
| @end quotation |
| |
| Followed on any target supporting such operations. |
| |
| @quotation |
| |
| “Standard numeric functions—e.g.:, sin, log.” |
| @end quotation |
| |
| Followed on any target supporting such operations. |
| |
| @quotation |
| |
| “String manipulation operations—e.g.:, translate and test.” |
| @end quotation |
| |
| Followed on any target supporting such operations. |
| |
| @quotation |
| |
| “Vector operations—e.g.:, compare vector against thresholds.” |
| @end quotation |
| |
| Followed on any target supporting such operations. |
| |
| @quotation |
| |
| “Direct operations on I/O ports.” |
| @end quotation |
| |
| Followed on any target supporting such operations. |
| |
| @geindex Interrupt support |
| |
| @node RM C 3 28 Interrupt Support,RM C 3 1 20-21 Protected Procedure Handlers,RM C 1 10-16 Access to Machine Operations,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{246} |
| @section RM C.3(28): Interrupt Support |
| |
| |
| @quotation |
| |
| “If the @code{Ceiling_Locking} policy is not in effect, the |
| implementation should provide means for the application to specify which |
| interrupts are to be blocked during protected actions, if the underlying |
| system allows for a finer-grain control of interrupt blocking.” |
| @end quotation |
| |
| Followed. The underlying system does not allow for finer-grain control |
| of interrupt blocking. |
| |
| @geindex Protected procedure handlers |
| |
| @node RM C 3 1 20-21 Protected Procedure Handlers,RM C 3 2 25 Package Interrupts,RM C 3 28 Interrupt Support,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{247} |
| @section RM C.3.1(20-21): Protected Procedure Handlers |
| |
| |
| @quotation |
| |
| “Whenever possible, the implementation should allow interrupt handlers to |
| be called directly by the hardware.” |
| @end quotation |
| |
| Followed on any target where the underlying operating system permits |
| such direct calls. |
| |
| @quotation |
| |
| “Whenever practical, violations of any |
| implementation-defined restrictions should be detected before run time.” |
| @end quotation |
| |
| Followed. Compile time warnings are given when possible. |
| |
| @geindex Package `@w{`}Interrupts`@w{`} |
| |
| @geindex Interrupts |
| |
| @node RM C 3 2 25 Package Interrupts,RM C 4 14 Pre-elaboration Requirements,RM C 3 1 20-21 Protected Procedure Handlers,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{248} |
| @section RM C.3.2(25): Package @code{Interrupts} |
| |
| |
| @quotation |
| |
| “If implementation-defined forms of interrupt handler procedures are |
| supported, such as protected procedures with parameters, then for each |
| such form of a handler, a type analogous to @code{Parameterless_Handler} |
| should be specified in a child package of @code{Interrupts}, with the |
| same operations as in the predefined package Interrupts.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Pre-elaboration requirements |
| |
| @node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{249} |
| @section RM C.4(14): Pre-elaboration Requirements |
| |
| |
| @quotation |
| |
| “It is recommended that pre-elaborated packages be implemented in such a |
| way that there should be little or no code executed at run time for the |
| elaboration of entities not already covered by the Implementation |
| Requirements.” |
| @end quotation |
| |
| Followed. Executable code is generated in some cases, e.g., loops |
| to initialize large arrays. |
| |
| @node RM C 5 8 Pragma Discard_Names,RM C 7 2 30 The Package Task_Attributes,RM C 4 14 Pre-elaboration Requirements,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{24a} |
| @section RM C.5(8): Pragma @code{Discard_Names} |
| |
| |
| @quotation |
| |
| “If the pragma applies to an entity, then the implementation should |
| reduce the amount of storage used for storing names associated with that |
| entity.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Package Task_Attributes |
| |
| @geindex Task_Attributes |
| |
| @node RM C 7 2 30 The Package Task_Attributes,RM D 3 17 Locking Policies,RM C 5 8 Pragma Discard_Names,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{24b} |
| @section RM C.7.2(30): The Package Task_Attributes |
| |
| |
| @quotation |
| |
| “Some implementations are targeted to domains in which memory use at run |
| time must be completely deterministic. For such implementations, it is |
| recommended that the storage for task attributes will be pre-allocated |
| statically and not from the heap. This can be accomplished by either |
| placing restrictions on the number and the size of the task’s |
| attributes, or by using the pre-allocated storage for the first @code{N} |
| attribute objects, and the heap for the others. In the latter case, |
| @code{N} should be documented.” |
| @end quotation |
| |
| Not followed. This implementation is not targeted to such a domain. |
| |
| @geindex Locking Policies |
| |
| @node RM D 3 17 Locking Policies,RM D 4 16 Entry Queuing Policies,RM C 7 2 30 The Package Task_Attributes,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{24c} |
| @section RM D.3(17): Locking Policies |
| |
| |
| @quotation |
| |
| “The implementation should use names that end with @code{_Locking} for |
| locking policies defined by the implementation.” |
| @end quotation |
| |
| Followed. Two implementation-defined locking policies are defined, |
| whose names (@code{Inheritance_Locking} and |
| @code{Concurrent_Readers_Locking}) follow this suggestion. |
| |
| @geindex Entry queuing policies |
| |
| @node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24d} |
| @section RM D.4(16): Entry Queuing Policies |
| |
| |
| @quotation |
| |
| “Names that end with @code{_Queuing} should be used |
| for all implementation-defined queuing policies.” |
| @end quotation |
| |
| Followed. No such implementation-defined queuing policies exist. |
| |
| @geindex Preemptive abort |
| |
| @node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24e} |
| @section RM D.6(9-10): Preemptive Abort |
| |
| |
| @quotation |
| |
| “Even though the @emph{abort_statement} is included in the list of |
| potentially blocking operations (see 9.5.1), it is recommended that this |
| statement be implemented in a way that never requires the task executing |
| the @emph{abort_statement} to block.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “On a multi-processor, the delay associated with aborting a task on |
| another processor should be bounded; the implementation should use |
| periodic polling, if necessary, to achieve this.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Tasking restrictions |
| |
| @node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24f} |
| @section RM D.7(21): Tasking Restrictions |
| |
| |
| @quotation |
| |
| “When feasible, the implementation should take advantage of the specified |
| restrictions to produce a more efficient implementation.” |
| @end quotation |
| |
| GNAT currently takes advantage of these restrictions by providing an optimized |
| run time when the Ravenscar profile and the GNAT restricted run time set |
| of restrictions are specified. See pragma @code{Profile (Ravenscar)} and |
| pragma @code{Profile (Restricted)} for more details. |
| |
| @geindex Time |
| @geindex monotonic |
| |
| @node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{250} |
| @section RM D.8(47-49): Monotonic Time |
| |
| |
| @quotation |
| |
| “When appropriate, implementations should provide configuration |
| mechanisms to change the value of @code{Tick}.” |
| @end quotation |
| |
| Such configuration mechanisms are not appropriate to this implementation |
| and are thus not supported. |
| |
| @quotation |
| |
| “It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} |
| be implemented as transformations of the same time base.” |
| @end quotation |
| |
| Followed. |
| |
| @quotation |
| |
| “It is recommended that the best time base which exists in |
| the underlying system be available to the application through |
| @code{Clock}. @cite{Best} may mean highest accuracy or largest range.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Partition communication subsystem |
| |
| @geindex PCS |
| |
| @node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{251} |
| @section RM E.5(28-29): Partition Communication Subsystem |
| |
| |
| @quotation |
| |
| “Whenever possible, the PCS on the called partition should allow for |
| multiple tasks to call the RPC-receiver with different messages and |
| should allow them to block until the corresponding subprogram body |
| returns.” |
| @end quotation |
| |
| Followed by GLADE, a separately supplied PCS that can be used with |
| GNAT. |
| |
| @quotation |
| |
| “The @code{Write} operation on a stream of type @code{Params_Stream_Type} |
| should raise @code{Storage_Error} if it runs out of space trying to |
| write the @code{Item} into the stream.” |
| @end quotation |
| |
| Followed by GLADE, a separately supplied PCS that can be used with |
| GNAT. |
| |
| @geindex COBOL support |
| |
| @node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{252} |
| @section RM F(7): COBOL Support |
| |
| |
| @quotation |
| |
| “If COBOL (respectively, C) is widely supported in the target |
| environment, implementations supporting the Information Systems Annex |
| should provide the child package @code{Interfaces.COBOL} (respectively, |
| @code{Interfaces.C}) specified in Annex B and should support a |
| @code{convention_identifier} of COBOL (respectively, C) in the interfacing |
| pragmas (see Annex B), thus allowing Ada programs to interface with |
| programs written in that language.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Decimal radix support |
| |
| @node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{253} |
| @section RM F.1(2): Decimal Radix Support |
| |
| |
| @quotation |
| |
| “Packed decimal should be used as the internal representation for objects |
| of subtype @code{S} when @code{S}’Machine_Radix = 10.” |
| @end quotation |
| |
| Not followed. GNAT ignores @code{S}’Machine_Radix and always uses binary |
| representations. |
| |
| @geindex Numerics |
| |
| @node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{254} |
| @section RM G: Numerics |
| |
| |
| @quotation |
| |
| “If Fortran (respectively, C) is widely supported in the target |
| environment, implementations supporting the Numerics Annex |
| should provide the child package @code{Interfaces.Fortran} (respectively, |
| @code{Interfaces.C}) specified in Annex B and should support a |
| @code{convention_identifier} of Fortran (respectively, C) in the interfacing |
| pragmas (see Annex B), thus allowing Ada programs to interface with |
| programs written in that language.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Complex types |
| |
| @node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{255} |
| @section RM G.1.1(56-58): Complex Types |
| |
| |
| @quotation |
| |
| “Because the usual mathematical meaning of multiplication of a complex |
| operand and a real operand is that of the scaling of both components of |
| the former by the latter, an implementation should not perform this |
| operation by first promoting the real operand to complex type and then |
| performing a full complex multiplication. In systems that, in the |
| future, support an Ada binding to IEC 559:1989, the latter technique |
| will not generate the required result when one of the components of the |
| complex operand is infinite. (Explicit multiplication of the infinite |
| component by the zero component obtained during promotion yields a NaN |
| that propagates into the final result.) Analogous advice applies in the |
| case of multiplication of a complex operand and a pure-imaginary |
| operand, and in the case of division of a complex operand by a real or |
| pure-imaginary operand.” |
| @end quotation |
| |
| Not followed. |
| |
| @quotation |
| |
| “Similarly, because the usual mathematical meaning of addition of a |
| complex operand and a real operand is that the imaginary operand remains |
| unchanged, an implementation should not perform this operation by first |
| promoting the real operand to complex type and then performing a full |
| complex addition. In implementations in which the @code{Signed_Zeros} |
| attribute of the component type is @code{True} (and which therefore |
| conform to IEC 559:1989 in regard to the handling of the sign of zero in |
| predefined arithmetic operations), the latter technique will not |
| generate the required result when the imaginary component of the complex |
| operand is a negatively signed zero. (Explicit addition of the negative |
| zero to the zero obtained during promotion yields a positive zero.) |
| Analogous advice applies in the case of addition of a complex operand |
| and a pure-imaginary operand, and in the case of subtraction of a |
| complex operand and a real or pure-imaginary operand.” |
| @end quotation |
| |
| Not followed. |
| |
| @quotation |
| |
| “Implementations in which @code{Real'Signed_Zeros} is @code{True} should |
| attempt to provide a rational treatment of the signs of zero results and |
| result components. As one example, the result of the @code{Argument} |
| function should have the sign of the imaginary component of the |
| parameter @code{X} when the point represented by that parameter lies on |
| the positive real axis; as another, the sign of the imaginary component |
| of the @code{Compose_From_Polar} function should be the same as |
| (respectively, the opposite of) that of the @code{Argument} parameter when that |
| parameter has a value of zero and the @code{Modulus} parameter has a |
| nonnegative (respectively, negative) value.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Complex elementary functions |
| |
| @node RM G 1 2 49 Complex Elementary Functions,RM G 2 4 19 Accuracy Requirements,RM G 1 1 56-58 Complex Types,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{256} |
| @section RM G.1.2(49): Complex Elementary Functions |
| |
| |
| @quotation |
| |
| “Implementations in which @code{Complex_Types.Real'Signed_Zeros} is |
| @code{True} should attempt to provide a rational treatment of the signs |
| of zero results and result components. For example, many of the complex |
| elementary functions have components that are odd functions of one of |
| the parameter components; in these cases, the result component should |
| have the sign of the parameter component at the origin. Other complex |
| elementary functions have zero components whose sign is opposite that of |
| a parameter component at the origin, or is always positive or always |
| negative.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Accuracy requirements |
| |
| @node RM G 2 4 19 Accuracy Requirements,RM G 2 6 15 Complex Arithmetic Accuracy,RM G 1 2 49 Complex Elementary Functions,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{257} |
| @section RM G.2.4(19): Accuracy Requirements |
| |
| |
| @quotation |
| |
| “The versions of the forward trigonometric functions without a |
| @code{Cycle} parameter should not be implemented by calling the |
| corresponding version with a @code{Cycle} parameter of |
| @code{2.0*Numerics.Pi}, since this will not provide the required |
| accuracy in some portions of the domain. For the same reason, the |
| version of @code{Log} without a @code{Base} parameter should not be |
| implemented by calling the corresponding version with a @code{Base} |
| parameter of @code{Numerics.e}.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Complex arithmetic accuracy |
| |
| @geindex Accuracy |
| @geindex complex arithmetic |
| |
| @node RM G 2 6 15 Complex Arithmetic Accuracy,RM H 6 15/2 Pragma Partition_Elaboration_Policy,RM G 2 4 19 Accuracy Requirements,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{258} |
| @section RM G.2.6(15): Complex Arithmetic Accuracy |
| |
| |
| @quotation |
| |
| “The version of the @code{Compose_From_Polar} function without a |
| @code{Cycle} parameter should not be implemented by calling the |
| corresponding version with a @code{Cycle} parameter of |
| @code{2.0*Numerics.Pi}, since this will not provide the required |
| accuracy in some portions of the domain.” |
| @end quotation |
| |
| Followed. |
| |
| @geindex Sequential elaboration policy |
| |
| @node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice |
| @anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{259} |
| @section RM H.6(15/2): Pragma Partition_Elaboration_Policy |
| |
| |
| @quotation |
| |
| “If the partition elaboration policy is @code{Sequential} and the |
| Environment task becomes permanently blocked during elaboration then the |
| partition is deadlocked and it is recommended that the partition be |
| immediately terminated.” |
| @end quotation |
| |
| Not followed. |
| |
| @node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top |
| @anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{25a}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{25b}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b} |
| @chapter Implementation Defined Characteristics |
| |
| |
| In addition to the implementation dependent pragmas and attributes, and the |
| implementation advice, there are a number of other Ada features that are |
| potentially implementation dependent and are designated as |
| implementation-defined. These are mentioned throughout the Ada Reference |
| Manual, and are summarized in Annex M. |
| |
| A requirement for conforming Ada compilers is that they provide |
| documentation describing how the implementation deals with each of these |
| issues. In this chapter you will find each point in Annex M listed, |
| followed by a description of how GNAT handles the implementation dependence. |
| |
| You can use this chapter as a guide to minimizing implementation |
| dependent features in your programs if portability to other compilers |
| and other operating systems is an important consideration. The numbers |
| in each entry below correspond to the paragraph numbers in the Ada |
| Reference Manual. |
| |
| |
| @itemize * |
| |
| @item |
| “Whether or not each recommendation given in Implementation |
| Advice is followed. See 1.1.2(37).” |
| @end itemize |
| |
| See @ref{a,,Implementation Advice}. |
| |
| |
| @itemize * |
| |
| @item |
| “Capacity limitations of the implementation. See 1.1.3(3).” |
| @end itemize |
| |
| The complexity of programs that can be processed is limited only by the |
| total amount of available virtual memory, and disk space for the |
| generated object files. |
| |
| |
| @itemize * |
| |
| @item |
| “Variations from the standard that are impractical to avoid |
| given the implementation’s execution environment. See 1.1.3(6).” |
| @end itemize |
| |
| There are no variations from the standard. |
| |
| |
| @itemize * |
| |
| @item |
| “Which code_statements cause external |
| interactions. See 1.1.3(10).” |
| @end itemize |
| |
| Any @emph{code_statement} can potentially cause external interactions. |
| |
| |
| @itemize * |
| |
| @item |
| “The coded representation for the text of an Ada |
| program. See 2.1(4).” |
| @end itemize |
| |
| See separate section on source representation. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The semantics of an Ada program whose text is not in |
| |
| Normalization Form C. See 2.1(4).” |
| @end table |
| @end itemize |
| |
| See separate section on source representation. |
| |
| |
| @itemize * |
| |
| @item |
| “The representation for an end of line. See 2.2(2).” |
| @end itemize |
| |
| See separate section on source representation. |
| |
| |
| @itemize * |
| |
| @item |
| “Maximum supported line length and lexical element |
| length. See 2.2(15).” |
| @end itemize |
| |
| The maximum line length is 255 characters and the maximum length of |
| a lexical element is also 255 characters. This is the default setting |
| if not overridden by the use of compiler switch @emph{-gnaty} (which |
| sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum |
| line length to be specified to be any value up to 32767. The maximum |
| length of a lexical element is the same as the maximum line length. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation defined pragmas. See 2.8(14).” |
| @end itemize |
| |
| See @ref{7,,Implementation Defined Pragmas}. |
| |
| |
| @itemize * |
| |
| @item |
| “Effect of pragma @code{Optimize}. See 2.8(27).” |
| @end itemize |
| |
| Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} |
| parameter, checks that the optimization flag is set, and aborts if it is |
| not. |
| |
| |
| @itemize * |
| |
| @item |
| “The message string associated with the Assertion_Error exception raised |
| by the failure of a predicate check if there is no applicable |
| Predicate_Failure aspect. See 3.2.4(31).” |
| @end itemize |
| |
| In the case of a Dynamic_Predicate aspect, the string is |
| “Dynamic_Predicate failed at <source position>”, where |
| “<source position>” might be something like “foo.adb:123”. |
| The Static_Predicate case is handled analogously. |
| |
| |
| @itemize * |
| |
| @item |
| “The predefined integer types declared in |
| @code{Standard}. See 3.5.4(25).” |
| @end itemize |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| Type |
| |
| @tab |
| |
| Representation |
| |
| @item |
| |
| @emph{Short_Short_Integer} |
| |
| @tab |
| |
| 8-bit signed |
| |
| @item |
| |
| @emph{Short_Integer} |
| |
| @tab |
| |
| 16-bit signed |
| |
| @item |
| |
| @emph{Integer} |
| |
| @tab |
| |
| 32-bit signed |
| |
| @item |
| |
| @emph{Long_Integer} |
| |
| @tab |
| |
| 64-bit signed (on most 64-bit targets, |
| depending on the C definition of long) |
| 32-bit signed (on all other targets) |
| |
| @item |
| |
| @emph{Long_Long_Integer} |
| |
| @tab |
| |
| 64-bit signed |
| |
| @item |
| |
| @emph{Long_Long_Long_Integer} |
| |
| @tab |
| |
| 128-bit signed (on 64-bit targets) |
| 64-bit signed (on 32-bit targets) |
| |
| @end multitable |
| |
| |
| |
| @itemize * |
| |
| @item |
| “Any nonstandard integer types and the operators defined |
| for them. See 3.5.4(26).” |
| @end itemize |
| |
| There are no nonstandard integer types. |
| |
| |
| @itemize * |
| |
| @item |
| “Any nonstandard real types and the operators defined for |
| them. See 3.5.6(8).” |
| @end itemize |
| |
| There are no nonstandard real types. |
| |
| |
| @itemize * |
| |
| @item |
| “What combinations of requested decimal precision and range |
| are supported for floating point types. See 3.5.7(7).” |
| @end itemize |
| |
| The precision and range are defined by the IEEE Standard for Floating-Point |
| Arithmetic (IEEE 754-2019). |
| |
| |
| @itemize * |
| |
| @item |
| “The predefined floating point types declared in |
| @code{Standard}. See 3.5.7(16).” |
| @end itemize |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| Type |
| |
| @tab |
| |
| Representation |
| |
| @item |
| |
| @emph{Short_Float} |
| |
| @tab |
| |
| IEEE Binary32 (Single) |
| |
| @item |
| |
| @emph{Float} |
| |
| @tab |
| |
| IEEE Binary32 (Single) |
| |
| @item |
| |
| @emph{Long_Float} |
| |
| @tab |
| |
| IEEE Binary64 (Double) |
| |
| @item |
| |
| @emph{Long_Long_Float} |
| |
| @tab |
| |
| IEEE Binary64 (Double) on non-x86 architectures |
| IEEE 80-bit Extended on x86 architecture |
| |
| @end multitable |
| |
| |
| The default rounding mode specified by the IEEE 754 Standard is assumed both |
| for static and dynamic computations (that is, round to nearest, ties to even). |
| The input routines yield correctly rounded values for Short_Float, Float, and |
| Long_Float at least. The output routines can compute up to twice as many exact |
| digits as the value of @code{T'Digits} for any type, for example 30 digits for |
| Long_Float; if more digits are requested, zeros are printed. |
| |
| |
| @itemize * |
| |
| @item |
| “The small of an ordinary fixed point type. See 3.5.9(8).” |
| @end itemize |
| |
| The small is the largest power of two that does not exceed the delta. |
| |
| |
| @itemize * |
| |
| @item |
| “What combinations of small, range, and digits are |
| supported for fixed point types. See 3.5.9(10).” |
| @end itemize |
| |
| For an ordinary fixed point type, on 32-bit platforms, the small must lie in |
| 2.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination |
| is permitted that does not result in a mantissa larger than 63 bits. |
| |
| On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the |
| range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not |
| result in a mantissa larger than 63 bits, and any combination is permitted |
| that results in a mantissa between 64 and 127 bits if the small is the |
| ratio of two integers that lie in 1 .. 2.0**127. |
| |
| If the small is the ratio of two integers with 64-bit magnitude on 32-bit |
| platforms and 128-bit magnitude on 64-bit platforms, which is the case if |
| no @code{small} clause is provided, then the operations of the fixed point |
| type are entirely implemented by means of integer instructions. In the |
| other cases, some operations, in particular input and output, may be |
| implemented by means of floating-point instructions and may be affected |
| by accuracy issues on architectures other than x86. |
| |
| For a decimal fixed point type, on 32-bit platforms, the small must lie in |
| 1.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the |
| small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of @code{Tags.Expanded_Name} for types declared |
| within an unnamed @emph{block_statement}. See 3.9(10).” |
| @end itemize |
| |
| Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a |
| decimal integer are allocated. |
| |
| |
| @itemize * |
| |
| @item |
| “The sequence of characters of the value returned by Tags.Expanded_Name |
| (respectively, Tags.Wide_Expanded_Name) when some of the graphic |
| characters of Tags.Wide_Wide_Expanded_Name are not defined in Character |
| (respectively, Wide_Character). See 3.9(10.1).” |
| @end itemize |
| |
| This is handled in the same way as the implementation-defined behavior |
| referenced in A.4.12(34). |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined attributes. See 4.1.4(12).” |
| @end itemize |
| |
| See @ref{8,,Implementation Defined Attributes}. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of the parameter to Empty for some container aggregates. |
| See 4.3.5(40).” |
| @end itemize |
| |
| As per the suggestion given in the Annotated Ada RM, the default value |
| of the formal parameter is used if one exists and zero is used otherwise. |
| |
| |
| @itemize * |
| |
| @item |
| “The maximum number of chunks for a parallel reduction expression without |
| a chunk_specification. See 4.5.10(21).” |
| @end itemize |
| |
| Feature unimplemented. |
| |
| |
| @itemize * |
| |
| @item |
| “Rounding of real static expressions which are exactly half-way between |
| two machine numbers. See 4.9(38).” |
| @end itemize |
| |
| Round to even is used in all such cases. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The maximum number of chunks for a parallel generalized iterator without |
| |
| a chunk_specification. See 5.5.2(10).” |
| @end table |
| @end itemize |
| |
| Feature unimplemented. |
| |
| |
| @itemize * |
| |
| @item |
| “The number of chunks for an array component iterator. See 5.5.2(11).” |
| @end itemize |
| |
| Feature unimplemented. |
| |
| |
| @itemize * |
| |
| @item |
| “Any extensions of the Global aspect. See 6.1.2(43).” |
| @end itemize |
| |
| Feature unimplemented. |
| |
| |
| @itemize * |
| |
| @item |
| “The circumstances the implementation passes in the null value for a view |
| conversion of an access type used as an out parameter. See 6.4.1(19).” |
| @end itemize |
| |
| Difficult to characterize. |
| |
| |
| @itemize * |
| |
| @item |
| “Any extensions of the Default_Initial_Condition aspect. See 7.3.3(11).” |
| @end itemize |
| |
| SPARK allows specifying @emph{null} as the Default_Initial_Condition |
| aspect of a type. See the SPARK reference manual for further details. |
| |
| |
| @itemize * |
| |
| @item |
| “Any implementation-defined time types. See 9.6(6).” |
| @end itemize |
| |
| There are no implementation-defined time types. |
| |
| |
| @itemize * |
| |
| @item |
| “The time base associated with relative delays. See 9.6(20).” |
| @end itemize |
| |
| See 9.6(20). The time base used is that provided by the C library |
| function @code{gettimeofday}. |
| |
| |
| @itemize * |
| |
| @item |
| “The time base of the type @code{Calendar.Time}. See 9.6(23).” |
| @end itemize |
| |
| The time base used is that provided by the C library function |
| @code{gettimeofday}. |
| |
| |
| @itemize * |
| |
| @item |
| “The time zone used for package @code{Calendar} |
| operations. See 9.6(24).” |
| @end itemize |
| |
| The time zone used by package @code{Calendar} is the current system time zone |
| setting for local time, as accessed by the C library function |
| @code{localtime}. |
| |
| |
| @itemize * |
| |
| @item |
| “Any limit on @emph{delay_until_statements} of |
| @emph{select_statements}. See 9.6(29).” |
| @end itemize |
| |
| There are no such limits. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The result of Calendar.Formatting.Image if its argument represents more |
| |
| than 100 hours. See 9.6.1(86).” |
| @end table |
| @end itemize |
| |
| Calendar.Time_Error is raised. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined conflict check policies. See 9.10.1(5).” |
| @end itemize |
| |
| There are no implementation-defined conflict check policies. |
| |
| |
| @itemize * |
| |
| @item |
| “The representation for a compilation. See 10.1(2).” |
| @end itemize |
| |
| A compilation is represented by a sequence of files presented to the |
| compiler in a single invocation of the @emph{gcc} command. |
| |
| |
| @itemize * |
| |
| @item |
| “Any restrictions on compilations that contain multiple |
| compilation_units. See 10.1(4).” |
| @end itemize |
| |
| No single file can contain more than one compilation unit, but any |
| sequence of files can be presented to the compiler as a single |
| compilation. |
| |
| |
| @itemize * |
| |
| @item |
| “The mechanisms for creating an environment and for adding |
| and replacing compilation units. See 10.1.4(3).” |
| @end itemize |
| |
| See separate section on compilation model. |
| |
| |
| @itemize * |
| |
| @item |
| “The manner of explicitly assigning library units to a |
| partition. See 10.2(2).” |
| @end itemize |
| |
| If a unit contains an Ada main program, then the Ada units for the partition |
| are determined by recursive application of the rules in the Ada Reference |
| Manual section 10.2(2-6). In other words, the Ada units will be those that |
| are needed by the main program, and then this definition of need is applied |
| recursively to those units, and the partition contains the transitive |
| closure determined by this relationship. In short, all the necessary units |
| are included, with no need to explicitly specify the list. If additional |
| units are required, e.g., by foreign language units, then all units must be |
| mentioned in the context clause of one of the needed Ada units. |
| |
| If the partition contains no main program, or if the main program is in |
| a language other than Ada, then GNAT |
| provides the binder options @emph{-z} and @emph{-n} respectively, and in |
| this case a list of units can be explicitly supplied to the binder for |
| inclusion in the partition (all units needed by these units will also |
| be included automatically). For full details on the use of these |
| options, refer to @emph{GNAT Make Program gnatmake} in the |
| @cite{GNAT User’s Guide}. |
| |
| |
| @itemize * |
| |
| @item |
| “The implementation-defined means, if any, of specifying which compilation |
| units are needed by a given compilation unit. See 10.2(2).” |
| @end itemize |
| |
| The units needed by a given compilation unit are as defined in |
| the Ada Reference Manual section 10.2(2-6). There are no |
| implementation-defined pragmas or other implementation-defined |
| means for specifying needed units. |
| |
| |
| @itemize * |
| |
| @item |
| “The manner of designating the main subprogram of a |
| partition. See 10.2(7).” |
| @end itemize |
| |
| The main program is designated by providing the name of the |
| corresponding @code{ALI} file as the input parameter to the binder. |
| |
| |
| @itemize * |
| |
| @item |
| “The order of elaboration of @emph{library_items}. See 10.2(18).” |
| @end itemize |
| |
| The first constraint on ordering is that it meets the requirements of |
| Chapter 10 of the Ada Reference Manual. This still leaves some |
| implementation-dependent choices, which are resolved by analyzing |
| the elaboration code of each unit and identifying implicit |
| elaboration-order dependencies. |
| |
| |
| @itemize * |
| |
| @item |
| “Parameter passing and function return for the main |
| subprogram. See 10.2(21).” |
| @end itemize |
| |
| The main program has no parameters. It may be a procedure, or a function |
| returning an integer type. In the latter case, the returned integer |
| value is the return code of the program (overriding any value that |
| may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). |
| |
| |
| @itemize * |
| |
| @item |
| “The mechanisms for building and running partitions. See 10.2(24).” |
| @end itemize |
| |
| GNAT itself supports programs with only a single partition. The GNATDIST |
| tool provided with the GLADE package (which also includes an implementation |
| of the PCS) provides a completely flexible method for building and running |
| programs consisting of multiple partitions. See the separate GLADE manual |
| for details. |
| |
| |
| @itemize * |
| |
| @item |
| “The details of program execution, including program |
| termination. See 10.2(25).” |
| @end itemize |
| |
| See separate section on compilation model. |
| |
| |
| @itemize * |
| |
| @item |
| “The semantics of any non-active partitions supported by the |
| implementation. See 10.2(28).” |
| @end itemize |
| |
| Passive partitions are supported on targets where shared memory is |
| provided by the operating system. See the GLADE reference manual for |
| further details. |
| |
| |
| @itemize * |
| |
| @item |
| “The information returned by @code{Exception_Message}. See 11.4.1(10).” |
| @end itemize |
| |
| Exception message returns the null string unless a specific message has |
| been passed by the program. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of @code{Exceptions.Exception_Name} for types |
| declared within an unnamed @emph{block_statement}. See 11.4.1(12).” |
| @end itemize |
| |
| Blocks have implementation defined names of the form @code{B@emph{nnn}} |
| where @emph{nnn} is an integer. |
| |
| |
| @itemize * |
| |
| @item |
| “The information returned by |
| @code{Exception_Information}. See 11.4.1(13).” |
| @end itemize |
| |
| @code{Exception_Information} returns a string in the following format: |
| |
| @example |
| *Exception_Name:* nnnnn |
| *Message:* mmmmm |
| *PID:* ppp |
| *Load address:* 0xhhhh |
| *Call stack traceback locations:* |
| 0xhhhh 0xhhhh 0xhhhh ... 0xhhh |
| @end example |
| |
| where |
| |
| @quotation |
| |
| |
| @itemize * |
| |
| @item |
| @code{nnnn} is the fully qualified name of the exception in all upper |
| case letters. This line is always present. |
| |
| @item |
| @code{mmmm} is the message (this line present only if message is non-null) |
| |
| @item |
| @code{ppp} is the Process Id value as a decimal integer (this line is |
| present only if the Process Id is nonzero). Currently we are |
| not making use of this field. |
| |
| @item |
| The Load address line, the Call stack traceback locations line and the |
| following values are present only if at least one traceback location was |
| recorded. The Load address indicates the address at which the main executable |
| was loaded; this line may not be present if operating system hasn’t relocated |
| the main executable. The values are given in C style format, with lower case |
| letters for a-f, and only as many digits present as are necessary. |
| The line terminator sequence at the end of each line, including |
| the last line is a single @code{LF} character (@code{16#0A#}). |
| @end itemize |
| @end quotation |
| |
| |
| @itemize * |
| |
| @item |
| “The sequence of characters of the value returned by |
| Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name) |
| when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name |
| are not defined in Character (respectively, Wide_Character). |
| See 11.4.1(12.1).” |
| @end itemize |
| |
| This is handled in the same way as the implementation-defined behavior |
| referenced in A.4.12(34). |
| |
| |
| @itemize * |
| |
| @item |
| “The information returned by Exception_Information. See 11.4.1(13).” |
| @end itemize |
| |
| The exception name and the source location at which the exception was |
| raised are included. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined policy_identifiers and assertion_aspect_marks |
| allowed in a pragma Assertion_Policy. See 11.4.2(9).” |
| @end itemize |
| |
| Implementation-defined assertion_aspect_marks include Assert_And_Cut, |
| Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant, |
| Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post, |
| Statement_Assertions, and Subprogram_Variant. Implementation-defined |
| policy_identifiers include Ignore and Suppressible. |
| |
| |
| @itemize * |
| |
| @item |
| “The default assertion policy. See 11.4.2(10).” |
| @end itemize |
| |
| The default assertion policy is Ignore, although this can be overridden |
| via compiler switches such as “-gnata”. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined check names. See 11.5(27).” |
| @end itemize |
| |
| The implementation defined check names include Alignment_Check, |
| Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, |
| Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user |
| program can add implementation-defined check names by means of the pragma |
| Check_Name. See the description of pragma @code{Suppress} for full details. |
| |
| |
| @itemize * |
| |
| @item |
| “Existence and meaning of second parameter of pragma Unsuppress. |
| See 11.5(27.1).” |
| @end itemize |
| |
| The legality rules for and semantics of the second parameter of pragma |
| Unsuppress match those for the second argument of pragma Suppress. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The cases that cause conflicts between the representation of the |
| |
| ancestors of a type_declaration. See 13.1(13.1).” |
| @end table |
| @end itemize |
| |
| No such cases exist. |
| |
| |
| @itemize * |
| |
| @item |
| “The interpretation of each representation aspect. See 13.1(20).” |
| @end itemize |
| |
| See separate section on data representations. |
| |
| |
| @itemize * |
| |
| @item |
| “Any restrictions placed upon the specification of representation aspects. |
| See 13.1(20).” |
| @end itemize |
| |
| See separate section on data representations. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined aspects, including the syntax for specifying |
| such aspects and the legality rules for such aspects. See 13.1.1(38).” |
| @end itemize |
| |
| See @ref{121,,Implementation Defined Aspects}. |
| |
| |
| @itemize * |
| |
| @item |
| “The set of machine scalars. See 13.3(8.1).” |
| @end itemize |
| |
| See separate section on data representations. |
| |
| |
| @itemize * |
| |
| @item |
| “The meaning of @code{Size} for indefinite subtypes. See 13.3(48).” |
| @end itemize |
| |
| The Size attribute of an indefinite subtype is not less than the Size |
| attribute of any object of that type. |
| |
| |
| @itemize * |
| |
| @item |
| “The meaning of Object_Size for indefinite subtypes. See 13.3(58).” |
| @end itemize |
| |
| The Object_Size attribute of an indefinite subtype is not less than the |
| Object_Size attribute of any object of that type. |
| |
| |
| @itemize * |
| |
| @item |
| “The default external representation for a type tag. See 13.3(75).” |
| @end itemize |
| |
| The default external representation for a type tag is the fully expanded |
| name of the type in upper case letters. |
| |
| |
| @itemize * |
| |
| @item |
| “What determines whether a compilation unit is the same in |
| two different partitions. See 13.3(76).” |
| @end itemize |
| |
| A compilation unit is the same in two different partitions if and only |
| if it derives from the same source file. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined components. See 13.5.1(15).” |
| @end itemize |
| |
| The only implementation defined component is the tag for a tagged type, |
| which contains a pointer to the dispatching table. |
| |
| |
| @itemize * |
| |
| @item |
| “If @code{Word_Size} = @code{Storage_Unit}, the default bit |
| ordering. See 13.5.3(5).” |
| @end itemize |
| |
| @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this |
| implementation, so no non-default bit ordering is supported. The default |
| bit ordering corresponds to the natural endianness of the target architecture. |
| |
| |
| @itemize * |
| |
| @item |
| “The contents of the visible part of package @code{System}. See 13.7(2).” |
| @end itemize |
| |
| See the definition of package System in @code{system.ads}. |
| Note that two declarations are added to package System. |
| |
| @example |
| Max_Priority : constant Positive := Priority'Last; |
| Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; |
| @end example |
| |
| |
| @itemize * |
| |
| @item |
| “The range of Storage_Elements.Storage_Offset, the modulus of |
| Storage_Elements.Storage_Element, and the declaration of |
| Storage_Elements.Integer_Address. See 13.7.1(11).” |
| @end itemize |
| |
| See the definition of package System.Storage_Elements in @code{s-stoele.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “The contents of the visible part of package @code{System.Machine_Code}, |
| and the meaning of @emph{code_statements}. See 13.8(7).” |
| @end itemize |
| |
| See the definition and documentation in file @code{s-maccod.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of unchecked conversion for instances with scalar result |
| types whose result is not defined by the language. See 13.9(11).” |
| @end itemize |
| |
| Unchecked conversion between types of the same size |
| results in an uninterpreted transmission of the bits from one type |
| to the other. If the types are of unequal sizes, then in the case of |
| discrete types, a shorter source is first zero or sign extended as |
| necessary, and a shorter target is simply truncated on the left. |
| For all non-discrete types, the source is first copied if necessary |
| to ensure that the alignment requirements of the target are met, then |
| a pointer is constructed to the source value, and the result is obtained |
| by dereferencing this pointer after converting it to be a pointer to the |
| target type. Unchecked conversions where the target subtype is an |
| unconstrained array are not permitted. If the target alignment is |
| greater than the source alignment, then a copy of the result is |
| made with appropriate alignment |
| |
| |
| @itemize * |
| |
| @item |
| “The result of unchecked conversion for instances with nonscalar result |
| types whose result is not defined by the language. See 13.9(11).” |
| @end itemize |
| |
| See preceding definition for the scalar result case. |
| |
| |
| @itemize * |
| |
| @item |
| “Whether or not the implementation provides user-accessible |
| names for the standard pool type(s). See 13.11(17).” |
| @end itemize |
| |
| There are 3 different standard pools used by the compiler when |
| @code{Storage_Pool} is not specified depending whether the type is local |
| to a subprogram or defined at the library level and whether |
| @code{Storage_Size`@w{`}is specified or not. See documentation in the runtime |
| library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and |
| @code{System.Pool_Local} in files @code{s-poosiz.ads}, |
| @code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the |
| default pools used. All these pools are accessible by means of @cite{with}ing |
| these units. |
| |
| |
| @itemize * |
| |
| @item |
| “The meaning of @code{Storage_Size} when neither the Storage_Size nor the |
| Storage_Pool is specified for an access type. See 13.11(18).” |
| @end itemize |
| |
| @code{Storage_Size} is measured in storage units, and refers to the |
| total space available for an access type collection, or to the primary |
| stack space for a task. |
| |
| |
| @itemize * |
| |
| @item |
| “The effect of specifying aspect Default_Storage_Pool on an instance |
| of a language-defined generic unit. See 13.11.3(5).” |
| @end itemize |
| |
| Instances of language-defined generic units are treated the same as other |
| instances with respect to the Default_Storage_Pool aspect. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined restrictions allowed in a pragma |
| @code{Restrictions}. See 13.12(8.7).” |
| @end itemize |
| |
| See @ref{9,,Standard and Implementation Defined Restrictions}. |
| |
| |
| @itemize * |
| |
| @item |
| “The consequences of violating limitations on |
| @code{Restrictions} pragmas. See 13.12(9).” |
| @end itemize |
| |
| Restrictions that can be checked at compile time are enforced at |
| compile time; violations are illegal. For other restrictions, any |
| violation during program execution results in erroneous execution. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined usage profiles allowed in a pragma Profile. |
| See 13.12(15).” |
| @end itemize |
| |
| See @ref{7,,Implementation Defined Pragmas}. |
| |
| |
| @itemize * |
| |
| @item |
| “The contents of the stream elements read and written by the Read and |
| Write attributes of elementary types. See 13.13.2(9).” |
| @end itemize |
| |
| The representation is the in-memory representation of the base type of |
| the type, using the number of bits corresponding to the |
| @code{type'Size} value, and the natural ordering of the machine. |
| |
| |
| @itemize * |
| |
| @item |
| “The names and characteristics of the numeric subtypes |
| declared in the visible part of package @code{Standard}. See A.1(3).” |
| @end itemize |
| |
| See items describing the integer and floating-point types supported. |
| |
| |
| @itemize * |
| |
| @item |
| “The values returned by Strings.Hash. See A.4.9(3).” |
| @end itemize |
| |
| This hash function has predictable collisions and is subject to |
| equivalent substring attacks. It is not suitable for construction of a |
| hash table keyed on possibly malicious user input. |
| |
| |
| @itemize * |
| |
| @item |
| “The value returned by a call to a Text_Buffer Get procedure if any |
| character in the returned sequence is not defined in Character. |
| See A.4.12(34).” |
| @end itemize |
| |
| The contents of a buffer is represented internally as a UTF_8 string. |
| The value return by Text_Buffer.Get is the result of passing that |
| UTF_8 string to UTF_Encoding.Strings.Decode. |
| |
| |
| @itemize * |
| |
| @item |
| “The value returned by a call to a Text_Buffer Wide_Get procedure if |
| any character in the returned sequence is not defined in Wide_Character. |
| See A.4.12(34).” |
| @end itemize |
| |
| The contents of a buffer is represented internally as a UTF_8 string. |
| The value return by Text_Buffer.Wide_Get is the result of passing that |
| UTF_8 string to UTF_Encoding.Wide_Strings.Decode. |
| |
| |
| @itemize * |
| |
| @item |
| “The accuracy actually achieved by the elementary |
| functions. See A.5.1(1).” |
| @end itemize |
| |
| The elementary functions correspond to the functions available in the C |
| library. Only fast math mode is implemented. |
| |
| |
| @itemize * |
| |
| @item |
| “The sign of a zero result from some of the operators or |
| functions in @code{Numerics.Generic_Elementary_Functions}, when |
| @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).” |
| @end itemize |
| |
| The sign of zeroes follows the requirements of the IEEE 754 standard on |
| floating-point. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of |
| @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).” |
| @end itemize |
| |
| Maximum image width is 6864, see library file @code{s-rannum.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of |
| @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).” |
| @end itemize |
| |
| Maximum image width is 6864, see library file @code{s-rannum.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “The string representation of a random number generator’s |
| state. See A.5.2(38).” |
| @end itemize |
| |
| The value returned by the Image function is the concatenation of |
| the fixed-width decimal representations of the 624 32-bit integers |
| of the state vector. |
| |
| |
| @itemize * |
| |
| @item |
| “The values of the @code{Model_Mantissa}, |
| @code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, |
| @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics |
| Annex is not supported. See A.5.3(72).” |
| @end itemize |
| |
| Running the compiler with @emph{-gnatS} to produce a listing of package |
| @code{Standard} displays the values of these attributes. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of @code{Buffer_Size} in @code{Storage_IO}. See A.9(10).” |
| @end itemize |
| |
| All type representations are contiguous, and the @code{Buffer_Size} is |
| the value of @code{type'Size} rounded up to the next storage unit |
| boundary. |
| |
| |
| @itemize * |
| |
| @item |
| “External files for standard input, standard output, and |
| standard error See A.10(5).” |
| @end itemize |
| |
| These files are mapped onto the files provided by the C streams |
| libraries. See source file @code{i-cstrea.ads} for further details. |
| |
| |
| @itemize * |
| |
| @item |
| “The accuracy of the value produced by @code{Put}. See A.10.9(36).” |
| @end itemize |
| |
| If more digits are requested in the output than are represented by the |
| precision of the value, zeroes are output in the corresponding least |
| significant digit positions. |
| |
| |
| @itemize * |
| |
| @item |
| “Current size for a stream file for which positioning is not supported. |
| See A.12.1(1.1).” |
| @end itemize |
| |
| Positioning is supported. |
| |
| |
| @itemize * |
| |
| @item |
| “The meaning of @code{Argument_Count}, @code{Argument}, and |
| @code{Command_Name}. See A.15(1).” |
| @end itemize |
| |
| These are mapped onto the @code{argv} and @code{argc} parameters of the |
| main program in the natural manner. |
| |
| |
| @itemize * |
| |
| @item |
| “The interpretation of file names and directory names. See A.16(46).” |
| @end itemize |
| |
| These names are interpreted consistently with the underlying file system. |
| |
| |
| @itemize * |
| |
| @item |
| “The maxium value for a file size in Directories. See A.16(87).” |
| @end itemize |
| |
| Directories.File_Size’Last is equal to Long_Long_Integer’Last . |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The result for Directories.Size for a directory or special file. |
| |
| See A.16(93).” |
| @end table |
| @end itemize |
| |
| Name_Error is raised. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The result for Directories.Modification_Time for a directory or special file. |
| |
| See A.16(93).” |
| @end table |
| @end itemize |
| |
| Name_Error is raised. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The interpretation of a nonnull search pattern in Directories. |
| |
| See A.16(104).” |
| @end table |
| @end itemize |
| |
| When the @code{Pattern} parameter is not the null string, it is interpreted |
| according to the syntax of regular expressions as defined in the |
| @code{GNAT.Regexp} package. |
| |
| See @ref{25c,,GNAT.Regexp (g-regexp.ads)}. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The results of a Directories search if the contents of the directory are |
| |
| altered while a search is in progress. See A.16(110).” |
| @end table |
| @end itemize |
| |
| The effect of a call to Get_Next_Entry is determined by the current |
| state of the directory. |
| |
| |
| @itemize * |
| |
| @item |
| “The definition and meaning of an environment variable. See A.17(1).” |
| @end itemize |
| |
| This definition is determined by the underlying operating system. |
| |
| |
| @itemize * |
| |
| @item |
| “The circumstances where an environment variable cannot be defined. |
| See A.17(16).” |
| |
| There are no such implementation-defined circumstances. |
| |
| @item |
| “Environment names for which Set has the effect of Clear. See A.17(17).” |
| @end itemize |
| |
| There are no such names. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of Containers.Hash_Type’Modulus. The value of |
| Containers.Count_Type’Last. See A.18.1(7).” |
| @end itemize |
| |
| Containers.Hash_Type’Modulus is 2**32. |
| Containers.Count_Type’Last is 2**31 - 1. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined convention names. See B.1(11).” |
| @end itemize |
| |
| The following convention names are supported |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| Convention Name |
| |
| @tab |
| |
| Interpretation |
| |
| @item |
| |
| @emph{Ada} |
| |
| @tab |
| |
| Ada |
| |
| @item |
| |
| @emph{Ada_Pass_By_Copy} |
| |
| @tab |
| |
| Allowed for any types except by-reference types such as limited |
| records. Compatible with convention Ada, but causes any parameters |
| with this convention to be passed by copy. |
| |
| @item |
| |
| @emph{Ada_Pass_By_Reference} |
| |
| @tab |
| |
| Allowed for any types except by-copy types such as scalars. |
| Compatible with convention Ada, but causes any parameters |
| with this convention to be passed by reference. |
| |
| @item |
| |
| @emph{Assembler} |
| |
| @tab |
| |
| Assembly language |
| |
| @item |
| |
| @emph{Asm} |
| |
| @tab |
| |
| Synonym for Assembler |
| |
| @item |
| |
| @emph{Assembly} |
| |
| @tab |
| |
| Synonym for Assembler |
| |
| @item |
| |
| @emph{C} |
| |
| @tab |
| |
| C |
| |
| @item |
| |
| @emph{C_Pass_By_Copy} |
| |
| @tab |
| |
| Allowed only for record types, like C, but also notes that record |
| is to be passed by copy rather than reference. |
| |
| @item |
| |
| @emph{COBOL} |
| |
| @tab |
| |
| COBOL |
| |
| @item |
| |
| @emph{C_Plus_Plus (or CPP)} |
| |
| @tab |
| |
| C++ |
| |
| @item |
| |
| @emph{Default} |
| |
| @tab |
| |
| Treated the same as C |
| |
| @item |
| |
| @emph{External} |
| |
| @tab |
| |
| Treated the same as C |
| |
| @item |
| |
| @emph{Fortran} |
| |
| @tab |
| |
| Fortran |
| |
| @item |
| |
| @emph{Intrinsic} |
| |
| @tab |
| |
| For support of pragma @code{Import} with convention Intrinsic, see |
| separate section on Intrinsic Subprograms. |
| |
| @item |
| |
| @emph{Stdcall} |
| |
| @tab |
| |
| Stdcall (used for Windows implementations only). This convention correspond |
| to the WINAPI (previously called Pascal convention) C/C++ convention under |
| Windows. A routine with this convention cleans the stack before |
| exit. This pragma cannot be applied to a dispatching call. |
| |
| @item |
| |
| @emph{DLL} |
| |
| @tab |
| |
| Synonym for Stdcall |
| |
| @item |
| |
| @emph{Win32} |
| |
| @tab |
| |
| Synonym for Stdcall |
| |
| @item |
| |
| @emph{Stubbed} |
| |
| @tab |
| |
| Stubbed is a special convention used to indicate that the body of the |
| subprogram will be entirely ignored. Any call to the subprogram |
| is converted into a raise of the @code{Program_Error} exception. If a |
| pragma @code{Import} specifies convention @code{stubbed} then no body need |
| be present at all. This convention is useful during development for the |
| inclusion of subprograms whose body has not yet been written. |
| In addition, all otherwise unrecognized convention names are also |
| treated as being synonymous with convention C. In all implementations, |
| use of such other names results in a warning. |
| |
| @end multitable |
| |
| |
| |
| @itemize * |
| |
| @item |
| “The meaning of link names. See B.1(36).” |
| @end itemize |
| |
| Link names are the actual names used by the linker. |
| |
| |
| @itemize * |
| |
| @item |
| “The manner of choosing link names when neither the link name nor the |
| address of an imported or exported entity is specified. See B.1(36).” |
| @end itemize |
| |
| The default linker name is that which would be assigned by the relevant |
| external language, interpreting the Ada name as being in all lower case |
| letters. |
| |
| |
| @itemize * |
| |
| @item |
| “The effect of pragma @code{Linker_Options}. See B.1(37).” |
| @end itemize |
| |
| The string passed to @code{Linker_Options} is presented uninterpreted as |
| an argument to the link command, unless it contains ASCII.NUL characters. |
| NUL characters if they appear act as argument separators, so for example |
| |
| @example |
| pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); |
| @end example |
| |
| causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the |
| linker. The order of linker options is preserved for a given unit. The final |
| list of options passed to the linker is in reverse order of the elaboration |
| order. For example, linker options for a body always appear before the options |
| from the corresponding package spec. |
| |
| |
| @itemize * |
| |
| @item |
| “The contents of the visible part of package |
| @code{Interfaces} and its language-defined descendants. See B.2(1).” |
| @end itemize |
| |
| See files with prefix @code{i-} in the distributed library. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined children of package |
| @code{Interfaces}. The contents of the visible part of package |
| @code{Interfaces}. See B.2(11).” |
| @end itemize |
| |
| See files with prefix @code{i-} in the distributed library. |
| |
| |
| @itemize * |
| |
| @item |
| “The definitions of certain types and constants in Interfaces.C. |
| See B.3(41).” |
| @end itemize |
| |
| See source file @code{i-c.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “The types @code{Floating}, @code{Long_Floating}, |
| @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and |
| @code{COBOL_Character}; and the initialization of the variables |
| @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in |
| @code{Interfaces.COBOL}. See B.4(50).” |
| @end itemize |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| COBOL |
| |
| @tab |
| |
| Ada |
| |
| @item |
| |
| @emph{Floating} |
| |
| @tab |
| |
| Float |
| |
| @item |
| |
| @emph{Long_Floating} |
| |
| @tab |
| |
| (Floating) Long_Float |
| |
| @item |
| |
| @emph{Binary} |
| |
| @tab |
| |
| Integer |
| |
| @item |
| |
| @emph{Long_Binary} |
| |
| @tab |
| |
| Long_Long_Integer |
| |
| @item |
| |
| @emph{Decimal_Element} |
| |
| @tab |
| |
| Character |
| |
| @item |
| |
| @emph{COBOL_Character} |
| |
| @tab |
| |
| Character |
| |
| @end multitable |
| |
| |
| For initialization, see the file @code{i-cobol.ads} in the distributed library. |
| |
| |
| @itemize * |
| |
| @item |
| “The types Fortran_Integer, Real, Double_Precision, and Character_Set |
| in Interfaces.Fortran. See B.5(17).” |
| @end itemize |
| |
| See source file @code{i-fortra.ads}. These types are derived, respectively, |
| from Integer, Float, Long_Float, and Character. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined intrinsic subprograms. See C.1(1).” |
| @end itemize |
| |
| See separate section on Intrinsic Subprograms. |
| |
| |
| @itemize * |
| |
| @item |
| “Any restrictions on a protected procedure or its containing type when an |
| aspect Attach_handler or Interrupt_Handler is specified. See C.3.1(17).” |
| @end itemize |
| |
| There are no such restrictions. |
| |
| |
| @itemize * |
| |
| @item |
| “Any other forms of interrupt handler supported by the Attach_Handler and |
| Interrupt_Handler aspects. See C.3.1(19).” |
| @end itemize |
| |
| There are no such forms. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The semantics of some attributes and functions of an entity for which |
| |
| aspect Discard_Names is True. See C.5(7).” |
| @end table |
| @end itemize |
| |
| If Discard_Names is True for an enumeration type, the Image attribute |
| provides the image of the Pos of the literal, and Value accepts |
| Pos values. |
| |
| If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true |
| for a tagged type, its Expanded_Name and External_Tag values are |
| empty strings. This is useful to avoid exposing entity names at binary |
| level. |
| |
| |
| @itemize * |
| |
| @item |
| “The modulus and size of Test_and_Set_Flag. See C.6.3(8).” |
| @end itemize |
| |
| The modulus is 2**8. The size is 8. |
| |
| |
| @itemize * |
| |
| @item |
| “The value used to represent the set value for Atomic_Test_and_Set. |
| See C.6.3(10).” |
| @end itemize |
| |
| The value is 1. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of the @code{Task_Identification.Image} |
| attribute. See C.7.1(7).” |
| @end itemize |
| |
| The result of this attribute is a string that identifies |
| the object or component that denotes a given task. If a variable @code{Var} |
| has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}}, |
| where the suffix @emph{XXXXXXXX} |
| is the hexadecimal representation of the virtual address of the corresponding |
| task control block. If the variable is an array of tasks, the image of each |
| task will have the form of an indexed component indicating the position of a |
| given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a |
| component of a record, the image of the task will have the form of a selected |
| component. These rules are fully recursive, so that the image of a task that |
| is a subcomponent of a composite object corresponds to the expression that |
| designates this task. |
| |
| If a task is created by an allocator, its image depends on the context. If the |
| allocator is part of an object declaration, the rules described above are used |
| to construct its image, and this image is not affected by subsequent |
| assignments. If the allocator appears within an expression, the image |
| includes only the name of the task type. |
| |
| If the configuration pragma Discard_Names is present, or if the restriction |
| No_Implicit_Heap_Allocation is in effect, the image reduces to |
| the numeric suffix, that is to say the hexadecimal representation of the |
| virtual address of the control block of the task. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of @code{Current_Task} when in a protected entry |
| or interrupt handler. See C.7.1(17).” |
| @end itemize |
| |
| Protected entries or interrupt handlers can be executed by any |
| convenient thread, so the value of @code{Current_Task} is undefined. |
| |
| |
| @itemize * |
| |
| @item |
| “Granularity of locking for Task_Attributes. See C.7.2(16).” |
| @end itemize |
| |
| No locking is needed if the formal type Attribute has the size and |
| alignment of either Integer or System.Address and the bit representation |
| of Initial_Value is all zeroes. Otherwise, locking is performed. |
| |
| |
| @itemize * |
| |
| @item |
| “The declarations of @code{Any_Priority} and |
| @code{Priority}. See D.1(11).” |
| @end itemize |
| |
| See declarations in file @code{system.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined execution resources. See D.1(15).” |
| @end itemize |
| |
| There are no implementation-defined execution resources. |
| |
| |
| @itemize * |
| |
| @item |
| “Whether, on a multiprocessor, a task that is waiting for |
| access to a protected object keeps its processor busy. See D.2.1(3).” |
| @end itemize |
| |
| On a multi-processor, a task that is waiting for access to a protected |
| object does not keep its processor busy. |
| |
| |
| @itemize * |
| |
| @item |
| “The affect of implementation defined execution resources |
| on task dispatching. See D.2.1(9).” |
| @end itemize |
| |
| Tasks map to threads in the threads package used by GNAT. Where possible |
| and appropriate, these threads correspond to native threads of the |
| underlying operating system. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined task dispatching policies. See D.2.2(3).” |
| @end itemize |
| |
| There are no implementation-defined task dispatching policies. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of Default_Quantum in Dispatching.Round_Robin. See D.2.5(4).” |
| @end itemize |
| |
| The value is 10 milliseconds. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined @emph{policy_identifiers} allowed |
| in a pragma @code{Locking_Policy}. See D.3(4).” |
| @end itemize |
| |
| The two implementation defined policies permitted in GNAT are |
| @code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On |
| targets that support the @code{Inheritance_Locking} policy, locking is |
| implemented by inheritance, i.e., the task owning the lock operates |
| at a priority equal to the highest priority of any task currently |
| requesting the lock. On targets that support the |
| @code{Concurrent_Readers_Locking} policy, locking is implemented with a |
| read/write lock allowing multiple protected object functions to enter |
| concurrently. |
| |
| |
| @itemize * |
| |
| @item |
| “Default ceiling priorities. See D.3(10).” |
| @end itemize |
| |
| The ceiling priority of protected objects of the type |
| @code{System.Interrupt_Priority'Last} as described in the Ada |
| Reference Manual D.3(10), |
| |
| |
| @itemize * |
| |
| @item |
| “The ceiling of any protected object used internally by |
| the implementation. See D.3(16).” |
| @end itemize |
| |
| The ceiling priority of internal protected objects is |
| @code{System.Priority'Last}. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined queuing policies. See D.4(1).” |
| @end itemize |
| |
| There are no implementation-defined queuing policies. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined admission policies. See D.4.1(1).” |
| @end itemize |
| |
| There are no implementation-defined admission policies. |
| |
| |
| @itemize * |
| |
| @item |
| “Any operations that implicitly require heap storage |
| allocation. See D.7(8).” |
| @end itemize |
| |
| The only operation that implicitly requires heap storage allocation is |
| task creation. |
| |
| |
| @itemize * |
| |
| @item |
| “When restriction No_Dynamic_CPU_Assignment applies to a partition, the |
| processor on which a task with a CPU value of a Not_A_Specific_CPU will |
| execute. See D.7(10).” |
| @end itemize |
| |
| Unknown. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “When restriction No_Task_Termination applies to a partition, what happens |
| |
| when a task terminates. See D.7(15.1).” |
| @end table |
| @end itemize |
| |
| Execution is erroneous in that case. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The behavior when restriction Max_Storage_At_Blocking is violated. |
| |
| See D.7(17).” |
| @end table |
| @end itemize |
| |
| Execution is erroneous in that case. |
| |
| |
| @itemize * |
| |
| @item |
| “The behavior when restriction Max_Asynchronous_Select_Nesting is violated. |
| See D.7(18).” |
| @end itemize |
| |
| Execution is erroneous in that case. |
| |
| |
| @itemize * |
| |
| @item |
| “The behavior when restriction Max_Tasks is violated. See D.7(19).” |
| @end itemize |
| |
| Execution is erroneous in that case. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “Whether the use of pragma Restrictions results in a reduction in program |
| |
| code or data size or execution time. See D.7(20).” |
| |
| Yes it can, but the precise circumstances and properties of such reductions |
| are difficult to characterize. |
| @end table |
| |
| @item |
| “The value of Barrier_Limit’Last in Synchronous_Barriers. See D.10.1(4).” |
| @end itemize |
| |
| Synchronous_Barriers.Barrier_Limit’Last is Integer’Last . |
| |
| |
| @itemize * |
| |
| @item |
| “When an aborted task that is waiting on a Synchronous_Barrier is aborted. |
| See D.10.1(13).” |
| @end itemize |
| |
| Difficult to characterize. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets. |
| |
| See D.14.2(7).” |
| @end table |
| @end itemize |
| |
| See source file @code{a-etgrbu.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of CPU_Range’Last in System.Multiprocessors. See D.16(4).” |
| @end itemize |
| |
| See source file @code{s-multip.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “The processor on which the environment task executes in the absence |
| of a value for the aspect CPU. See D.16(13).” |
| @end itemize |
| |
| Unknown. |
| |
| |
| @itemize * |
| |
| @item |
| “The means for creating and executing distributed |
| programs. See E(5).” |
| @end itemize |
| |
| The GLADE package provides a utility GNATDIST for creating and executing |
| distributed programs. See the GLADE reference manual for further details. |
| |
| |
| @itemize * |
| |
| @item |
| “Any events that can result in a partition becoming |
| inaccessible. See E.1(7).” |
| @end itemize |
| |
| See the GLADE reference manual for full details on such events. |
| |
| |
| @itemize * |
| |
| @item |
| “The scheduling policies, treatment of priorities, and management of |
| shared resources between partitions in certain cases. See E.1(11).” |
| @end itemize |
| |
| See the GLADE reference manual for full details on these aspects of |
| multi-partition execution. |
| |
| |
| @itemize * |
| |
| @item |
| “Whether the execution of the remote subprogram is |
| immediately aborted as a result of cancellation. See E.4(13).” |
| @end itemize |
| |
| See the GLADE reference manual for details on the effect of abort in |
| a distributed application. |
| |
| |
| @itemize * |
| |
| @item |
| “The range of type System.RPC.Partition_Id. See E.5(14).” |
| @end itemize |
| |
| System.RPC.Partion_ID’Last is Integer’Last. See source file @code{s-rpc.ads}. |
| |
| |
| @itemize * |
| |
| @item |
| “Implementation-defined interfaces in the PCS. See E.5(26).” |
| @end itemize |
| |
| See the GLADE reference manual for a full description of all |
| implementation defined interfaces. |
| |
| |
| @itemize * |
| |
| @item |
| “The values of named numbers in the package |
| @code{Decimal}. See F.2(7).” |
| @end itemize |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} |
| @headitem |
| |
| Named Number |
| |
| @tab |
| |
| Value |
| |
| @item |
| |
| @emph{Max_Scale} |
| |
| @tab |
| |
| +18 |
| |
| @item |
| |
| @emph{Min_Scale} |
| |
| @tab |
| |
| -18 |
| |
| @item |
| |
| @emph{Min_Delta} |
| |
| @tab |
| |
| 1.0E-18 |
| |
| @item |
| |
| @emph{Max_Delta} |
| |
| @tab |
| |
| 1.0E+18 |
| |
| @item |
| |
| @emph{Max_Decimal_Digits} |
| |
| @tab |
| |
| 18 |
| |
| @end multitable |
| |
| |
| |
| @itemize * |
| |
| @item |
| “The value of @code{Max_Picture_Length} in the package |
| @code{Text_IO.Editing}. See F.3.3(16).” |
| @end itemize |
| |
| 64 |
| |
| |
| @itemize * |
| |
| @item |
| “The value of @code{Max_Picture_Length} in the package |
| @code{Wide_Text_IO.Editing}. See F.3.4(5).” |
| @end itemize |
| |
| 64 |
| |
| |
| @itemize * |
| |
| @item |
| “The accuracy actually achieved by the complex elementary |
| functions and by other complex arithmetic operations. See G.1(1).” |
| @end itemize |
| |
| Standard library functions are used for the complex arithmetic |
| operations. Only fast math mode is currently supported. |
| |
| |
| @itemize * |
| |
| @item |
| “The sign of a zero result (or a component thereof) from |
| any operator or function in @code{Numerics.Generic_Complex_Types}, when |
| @code{Real'Signed_Zeros} is True. See G.1.1(53).” |
| @end itemize |
| |
| The signs of zero values are as recommended by the relevant |
| implementation advice. |
| |
| |
| @itemize * |
| |
| @item |
| “The sign of a zero result (or a component thereof) from |
| any operator or function in |
| @code{Numerics.Generic_Complex_Elementary_Functions}, when |
| @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).” |
| @end itemize |
| |
| The signs of zero values are as recommended by the relevant |
| implementation advice. |
| |
| |
| @itemize * |
| |
| @item |
| “Whether the strict mode or the relaxed mode is the |
| default. See G.2(2).” |
| @end itemize |
| |
| The strict mode is the default. There is no separate relaxed mode. GNAT |
| provides a highly efficient implementation of strict mode. |
| |
| |
| @itemize * |
| |
| @item |
| “The result interval in certain cases of fixed-to-float |
| conversion. See G.2.1(10).” |
| @end itemize |
| |
| For cases where the result interval is implementation dependent, the |
| accuracy is that provided by performing all operations in 64-bit IEEE |
| floating-point format. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of a floating point arithmetic operation in |
| overflow situations, when the @code{Machine_Overflows} attribute of the |
| result type is @code{False}. See G.2.1(13).” |
| @end itemize |
| |
| Infinite and NaN values are produced as dictated by the IEEE |
| floating-point standard. |
| Note that on machines that are not fully compliant with the IEEE |
| floating-point standard, such as Alpha, the @emph{-mieee} compiler flag |
| must be used for achieving IEEE conforming behavior (although at the cost |
| of a significant performance penalty), so infinite and NaN values are |
| properly generated. |
| |
| |
| @itemize * |
| |
| @item |
| “The result interval for division (or exponentiation by a |
| negative exponent), when the floating point hardware implements division |
| as multiplication by a reciprocal. See G.2.1(16).” |
| @end itemize |
| |
| Not relevant, division is IEEE exact. |
| |
| |
| @itemize * |
| |
| @item |
| “The definition of close result set, which determines the accuracy of |
| certain fixed point multiplications and divisions. See G.2.3(5).” |
| @end itemize |
| |
| Operations in the close result set are performed using IEEE long format |
| floating-point arithmetic. The input operands are converted to |
| floating-point, the operation is done in floating-point, and the result |
| is converted to the target type. |
| |
| |
| @itemize * |
| |
| @item |
| “Conditions on a @emph{universal_real} operand of a fixed |
| point multiplication or division for which the result shall be in the |
| perfect result set. See G.2.3(22).” |
| @end itemize |
| |
| The result is only defined to be in the perfect result set if the result |
| can be computed by a single scaling operation involving a scale factor |
| representable in 64 bits. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of a fixed point arithmetic operation in |
| overflow situations, when the @code{Machine_Overflows} attribute of the |
| result type is @code{False}. See G.2.3(27).” |
| @end itemize |
| |
| Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point |
| types. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of an elementary function reference in |
| overflow situations, when the @code{Machine_Overflows} attribute of the |
| result type is @code{False}. See G.2.4(4).” |
| @end itemize |
| |
| IEEE infinite and Nan values are produced as appropriate. |
| |
| |
| @itemize * |
| |
| @item |
| “The value of the angle threshold, within which certain |
| elementary functions, complex arithmetic operations, and complex |
| elementary functions yield results conforming to a maximum relative |
| error bound. See G.2.4(10).” |
| @end itemize |
| |
| Information on this subject is not yet available. |
| |
| |
| @itemize * |
| |
| @item |
| “The accuracy of certain elementary functions for |
| parameters beyond the angle threshold. See G.2.4(10).” |
| @end itemize |
| |
| Information on this subject is not yet available. |
| |
| |
| @itemize * |
| |
| @item |
| “The result of a complex arithmetic operation or complex |
| elementary function reference in overflow situations, when the |
| @code{Machine_Overflows} attribute of the corresponding real type is |
| @code{False}. See G.2.6(5).” |
| @end itemize |
| |
| IEEE infinite and Nan values are produced as appropriate. |
| |
| |
| @itemize * |
| |
| @item |
| “The accuracy of certain complex arithmetic operations and |
| certain complex elementary functions for parameters (or components |
| thereof) beyond the angle threshold. See G.2.6(8).” |
| @end itemize |
| |
| Information on those subjects is not yet available. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The accuracy requirements for the subprograms Solve, Inverse, |
| |
| Determinant, Eigenvalues and Eigensystem for type Real_Matrix. |
| See G.3.1(81).” |
| @end table |
| @end itemize |
| |
| Information on those subjects is not yet available. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item “The accuracy requirements for the subprograms Solve, Inverse, |
| |
| Determinant, Eigenvalues and Eigensystem for type Complex_Matrix. |
| See G.3.2(149).” |
| @end table |
| @end itemize |
| |
| Information on those subjects is not yet available. |
| |
| |
| @itemize * |
| |
| @item |
| “The consequences of violating No_Hidden_Indirect_Globals. See H.4(23.9).” |
| @end itemize |
| |
| Execution is erroneous in that case. |
| |
| @node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top |
| @anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c} |
| @chapter Intrinsic Subprograms |
| |
| |
| @geindex Intrinsic Subprograms |
| |
| GNAT allows a user application program to write the declaration: |
| |
| @example |
| pragma Import (Intrinsic, name); |
| @end example |
| |
| providing that the name corresponds to one of the implemented intrinsic |
| subprograms in GNAT, and that the parameter profile of the referenced |
| subprogram meets the requirements. This chapter describes the set of |
| implemented intrinsic subprograms, and the requirements on parameter profiles. |
| Note that no body is supplied; as with other uses of pragma Import, the |
| body is supplied elsewhere (in this case by the compiler itself). Note |
| that any use of this feature is potentially non-portable, since the |
| Ada standard does not require Ada compilers to implement this feature. |
| |
| @menu |
| * Intrinsic Operators:: |
| * Compilation_ISO_Date:: |
| * Compilation_Date:: |
| * Compilation_Time:: |
| * Enclosing_Entity:: |
| * Exception_Information:: |
| * Exception_Message:: |
| * Exception_Name:: |
| * File:: |
| * Line:: |
| * Shifts and Rotates:: |
| * Source_Location:: |
| |
| @end menu |
| |
| @node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{260} |
| @section Intrinsic Operators |
| |
| |
| @geindex Intrinsic operator |
| |
| All the predefined numeric operators in package Standard |
| in @code{pragma Import (Intrinsic,..)} |
| declarations. In the binary operator case, the operands must have the same |
| size. The operand or operands must also be appropriate for |
| the operator. For example, for addition, the operands must |
| both be floating-point or both be fixed-point, and the |
| right operand for @code{"**"} must have a root type of |
| @code{Standard.Integer'Base}. |
| You can use an intrinsic operator declaration as in the following example: |
| |
| @example |
| type Int1 is new Integer; |
| type Int2 is new Integer; |
| |
| function "+" (X1 : Int1; X2 : Int2) return Int1; |
| function "+" (X1 : Int1; X2 : Int2) return Int2; |
| pragma Import (Intrinsic, "+"); |
| @end example |
| |
| This declaration would permit ‘mixed mode’ arithmetic on items |
| of the differing types @code{Int1} and @code{Int2}. |
| It is also possible to specify such operators for private types, if the |
| full views are appropriate arithmetic types. |
| |
| @node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{262} |
| @section Compilation_ISO_Date |
| |
| |
| @geindex Compilation_ISO_Date |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of |
| the current compilation (in local time format YYYY-MM-DD). |
| |
| @node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{264} |
| @section Compilation_Date |
| |
| |
| @geindex Compilation_Date |
| |
| Same as Compilation_ISO_Date, except the string is in the form |
| MMM DD YYYY. |
| |
| @node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{266} |
| @section Compilation_Time |
| |
| |
| @geindex Compilation_Time |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Compilation_Time} to obtain the time of |
| the current compilation (in local time format HH:MM:SS). |
| |
| @node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{268} |
| @section Enclosing_Entity |
| |
| |
| @geindex Enclosing_Entity |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of |
| the current subprogram, package, task, entry, or protected subprogram. |
| |
| @node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{26a} |
| @section Exception_Information |
| |
| |
| @geindex Exception_Information' |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Current_Exception}. The only useful |
| use of the intrinsic import in this case is the one in this unit, |
| so an application program should simply call the function |
| @code{GNAT.Current_Exception.Exception_Information} to obtain |
| the exception information associated with the current exception. |
| |
| @node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26c} |
| @section Exception_Message |
| |
| |
| @geindex Exception_Message |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Current_Exception}. The only useful |
| use of the intrinsic import in this case is the one in this unit, |
| so an application program should simply call the function |
| @code{GNAT.Current_Exception.Exception_Message} to obtain |
| the message associated with the current exception. |
| |
| @node Exception_Name,File,Exception_Message,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26e} |
| @section Exception_Name |
| |
| |
| @geindex Exception_Name |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Current_Exception}. The only useful |
| use of the intrinsic import in this case is the one in this unit, |
| so an application program should simply call the function |
| @code{GNAT.Current_Exception.Exception_Name} to obtain |
| the name of the current exception. |
| |
| @node File,Line,Exception_Name,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms file}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{270} |
| @section File |
| |
| |
| @geindex File |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.File} to obtain the name of the current |
| file. |
| |
| @node Line,Shifts and Rotates,File,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms id11}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{272} |
| @section Line |
| |
| |
| @geindex Line |
| |
| This intrinsic subprogram is used in the implementation of the |
| library package @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Line} to obtain the number of the current |
| source line. |
| |
| @node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms id12}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{274} |
| @section Shifts and Rotates |
| |
| |
| @geindex Shift_Left |
| |
| @geindex Shift_Right |
| |
| @geindex Shift_Right_Arithmetic |
| |
| @geindex Rotate_Left |
| |
| @geindex Rotate_Right |
| |
| In standard Ada, the shift and rotate functions are available only |
| for the predefined modular types in package @code{Interfaces}. However, in |
| GNAT it is possible to define these functions for any integer |
| type (signed or modular), as in this example: |
| |
| @example |
| function Shift_Left |
| (Value : T; |
| Amount : Natural) return T |
| with Import, Convention => Intrinsic; |
| @end example |
| |
| The function name must be one of |
| Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or |
| Rotate_Right. T must be an integer type. T’Size must be |
| 8, 16, 32 or 64 bits; if T is modular, the modulus |
| must be 2**8, 2**16, 2**32 or 2**64. |
| The result type must be the same as the type of @code{Value}. |
| The shift amount must be Natural. |
| The formal parameter names can be anything. |
| |
| A more convenient way of providing these shift operators is to use the |
| Provide_Shift_Operators pragma, which provides the function declarations and |
| corresponding pragma Import’s for all five shift functions. For signed types |
| the semantics of these operators is to interpret the bitwise result of the |
| corresponding operator for modular type. In particular, shifting a negative |
| number may change its sign bit to positive. |
| |
| @node Source_Location,,Shifts and Rotates,Intrinsic Subprograms |
| @anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{276} |
| @section Source_Location |
| |
| |
| @geindex Source_Location |
| |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Source_Location} to obtain the current |
| source file location. |
| |
| @node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top |
| @anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d} |
| @chapter Representation Clauses and Pragmas |
| |
| |
| @geindex Representation Clauses |
| |
| @geindex Representation Clause |
| |
| @geindex Representation Pragma |
| |
| @geindex Pragma |
| @geindex representation |
| |
| This section describes the representation clauses accepted by GNAT, and |
| their effect on the representation of corresponding data objects. |
| |
| GNAT fully implements Annex C (Systems Programming). This means that all |
| the implementation advice sections in chapter 13 are fully implemented. |
| However, these sections only require a minimal level of support for |
| representation clauses. GNAT provides much more extensive capabilities, |
| and this section describes the additional capabilities provided. |
| |
| @menu |
| * Alignment Clauses:: |
| * Size Clauses:: |
| * Storage_Size Clauses:: |
| * Size of Variant Record Objects:: |
| * Biased Representation:: |
| * Value_Size and Object_Size Clauses:: |
| * Component_Size Clauses:: |
| * Bit_Order Clauses:: |
| * Effect of Bit_Order on Byte Ordering:: |
| * Pragma Pack for Arrays:: |
| * Pragma Pack for Records:: |
| * Record Representation Clauses:: |
| * Handling of Records with Holes:: |
| * Enumeration Clauses:: |
| * Address Clauses:: |
| * Use of Address Clauses for Memory-Mapped I/O:: |
| * Effect of Convention on Representation:: |
| * Conventions and Anonymous Access Types:: |
| * Determining the Representations chosen by GNAT:: |
| |
| @end menu |
| |
| @node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{27a} |
| @section Alignment Clauses |
| |
| |
| @geindex Alignment Clause |
| |
| GNAT requires that all alignment clauses specify 0 or a power of 2, and |
| all default alignments are always a power of 2. Specifying 0 is the |
| same as specifying 1. |
| |
| The default alignment values are as follows: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Elementary Types}. |
| |
| For elementary types, the alignment is the minimum of the actual size of |
| objects of the type divided by @code{Storage_Unit}, |
| and the maximum alignment supported by the target. |
| (This maximum alignment is given by the GNAT-specific attribute |
| @code{Standard'Maximum_Alignment}; see @ref{18e,,Attribute Maximum_Alignment}.) |
| |
| @geindex Maximum_Alignment attribute |
| |
| For example, for type @code{Long_Float}, the object size is 8 bytes, and the |
| default alignment will be 8 on any target that supports alignments |
| this large, but on some targets, the maximum alignment may be smaller |
| than 8, in which case objects of type @code{Long_Float} will be maximally |
| aligned. |
| |
| @item |
| @emph{Arrays}. |
| |
| For arrays, the alignment is equal to the alignment of the component type |
| for the normal case where no packing or component size is given. If the |
| array is packed, and the packing is effective (see separate section on |
| packed arrays), then the alignment will be either 4, 2, or 1 for long packed |
| arrays or arrays whose length is not known at compile time, depending on |
| whether the component size is divisible by 4, 2, or is odd. For short packed |
| arrays, which are handled internally as modular types, the alignment |
| will be as described for elementary types, e.g. a packed array of length |
| 31 bits will have an object size of four bytes, and an alignment of 4. |
| |
| @item |
| @emph{Records}. |
| |
| For the normal unpacked case, the alignment of a record is equal to |
| the maximum alignment of any of its components. For tagged records, this |
| includes the implicit access type used for the tag. If a pragma @code{Pack} |
| is used and all components are packable (see separate section on pragma |
| @code{Pack}), then the resulting alignment is 1, unless the layout of the |
| record makes it profitable to increase it. |
| |
| A special case is when: |
| |
| |
| @itemize * |
| |
| @item |
| the size of the record is given explicitly, or a |
| full record representation clause is given, and |
| |
| @item |
| the size of the record is 2, 4, or 8 bytes. |
| @end itemize |
| |
| In this case, an alignment is chosen to match the |
| size of the record. For example, if we have: |
| |
| @example |
| type Small is record |
| A, B : Character; |
| end record; |
| for Small'Size use 16; |
| @end example |
| |
| then the default alignment of the record type @code{Small} is 2, not 1. This |
| leads to more efficient code when the record is treated as a unit, and also |
| allows the type to specified as @code{Atomic} on architectures requiring |
| strict alignment. |
| @end itemize |
| |
| An alignment clause may specify a larger alignment than the default value |
| up to some maximum value dependent on the target (obtainable by using the |
| attribute reference @code{Standard'Maximum_Alignment}). It may also specify |
| a smaller alignment than the default value for enumeration, integer and |
| fixed point types, as well as for record types, for example |
| |
| @example |
| type V is record |
| A : Integer; |
| end record; |
| |
| for V'alignment use 1; |
| @end example |
| |
| @geindex Alignment |
| @geindex default |
| |
| The default alignment for the type @code{V} is 4, as a result of the |
| Integer field in the record, but it is permissible, as shown, to |
| override the default alignment of the record with a smaller value. |
| |
| @geindex Alignment |
| @geindex subtypes |
| |
| Note that according to the Ada standard, an alignment clause applies only |
| to the first named subtype. If additional subtypes are declared, then the |
| compiler is allowed to choose any alignment it likes, and there is no way |
| to control this choice. Consider: |
| |
| @example |
| type R is range 1 .. 10_000; |
| for R'Alignment use 1; |
| subtype RS is R range 1 .. 1000; |
| @end example |
| |
| The alignment clause specifies an alignment of 1 for the first named subtype |
| @code{R} but this does not necessarily apply to @code{RS}. When writing |
| portable Ada code, you should avoid writing code that explicitly or |
| implicitly relies on the alignment of such subtypes. |
| |
| For the GNAT compiler, if an explicit alignment clause is given, this |
| value is also used for any subsequent subtypes. So for GNAT, in the |
| above example, you can count on the alignment of @code{RS} being 1. But this |
| assumption is non-portable, and other compilers may choose different |
| alignments for the subtype @code{RS}. |
| |
| @node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27c} |
| @section Size Clauses |
| |
| |
| @geindex Size Clause |
| |
| The default size for a type @code{T} is obtainable through the |
| language-defined attribute @code{T'Size} and also through the |
| equivalent GNAT-defined attribute @code{T'Value_Size}. |
| For objects of type @code{T}, GNAT will generally increase the type size |
| so that the object size (obtainable through the GNAT-defined attribute |
| @code{T'Object_Size}) |
| is a multiple of @code{T'Alignment * Storage_Unit}. |
| |
| For example: |
| |
| @example |
| type Smallint is range 1 .. 6; |
| |
| type Rec is record |
| Y1 : integer; |
| Y2 : boolean; |
| end record; |
| @end example |
| |
| In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, |
| as specified by the RM rules, |
| but objects of this type will have a size of 8 |
| (@code{Smallint'Object_Size} = 8), |
| since objects by default occupy an integral number |
| of storage units. On some targets, notably older |
| versions of the Digital Alpha, the size of stand |
| alone objects of this type may be 32, reflecting |
| the inability of the hardware to do byte load/stores. |
| |
| Similarly, the size of type @code{Rec} is 40 bits |
| (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but |
| the alignment is 4, so objects of this type will have |
| their size increased to 64 bits so that it is a multiple |
| of the alignment (in bits). This decision is |
| in accordance with the specific Implementation Advice in RM 13.3(43): |
| |
| @quotation |
| |
| “A @code{Size} clause should be supported for an object if the specified |
| @code{Size} is at least as large as its subtype’s @code{Size}, and corresponds |
| to a size in storage elements that is a multiple of the object’s |
| @code{Alignment} (if the @code{Alignment} is nonzero).” |
| @end quotation |
| |
| An explicit size clause may be used to override the default size by |
| increasing it. For example, if we have: |
| |
| @example |
| type My_Boolean is new Boolean; |
| for My_Boolean'Size use 32; |
| @end example |
| |
| then values of this type will always be 32-bit long. In the case of discrete |
| types, the size can be increased up to 64 bits on 32-bit targets and 128 bits |
| on 64-bit targets, with the effect that the entire specified field is used to |
| hold the value, sign- or zero-extended as appropriate. If more than 64 bits |
| or 128 bits resp. is specified, then padding space is allocated after the |
| value, and a warning is issued that there are unused bits. |
| |
| Similarly the size of records and arrays may be increased, and the effect |
| is to add padding bits after the value. This also causes a warning message |
| to be generated. |
| |
| The largest Size value permitted in GNAT is 2**31-1. Since this is a |
| Size in bits, this corresponds to an object of size 256 megabytes (minus |
| one). This limitation is true on all targets. The reason for this |
| limitation is that it improves the quality of the code in many cases |
| if it is known that a Size value can be accommodated in an object of |
| type Integer. |
| |
| @node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27e} |
| @section Storage_Size Clauses |
| |
| |
| @geindex Storage_Size Clause |
| |
| For tasks, the @code{Storage_Size} clause specifies the amount of space |
| to be allocated for the task stack. This cannot be extended, and if the |
| stack is exhausted, then @code{Storage_Error} will be raised (if stack |
| checking is enabled). Use a @code{Storage_Size} attribute definition clause, |
| or a @code{Storage_Size} pragma in the task definition to set the |
| appropriate required size. A useful technique is to include in every |
| task definition a pragma of the form: |
| |
| @example |
| pragma Storage_Size (Default_Stack_Size); |
| @end example |
| |
| Then @code{Default_Stack_Size} can be defined in a global package, and |
| modified as required. Any tasks requiring stack sizes different from the |
| default can have an appropriate alternative reference in the pragma. |
| |
| You can also use the @emph{-d} binder switch to modify the default stack |
| size. |
| |
| For access types, the @code{Storage_Size} clause specifies the maximum |
| space available for allocation of objects of the type. If this space is |
| exceeded then @code{Storage_Error} will be raised by an allocation attempt. |
| In the case where the access type is declared local to a subprogram, the |
| use of a @code{Storage_Size} clause triggers automatic use of a special |
| predefined storage pool (@code{System.Pool_Size}) that ensures that all |
| space for the pool is automatically reclaimed on exit from the scope in |
| which the type is declared. |
| |
| A special case recognized by the compiler is the specification of a |
| @code{Storage_Size} of zero for an access type. This means that no |
| items can be allocated from the pool, and this is recognized at compile |
| time, and all the overhead normally associated with maintaining a fixed |
| size storage pool is eliminated. Consider the following example: |
| |
| @example |
| procedure p is |
| type R is array (Natural) of Character; |
| type P is access all R; |
| for P'Storage_Size use 0; |
| -- Above access type intended only for interfacing purposes |
| |
| y : P; |
| |
| procedure g (m : P); |
| pragma Import (C, g); |
| |
| -- ... |
| |
| begin |
| -- ... |
| y := new R; |
| end; |
| @end example |
| |
| As indicated in this example, these dummy storage pools are often useful in |
| connection with interfacing where no object will ever be allocated. If you |
| compile the above example, you get the warning: |
| |
| @example |
| p.adb:16:09: warning: allocation from empty storage pool |
| p.adb:16:09: warning: Storage_Error will be raised at run time |
| @end example |
| |
| Of course in practice, there will not be any explicit allocators in the |
| case of such an access declaration. |
| |
| @node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{280} |
| @section Size of Variant Record Objects |
| |
| |
| @geindex Size |
| @geindex variant record objects |
| |
| @geindex Variant record objects |
| @geindex size |
| |
| In the case of variant record objects, there is a question whether Size gives |
| information about a particular variant, or the maximum size required |
| for any variant. Consider the following program |
| |
| @example |
| with Text_IO; use Text_IO; |
| procedure q is |
| type R1 (A : Boolean := False) is record |
| case A is |
| when True => X : Character; |
| when False => null; |
| end case; |
| end record; |
| |
| V1 : R1 (False); |
| V2 : R1; |
| |
| begin |
| Put_Line (Integer'Image (V1'Size)); |
| Put_Line (Integer'Image (V2'Size)); |
| end q; |
| @end example |
| |
| Here we are dealing with a variant record, where the True variant |
| requires 16 bits, and the False variant requires 8 bits. |
| In the above example, both V1 and V2 contain the False variant, |
| which is only 8 bits long. However, the result of running the |
| program is: |
| |
| @example |
| 8 |
| 16 |
| @end example |
| |
| The reason for the difference here is that the discriminant value of |
| V1 is fixed, and will always be False. It is not possible to assign |
| a True variant value to V1, therefore 8 bits is sufficient. On the |
| other hand, in the case of V2, the initial discriminant value is |
| False (from the default), but it is possible to assign a True |
| variant value to V2, therefore 16 bits must be allocated for V2 |
| in the general case, even fewer bits may be needed at any particular |
| point during the program execution. |
| |
| As can be seen from the output of this program, the @code{'Size} |
| attribute applied to such an object in GNAT gives the actual allocated |
| size of the variable, which is the largest size of any of the variants. |
| The Ada Reference Manual is not completely clear on what choice should |
| be made here, but the GNAT behavior seems most consistent with the |
| language in the RM. |
| |
| In some cases, it may be desirable to obtain the size of the current |
| variant, rather than the size of the largest variant. This can be |
| achieved in GNAT by making use of the fact that in the case of a |
| subprogram parameter, GNAT does indeed return the size of the current |
| variant (because a subprogram has no way of knowing how much space |
| is actually allocated for the actual). |
| |
| Consider the following modified version of the above program: |
| |
| @example |
| with Text_IO; use Text_IO; |
| procedure q is |
| type R1 (A : Boolean := False) is record |
| case A is |
| when True => X : Character; |
| when False => null; |
| end case; |
| end record; |
| |
| V2 : R1; |
| |
| function Size (V : R1) return Integer is |
| begin |
| return V'Size; |
| end Size; |
| |
| begin |
| Put_Line (Integer'Image (V2'Size)); |
| Put_Line (Integer'Image (Size (V2))); |
| V2 := (True, 'x'); |
| Put_Line (Integer'Image (V2'Size)); |
| Put_Line (Integer'Image (Size (V2))); |
| end q; |
| @end example |
| |
| The output from this program is |
| |
| @example |
| 16 |
| 8 |
| 16 |
| 16 |
| @end example |
| |
| Here we see that while the @code{'Size} attribute always returns |
| the maximum size, regardless of the current variant value, the |
| @code{Size} function does indeed return the size of the current |
| variant value. |
| |
| @node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{282} |
| @section Biased Representation |
| |
| |
| @geindex Size for biased representation |
| |
| @geindex Biased representation |
| |
| In the case of scalars with a range starting at other than zero, it is |
| possible in some cases to specify a size smaller than the default minimum |
| value, and in such cases, GNAT uses an unsigned biased representation, |
| in which zero is used to represent the lower bound, and successive values |
| represent successive values of the type. |
| |
| For example, suppose we have the declaration: |
| |
| @example |
| type Small is range -7 .. -4; |
| for Small'Size use 2; |
| @end example |
| |
| Although the default size of type @code{Small} is 4, the @code{Size} |
| clause is accepted by GNAT and results in the following representation |
| scheme: |
| |
| @example |
| -7 is represented as 2#00# |
| -6 is represented as 2#01# |
| -5 is represented as 2#10# |
| -4 is represented as 2#11# |
| @end example |
| |
| Biased representation is only used if the specified @code{Size} clause |
| cannot be accepted in any other manner. These reduced sizes that force |
| biased representation can be used for all discrete types except for |
| enumeration types for which a representation clause is given. |
| |
| @node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{284} |
| @section Value_Size and Object_Size Clauses |
| |
| |
| @geindex Value_Size |
| |
| @geindex Object_Size |
| |
| @geindex Size |
| @geindex of objects |
| |
| In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum |
| number of bits required to hold values of type @code{T}. |
| Although this interpretation was allowed in Ada 83, it was not required, |
| and this requirement in practice can cause some significant difficulties. |
| For example, in most Ada 83 compilers, @code{Natural'Size} was 32. |
| However, in Ada 95 and Ada 2005, |
| @code{Natural'Size} is |
| typically 31. This means that code may change in behavior when moving |
| from Ada 83 to Ada 95 or Ada 2005. For example, consider: |
| |
| @example |
| type Rec is record; |
| A : Natural; |
| B : Natural; |
| end record; |
| |
| for Rec use record |
| at 0 range 0 .. Natural'Size - 1; |
| at 0 range Natural'Size .. 2 * Natural'Size - 1; |
| end record; |
| @end example |
| |
| In the above code, since the typical size of @code{Natural} objects |
| is 32 bits and @code{Natural'Size} is 31, the above code can cause |
| unexpected inefficient packing in Ada 95 and Ada 2005, and in general |
| there are cases where the fact that the object size can exceed the |
| size of the type causes surprises. |
| |
| To help get around this problem GNAT provides two implementation |
| defined attributes, @code{Value_Size} and @code{Object_Size}. When |
| applied to a type, these attributes yield the size of the type |
| (corresponding to the RM defined size attribute), and the size of |
| objects of the type respectively. |
| |
| The @code{Object_Size} is used for determining the default size of |
| objects and components. This size value can be referred to using the |
| @code{Object_Size} attribute. The phrase ‘is used’ here means that it is |
| the basis of the determination of the size. The backend is free to |
| pad this up if necessary for efficiency, e.g., an 8-bit stand-alone |
| character might be stored in 32 bits on a machine with no efficient |
| byte access instructions such as the Alpha. |
| |
| The default rules for the value of @code{Object_Size} for |
| discrete types are as follows: |
| |
| |
| @itemize * |
| |
| @item |
| The @code{Object_Size} for base subtypes reflect the natural hardware |
| size in bits (run the compiler with @emph{-gnatS} to find those values |
| for numeric types). Enumeration types and fixed-point base subtypes have |
| 8, 16, 32, or 64 bits for this size, depending on the range of values |
| to be stored. |
| |
| @item |
| The @code{Object_Size} of a subtype is the same as the |
| @code{Object_Size} of |
| the type from which it is obtained. |
| |
| @item |
| The @code{Object_Size} of a derived base type is copied from the parent |
| base type, and the @code{Object_Size} of a derived first subtype is copied |
| from the parent first subtype. |
| @end itemize |
| |
| The @code{Value_Size} attribute |
| is the (minimum) number of bits required to store a value |
| of the type. |
| This value is used to determine how tightly to pack |
| records or arrays with components of this type, and also affects |
| the semantics of unchecked conversion (unchecked conversions where |
| the @code{Value_Size} values differ generate a warning, and are potentially |
| target dependent). |
| |
| The default rules for the value of @code{Value_Size} are as follows: |
| |
| |
| @itemize * |
| |
| @item |
| The @code{Value_Size} for a base subtype is the minimum number of bits |
| required to store all values of the type (including the sign bit |
| only if negative values are possible). |
| |
| @item |
| If a subtype statically matches the first subtype of a given type, then it has |
| by default the same @code{Value_Size} as the first subtype. This is a |
| consequence of RM 13.1(14): “if two subtypes statically match, |
| then their subtype-specific aspects are the same”.) |
| |
| @item |
| All other subtypes have a @code{Value_Size} corresponding to the minimum |
| number of bits required to store all values of the subtype. For |
| dynamic bounds, it is assumed that the value can range down or up |
| to the corresponding bound of the ancestor |
| @end itemize |
| |
| The RM defined attribute @code{Size} corresponds to the |
| @code{Value_Size} attribute. |
| |
| The @code{Size} attribute may be defined for a first-named subtype. This sets |
| the @code{Value_Size} of |
| the first-named subtype to the given value, and the |
| @code{Object_Size} of this first-named subtype to the given value padded up |
| to an appropriate boundary. It is a consequence of the default rules |
| above that this @code{Object_Size} will apply to all further subtypes. On the |
| other hand, @code{Value_Size} is affected only for the first subtype, any |
| dynamic subtypes obtained from it directly, and any statically matching |
| subtypes. The @code{Value_Size} of any other static subtypes is not affected. |
| |
| @code{Value_Size} and |
| @code{Object_Size} may be explicitly set for any subtype using |
| an attribute definition clause. Note that the use of these attributes |
| can cause the RM 13.1(14) rule to be violated. If two access types |
| reference aliased objects whose subtypes have differing @code{Object_Size} |
| values as a result of explicit attribute definition clauses, then it |
| is illegal to convert from one access subtype to the other. For a more |
| complete description of this additional legality rule, see the |
| description of the @code{Object_Size} attribute. |
| |
| To get a feel for the difference, consider the following examples (note |
| that in each case the base is @code{Short_Short_Integer} with a size of 8): |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} |
| @headitem |
| |
| Type or subtype declaration |
| |
| @tab |
| |
| Object_Size |
| |
| @tab |
| |
| Value_Size |
| |
| @item |
| |
| @code{type x1 is range 0 .. 5;} |
| |
| @tab |
| |
| 8 |
| |
| @tab |
| |
| 3 |
| |
| @item |
| |
| @code{type x2 is range 0 .. 5;} |
| @code{for x2'size use 12;} |
| |
| @tab |
| |
| 16 |
| |
| @tab |
| |
| 12 |
| |
| @item |
| |
| @code{subtype x3 is x2 range 0 .. 3;} |
| |
| @tab |
| |
| 16 |
| |
| @tab |
| |
| 2 |
| |
| @item |
| |
| @code{subtype x4 is x2'base range 0 .. 10;} |
| |
| @tab |
| |
| 8 |
| |
| @tab |
| |
| 4 |
| |
| @item |
| |
| @code{dynamic : x2'Base range -64 .. +63;} |
| |
| @tab |
| |
| @tab |
| |
| @item |
| |
| @code{subtype x5 is x2 range 0 .. dynamic;} |
| |
| @tab |
| |
| 16 |
| |
| @tab |
| |
| 3* |
| |
| @item |
| |
| @code{subtype x6 is x2'base range 0 .. dynamic;} |
| |
| @tab |
| |
| 8 |
| |
| @tab |
| |
| 7* |
| |
| @end multitable |
| |
| |
| Note: the entries marked ‘*’ are not actually specified by the Ada |
| Reference Manual, which has nothing to say about size in the dynamic |
| case. What GNAT does is to allocate sufficient bits to accommodate any |
| possible dynamic values for the bounds at run-time. |
| |
| So far, so good, but GNAT has to obey the RM rules, so the question is |
| under what conditions must the RM @code{Size} be used. |
| The following is a list |
| of the occasions on which the RM @code{Size} must be used: |
| |
| |
| @itemize * |
| |
| @item |
| Component size for packed arrays or records |
| |
| @item |
| Value of the attribute @code{Size} for a type |
| |
| @item |
| Warning about sizes not matching for unchecked conversion |
| @end itemize |
| |
| For record types, the @code{Object_Size} is always a multiple of the |
| alignment of the type (this is true for all types). In some cases the |
| @code{Value_Size} can be smaller. Consider: |
| |
| @example |
| type R is record |
| X : Integer; |
| Y : Character; |
| end record; |
| @end example |
| |
| On a typical 32-bit architecture, the X component will occupy four bytes |
| and the Y component will occupy one byte, for a total of 5 bytes. As a |
| result @code{R'Value_Size} will be 40 (bits) since this is the minimum size |
| required to store a value of this type. For example, it is permissible |
| to have a component of type R in an array whose component size is |
| specified to be 40 bits. |
| |
| However, @code{R'Object_Size} will be 64 (bits). The difference is due to |
| the alignment requirement for objects of the record type. The X |
| component will require four-byte alignment because that is what type |
| Integer requires, whereas the Y component, a Character, will only |
| require 1-byte alignment. Since the alignment required for X is the |
| greatest of all the components’ alignments, that is the alignment |
| required for the enclosing record type, i.e., 4 bytes or 32 bits. As |
| indicated above, the actual object size must be rounded up so that it is |
| a multiple of the alignment value. Therefore, 40 bits rounded up to the |
| next multiple of 32 yields 64 bits. |
| |
| For all other types, the @code{Object_Size} |
| and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). |
| Only @code{Size} may be specified for such types. |
| |
| Note that @code{Value_Size} can be used to force biased representation |
| for a particular subtype. Consider this example: |
| |
| @example |
| type R is (A, B, C, D, E, F); |
| subtype RAB is R range A .. B; |
| subtype REF is R range E .. F; |
| @end example |
| |
| By default, @code{RAB} |
| has a size of 1 (sufficient to accommodate the representation |
| of @code{A} and @code{B}, 0 and 1), and @code{REF} |
| has a size of 3 (sufficient to accommodate the representation |
| of @code{E} and @code{F}, 4 and 5). But if we add the |
| following @code{Value_Size} attribute definition clause: |
| |
| @example |
| for REF'Value_Size use 1; |
| @end example |
| |
| then biased representation is forced for @code{REF}, |
| and 0 will represent @code{E} and 1 will represent @code{F}. |
| A warning is issued when a @code{Value_Size} attribute |
| definition clause forces biased representation. This |
| warning can be turned off using @code{-gnatw.B}. |
| |
| @node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{286} |
| @section Component_Size Clauses |
| |
| |
| @geindex Component_Size Clause |
| |
| Normally, the value specified in a component size clause must be consistent |
| with the subtype of the array component with regard to size and alignment. |
| In other words, the value specified must be at least equal to the size |
| of this subtype, and must be a multiple of the alignment value. |
| |
| In addition, component size clauses are allowed which cause the array |
| to be packed, by specifying a smaller value. A first case is for |
| component size values in the range 1 through 63 on 32-bit targets, |
| and 1 through 127 on 64-bit targets. The value specified may not |
| be smaller than the Size of the subtype. GNAT will accurately |
| honor all packing requests in this range. For example, if we have: |
| |
| @example |
| type r is array (1 .. 8) of Natural; |
| for r'Component_Size use 31; |
| @end example |
| |
| then the resulting array has a length of 31 bytes (248 bits = 8 * 31). |
| Of course access to the components of such an array is considerably |
| less efficient than if the natural component size of 32 is used. |
| A second case is when the subtype of the component is a record type |
| padded because of its default alignment. For example, if we have: |
| |
| @example |
| type r is record |
| i : Integer; |
| j : Integer; |
| b : Boolean; |
| end record; |
| |
| type a is array (1 .. 8) of r; |
| for a'Component_Size use 72; |
| @end example |
| |
| then the resulting array has a length of 72 bytes, instead of 96 bytes |
| if the alignment of the record (4) was obeyed. |
| |
| Note that there is no point in giving both a component size clause |
| and a pragma Pack for the same array type. if such duplicate |
| clauses are given, the pragma Pack will be ignored. |
| |
| @node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{288} |
| @section Bit_Order Clauses |
| |
| |
| @geindex Bit_Order Clause |
| |
| @geindex bit ordering |
| |
| @geindex ordering |
| @geindex of bits |
| |
| For record subtypes, GNAT permits the specification of the @code{Bit_Order} |
| attribute. The specification may either correspond to the default bit |
| order for the target, in which case the specification has no effect and |
| places no additional restrictions, or it may be for the non-standard |
| setting (that is the opposite of the default). |
| |
| In the case where the non-standard value is specified, the effect is |
| to renumber bits within each byte, but the ordering of bytes is not |
| affected. There are certain |
| restrictions placed on component clauses as follows: |
| |
| |
| @itemize * |
| |
| @item |
| Components fitting within a single storage unit. |
| |
| These are unrestricted, and the effect is merely to renumber bits. For |
| example if we are on a little-endian machine with @code{Low_Order_First} |
| being the default, then the following two declarations have exactly |
| the same effect: |
| |
| @example |
| type R1 is record |
| A : Boolean; |
| B : Integer range 1 .. 120; |
| end record; |
| |
| for R1 use record |
| A at 0 range 0 .. 0; |
| B at 0 range 1 .. 7; |
| end record; |
| |
| type R2 is record |
| A : Boolean; |
| B : Integer range 1 .. 120; |
| end record; |
| |
| for R2'Bit_Order use High_Order_First; |
| |
| for R2 use record |
| A at 0 range 7 .. 7; |
| B at 0 range 0 .. 6; |
| end record; |
| @end example |
| |
| The useful application here is to write the second declaration with the |
| @code{Bit_Order} attribute definition clause, and know that it will be treated |
| the same, regardless of whether the target is little-endian or big-endian. |
| |
| @item |
| Components occupying an integral number of bytes. |
| |
| These are components that exactly fit in two or more bytes. Such component |
| declarations are allowed, but have no effect, since it is important to realize |
| that the @code{Bit_Order} specification does not affect the ordering of bytes. |
| In particular, the following attempt at getting an endian-independent integer |
| does not work: |
| |
| @example |
| type R2 is record |
| A : Integer; |
| end record; |
| |
| for R2'Bit_Order use High_Order_First; |
| |
| for R2 use record |
| A at 0 range 0 .. 31; |
| end record; |
| @end example |
| |
| This declaration will result in a little-endian integer on a |
| little-endian machine, and a big-endian integer on a big-endian machine. |
| If byte flipping is required for interoperability between big- and |
| little-endian machines, this must be explicitly programmed. This capability |
| is not provided by @code{Bit_Order}. |
| |
| @item |
| Components that are positioned across byte boundaries. |
| |
| but do not occupy an integral number of bytes. Given that bytes are not |
| reordered, such fields would occupy a non-contiguous sequence of bits |
| in memory, requiring non-trivial code to reassemble. They are for this |
| reason not permitted, and any component clause specifying such a layout |
| will be flagged as illegal by GNAT. |
| @end itemize |
| |
| Since the misconception that Bit_Order automatically deals with all |
| endian-related incompatibilities is a common one, the specification of |
| a component field that is an integral number of bytes will always |
| generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} |
| if desired. The following section contains additional |
| details regarding the issue of byte ordering. |
| |
| @node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{28a} |
| @section Effect of Bit_Order on Byte Ordering |
| |
| |
| @geindex byte ordering |
| |
| @geindex ordering |
| @geindex of bytes |
| |
| In this section we will review the effect of the @code{Bit_Order} attribute |
| definition clause on byte ordering. Briefly, it has no effect at all, but |
| a detailed example will be helpful. Before giving this |
| example, let us review the precise |
| definition of the effect of defining @code{Bit_Order}. The effect of a |
| non-standard bit order is described in section 13.5.3 of the Ada |
| Reference Manual: |
| |
| @quotation |
| |
| “2 A bit ordering is a method of interpreting the meaning of |
| the storage place attributes.” |
| @end quotation |
| |
| To understand the precise definition of storage place attributes in |
| this context, we visit section 13.5.1 of the manual: |
| |
| @quotation |
| |
| “13 A record_representation_clause (without the mod_clause) |
| specifies the layout. The storage place attributes (see 13.5.2) |
| are taken from the values of the position, first_bit, and last_bit |
| expressions after normalizing those values so that first_bit is |
| less than Storage_Unit.” |
| @end quotation |
| |
| The critical point here is that storage places are taken from |
| the values after normalization, not before. So the @code{Bit_Order} |
| interpretation applies to normalized values. The interpretation |
| is described in the later part of the 13.5.3 paragraph: |
| |
| @quotation |
| |
| “2 A bit ordering is a method of interpreting the meaning of |
| the storage place attributes. High_Order_First (known in the |
| vernacular as ‘big endian’) means that the first bit of a |
| storage element (bit 0) is the most significant bit (interpreting |
| the sequence of bits that represent a component as an unsigned |
| integer value). Low_Order_First (known in the vernacular as |
| ‘little endian’) means the opposite: the first bit is the |
| least significant.” |
| @end quotation |
| |
| Note that the numbering is with respect to the bits of a storage |
| unit. In other words, the specification affects only the numbering |
| of bits within a single storage unit. |
| |
| We can make the effect clearer by giving an example. |
| |
| Suppose that we have an external device which presents two bytes, the first |
| byte presented, which is the first (low addressed byte) of the two byte |
| record is called Master, and the second byte is called Slave. |
| |
| The left most (most significant bit is called Control for each byte, and |
| the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost |
| (least significant) bit. |
| |
| On a big-endian machine, we can write the following representation clause |
| |
| @example |
| type Data is record |
| Master_Control : Bit; |
| Master_V1 : Bit; |
| Master_V2 : Bit; |
| Master_V3 : Bit; |
| Master_V4 : Bit; |
| Master_V5 : Bit; |
| Master_V6 : Bit; |
| Master_V7 : Bit; |
| Slave_Control : Bit; |
| Slave_V1 : Bit; |
| Slave_V2 : Bit; |
| Slave_V3 : Bit; |
| Slave_V4 : Bit; |
| Slave_V5 : Bit; |
| Slave_V6 : Bit; |
| Slave_V7 : Bit; |
| end record; |
| |
| for Data use record |
| Master_Control at 0 range 0 .. 0; |
| Master_V1 at 0 range 1 .. 1; |
| Master_V2 at 0 range 2 .. 2; |
| Master_V3 at 0 range 3 .. 3; |
| Master_V4 at 0 range 4 .. 4; |
| Master_V5 at 0 range 5 .. 5; |
| Master_V6 at 0 range 6 .. 6; |
| Master_V7 at 0 range 7 .. 7; |
| Slave_Control at 1 range 0 .. 0; |
| Slave_V1 at 1 range 1 .. 1; |
| Slave_V2 at 1 range 2 .. 2; |
| Slave_V3 at 1 range 3 .. 3; |
| Slave_V4 at 1 range 4 .. 4; |
| Slave_V5 at 1 range 5 .. 5; |
| Slave_V6 at 1 range 6 .. 6; |
| Slave_V7 at 1 range 7 .. 7; |
| end record; |
| @end example |
| |
| Now if we move this to a little endian machine, then the bit ordering within |
| the byte is backwards, so we have to rewrite the record rep clause as: |
| |
| @example |
| for Data use record |
| Master_Control at 0 range 7 .. 7; |
| Master_V1 at 0 range 6 .. 6; |
| Master_V2 at 0 range 5 .. 5; |
| Master_V3 at 0 range 4 .. 4; |
| Master_V4 at 0 range 3 .. 3; |
| Master_V5 at 0 range 2 .. 2; |
| Master_V6 at 0 range 1 .. 1; |
| Master_V7 at 0 range 0 .. 0; |
| Slave_Control at 1 range 7 .. 7; |
| Slave_V1 at 1 range 6 .. 6; |
| Slave_V2 at 1 range 5 .. 5; |
| Slave_V3 at 1 range 4 .. 4; |
| Slave_V4 at 1 range 3 .. 3; |
| Slave_V5 at 1 range 2 .. 2; |
| Slave_V6 at 1 range 1 .. 1; |
| Slave_V7 at 1 range 0 .. 0; |
| end record; |
| @end example |
| |
| It is a nuisance to have to rewrite the clause, especially if |
| the code has to be maintained on both machines. However, |
| this is a case that we can handle with the |
| @code{Bit_Order} attribute if it is implemented. |
| Note that the implementation is not required on byte addressed |
| machines, but it is indeed implemented in GNAT. |
| This means that we can simply use the |
| first record clause, together with the declaration |
| |
| @example |
| for Data'Bit_Order use High_Order_First; |
| @end example |
| |
| and the effect is what is desired, namely the layout is exactly the same, |
| independent of whether the code is compiled on a big-endian or little-endian |
| machine. |
| |
| The important point to understand is that byte ordering is not affected. |
| A @code{Bit_Order} attribute definition never affects which byte a field |
| ends up in, only where it ends up in that byte. |
| To make this clear, let us rewrite the record rep clause of the previous |
| example as: |
| |
| @example |
| for Data'Bit_Order use High_Order_First; |
| for Data use record |
| Master_Control at 0 range 0 .. 0; |
| Master_V1 at 0 range 1 .. 1; |
| Master_V2 at 0 range 2 .. 2; |
| Master_V3 at 0 range 3 .. 3; |
| Master_V4 at 0 range 4 .. 4; |
| Master_V5 at 0 range 5 .. 5; |
| Master_V6 at 0 range 6 .. 6; |
| Master_V7 at 0 range 7 .. 7; |
| Slave_Control at 0 range 8 .. 8; |
| Slave_V1 at 0 range 9 .. 9; |
| Slave_V2 at 0 range 10 .. 10; |
| Slave_V3 at 0 range 11 .. 11; |
| Slave_V4 at 0 range 12 .. 12; |
| Slave_V5 at 0 range 13 .. 13; |
| Slave_V6 at 0 range 14 .. 14; |
| Slave_V7 at 0 range 15 .. 15; |
| end record; |
| @end example |
| |
| This is exactly equivalent to saying (a repeat of the first example): |
| |
| @example |
| for Data'Bit_Order use High_Order_First; |
| for Data use record |
| Master_Control at 0 range 0 .. 0; |
| Master_V1 at 0 range 1 .. 1; |
| Master_V2 at 0 range 2 .. 2; |
| Master_V3 at 0 range 3 .. 3; |
| Master_V4 at 0 range 4 .. 4; |
| Master_V5 at 0 range 5 .. 5; |
| Master_V6 at 0 range 6 .. 6; |
| Master_V7 at 0 range 7 .. 7; |
| Slave_Control at 1 range 0 .. 0; |
| Slave_V1 at 1 range 1 .. 1; |
| Slave_V2 at 1 range 2 .. 2; |
| Slave_V3 at 1 range 3 .. 3; |
| Slave_V4 at 1 range 4 .. 4; |
| Slave_V5 at 1 range 5 .. 5; |
| Slave_V6 at 1 range 6 .. 6; |
| Slave_V7 at 1 range 7 .. 7; |
| end record; |
| @end example |
| |
| Why are they equivalent? Well take a specific field, the @code{Slave_V2} |
| field. The storage place attributes are obtained by normalizing the |
| values given so that the @code{First_Bit} value is less than 8. After |
| normalizing the values (0,10,10) we get (1,2,2) which is exactly what |
| we specified in the other case. |
| |
| Now one might expect that the @code{Bit_Order} attribute might affect |
| bit numbering within the entire record component (two bytes in this |
| case, thus affecting which byte fields end up in), but that is not |
| the way this feature is defined, it only affects numbering of bits, |
| not which byte they end up in. |
| |
| Consequently it never makes sense to specify a starting bit number |
| greater than 7 (for a byte addressable field) if an attribute |
| definition for @code{Bit_Order} has been given, and indeed it |
| may be actively confusing to specify such a value, so the compiler |
| generates a warning for such usage. |
| |
| If you do need to control byte ordering then appropriate conditional |
| values must be used. If in our example, the slave byte came first on |
| some machines we might write: |
| |
| @example |
| Master_Byte_First constant Boolean := ...; |
| |
| Master_Byte : constant Natural := |
| 1 - Boolean'Pos (Master_Byte_First); |
| Slave_Byte : constant Natural := |
| Boolean'Pos (Master_Byte_First); |
| |
| for Data'Bit_Order use High_Order_First; |
| for Data use record |
| Master_Control at Master_Byte range 0 .. 0; |
| Master_V1 at Master_Byte range 1 .. 1; |
| Master_V2 at Master_Byte range 2 .. 2; |
| Master_V3 at Master_Byte range 3 .. 3; |
| Master_V4 at Master_Byte range 4 .. 4; |
| Master_V5 at Master_Byte range 5 .. 5; |
| Master_V6 at Master_Byte range 6 .. 6; |
| Master_V7 at Master_Byte range 7 .. 7; |
| Slave_Control at Slave_Byte range 0 .. 0; |
| Slave_V1 at Slave_Byte range 1 .. 1; |
| Slave_V2 at Slave_Byte range 2 .. 2; |
| Slave_V3 at Slave_Byte range 3 .. 3; |
| Slave_V4 at Slave_Byte range 4 .. 4; |
| Slave_V5 at Slave_Byte range 5 .. 5; |
| Slave_V6 at Slave_Byte range 6 .. 6; |
| Slave_V7 at Slave_Byte range 7 .. 7; |
| end record; |
| @end example |
| |
| Now to switch between machines, all that is necessary is |
| to set the boolean constant @code{Master_Byte_First} in |
| an appropriate manner. |
| |
| @node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{28c} |
| @section Pragma Pack for Arrays |
| |
| |
| @geindex Pragma Pack (for arrays) |
| |
| Pragma @code{Pack} applied to an array has an effect that depends upon whether the |
| component type is @emph{packable}. For a component type to be @emph{packable}, it must |
| be one of the following cases: |
| |
| |
| @itemize * |
| |
| @item |
| Any elementary type. |
| |
| @item |
| Any small packed array type with a static size. |
| |
| @item |
| Any small simple record type with a static size. |
| @end itemize |
| |
| For all these cases, if the component subtype size is in the range |
| 1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets, |
| then the effect of the pragma @code{Pack} is exactly as though a |
| component size were specified giving the component subtype size. |
| |
| All other types are non-packable, they occupy an integral number of storage |
| units and the only effect of pragma Pack is to remove alignment gaps. |
| |
| For example if we have: |
| |
| @example |
| type r is range 0 .. 17; |
| |
| type ar is array (1 .. 8) of r; |
| pragma Pack (ar); |
| @end example |
| |
| Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, |
| and the size of the array @code{ar} will be exactly 40 bits). |
| |
| Note that in some cases this rather fierce approach to packing can produce |
| unexpected effects. For example, in Ada 95 and Ada 2005, |
| subtype @code{Natural} typically has a size of 31, meaning that if you |
| pack an array of @code{Natural}, you get 31-bit |
| close packing, which saves a few bits, but results in far less efficient |
| access. Since many other Ada compilers will ignore such a packing request, |
| GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses |
| might not be what is intended. You can easily remove this warning by |
| using an explicit @code{Component_Size} setting instead, which never generates |
| a warning, since the intention of the programmer is clear in this case. |
| |
| GNAT treats packed arrays in one of two ways. If the size of the array is |
| known at compile time and is at most 64 bits on 32-bit targets, and at most |
| 128 bits on 64-bit targets, then internally the array is represented as a |
| single modular type, of exactly the appropriate number of bits. If the |
| length is greater than 64 bits on 32-bit targets, and greater than 128 |
| bits on 64-bit targets, or is not known at compile time, then the packed |
| array is represented as an array of bytes, and its length is always a |
| multiple of 8 bits. |
| |
| Note that to represent a packed array as a modular type, the alignment must |
| be suitable for the modular type involved. For example, on typical machines |
| a 32-bit packed array will be represented by a 32-bit modular integer with |
| an alignment of four bytes. If you explicitly override the default alignment |
| with an alignment clause that is too small, the modular representation |
| cannot be used. For example, consider the following set of declarations: |
| |
| @example |
| type R is range 1 .. 3; |
| type S is array (1 .. 31) of R; |
| for S'Component_Size use 2; |
| for S'Size use 62; |
| for S'Alignment use 1; |
| @end example |
| |
| If the alignment clause were not present, then a 62-bit modular |
| representation would be chosen (typically with an alignment of 4 or 8 |
| bytes depending on the target). But the default alignment is overridden |
| with the explicit alignment clause. This means that the modular |
| representation cannot be used, and instead the array of bytes |
| representation must be used, meaning that the length must be a multiple |
| of 8. Thus the above set of declarations will result in a diagnostic |
| rejecting the size clause and noting that the minimum size allowed is 64. |
| |
| @geindex Pragma Pack (for type Natural) |
| |
| @geindex Pragma Pack warning |
| |
| One special case that is worth noting occurs when the base type of the |
| component size is 8/16/32 and the subtype is one bit less. Notably this |
| occurs with subtype @code{Natural}. Consider: |
| |
| @example |
| type Arr is array (1 .. 32) of Natural; |
| pragma Pack (Arr); |
| @end example |
| |
| In all commonly used Ada 83 compilers, this pragma Pack would be ignored, |
| since typically @code{Natural'Size} is 32 in Ada 83, and in any case most |
| Ada 83 compilers did not attempt 31 bit packing. |
| |
| In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, |
| GNAT really does pack 31-bit subtype to 31 bits. This may result in a |
| substantial unintended performance penalty when porting legacy Ada 83 code. |
| To help prevent this, GNAT generates a warning in such cases. If you really |
| want 31 bit packing in a case like this, you can set the component size |
| explicitly: |
| |
| @example |
| type Arr is array (1 .. 32) of Natural; |
| for Arr'Component_Size use 31; |
| @end example |
| |
| Here 31-bit packing is achieved as required, and no warning is generated, |
| since in this case the programmer intention is clear. |
| |
| @node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28e} |
| @section Pragma Pack for Records |
| |
| |
| @geindex Pragma Pack (for records) |
| |
| Pragma @code{Pack} applied to a record will pack the components to reduce |
| wasted space from alignment gaps and by reducing the amount of space |
| taken by components. We distinguish between @emph{packable} components and |
| @emph{non-packable} components. |
| Components of the following types are considered packable: |
| |
| |
| @itemize * |
| |
| @item |
| Components of an elementary type are packable unless they are aliased, |
| independent or atomic. |
| |
| @item |
| Small packed arrays, where the size is statically known, are represented |
| internally as modular integers, and so they are also packable. |
| |
| @item |
| Small simple records, where the size is statically known, are also packable. |
| @end itemize |
| |
| For all these cases, if the @code{'Size} value is in the range 1 through 64 on |
| 32-bit targets, and 1 through 128 on 64-bit targets, the components occupy |
| the exact number of bits corresponding to this value and are packed with no |
| padding bits, i.e. they can start on an arbitrary bit boundary. |
| |
| All other types are non-packable, they occupy an integral number of storage |
| units and the only effect of pragma @code{Pack} is to remove alignment gaps. |
| |
| For example, consider the record |
| |
| @example |
| type Rb1 is array (1 .. 13) of Boolean; |
| pragma Pack (Rb1); |
| |
| type Rb2 is array (1 .. 65) of Boolean; |
| pragma Pack (Rb2); |
| |
| type AF is new Float with Atomic; |
| |
| type X2 is record |
| L1 : Boolean; |
| L2 : Duration; |
| L3 : AF; |
| L4 : Boolean; |
| L5 : Rb1; |
| L6 : Rb2; |
| end record; |
| pragma Pack (X2); |
| @end example |
| |
| The representation for the record @code{X2} is as follows on 32-bit targets: |
| |
| @example |
| for X2'Size use 224; |
| for X2 use record |
| L1 at 0 range 0 .. 0; |
| L2 at 0 range 1 .. 64; |
| L3 at 12 range 0 .. 31; |
| L4 at 16 range 0 .. 0; |
| L5 at 16 range 1 .. 13; |
| L6 at 18 range 0 .. 71; |
| end record; |
| @end example |
| |
| Studying this example, we see that the packable fields @code{L1} |
| and @code{L2} are of length equal to their sizes, and placed at |
| specific bit boundaries (and not byte boundaries) to eliminate |
| padding. But @code{L3} is of a non-packable float type (because |
| it is aliased), so it is on the next appropriate alignment boundary. |
| |
| The next two fields are fully packable, so @code{L4} and @code{L5} are |
| minimally packed with no gaps. However, type @code{Rb2} is a packed |
| array that is longer than 64 bits, so it is itself non-packable on |
| 32-bit targets. Thus the @code{L6} field is aligned to the next byte |
| boundary, and takes an integral number of bytes, i.e., 72 bits. |
| |
| @node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{290} |
| @section Record Representation Clauses |
| |
| |
| @geindex Record Representation Clause |
| |
| Record representation clauses may be given for all record types, including |
| types obtained by record extension. Component clauses are allowed for any |
| static component. The restrictions on component clauses depend on the type |
| of the component. |
| |
| @geindex Component Clause |
| |
| For all components of an elementary type, the only restriction on component |
| clauses is that the size must be at least the @code{'Size} value of the type |
| (actually the Value_Size). There are no restrictions due to alignment, |
| and such components may freely cross storage boundaries. |
| |
| Packed arrays with a size up to and including 64 bits on 32-bit targets, |
| and up to and including 128 bits on 64-bit targets, are represented |
| internally using a modular type with the appropriate number of bits, and |
| thus the same lack of restriction applies. For example, if you declare: |
| |
| @example |
| type R is array (1 .. 49) of Boolean; |
| pragma Pack (R); |
| for R'Size use 49; |
| @end example |
| |
| then a component clause for a component of type @code{R} may start on any |
| specified bit boundary, and may specify a value of 49 bits or greater. |
| |
| For packed bit arrays that are longer than 64 bits on 32-bit targets, |
| and longer than 128 bits on 64-bit targets, there are two cases. If the |
| component size is a power of 2 (1,2,4,8,16,32,64 bits), including the |
| important case of single bits or boolean values, then there are no |
| limitations on placement of such components, and they may start and |
| end at arbitrary bit boundaries. |
| |
| If the component size is not a power of 2 (e.g., 3 or 5), then an array |
| of this type must always be placed on on a storage unit (byte) boundary |
| and occupy an integral number of storage units (bytes). Any component |
| clause that does not meet this requirement will be rejected. |
| |
| Any aliased component, or component of an aliased type, must have its |
| normal alignment and size. A component clause that does not meet this |
| requirement will be rejected. |
| |
| The tag field of a tagged type always occupies an address sized field at |
| the start of the record. No component clause may attempt to overlay this |
| tag. When a tagged type appears as a component, the tag field must have |
| proper alignment |
| |
| In the case of a record extension @code{T1}, of a type @code{T}, no component |
| clause applied to the type @code{T1} can specify a storage location that |
| would overlap the first @code{T'Object_Size} bits of the record. |
| |
| For all other component types, including non-bit-packed arrays, |
| the component can be placed at an arbitrary bit boundary, |
| so for example, the following is permitted: |
| |
| @example |
| type R is array (1 .. 10) of Boolean; |
| for R'Size use 80; |
| |
| type Q is record |
| G, H : Boolean; |
| L, M : R; |
| end record; |
| |
| for Q use record |
| G at 0 range 0 .. 0; |
| H at 0 range 1 .. 1; |
| L at 0 range 2 .. 81; |
| R at 0 range 82 .. 161; |
| end record; |
| @end example |
| |
| @node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{292} |
| @section Handling of Records with Holes |
| |
| |
| @geindex Handling of Records with Holes |
| |
| As a result of alignment considerations, records may contain “holes” |
| or gaps which do not correspond to the data bits of any of the components. |
| Record representation clauses can also result in holes in records. |
| |
| GNAT does not attempt to clear these holes, so in record objects, |
| they should be considered to hold undefined rubbish. The generated |
| equality routine just tests components so does not access these |
| undefined bits, and assignment and copy operations may or may not |
| preserve the contents of these holes (for assignments, the holes |
| in the target will in practice contain either the bits that are |
| present in the holes in the source, or the bits that were present |
| in the target before the assignment). |
| |
| If it is necessary to ensure that holes in records have all zero |
| bits, then record objects for which this initialization is desired |
| should be explicitly set to all zero values using Unchecked_Conversion |
| or address overlays. For example |
| |
| @example |
| type HRec is record |
| C : Character; |
| I : Integer; |
| end record; |
| @end example |
| |
| On typical machines, integers need to be aligned on a four-byte |
| boundary, resulting in three bytes of undefined rubbish following |
| the 8-bit field for C. To ensure that the hole in a variable of |
| type HRec is set to all zero bits, |
| you could for example do: |
| |
| @example |
| type Base is record |
| Dummy1, Dummy2 : Integer := 0; |
| end record; |
| |
| BaseVar : Base; |
| RealVar : Hrec; |
| for RealVar'Address use BaseVar'Address; |
| @end example |
| |
| Now the 8-bytes of the value of RealVar start out containing all zero |
| bits. A safer approach is to just define dummy fields, avoiding the |
| holes, as in: |
| |
| @example |
| type HRec is record |
| C : Character; |
| Dummy1 : Short_Short_Integer := 0; |
| Dummy2 : Short_Short_Integer := 0; |
| Dummy3 : Short_Short_Integer := 0; |
| I : Integer; |
| end record; |
| @end example |
| |
| And to make absolutely sure that the intent of this is followed, you |
| can use representation clauses: |
| |
| @example |
| for Hrec use record |
| C at 0 range 0 .. 7; |
| Dummy1 at 1 range 0 .. 7; |
| Dummy2 at 2 range 0 .. 7; |
| Dummy3 at 3 range 0 .. 7; |
| I at 4 range 0 .. 31; |
| end record; |
| for Hrec'Size use 64; |
| @end example |
| |
| @node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{294} |
| @section Enumeration Clauses |
| |
| |
| The only restriction on enumeration clauses is that the range of values |
| must be representable. For the signed case, if one or more of the |
| representation values are negative, all values must be in the range: |
| |
| @example |
| System.Min_Int .. System.Max_Int |
| @end example |
| |
| For the unsigned case, where all values are nonnegative, the values must |
| be in the range: |
| |
| @example |
| 0 .. System.Max_Binary_Modulus; |
| @end example |
| |
| A @emph{confirming} representation clause is one in which the values range |
| from 0 in sequence, i.e., a clause that confirms the default representation |
| for an enumeration type. |
| Such a confirming representation |
| is permitted by these rules, and is specially recognized by the compiler so |
| that no extra overhead results from the use of such a clause. |
| |
| If an array has an index type which is an enumeration type to which an |
| enumeration clause has been applied, then the array is stored in a compact |
| manner. Consider the declarations: |
| |
| @example |
| type r is (A, B, C); |
| for r use (A => 1, B => 5, C => 10); |
| type t is array (r) of Character; |
| @end example |
| |
| The array type t corresponds to a vector with exactly three elements and |
| has a default size equal to @code{3*Character'Size}. This ensures efficient |
| use of space, but means that accesses to elements of the array will incur |
| the overhead of converting representation values to the corresponding |
| positional values, (i.e., the value delivered by the @code{Pos} attribute). |
| |
| @node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{296} |
| @section Address Clauses |
| |
| |
| @geindex Address Clause |
| |
| The reference manual allows a general restriction on representation clauses, |
| as found in RM 13.1(22): |
| |
| @quotation |
| |
| “An implementation need not support representation |
| items containing nonstatic expressions, except that |
| an implementation should support a representation item |
| for a given entity if each nonstatic expression in the |
| representation item is a name that statically denotes |
| a constant declared before the entity.” |
| @end quotation |
| |
| In practice this is applicable only to address clauses, since this is the |
| only case in which a nonstatic expression is permitted by the syntax. As |
| the AARM notes in sections 13.1 (22.a-22.h): |
| |
| @quotation |
| |
| 22.a Reason: This is to avoid the following sort of thing: |
| |
| 22.b X : Integer := F(…); |
| Y : Address := G(…); |
| for X’Address use Y; |
| |
| 22.c In the above, we have to evaluate the |
| initialization expression for X before we |
| know where to put the result. This seems |
| like an unreasonable implementation burden. |
| |
| 22.d The above code should instead be written |
| like this: |
| |
| 22.e Y : constant Address := G(…); |
| X : Integer := F(…); |
| for X’Address use Y; |
| |
| 22.f This allows the expression ‘Y’ to be safely |
| evaluated before X is created. |
| |
| 22.g The constant could be a formal parameter of mode in. |
| |
| 22.h An implementation can support other nonstatic |
| expressions if it wants to. Expressions of type |
| Address are hardly ever static, but their value |
| might be known at compile time anyway in many |
| cases. |
| @end quotation |
| |
| GNAT does indeed permit many additional cases of nonstatic expressions. In |
| particular, if the type involved is elementary there are no restrictions |
| (since in this case, holding a temporary copy of the initialization value, |
| if one is present, is inexpensive). In addition, if there is no implicit or |
| explicit initialization, then there are no restrictions. GNAT will reject |
| only the case where all three of these conditions hold: |
| |
| |
| @itemize * |
| |
| @item |
| The type of the item is non-elementary (e.g., a record or array). |
| |
| @item |
| There is explicit or implicit initialization required for the object. |
| Note that access values are always implicitly initialized. |
| |
| @item |
| The address value is nonstatic. Here GNAT is more permissive than the |
| RM, and allows the address value to be the address of a previously declared |
| stand-alone variable, as long as it does not itself have an address clause. |
| |
| @example |
| Anchor : Some_Initialized_Type; |
| Overlay : Some_Initialized_Type; |
| for Overlay'Address use Anchor'Address; |
| @end example |
| |
| However, the prefix of the address clause cannot be an array component, or |
| a component of a discriminated record. |
| @end itemize |
| |
| As noted above in section 22.h, address values are typically nonstatic. In |
| particular the To_Address function, even if applied to a literal value, is |
| a nonstatic function call. To avoid this minor annoyance, GNAT provides |
| the implementation defined attribute ‘To_Address. The following two |
| expressions have identical values: |
| |
| @geindex Attribute |
| |
| @geindex To_Address |
| |
| @example |
| To_Address (16#1234_0000#) |
| System'To_Address (16#1234_0000#); |
| @end example |
| |
| except that the second form is considered to be a static expression, and |
| thus when used as an address clause value is always permitted. |
| |
| Additionally, GNAT treats as static an address clause that is an |
| unchecked_conversion of a static integer value. This simplifies the porting |
| of legacy code, and provides a portable equivalent to the GNAT attribute |
| @code{To_Address}. |
| |
| Another issue with address clauses is the interaction with alignment |
| requirements. When an address clause is given for an object, the address |
| value must be consistent with the alignment of the object (which is usually |
| the same as the alignment of the type of the object). If an address clause |
| is given that specifies an inappropriately aligned address value, then the |
| program execution is erroneous. |
| |
| Since this source of erroneous behavior can have unfortunate effects on |
| machines with strict alignment requirements, GNAT |
| checks (at compile time if possible, generating a warning, or at execution |
| time with a run-time check) that the alignment is appropriate. If the |
| run-time check fails, then @code{Program_Error} is raised. This run-time |
| check is suppressed if range checks are suppressed, or if the special GNAT |
| check Alignment_Check is suppressed, or if |
| @code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also |
| suppressed by default on non-strict alignment machines (such as the x86). |
| |
| Finally, GNAT does not permit overlaying of objects of class-wide types. In |
| most cases, the compiler can detect an attempt at such overlays and will |
| generate a warning at compile time and a Program_Error exception at run time. |
| |
| @geindex Export |
| |
| An address clause cannot be given for an exported object. More |
| understandably the real restriction is that objects with an address |
| clause cannot be exported. This is because such variables are not |
| defined by the Ada program, so there is no external object to export. |
| |
| @geindex Import |
| |
| It is permissible to give an address clause and a pragma Import for the |
| same object. In this case, the variable is not really defined by the |
| Ada program, so there is no external symbol to be linked. The link name |
| and the external name are ignored in this case. The reason that we allow this |
| combination is that it provides a useful idiom to avoid unwanted |
| initializations on objects with address clauses. |
| |
| When an address clause is given for an object that has implicit or |
| explicit initialization, then by default initialization takes place. This |
| means that the effect of the object declaration is to overwrite the |
| memory at the specified address. This is almost always not what the |
| programmer wants, so GNAT will output a warning: |
| |
| @example |
| with System; |
| package G is |
| type R is record |
| M : Integer := 0; |
| end record; |
| |
| Ext : R; |
| for Ext'Address use System'To_Address (16#1234_1234#); |
| | |
| >>> warning: implicit initialization of "Ext" may |
| modify overlaid storage |
| >>> warning: use pragma Import for "Ext" to suppress |
| initialization (RM B(24)) |
| |
| end G; |
| @end example |
| |
| As indicated by the warning message, the solution is to use a (dummy) pragma |
| Import to suppress this initialization. The pragma tell the compiler that the |
| object is declared and initialized elsewhere. The following package compiles |
| without warnings (and the initialization is suppressed): |
| |
| @example |
| with System; |
| package G is |
| type R is record |
| M : Integer := 0; |
| end record; |
| |
| Ext : R; |
| for Ext'Address use System'To_Address (16#1234_1234#); |
| pragma Import (Ada, Ext); |
| end G; |
| @end example |
| |
| A final issue with address clauses involves their use for overlaying |
| variables, as in the following example: |
| |
| @geindex Overlaying of objects |
| |
| @example |
| A : Integer; |
| B : Integer; |
| for B'Address use A'Address; |
| @end example |
| |
| or alternatively, using the form recommended by the RM: |
| |
| @example |
| A : Integer; |
| Addr : constant Address := A'Address; |
| B : Integer; |
| for B'Address use Addr; |
| @end example |
| |
| In both of these cases, @code{A} and @code{B} become aliased to one another |
| via the address clause. This use of address clauses to overlay |
| variables, achieving an effect similar to unchecked conversion |
| was erroneous in Ada 83, but in Ada 95 and Ada 2005 |
| the effect is implementation defined. Furthermore, the |
| Ada RM specifically recommends that in a situation |
| like this, @code{B} should be subject to the following |
| implementation advice (RM 13.3(19)): |
| |
| @quotation |
| |
| “19 If the Address of an object is specified, or it is imported |
| or exported, then the implementation should not perform |
| optimizations based on assumptions of no aliases.” |
| @end quotation |
| |
| GNAT follows this recommendation, and goes further by also applying |
| this recommendation to the overlaid variable (@code{A} in the above example) |
| in this case. This means that the overlay works “as expected”, in that |
| a modification to one of the variables will affect the value of the other. |
| |
| More generally, GNAT interprets this recommendation conservatively for |
| address clauses: in the cases other than overlays, it considers that the |
| object is effectively subject to pragma @code{Volatile} and implements the |
| associated semantics. |
| |
| Note that when address clause overlays are used in this way, there is an |
| issue of unintentional initialization, as shown by this example: |
| |
| @example |
| package Overwrite_Record is |
| type R is record |
| A : Character := 'C'; |
| B : Character := 'A'; |
| end record; |
| X : Short_Integer := 3; |
| Y : R; |
| for Y'Address use X'Address; |
| | |
| >>> warning: default initialization of "Y" may |
| modify "X", use pragma Import for "Y" to |
| suppress initialization (RM B.1(24)) |
| |
| end Overwrite_Record; |
| @end example |
| |
| Here the default initialization of @code{Y} will clobber the value |
| of @code{X}, which justifies the warning. The warning notes that |
| this effect can be eliminated by adding a @code{pragma Import} |
| which suppresses the initialization: |
| |
| @example |
| package Overwrite_Record is |
| type R is record |
| A : Character := 'C'; |
| B : Character := 'A'; |
| end record; |
| X : Short_Integer := 3; |
| Y : R; |
| for Y'Address use X'Address; |
| pragma Import (Ada, Y); |
| end Overwrite_Record; |
| @end example |
| |
| Note that the use of @code{pragma Initialize_Scalars} may cause variables to |
| be initialized when they would not otherwise have been in the absence |
| of the use of this pragma. This may cause an overlay to have this |
| unintended clobbering effect. The compiler avoids this for scalar |
| types, but not for composite objects (where in general the effect |
| of @code{Initialize_Scalars} is part of the initialization routine |
| for the composite object): |
| |
| @example |
| pragma Initialize_Scalars; |
| with Ada.Text_IO; use Ada.Text_IO; |
| procedure Overwrite_Array is |
| type Arr is array (1 .. 5) of Integer; |
| X : Arr := (others => 1); |
| A : Arr; |
| for A'Address use X'Address; |
| | |
| >>> warning: default initialization of "A" may |
| modify "X", use pragma Import for "A" to |
| suppress initialization (RM B.1(24)) |
| |
| begin |
| if X /= Arr'(others => 1) then |
| Put_Line ("X was clobbered"); |
| else |
| Put_Line ("X was not clobbered"); |
| end if; |
| end Overwrite_Array; |
| @end example |
| |
| The above program generates the warning as shown, and at execution |
| time, prints @code{X was clobbered}. If the @code{pragma Import} is |
| added as suggested: |
| |
| @example |
| pragma Initialize_Scalars; |
| with Ada.Text_IO; use Ada.Text_IO; |
| procedure Overwrite_Array is |
| type Arr is array (1 .. 5) of Integer; |
| X : Arr := (others => 1); |
| A : Arr; |
| for A'Address use X'Address; |
| pragma Import (Ada, A); |
| begin |
| if X /= Arr'(others => 1) then |
| Put_Line ("X was clobbered"); |
| else |
| Put_Line ("X was not clobbered"); |
| end if; |
| end Overwrite_Array; |
| @end example |
| |
| then the program compiles without the warning and when run will generate |
| the output @code{X was not clobbered}. |
| |
| @node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{297}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{298} |
| @section Use of Address Clauses for Memory-Mapped I/O |
| |
| |
| @geindex Memory-mapped I/O |
| |
| A common pattern is to use an address clause to map an atomic variable to |
| a location in memory that corresponds to a memory-mapped I/O operation or |
| operations, for example: |
| |
| @example |
| type Mem_Word is record |
| A,B,C,D : Byte; |
| end record; |
| pragma Atomic (Mem_Word); |
| for Mem_Word_Size use 32; |
| |
| Mem : Mem_Word; |
| for Mem'Address use some-address; |
| ... |
| Temp := Mem; |
| Temp.A := 32; |
| Mem := Temp; |
| @end example |
| |
| For a full access (reference or modification) of the variable (Mem) in this |
| case, as in the above examples, GNAT guarantees that the entire atomic word |
| will be accessed, in accordance with the RM C.6(15) clause. |
| |
| A problem arises with a component access such as: |
| |
| @example |
| Mem.A := 32; |
| @end example |
| |
| Note that the component A is not declared as atomic. This means that it is |
| not clear what this assignment means. It could correspond to full word read |
| and write as given in the first example, or on architectures that supported |
| such an operation it might be a single byte store instruction. The RM does |
| not have anything to say in this situation, and GNAT does not make any |
| guarantee. The code generated may vary from target to target. GNAT will issue |
| a warning in such a case: |
| |
| @example |
| Mem.A := 32; |
| | |
| >>> warning: access to non-atomic component of atomic array, |
| may cause unexpected accesses to atomic object |
| @end example |
| |
| It is best to be explicit in this situation, by either declaring the |
| components to be atomic if you want the byte store, or explicitly writing |
| the full word access sequence if that is what the hardware requires. |
| Alternatively, if the full word access sequence is required, GNAT also |
| provides the pragma @code{Volatile_Full_Access} which can be used in lieu of |
| pragma @code{Atomic} and will give the additional guarantee. |
| |
| @node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{29a} |
| @section Effect of Convention on Representation |
| |
| |
| @geindex Convention |
| @geindex effect on representation |
| |
| Normally the specification of a foreign language convention for a type or |
| an object has no effect on the chosen representation. In particular, the |
| representation chosen for data in GNAT generally meets the standard system |
| conventions, and for example records are laid out in a manner that is |
| consistent with C. This means that specifying convention C (for example) |
| has no effect. |
| |
| There are four exceptions to this general rule: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Convention Fortran and array subtypes}. |
| |
| If pragma Convention Fortran is specified for an array subtype, then in |
| accordance with the implementation advice in section 3.6.2(11) of the |
| Ada Reference Manual, the array will be stored in a Fortran-compatible |
| column-major manner, instead of the normal default row-major order. |
| |
| @item |
| @emph{Convention C and enumeration types} |
| |
| GNAT normally stores enumeration types in 8, 16, or 32 bits as required |
| to accommodate all values of the type. For example, for the enumeration |
| type declared by: |
| |
| @example |
| type Color is (Red, Green, Blue); |
| @end example |
| |
| 8 bits is sufficient to store all values of the type, so by default, objects |
| of type @code{Color} will be represented using 8 bits. However, normal C |
| convention is to use 32 bits for all enum values in C, since enum values |
| are essentially of type int. If pragma @code{Convention C} is specified for an |
| Ada enumeration type, then the size is modified as necessary (usually to |
| 32 bits) to be consistent with the C convention for enum values. |
| |
| Note that this treatment applies only to types. If Convention C is given for |
| an enumeration object, where the enumeration type is not Convention C, then |
| Object_Size bits are allocated. For example, for a normal enumeration type, |
| with less than 256 elements, only 8 bits will be allocated for the object. |
| Since this may be a surprise in terms of what C expects, GNAT will issue a |
| warning in this situation. The warning can be suppressed by giving an explicit |
| size clause specifying the desired size. |
| |
| @item |
| @emph{Convention C/Fortran and Boolean types} |
| |
| In C, the usual convention for boolean values, that is values used for |
| conditions, is that zero represents false, and nonzero values represent |
| true. In Ada, the normal convention is that two specific values, typically |
| 0/1, are used to represent false/true respectively. |
| |
| Fortran has a similar convention for @code{LOGICAL} values (any nonzero |
| value represents true). |
| |
| To accommodate the Fortran and C conventions, if a pragma Convention specifies |
| C or Fortran convention for a derived Boolean, as in the following example: |
| |
| @example |
| type C_Switch is new Boolean; |
| pragma Convention (C, C_Switch); |
| @end example |
| |
| then the GNAT generated code will treat any nonzero value as true. For truth |
| values generated by GNAT, the conventional value 1 will be used for True, but |
| when one of these values is read, any nonzero value is treated as True. |
| @end itemize |
| |
| @node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29c} |
| @section Conventions and Anonymous Access Types |
| |
| |
| @geindex Anonymous access types |
| |
| @geindex Convention for anonymous access types |
| |
| The RM is not entirely clear on convention handling in a number of cases, |
| and in particular, it is not clear on the convention to be given to |
| anonymous access types in general, and in particular what is to be |
| done for the case of anonymous access-to-subprogram. |
| |
| In GNAT, we decide that if an explicit Convention is applied |
| to an object or component, and its type is such an anonymous type, |
| then the convention will apply to this anonymous type as well. This |
| seems to make sense since it is anomolous in any case to have a |
| different convention for an object and its type, and there is clearly |
| no way to explicitly specify a convention for an anonymous type, since |
| it doesn’t have a name to specify! |
| |
| Furthermore, we decide that if a convention is applied to a record type, |
| then this convention is inherited by any of its components that are of an |
| anonymous access type which do not have an explicitly specified convention. |
| |
| The following program shows these conventions in action: |
| |
| @example |
| package ConvComp is |
| type Foo is range 1 .. 10; |
| type T1 is record |
| A : access function (X : Foo) return Integer; |
| B : Integer; |
| end record; |
| pragma Convention (C, T1); |
| |
| type T2 is record |
| A : access function (X : Foo) return Integer; |
| pragma Convention (C, A); |
| B : Integer; |
| end record; |
| pragma Convention (COBOL, T2); |
| |
| type T3 is record |
| A : access function (X : Foo) return Integer; |
| pragma Convention (COBOL, A); |
| B : Integer; |
| end record; |
| pragma Convention (C, T3); |
| |
| type T4 is record |
| A : access function (X : Foo) return Integer; |
| B : Integer; |
| end record; |
| pragma Convention (COBOL, T4); |
| |
| function F (X : Foo) return Integer; |
| pragma Convention (C, F); |
| |
| function F (X : Foo) return Integer is (13); |
| |
| TV1 : T1 := (F'Access, 12); -- OK |
| TV2 : T2 := (F'Access, 13); -- OK |
| |
| TV3 : T3 := (F'Access, 13); -- ERROR |
| | |
| >>> subprogram "F" has wrong convention |
| >>> does not match access to subprogram declared at line 17 |
| 38. TV4 : T4 := (F'Access, 13); -- ERROR |
| | |
| >>> subprogram "F" has wrong convention |
| >>> does not match access to subprogram declared at line 24 |
| 39. end ConvComp; |
| @end example |
| |
| @node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas |
| @anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{29d}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29e} |
| @section Determining the Representations chosen by GNAT |
| |
| |
| @geindex Representation |
| @geindex determination of |
| |
| @geindex -gnatR (gcc) |
| |
| Although the descriptions in this section are intended to be complete, it is |
| often easier to simply experiment to see what GNAT accepts and what the |
| effect is on the layout of types and objects. |
| |
| As required by the Ada RM, if a representation clause is not accepted, then |
| it must be rejected as illegal by the compiler. However, when a |
| representation clause or pragma is accepted, there can still be questions |
| of what the compiler actually does. For example, if a partial record |
| representation clause specifies the location of some components and not |
| others, then where are the non-specified components placed? Or if pragma |
| @code{Pack} is used on a record, then exactly where are the resulting |
| fields placed? The section on pragma @code{Pack} in this chapter can be |
| used to answer the second question, but it is often easier to just see |
| what the compiler does. |
| |
| For this purpose, GNAT provides the option @emph{-gnatR}. If you compile |
| with this option, then the compiler will output information on the actual |
| representations chosen, in a format similar to source representation |
| clauses. For example, if we compile the package: |
| |
| @example |
| package q is |
| type r (x : boolean) is tagged record |
| case x is |
| when True => S : String (1 .. 100); |
| when False => null; |
| end case; |
| end record; |
| |
| type r2 is new r (false) with record |
| y2 : integer; |
| end record; |
| |
| for r2 use record |
| y2 at 16 range 0 .. 31; |
| end record; |
| |
| type x is record |
| y : character; |
| end record; |
| |
| type x1 is array (1 .. 10) of x; |
| for x1'component_size use 11; |
| |
| type ia is access integer; |
| |
| type Rb1 is array (1 .. 13) of Boolean; |
| pragma Pack (rb1); |
| |
| type Rb2 is array (1 .. 65) of Boolean; |
| pragma Pack (rb2); |
| |
| type x2 is record |
| l1 : Boolean; |
| l2 : Duration; |
| l3 : Float; |
| l4 : Boolean; |
| l5 : Rb1; |
| l6 : Rb2; |
| end record; |
| pragma Pack (x2); |
| end q; |
| @end example |
| |
| using the switch @emph{-gnatR} we obtain the following output: |
| |
| @example |
| Representation information for unit q |
| ------------------------------------- |
| |
| for r'Size use ??; |
| for r'Alignment use 4; |
| for r use record |
| x at 4 range 0 .. 7; |
| _tag at 0 range 0 .. 31; |
| s at 5 range 0 .. 799; |
| end record; |
| |
| for r2'Size use 160; |
| for r2'Alignment use 4; |
| for r2 use record |
| x at 4 range 0 .. 7; |
| _tag at 0 range 0 .. 31; |
| _parent at 0 range 0 .. 63; |
| y2 at 16 range 0 .. 31; |
| end record; |
| |
| for x'Size use 8; |
| for x'Alignment use 1; |
| for x use record |
| y at 0 range 0 .. 7; |
| end record; |
| |
| for x1'Size use 112; |
| for x1'Alignment use 1; |
| for x1'Component_Size use 11; |
| |
| for rb1'Size use 13; |
| for rb1'Alignment use 2; |
| for rb1'Component_Size use 1; |
| |
| for rb2'Size use 72; |
| for rb2'Alignment use 1; |
| for rb2'Component_Size use 1; |
| |
| for x2'Size use 224; |
| for x2'Alignment use 4; |
| for x2 use record |
| l1 at 0 range 0 .. 0; |
| l2 at 0 range 1 .. 64; |
| l3 at 12 range 0 .. 31; |
| l4 at 16 range 0 .. 0; |
| l5 at 16 range 1 .. 13; |
| l6 at 18 range 0 .. 71; |
| end record; |
| @end example |
| |
| The Size values are actually the Object_Size, i.e., the default size that |
| will be allocated for objects of the type. |
| The @code{??} size for type r indicates that we have a variant record, and the |
| actual size of objects will depend on the discriminant value. |
| |
| The Alignment values show the actual alignment chosen by the compiler |
| for each record or array type. |
| |
| The record representation clause for type r shows where all fields |
| are placed, including the compiler generated tag field (whose location |
| cannot be controlled by the programmer). |
| |
| The record representation clause for the type extension r2 shows all the |
| fields present, including the parent field, which is a copy of the fields |
| of the parent type of r2, i.e., r1. |
| |
| The component size and size clauses for types rb1 and rb2 show |
| the exact effect of pragma @code{Pack} on these arrays, and the record |
| representation clause for type x2 shows how pragma @cite{Pack} affects |
| this record type. |
| |
| In some cases, it may be useful to cut and paste the representation clauses |
| generated by the compiler into the original source to fix and guarantee |
| the actual representation to be used. |
| |
| @node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top |
| @anchor{gnat_rm/standard_library_routines doc}@anchor{29f}@anchor{gnat_rm/standard_library_routines id1}@anchor{2a0}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e} |
| @chapter Standard Library Routines |
| |
| |
| The Ada Reference Manual contains in Annex A a full description of an |
| extensive set of standard library routines that can be used in any Ada |
| program, and which must be provided by all Ada compilers. They are |
| analogous to the standard C library used by C programs. |
| |
| GNAT implements all of the facilities described in annex A, and for most |
| purposes the description in the Ada Reference Manual, or appropriate Ada |
| text book, will be sufficient for making use of these facilities. |
| |
| In the case of the input-output facilities, |
| @ref{f,,The Implementation of Standard I/O}, |
| gives details on exactly how GNAT interfaces to the |
| file system. For the remaining packages, the Ada Reference Manual |
| should be sufficient. The following is a list of the packages included, |
| together with a brief description of the functionality that is provided. |
| |
| For completeness, references are included to other predefined library |
| routines defined in other sections of the Ada Reference Manual (these are |
| cross-indexed from Annex A). For further details see the relevant |
| package declarations in the run-time library. In particular, a few units |
| are not implemented, as marked by the presence of pragma Unimplemented_Unit, |
| and in this case the package declaration contains comments explaining why |
| the unit is not implemented. |
| |
| |
| @table @asis |
| |
| @item @code{Ada} @emph{(A.2)} |
| |
| This is a parent package for all the standard library packages. It is |
| usually included implicitly in your program, and itself contains no |
| useful data or routines. |
| |
| @item @code{Ada.Assertions} @emph{(11.4.2)} |
| |
| @code{Assertions} provides the @code{Assert} subprograms, and also |
| the declaration of the @code{Assertion_Error} exception. |
| |
| @item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} |
| |
| @code{Asynchronous_Task_Control} provides low level facilities for task |
| synchronization. It is typically not implemented. See package spec for details. |
| |
| @item @code{Ada.Calendar} @emph{(9.6)} |
| |
| @code{Calendar} provides time of day access, and routines for |
| manipulating times and durations. |
| |
| @item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} |
| |
| This package provides additional arithmetic |
| operations for @code{Calendar}. |
| |
| @item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} |
| |
| This package provides formatting operations for @code{Calendar}. |
| |
| @item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} |
| |
| This package provides additional @code{Calendar} facilities |
| for handling time zones. |
| |
| @item @code{Ada.Characters} @emph{(A.3.1)} |
| |
| This is a dummy parent package that contains no useful entities |
| |
| @item @code{Ada.Characters.Conversions} @emph{(A.3.2)} |
| |
| This package provides character conversion functions. |
| |
| @item @code{Ada.Characters.Handling} @emph{(A.3.2)} |
| |
| This package provides some basic character handling capabilities, |
| including classification functions for classes of characters (e.g., test |
| for letters, or digits). |
| |
| @item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} |
| |
| This package includes a complete set of definitions of the characters |
| that appear in type CHARACTER. It is useful for writing programs that |
| will run in international environments. For example, if you want an |
| upper case E with an acute accent in a string, it is often better to use |
| the definition of @code{UC_E_Acute} in this package. Then your program |
| will print in an understandable manner even if your environment does not |
| support these extended characters. |
| |
| @item @code{Ada.Command_Line} @emph{(A.15)} |
| |
| This package provides access to the command line parameters and the name |
| of the current program (analogous to the use of @code{argc} and @code{argv} |
| in C), and also allows the exit status for the program to be set in a |
| system-independent manner. |
| |
| @item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} |
| |
| This package provides text input and output of complex numbers. |
| |
| @item @code{Ada.Containers} @emph{(A.18.1)} |
| |
| A top level package providing a few basic definitions used by all the |
| following specific child packages that provide specific kinds of |
| containers. |
| @end table |
| |
| @code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} |
| |
| @code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} |
| |
| @code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} |
| |
| @code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} |
| |
| @code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} |
| |
| @code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} |
| |
| @code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} |
| |
| @code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} |
| |
| @code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} |
| |
| @code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} |
| |
| @code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} |
| |
| @code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} |
| |
| @code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} |
| |
| @code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} |
| |
| @code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} |
| |
| @code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} |
| |
| @code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} |
| |
| @code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} |
| |
| @code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} |
| |
| @code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} |
| |
| @code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} |
| |
| @code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} |
| |
| @code{Ada.Containers.Vectors} @emph{(A.18.2)} |
| |
| |
| @table @asis |
| |
| @item @code{Ada.Directories} @emph{(A.16)} |
| |
| This package provides operations on directories. |
| |
| @item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} |
| |
| This package provides additional directory operations handling |
| hiearchical file names. |
| |
| @item @code{Ada.Directories.Information} @emph{(A.16)} |
| |
| This is an implementation defined package for additional directory |
| operations, which is not implemented in GNAT. |
| |
| @item @code{Ada.Decimal} @emph{(F.2)} |
| |
| This package provides constants describing the range of decimal numbers |
| implemented, and also a decimal divide routine (analogous to the COBOL |
| verb DIVIDE … GIVING … REMAINDER …) |
| |
| @item @code{Ada.Direct_IO} @emph{(A.8.4)} |
| |
| This package provides input-output using a model of a set of records of |
| fixed-length, containing an arbitrary definite Ada type, indexed by an |
| integer record number. |
| |
| @item @code{Ada.Dispatching} @emph{(D.2.1)} |
| |
| A parent package containing definitions for task dispatching operations. |
| |
| @item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} |
| |
| Not implemented in GNAT. |
| |
| @item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} |
| |
| Not implemented in GNAT. |
| |
| @item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} |
| |
| Not implemented in GNAT. |
| |
| @item @code{Ada.Dynamic_Priorities} @emph{(D.5)} |
| |
| This package allows the priorities of a task to be adjusted dynamically |
| as the task is running. |
| |
| @item @code{Ada.Environment_Variables} @emph{(A.17)} |
| |
| This package provides facilities for accessing environment variables. |
| |
| @item @code{Ada.Exceptions} @emph{(11.4.1)} |
| |
| This package provides additional information on exceptions, and also |
| contains facilities for treating exceptions as data objects, and raising |
| exceptions with associated messages. |
| |
| @item @code{Ada.Execution_Time} @emph{(D.14)} |
| |
| This package provides CPU clock functionalities. It is not implemented on |
| all targets (see package spec for details). |
| |
| @item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} |
| |
| Not implemented in GNAT. |
| |
| @item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)’} |
| |
| Not implemented in GNAT. |
| |
| @item @code{Ada.Finalization} @emph{(7.6)} |
| |
| This package contains the declarations and subprograms to support the |
| use of controlled types, providing for automatic initialization and |
| finalization (analogous to the constructors and destructors of C++). |
| |
| @item @code{Ada.Float_Text_IO} @emph{(A.10.9)} |
| |
| A library level instantiation of Text_IO.Float_IO for type Float. |
| |
| @item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} |
| |
| A library level instantiation of Wide_Text_IO.Float_IO for type Float. |
| |
| @item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} |
| |
| A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. |
| |
| @item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} |
| |
| A library level instantiation of Text_IO.Integer_IO for type Integer. |
| |
| @item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} |
| |
| A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. |
| |
| @item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} |
| |
| A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. |
| |
| @item @code{Ada.Interrupts} @emph{(C.3.2)} |
| |
| This package provides facilities for interfacing to interrupts, which |
| includes the set of signals or conditions that can be raised and |
| recognized as interrupts. |
| |
| @item @code{Ada.Interrupts.Names} @emph{(C.3.2)} |
| |
| This package provides the set of interrupt names (actually signal |
| or condition names) that can be handled by GNAT. |
| |
| @item @code{Ada.IO_Exceptions} @emph{(A.13)} |
| |
| This package defines the set of exceptions that can be raised by use of |
| the standard IO packages. |
| |
| @item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} |
| |
| This package provides a generic interface to generalized iterators. |
| |
| @item @code{Ada.Locales} @emph{(A.19)} |
| |
| This package provides declarations providing information (Language |
| and Country) about the current locale. |
| |
| @item @code{Ada.Numerics} |
| |
| This package contains some standard constants and exceptions used |
| throughout the numerics packages. Note that the constants pi and e are |
| defined here, and it is better to use these definitions than rolling |
| your own. |
| |
| @item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} |
| |
| Provides operations on arrays of complex numbers. |
| |
| @item @code{Ada.Numerics.Complex_Elementary_Functions} |
| |
| Provides the implementation of standard elementary functions (such as |
| log and trigonometric functions) operating on complex numbers using the |
| standard @code{Float} and the @code{Complex} and @code{Imaginary} types |
| created by the package @code{Numerics.Complex_Types}. |
| |
| @item @code{Ada.Numerics.Complex_Types} |
| |
| This is a predefined instantiation of |
| @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to |
| build the type @code{Complex} and @code{Imaginary}. |
| |
| @item @code{Ada.Numerics.Discrete_Random} |
| |
| This generic package provides a random number generator suitable for generating |
| uniformly distributed values of a specified discrete subtype. |
| |
| @item @code{Ada.Numerics.Float_Random} |
| |
| This package provides a random number generator suitable for generating |
| uniformly distributed floating point values in the unit interval. |
| |
| @item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} |
| |
| This is a generic version of the package that provides the |
| implementation of standard elementary functions (such as log and |
| trigonometric functions) for an arbitrary complex type. |
| |
| The following predefined instantiations of this package are provided: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Short_Float} |
| |
| @code{Ada.Numerics.Short_Complex_Elementary_Functions} |
| |
| @item |
| @code{Float} |
| |
| @code{Ada.Numerics.Complex_Elementary_Functions} |
| |
| @item |
| @code{Long_Float} |
| |
| @code{Ada.Numerics.Long_Complex_Elementary_Functions} |
| @end itemize |
| |
| @item @code{Ada.Numerics.Generic_Complex_Types} |
| |
| This is a generic package that allows the creation of complex types, |
| with associated complex arithmetic operations. |
| |
| The following predefined instantiations of this package exist |
| |
| |
| @itemize * |
| |
| @item |
| @code{Short_Float} |
| |
| @code{Ada.Numerics.Short_Complex_Complex_Types} |
| |
| @item |
| @code{Float} |
| |
| @code{Ada.Numerics.Complex_Complex_Types} |
| |
| @item |
| @code{Long_Float} |
| |
| @code{Ada.Numerics.Long_Complex_Complex_Types} |
| @end itemize |
| |
| @item @code{Ada.Numerics.Generic_Elementary_Functions} |
| |
| This is a generic package that provides the implementation of standard |
| elementary functions (such as log an trigonometric functions) for an |
| arbitrary float type. |
| |
| The following predefined instantiations of this package exist |
| |
| |
| @itemize * |
| |
| @item |
| @code{Short_Float} |
| |
| @code{Ada.Numerics.Short_Elementary_Functions} |
| |
| @item |
| @code{Float} |
| |
| @code{Ada.Numerics.Elementary_Functions} |
| |
| @item |
| @code{Long_Float} |
| |
| @code{Ada.Numerics.Long_Elementary_Functions} |
| @end itemize |
| |
| @item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} |
| |
| Generic operations on arrays of reals |
| |
| @item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} |
| |
| Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). |
| |
| @item @code{Ada.Real_Time} @emph{(D.8)} |
| |
| This package provides facilities similar to those of @code{Calendar}, but |
| operating with a finer clock suitable for real time control. Note that |
| annex D requires that there be no backward clock jumps, and GNAT generally |
| guarantees this behavior, but of course if the external clock on which |
| the GNAT runtime depends is deliberately reset by some external event, |
| then such a backward jump may occur. |
| |
| @item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} |
| |
| Not implemented in GNAT. |
| |
| @item @code{Ada.Sequential_IO} @emph{(A.8.1)} |
| |
| This package provides input-output facilities for sequential files, |
| which can contain a sequence of values of a single type, which can be |
| any Ada type, including indefinite (unconstrained) types. |
| |
| @item @code{Ada.Storage_IO} @emph{(A.9)} |
| |
| This package provides a facility for mapping arbitrary Ada types to and |
| from a storage buffer. It is primarily intended for the creation of new |
| IO packages. |
| |
| @item @code{Ada.Streams} @emph{(13.13.1)} |
| |
| This is a generic package that provides the basic support for the |
| concept of streams as used by the stream attributes (@code{Input}, |
| @code{Output}, @code{Read} and @code{Write}). |
| |
| @item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} |
| |
| This package is a specialization of the type @code{Streams} defined in |
| package @code{Streams} together with a set of operations providing |
| Stream_IO capability. The Stream_IO model permits both random and |
| sequential access to a file which can contain an arbitrary set of values |
| of one or more Ada types. |
| |
| @item @code{Ada.Strings} @emph{(A.4.1)} |
| |
| This package provides some basic constants used by the string handling |
| packages. |
| |
| @item @code{Ada.Strings.Bounded} @emph{(A.4.4)} |
| |
| This package provides facilities for handling variable length |
| strings. The bounded model requires a maximum length. It is thus |
| somewhat more limited than the unbounded model, but avoids the use of |
| dynamic allocation or finalization. |
| |
| @item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} |
| |
| Provides case-insensitive comparisons of bounded strings |
| |
| @item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} |
| |
| This package provides a generic hash function for bounded strings |
| |
| @item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} |
| |
| This package provides a generic hash function for bounded strings that |
| converts the string to be hashed to lower case. |
| |
| @item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} |
| |
| This package provides a comparison function for bounded strings that works |
| in a case insensitive manner by converting to lower case before the comparison. |
| |
| @item @code{Ada.Strings.Fixed} @emph{(A.4.3)} |
| |
| This package provides facilities for handling fixed length strings. |
| |
| @item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} |
| |
| This package provides an equality function for fixed strings that compares |
| the strings after converting both to lower case. |
| |
| @item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} |
| |
| This package provides a case insensitive hash function for fixed strings that |
| converts the string to lower case before computing the hash. |
| |
| @item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} |
| |
| This package provides a comparison function for fixed strings that works |
| in a case insensitive manner by converting to lower case before the comparison. |
| |
| @item @code{Ada.Strings.Hash} @emph{(A.4.9)} |
| |
| This package provides a hash function for strings. |
| |
| @item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} |
| |
| This package provides a hash function for strings that is case insensitive. |
| The string is converted to lower case before computing the hash. |
| |
| @item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} |
| |
| This package provides a comparison function for\strings that works |
| in a case insensitive manner by converting to lower case before the comparison. |
| |
| @item @code{Ada.Strings.Maps} @emph{(A.4.2)} |
| |
| This package provides facilities for handling character mappings and |
| arbitrarily defined subsets of characters. For instance it is useful in |
| defining specialized translation tables. |
| |
| @item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} |
| |
| This package provides a standard set of predefined mappings and |
| predefined character sets. For example, the standard upper to lower case |
| conversion table is found in this package. Note that upper to lower case |
| conversion is non-trivial if you want to take the entire set of |
| characters, including extended characters like E with an acute accent, |
| into account. You should use the mappings in this package (rather than |
| adding 32 yourself) to do case mappings. |
| |
| @item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} |
| |
| This package provides facilities for handling variable length |
| strings. The unbounded model allows arbitrary length strings, but |
| requires the use of dynamic allocation and finalization. |
| |
| @item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} |
| |
| Provides case-insensitive comparisons of unbounded strings |
| |
| @item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} |
| |
| This package provides a generic hash function for unbounded strings |
| |
| @item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} |
| |
| This package provides a generic hash function for unbounded strings that |
| converts the string to be hashed to lower case. |
| |
| @item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} |
| |
| This package provides a comparison function for unbounded strings that works |
| in a case insensitive manner by converting to lower case before the comparison. |
| |
| @item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} |
| |
| This package provides basic definitions for dealing with UTF-encoded strings. |
| |
| @item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} |
| |
| This package provides conversion functions for UTF-encoded strings. |
| @end table |
| |
| @code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} |
| |
| @code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} |
| |
| |
| @table @asis |
| |
| @item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} |
| |
| These packages provide facilities for handling UTF encodings for |
| Strings, Wide_Strings and Wide_Wide_Strings. |
| @end table |
| |
| @code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} |
| |
| @code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} |
| |
| @code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} |
| |
| |
| @table @asis |
| |
| @item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} |
| |
| These packages provide analogous capabilities to the corresponding |
| packages without @code{Wide_} in the name, but operate with the types |
| @code{Wide_String} and @code{Wide_Character} instead of @code{String} |
| and @code{Character}. Versions of all the child packages are available. |
| @end table |
| |
| @code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} |
| |
| @code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} |
| |
| @code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} |
| |
| |
| @table @asis |
| |
| @item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} |
| |
| These packages provide analogous capabilities to the corresponding |
| packages without @code{Wide_} in the name, but operate with the types |
| @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead |
| of @code{String} and @code{Character}. |
| |
| @item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} |
| |
| This package provides facilities for synchronizing tasks at a low level |
| with barriers. |
| |
| @item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} |
| |
| This package provides some standard facilities for controlling task |
| communication in a synchronous manner. |
| |
| @item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} |
| |
| Not implemented in GNAT. |
| |
| @item @code{Ada.Tags} |
| |
| This package contains definitions for manipulation of the tags of tagged |
| values. |
| |
| @item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} |
| |
| This package provides a way of constructing tagged class-wide values given |
| only the tag value. |
| |
| @item @code{Ada.Task_Attributes} @emph{(C.7.2)} |
| |
| This package provides the capability of associating arbitrary |
| task-specific data with separate tasks. |
| |
| @item @code{Ada.Task_Identifification} @emph{(C.7.1)} |
| |
| This package provides capabilities for task identification. |
| |
| @item @code{Ada.Task_Termination} @emph{(C.7.3)} |
| |
| This package provides control over task termination. |
| |
| @item @code{Ada.Text_IO} |
| |
| This package provides basic text input-output capabilities for |
| character, string and numeric data. The subpackages of this |
| package are listed next. Note that although these are defined |
| as subpackages in the RM, they are actually transparently |
| implemented as child packages in GNAT, meaning that they |
| are only loaded if needed. |
| |
| @item @code{Ada.Text_IO.Decimal_IO} |
| |
| Provides input-output facilities for decimal fixed-point types |
| |
| @item @code{Ada.Text_IO.Enumeration_IO} |
| |
| Provides input-output facilities for enumeration types. |
| |
| @item @code{Ada.Text_IO.Fixed_IO} |
| |
| Provides input-output facilities for ordinary fixed-point types. |
| |
| @item @code{Ada.Text_IO.Float_IO} |
| |
| Provides input-output facilities for float types. The following |
| predefined instantiations of this generic package are available: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Short_Float} |
| |
| @code{Short_Float_Text_IO} |
| |
| @item |
| @code{Float} |
| |
| @code{Float_Text_IO} |
| |
| @item |
| @code{Long_Float} |
| |
| @code{Long_Float_Text_IO} |
| @end itemize |
| |
| @item @code{Ada.Text_IO.Integer_IO} |
| |
| Provides input-output facilities for integer types. The following |
| predefined instantiations of this generic package are available: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Short_Short_Integer} |
| |
| @code{Ada.Short_Short_Integer_Text_IO} |
| |
| @item |
| @code{Short_Integer} |
| |
| @code{Ada.Short_Integer_Text_IO} |
| |
| @item |
| @code{Integer} |
| |
| @code{Ada.Integer_Text_IO} |
| |
| @item |
| @code{Long_Integer} |
| |
| @code{Ada.Long_Integer_Text_IO} |
| |
| @item |
| @code{Long_Long_Integer} |
| |
| @code{Ada.Long_Long_Integer_Text_IO} |
| @end itemize |
| |
| @item @code{Ada.Text_IO.Modular_IO} |
| |
| Provides input-output facilities for modular (unsigned) types. |
| |
| @item @code{Ada.Text_IO.Bounded_IO (A.10.11)} |
| |
| Provides input-output facilities for bounded strings. |
| |
| @item @code{Ada.Text_IO.Complex_IO (G.1.3)} |
| |
| This package provides basic text input-output capabilities for complex |
| data. |
| |
| @item @code{Ada.Text_IO.Editing (F.3.3)} |
| |
| This package contains routines for edited output, analogous to the use |
| of pictures in COBOL. The picture formats used by this package are a |
| close copy of the facility in COBOL. |
| |
| @item @code{Ada.Text_IO.Text_Streams (A.12.2)} |
| |
| This package provides a facility that allows Text_IO files to be treated |
| as streams, so that the stream attributes can be used for writing |
| arbitrary data, including binary data, to Text_IO files. |
| |
| @item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} |
| |
| This package provides input-output facilities for unbounded strings. |
| |
| @item @code{Ada.Unchecked_Conversion (13.9)} |
| |
| This generic package allows arbitrary conversion from one type to |
| another of the same size, providing for breaking the type safety in |
| special circumstances. |
| |
| If the types have the same Size (more accurately the same Value_Size), |
| then the effect is simply to transfer the bits from the source to the |
| target type without any modification. This usage is well defined, and |
| for simple types whose representation is typically the same across |
| all implementations, gives a portable method of performing such |
| conversions. |
| |
| If the types do not have the same size, then the result is implementation |
| defined, and thus may be non-portable. The following describes how GNAT |
| handles such unchecked conversion cases. |
| |
| If the types are of different sizes, and are both discrete types, then |
| the effect is of a normal type conversion without any constraint checking. |
| In particular if the result type has a larger size, the result will be |
| zero or sign extended. If the result type has a smaller size, the result |
| will be truncated by ignoring high order bits. |
| |
| If the types are of different sizes, and are not both discrete types, |
| then the conversion works as though pointers were created to the source |
| and target, and the pointer value is converted. The effect is that bits |
| are copied from successive low order storage units and bits of the source |
| up to the length of the target type. |
| |
| A warning is issued if the lengths differ, since the effect in this |
| case is implementation dependent, and the above behavior may not match |
| that of some other compiler. |
| |
| A pointer to one type may be converted to a pointer to another type using |
| unchecked conversion. The only case in which the effect is undefined is |
| when one or both pointers are pointers to unconstrained array types. In |
| this case, the bounds information may get incorrectly transferred, and in |
| particular, GNAT uses double size pointers for such types, and it is |
| meaningless to convert between such pointer types. GNAT will issue a |
| warning if the alignment of the target designated type is more strict |
| than the alignment of the source designated type (since the result may |
| be unaligned in this case). |
| |
| A pointer other than a pointer to an unconstrained array type may be |
| converted to and from System.Address. Such usage is common in Ada 83 |
| programs, but note that Ada.Address_To_Access_Conversions is the |
| preferred method of performing such conversions in Ada 95 and Ada 2005. |
| Neither |
| unchecked conversion nor Ada.Address_To_Access_Conversions should be |
| used in conjunction with pointers to unconstrained objects, since |
| the bounds information cannot be handled correctly in this case. |
| |
| @item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} |
| |
| This generic package allows explicit freeing of storage previously |
| allocated by use of an allocator. |
| |
| @item @code{Ada.Wide_Text_IO} @emph{(A.11)} |
| |
| This package is similar to @code{Ada.Text_IO}, except that the external |
| file supports wide character representations, and the internal types are |
| @code{Wide_Character} and @code{Wide_String} instead of @code{Character} |
| and @code{String}. The corresponding set of nested packages and child |
| packages are defined. |
| |
| @item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} |
| |
| This package is similar to @code{Ada.Text_IO}, except that the external |
| file supports wide character representations, and the internal types are |
| @code{Wide_Character} and @code{Wide_String} instead of @code{Character} |
| and @code{String}. The corresponding set of nested packages and child |
| packages are defined. |
| @end table |
| |
| For packages in Interfaces and System, all the RM defined packages are |
| available in GNAT, see the Ada 2012 RM for full details. |
| |
| @node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top |
| @anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f} |
| @chapter The Implementation of Standard I/O |
| |
| |
| GNAT implements all the required input-output facilities described in |
| A.6 through A.14. These sections of the Ada Reference Manual describe the |
| required behavior of these packages from the Ada point of view, and if |
| you are writing a portable Ada program that does not need to know the |
| exact manner in which Ada maps to the outside world when it comes to |
| reading or writing external files, then you do not need to read this |
| chapter. As long as your files are all regular files (not pipes or |
| devices), and as long as you write and read the files only from Ada, the |
| description in the Ada Reference Manual is sufficient. |
| |
| However, if you want to do input-output to pipes or other devices, such |
| as the keyboard or screen, or if the files you are dealing with are |
| either generated by some other language, or to be read by some other |
| language, then you need to know more about the details of how the GNAT |
| implementation of these input-output facilities behaves. |
| |
| In this chapter we give a detailed description of exactly how GNAT |
| interfaces to the file system. As always, the sources of the system are |
| available to you for answering questions at an even more detailed level, |
| but for most purposes the information in this chapter will suffice. |
| |
| Another reason that you may need to know more about how input-output is |
| implemented arises when you have a program written in mixed languages |
| where, for example, files are shared between the C and Ada sections of |
| the same program. GNAT provides some additional facilities, in the form |
| of additional child library packages, that facilitate this sharing, and |
| these additional facilities are also described in this chapter. |
| |
| @menu |
| * Standard I/O Packages:: |
| * FORM Strings:: |
| * Direct_IO:: |
| * Sequential_IO:: |
| * Text_IO:: |
| * Wide_Text_IO:: |
| * Wide_Wide_Text_IO:: |
| * Stream_IO:: |
| * Text Translation:: |
| * Shared Files:: |
| * Filenames encoding:: |
| * File content encoding:: |
| * Open Modes:: |
| * Operations on C Streams:: |
| * Interfacing to C Streams:: |
| |
| @end menu |
| |
| @node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a4} |
| @section Standard I/O Packages |
| |
| |
| The Standard I/O packages described in Annex A for |
| |
| |
| @itemize * |
| |
| @item |
| Ada.Text_IO |
| |
| @item |
| Ada.Text_IO.Complex_IO |
| |
| @item |
| Ada.Text_IO.Text_Streams |
| |
| @item |
| Ada.Wide_Text_IO |
| |
| @item |
| Ada.Wide_Text_IO.Complex_IO |
| |
| @item |
| Ada.Wide_Text_IO.Text_Streams |
| |
| @item |
| Ada.Wide_Wide_Text_IO |
| |
| @item |
| Ada.Wide_Wide_Text_IO.Complex_IO |
| |
| @item |
| Ada.Wide_Wide_Text_IO.Text_Streams |
| |
| @item |
| Ada.Stream_IO |
| |
| @item |
| Ada.Sequential_IO |
| |
| @item |
| Ada.Direct_IO |
| @end itemize |
| |
| are implemented using the C |
| library streams facility; where |
| |
| |
| @itemize * |
| |
| @item |
| All files are opened using @code{fopen}. |
| |
| @item |
| All input/output operations use @code{fread}/@cite{fwrite}. |
| @end itemize |
| |
| There is no internal buffering of any kind at the Ada library level. The only |
| buffering is that provided at the system level in the implementation of the |
| library routines that support streams. This facilitates shared use of these |
| streams by mixed language programs. Note though that system level buffering is |
| explicitly enabled at elaboration of the standard I/O packages and that can |
| have an impact on mixed language programs, in particular those using I/O before |
| calling the Ada elaboration routine (e.g., adainit). It is recommended to call |
| the Ada elaboration routine before performing any I/O or when impractical, |
| flush the common I/O streams and in particular Standard_Output before |
| elaborating the Ada code. |
| |
| @node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a6} |
| @section FORM Strings |
| |
| |
| The format of a FORM string in GNAT is: |
| |
| @example |
| "keyword=value,keyword=value,...,keyword=value" |
| @end example |
| |
| where letters may be in upper or lower case, and there are no spaces |
| between values. The order of the entries is not important. Currently |
| the following keywords defined. |
| |
| @example |
| TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] |
| SHARED=[YES|NO] |
| WCEM=[n|h|u|s|e|8|b] |
| ENCODING=[UTF8|8BITS] |
| @end example |
| |
| The use of these parameters is described later in this section. If an |
| unrecognized keyword appears in a form string, it is silently ignored |
| and not considered invalid. |
| |
| @node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a8} |
| @section Direct_IO |
| |
| |
| Direct_IO can only be instantiated for definite types. This is a |
| restriction of the Ada language, which means that the records are fixed |
| length (the length being determined by @code{type'Size}, rounded |
| up to the next storage unit boundary if necessary). |
| |
| The records of a Direct_IO file are simply written to the file in index |
| sequence, with the first record starting at offset zero, and subsequent |
| records following. There is no control information of any kind. For |
| example, if 32-bit integers are being written, each record takes |
| 4-bytes, so the record at index @code{K} starts at offset |
| (@code{K}-1)*4. |
| |
| There is no limit on the size of Direct_IO files, they are expanded as |
| necessary to accommodate whatever records are written to the file. |
| |
| @node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2aa} |
| @section Sequential_IO |
| |
| |
| Sequential_IO may be instantiated with either a definite (constrained) |
| or indefinite (unconstrained) type. |
| |
| For the definite type case, the elements written to the file are simply |
| the memory images of the data values with no control information of any |
| kind. The resulting file should be read using the same type, no validity |
| checking is performed on input. |
| |
| For the indefinite type case, the elements written consist of two |
| parts. First is the size of the data item, written as the memory image |
| of a @code{Interfaces.C.size_t} value, followed by the memory image of |
| the data value. The resulting file can only be read using the same |
| (unconstrained) type. Normal assignment checks are performed on these |
| read operations, and if these checks fail, @code{Data_Error} is |
| raised. In particular, in the array case, the lengths must match, and in |
| the variant record case, if the variable for a particular read operation |
| is constrained, the discriminants must match. |
| |
| Note that it is not possible to use Sequential_IO to write variable |
| length array items, and then read the data back into different length |
| arrays. For example, the following will raise @code{Data_Error}: |
| |
| @example |
| package IO is new Sequential_IO (String); |
| F : IO.File_Type; |
| S : String (1..4); |
| ... |
| IO.Create (F) |
| IO.Write (F, "hello!") |
| IO.Reset (F, Mode=>In_File); |
| IO.Read (F, S); |
| Put_Line (S); |
| @end example |
| |
| On some Ada implementations, this will print @code{hell}, but the program is |
| clearly incorrect, since there is only one element in the file, and that |
| element is the string @code{hello!}. |
| |
| In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved |
| using Stream_IO, and this is the preferred mechanism. In particular, the |
| above program fragment rewritten to use Stream_IO will work correctly. |
| |
| @node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2ac} |
| @section Text_IO |
| |
| |
| Text_IO files consist of a stream of characters containing the following |
| special control characters: |
| |
| @example |
| LF (line feed, 16#0A#) Line Mark |
| FF (form feed, 16#0C#) Page Mark |
| @end example |
| |
| A canonical Text_IO file is defined as one in which the following |
| conditions are met: |
| |
| |
| @itemize * |
| |
| @item |
| The character @code{LF} is used only as a line mark, i.e., to mark the end |
| of the line. |
| |
| @item |
| The character @code{FF} is used only as a page mark, i.e., to mark the |
| end of a page and consequently can appear only immediately following a |
| @code{LF} (line mark) character. |
| |
| @item |
| The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} |
| (line mark, page mark). In the former case, the page mark is implicitly |
| assumed to be present. |
| @end itemize |
| |
| A file written using Text_IO will be in canonical form provided that no |
| explicit @code{LF} or @code{FF} characters are written using @code{Put} |
| or @code{Put_Line}. There will be no @code{FF} character at the end of |
| the file unless an explicit @code{New_Page} operation was performed |
| before closing the file. |
| |
| A canonical Text_IO file that is a regular file (i.e., not a device or a |
| pipe) can be read using any of the routines in Text_IO. The |
| semantics in this case will be exactly as defined in the Ada Reference |
| Manual, and all the routines in Text_IO are fully implemented. |
| |
| A text file that does not meet the requirements for a canonical Text_IO |
| file has one of the following: |
| |
| |
| @itemize * |
| |
| @item |
| The file contains @code{FF} characters not immediately following a |
| @code{LF} character. |
| |
| @item |
| The file contains @code{LF} or @code{FF} characters written by |
| @code{Put} or @code{Put_Line}, which are not logically considered to be |
| line marks or page marks. |
| |
| @item |
| The file ends in a character other than @code{LF} or @code{FF}, |
| i.e., there is no explicit line mark or page mark at the end of the file. |
| @end itemize |
| |
| Text_IO can be used to read such non-standard text files but subprograms |
| to do with line or page numbers do not have defined meanings. In |
| particular, a @code{FF} character that does not follow a @code{LF} |
| character may or may not be treated as a page mark from the point of |
| view of page and line numbering. Every @code{LF} character is considered |
| to end a line, and there is an implied @code{LF} character at the end of |
| the file. |
| |
| @menu |
| * Stream Pointer Positioning:: |
| * Reading and Writing Non-Regular Files:: |
| * Get_Immediate:: |
| * Treating Text_IO Files as Streams:: |
| * Text_IO Extensions:: |
| * Text_IO Facilities for Unbounded Strings:: |
| |
| @end menu |
| |
| @node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ae} |
| @subsection Stream Pointer Positioning |
| |
| |
| @code{Ada.Text_IO} has a definition of current position for a file that |
| is being read. No internal buffering occurs in Text_IO, and usually the |
| physical position in the stream used to implement the file corresponds |
| to this logical position defined by Text_IO. There are two exceptions: |
| |
| |
| @itemize * |
| |
| @item |
| After a call to @code{End_Of_Page} that returns @code{True}, the stream |
| is positioned past the @code{LF} (line mark) that precedes the page |
| mark. Text_IO maintains an internal flag so that subsequent read |
| operations properly handle the logical position which is unchanged by |
| the @code{End_Of_Page} call. |
| |
| @item |
| After a call to @code{End_Of_File} that returns @code{True}, if the |
| Text_IO file was positioned before the line mark at the end of file |
| before the call, then the logical position is unchanged, but the stream |
| is physically positioned right at the end of file (past the line mark, |
| and past a possible page mark following the line mark. Again Text_IO |
| maintains internal flags so that subsequent read operations properly |
| handle the logical position. |
| @end itemize |
| |
| These discrepancies have no effect on the observable behavior of |
| Text_IO, but if a single Ada stream is shared between a C program and |
| Ada program, or shared (using @code{shared=yes} in the form string) |
| between two Ada files, then the difference may be observable in some |
| situations. |
| |
| @node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2b0} |
| @subsection Reading and Writing Non-Regular Files |
| |
| |
| A non-regular file is a device (such as a keyboard), or a pipe. Text_IO |
| can be used for reading and writing. Writing is not affected and the |
| sequence of characters output is identical to the normal file case, but |
| for reading, the behavior of Text_IO is modified to avoid undesirable |
| look-ahead as follows: |
| |
| An input file that is not a regular file is considered to have no page |
| marks. Any @code{Ascii.FF} characters (the character normally used for a |
| page mark) appearing in the file are considered to be data |
| characters. In particular: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Get_Line} and @code{Skip_Line} do not test for a page mark |
| following a line mark. If a page mark appears, it will be treated as a |
| data character. |
| |
| @item |
| This avoids the need to wait for an extra character to be typed or |
| entered from the pipe to complete one of these operations. |
| |
| @item |
| @code{End_Of_Page} always returns @code{False} |
| |
| @item |
| @code{End_Of_File} will return @code{False} if there is a page mark at |
| the end of the file. |
| @end itemize |
| |
| Output to non-regular files is the same as for regular files. Page marks |
| may be written to non-regular files using @code{New_Page}, but as noted |
| above they will not be treated as page marks on input if the output is |
| piped to another Ada program. |
| |
| Another important discrepancy when reading non-regular files is that the end |
| of file indication is not ‘sticky’. If an end of file is entered, e.g., by |
| pressing the @code{EOT} key, |
| then end of file |
| is signaled once (i.e., the test @code{End_Of_File} |
| will yield @code{True}, or a read will |
| raise @code{End_Error}), but then reading can resume |
| to read data past that end of |
| file indication, until another end of file indication is entered. |
| |
| @node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b2} |
| @subsection Get_Immediate |
| |
| |
| @geindex Get_Immediate |
| |
| Get_Immediate returns the next character (including control characters) |
| from the input file. In particular, Get_Immediate will return LF or FF |
| characters used as line marks or page marks. Such operations leave the |
| file positioned past the control character, and it is thus not treated |
| as having its normal function. This means that page, line and column |
| counts after this kind of Get_Immediate call are set as though the mark |
| did not occur. In the case where a Get_Immediate leaves the file |
| positioned between the line mark and page mark (which is not normally |
| possible), it is undefined whether the FF character will be treated as a |
| page mark. |
| |
| @node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b4} |
| @subsection Treating Text_IO Files as Streams |
| |
| |
| @geindex Stream files |
| |
| The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated |
| as a stream. Data written to a @code{Text_IO} file in this stream mode is |
| binary data. If this binary data contains bytes 16#0A# (@code{LF}) or |
| 16#0C# (@code{FF}), the resulting file may have non-standard |
| format. Similarly if read operations are used to read from a Text_IO |
| file treated as a stream, then @code{LF} and @code{FF} characters may be |
| skipped and the effect is similar to that described above for |
| @code{Get_Immediate}. |
| |
| @node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b6} |
| @subsection Text_IO Extensions |
| |
| |
| @geindex Text_IO extensions |
| |
| A package GNAT.IO_Aux in the GNAT library provides some useful extensions |
| to the standard @code{Text_IO} package: |
| |
| |
| @itemize * |
| |
| @item |
| function File_Exists (Name : String) return Boolean; |
| Determines if a file of the given name exists. |
| |
| @item |
| function Get_Line return String; |
| Reads a string from the standard input file. The value returned is exactly |
| the length of the line that was read. |
| |
| @item |
| function Get_Line (File : Ada.Text_IO.File_Type) return String; |
| Similar, except that the parameter File specifies the file from which |
| the string is to be read. |
| @end itemize |
| |
| @node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b8} |
| @subsection Text_IO Facilities for Unbounded Strings |
| |
| |
| @geindex Text_IO for unbounded strings |
| |
| @geindex Unbounded_String |
| @geindex Text_IO operations |
| |
| The package @code{Ada.Strings.Unbounded.Text_IO} |
| in library files @code{a-suteio.ads/adb} contains some GNAT-specific |
| subprograms useful for Text_IO operations on unbounded strings: |
| |
| |
| @itemize * |
| |
| @item |
| function Get_Line (File : File_Type) return Unbounded_String; |
| Reads a line from the specified file |
| and returns the result as an unbounded string. |
| |
| @item |
| procedure Put (File : File_Type; U : Unbounded_String); |
| Writes the value of the given unbounded string to the specified file |
| Similar to the effect of |
| @code{Put (To_String (U))} except that an extra copy is avoided. |
| |
| @item |
| procedure Put_Line (File : File_Type; U : Unbounded_String); |
| Writes the value of the given unbounded string to the specified file, |
| followed by a @code{New_Line}. |
| Similar to the effect of @code{Put_Line (To_String (U))} except |
| that an extra copy is avoided. |
| @end itemize |
| |
| In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} |
| and is optional. If the parameter is omitted, then the standard input or |
| output file is referenced as appropriate. |
| |
| The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library |
| files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended |
| @code{Wide_Text_IO} functionality for unbounded wide strings. |
| |
| The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library |
| files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended |
| @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. |
| |
| @node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2ba} |
| @section Wide_Text_IO |
| |
| |
| @code{Wide_Text_IO} is similar in most respects to Text_IO, except that |
| both input and output files may contain special sequences that represent |
| wide character values. The encoding scheme for a given file may be |
| specified using a FORM parameter: |
| |
| @example |
| WCEM=`x` |
| @end example |
| |
| as part of the FORM string (WCEM = wide character encoding method), |
| where @code{x} is one of the following characters |
| |
| |
| @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| Character |
| |
| @tab |
| |
| Encoding |
| |
| @item |
| |
| @emph{h} |
| |
| @tab |
| |
| Hex ESC encoding |
| |
| @item |
| |
| @emph{u} |
| |
| @tab |
| |
| Upper half encoding |
| |
| @item |
| |
| @emph{s} |
| |
| @tab |
| |
| Shift-JIS encoding |
| |
| @item |
| |
| @emph{e} |
| |
| @tab |
| |
| EUC Encoding |
| |
| @item |
| |
| @emph{8} |
| |
| @tab |
| |
| UTF-8 encoding |
| |
| @item |
| |
| @emph{b} |
| |
| @tab |
| |
| Brackets encoding |
| |
| @end multitable |
| |
| |
| The encoding methods match those that |
| can be used in a source |
| program, but there is no requirement that the encoding method used for |
| the source program be the same as the encoding method used for files, |
| and different files may use different encoding methods. |
| |
| The default encoding method for the standard files, and for opened files |
| for which no WCEM parameter is given in the FORM string matches the |
| wide character encoding specified for the main program (the default |
| being brackets encoding if no coding method was specified with -gnatW). |
| |
| |
| @table @asis |
| |
| @item @emph{Hex Coding} |
| |
| In this encoding, a wide character is represented by a five character |
| sequence: |
| @end table |
| |
| @example |
| ESC a b c d |
| @end example |
| |
| |
| @quotation |
| |
| where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal |
| characters (using upper case letters) of the wide character code. For |
| example, ESC A345 is used to represent the wide character with code |
| 16#A345#. This scheme is compatible with use of the full |
| @code{Wide_Character} set. |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @emph{Upper Half Coding} |
| |
| The wide character with encoding 16#abcd#, where the upper bit is on |
| (i.e., a is in the range 8-F) is represented as two bytes 16#ab# and |
| 16#cd#. The second byte may never be a format control character, but is |
| not required to be in the upper half. This method can be also used for |
| shift-JIS or EUC where the internal coding matches the external coding. |
| |
| @item @emph{Shift JIS Coding} |
| |
| A wide character is represented by a two character sequence 16#ab# and |
| 16#cd#, with the restrictions described for upper half encoding as |
| described above. The internal character code is the corresponding JIS |
| character according to the standard algorithm for Shift-JIS |
| conversion. Only characters defined in the JIS code set table can be |
| used with this encoding method. |
| |
| @item @emph{EUC Coding} |
| |
| A wide character is represented by a two character sequence 16#ab# and |
| 16#cd#, with both characters being in the upper half. The internal |
| character code is the corresponding JIS character according to the EUC |
| encoding algorithm. Only characters defined in the JIS code set table |
| can be used with this encoding method. |
| |
| @item @emph{UTF-8 Coding} |
| |
| A wide character is represented using |
| UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO |
| 10646-1/Am.2. Depending on the character value, the representation |
| is a one, two, or three byte sequence: |
| @end table |
| |
| @example |
| 16#0000#-16#007f#: 2#0xxxxxxx# |
| 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# |
| 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# |
| @end example |
| |
| |
| @quotation |
| |
| where the @code{xxx} bits correspond to the left-padded bits of the |
| 16-bit character value. Note that all lower half ASCII characters |
| are represented as ASCII bytes and all upper half characters and |
| other wide characters are represented as sequences of upper-half |
| (The full UTF-8 scheme allows for encoding 31-bit characters as |
| 6-byte sequences, but in this implementation, all UTF-8 sequences |
| of four or more bytes length will raise a Constraint_Error, as |
| will all invalid UTF-8 sequences.) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @emph{Brackets Coding} |
| |
| In this encoding, a wide character is represented by the following eight |
| character sequence: |
| @end table |
| |
| @example |
| [ " a b c d " ] |
| @end example |
| |
| |
| @quotation |
| |
| where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal |
| characters (using uppercase letters) of the wide character code. For |
| example, @code{["A345"]} is used to represent the wide character with code |
| @code{16#A345#}. |
| This scheme is compatible with use of the full Wide_Character set. |
| On input, brackets coding can also be used for upper half characters, |
| e.g., @code{["C1"]} for lower case a. However, on output, brackets notation |
| is only used for wide characters with a code greater than @code{16#FF#}. |
| |
| Note that brackets coding is not normally used in the context of |
| Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as |
| a portable way of encoding source files. In the context of Wide_Text_IO |
| or Wide_Wide_Text_IO, it can only be used if the file does not contain |
| any instance of the left bracket character other than to encode wide |
| character values using the brackets encoding method. In practice it is |
| expected that some standard wide character encoding method such |
| as UTF-8 will be used for text input output. |
| |
| If brackets notation is used, then any occurrence of a left bracket |
| in the input file which is not the start of a valid wide character |
| sequence will cause Constraint_Error to be raised. It is possible to |
| encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO |
| input will interpret this as a left bracket. |
| |
| However, when a left bracket is output, it will be output as a left bracket |
| and not as [“5B”]. We make this decision because for normal use of |
| Wide_Text_IO for outputting messages, it is unpleasant to clobber left |
| brackets. For example, if we write: |
| |
| @example |
| Put_Line ("Start of output [first run]"); |
| @end example |
| |
| we really do not want to have the left bracket in this message clobbered so |
| that the output reads: |
| @end quotation |
| |
| @example |
| Start of output ["5B"]first run] |
| @end example |
| |
| |
| @quotation |
| |
| In practice brackets encoding is reasonably useful for normal Put_Line use |
| since we won’t get confused between left brackets and wide character |
| sequences in the output. But for input, or when files are written out |
| and read back in, it really makes better sense to use one of the standard |
| encoding methods such as UTF-8. |
| @end quotation |
| |
| For the coding schemes other than UTF-8, Hex, or Brackets encoding, |
| not all wide character |
| values can be represented. An attempt to output a character that cannot |
| be represented using the encoding scheme for the file causes |
| Constraint_Error to be raised. An invalid wide character sequence on |
| input also causes Constraint_Error to be raised. |
| |
| @menu |
| * Stream Pointer Positioning: Stream Pointer Positioning<2>. |
| * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. |
| |
| @end menu |
| |
| @node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2bc} |
| @subsection Stream Pointer Positioning |
| |
| |
| @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling |
| of stream pointer positioning (@ref{2ac,,Text_IO}). There is one additional |
| case: |
| |
| If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the |
| normal lower ASCII set (i.e., a character in the range: |
| |
| @example |
| Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) |
| @end example |
| |
| then although the logical position of the file pointer is unchanged by |
| the @code{Look_Ahead} call, the stream is physically positioned past the |
| wide character sequence. Again this is to avoid the need for buffering |
| or backup, and all @code{Wide_Text_IO} routines check the internal |
| indication that this situation has occurred so that this is not visible |
| to a normal program using @code{Wide_Text_IO}. However, this discrepancy |
| can be observed if the wide text file shares a stream with another file. |
| |
| @node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2be} |
| @subsection Reading and Writing Non-Regular Files |
| |
| |
| As in the case of Text_IO, when a non-regular file is read, it is |
| assumed that the file contains no page marks (any form characters are |
| treated as data characters), and @code{End_Of_Page} always returns |
| @code{False}. Similarly, the end of file indication is not sticky, so |
| it is possible to read beyond an end of file. |
| |
| @node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2c0} |
| @section Wide_Wide_Text_IO |
| |
| |
| @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that |
| both input and output files may contain special sequences that represent |
| wide wide character values. The encoding scheme for a given file may be |
| specified using a FORM parameter: |
| |
| @example |
| WCEM=`x` |
| @end example |
| |
| as part of the FORM string (WCEM = wide character encoding method), |
| where @code{x} is one of the following characters |
| |
| |
| @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| Character |
| |
| @tab |
| |
| Encoding |
| |
| @item |
| |
| @emph{h} |
| |
| @tab |
| |
| Hex ESC encoding |
| |
| @item |
| |
| @emph{u} |
| |
| @tab |
| |
| Upper half encoding |
| |
| @item |
| |
| @emph{s} |
| |
| @tab |
| |
| Shift-JIS encoding |
| |
| @item |
| |
| @emph{e} |
| |
| @tab |
| |
| EUC Encoding |
| |
| @item |
| |
| @emph{8} |
| |
| @tab |
| |
| UTF-8 encoding |
| |
| @item |
| |
| @emph{b} |
| |
| @tab |
| |
| Brackets encoding |
| |
| @end multitable |
| |
| |
| The encoding methods match those that |
| can be used in a source |
| program, but there is no requirement that the encoding method used for |
| the source program be the same as the encoding method used for files, |
| and different files may use different encoding methods. |
| |
| The default encoding method for the standard files, and for opened files |
| for which no WCEM parameter is given in the FORM string matches the |
| wide character encoding specified for the main program (the default |
| being brackets encoding if no coding method was specified with -gnatW). |
| |
| |
| @table @asis |
| |
| @item @emph{UTF-8 Coding} |
| |
| A wide character is represented using |
| UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO |
| 10646-1/Am.2. Depending on the character value, the representation |
| is a one, two, three, or four byte sequence: |
| @end table |
| |
| @example |
| 16#000000#-16#00007f#: 2#0xxxxxxx# |
| 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# |
| 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# |
| 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# |
| @end example |
| |
| |
| @quotation |
| |
| where the @code{xxx} bits correspond to the left-padded bits of the |
| 21-bit character value. Note that all lower half ASCII characters |
| are represented as ASCII bytes and all upper half characters and |
| other wide characters are represented as sequences of upper-half |
| characters. |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @emph{Brackets Coding} |
| |
| In this encoding, a wide wide character is represented by the following eight |
| character sequence if is in wide character range |
| @end table |
| |
| @example |
| [ " a b c d " ] |
| @end example |
| |
| |
| @quotation |
| |
| and by the following ten character sequence if not |
| @end quotation |
| |
| @example |
| [ " a b c d e f " ] |
| @end example |
| |
| |
| @quotation |
| |
| where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} |
| are the four or six hexadecimal |
| characters (using uppercase letters) of the wide wide character code. For |
| example, @code{["01A345"]} is used to represent the wide wide character |
| with code @code{16#01A345#}. |
| |
| This scheme is compatible with use of the full Wide_Wide_Character set. |
| On input, brackets coding can also be used for upper half characters, |
| e.g., @code{["C1"]} for lower case a. However, on output, brackets notation |
| is only used for wide characters with a code greater than @code{16#FF#}. |
| @end quotation |
| |
| If is also possible to use the other Wide_Character encoding methods, |
| such as Shift-JIS, but the other schemes cannot support the full range |
| of wide wide characters. |
| An attempt to output a character that cannot |
| be represented using the encoding scheme for the file causes |
| Constraint_Error to be raised. An invalid wide character sequence on |
| input also causes Constraint_Error to be raised. |
| |
| @menu |
| * Stream Pointer Positioning: Stream Pointer Positioning<3>. |
| * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. |
| |
| @end menu |
| |
| @node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2c2} |
| @subsection Stream Pointer Positioning |
| |
| |
| @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling |
| of stream pointer positioning (@ref{2ac,,Text_IO}). There is one additional |
| case: |
| |
| If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the |
| normal lower ASCII set (i.e., a character in the range: |
| |
| @example |
| Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) |
| @end example |
| |
| then although the logical position of the file pointer is unchanged by |
| the @code{Look_Ahead} call, the stream is physically positioned past the |
| wide character sequence. Again this is to avoid the need for buffering |
| or backup, and all @code{Wide_Wide_Text_IO} routines check the internal |
| indication that this situation has occurred so that this is not visible |
| to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy |
| can be observed if the wide text file shares a stream with another file. |
| |
| @node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c4} |
| @subsection Reading and Writing Non-Regular Files |
| |
| |
| As in the case of Text_IO, when a non-regular file is read, it is |
| assumed that the file contains no page marks (any form characters are |
| treated as data characters), and @code{End_Of_Page} always returns |
| @code{False}. Similarly, the end of file indication is not sticky, so |
| it is possible to read beyond an end of file. |
| |
| @node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c6} |
| @section Stream_IO |
| |
| |
| A stream file is a sequence of bytes, where individual elements are |
| written to the file as described in the Ada Reference Manual. The type |
| @code{Stream_Element} is simply a byte. There are two ways to read or |
| write a stream file. |
| |
| |
| @itemize * |
| |
| @item |
| The operations @code{Read} and @code{Write} directly read or write a |
| sequence of stream elements with no control information. |
| |
| @item |
| The stream attributes applied to a stream file transfer data in the |
| manner described for stream attributes. |
| @end itemize |
| |
| @node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c8} |
| @section Text Translation |
| |
| |
| @code{Text_Translation=xxx} may be used as the Form parameter |
| passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} |
| has no effect on Unix systems. Possible values are: |
| |
| |
| @itemize * |
| |
| @item |
| @code{Yes} or @code{Text} is the default, which means to |
| translate LF to/from CR/LF on Windows systems. |
| |
| @code{No} disables this translation; i.e. it |
| uses binary mode. For output files, @code{Text_Translation=No} |
| may be used to create Unix-style files on |
| Windows. |
| |
| @item |
| @code{wtext} translation enabled in Unicode mode. |
| (corresponds to _O_WTEXT). |
| |
| @item |
| @code{u8text} translation enabled in Unicode UTF-8 mode. |
| (corresponds to O_U8TEXT). |
| |
| @item |
| @code{u16text} translation enabled in Unicode UTF-16 |
| mode. (corresponds to_O_U16TEXT). |
| @end itemize |
| |
| @node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2ca} |
| @section Shared Files |
| |
| |
| Section A.14 of the Ada Reference Manual allows implementations to |
| provide a wide variety of behavior if an attempt is made to access the |
| same external file with two or more internal files. |
| |
| To provide a full range of functionality, while at the same time |
| minimizing the problems of portability caused by this implementation |
| dependence, GNAT handles file sharing as follows: |
| |
| |
| @itemize * |
| |
| @item |
| In the absence of a @code{shared=xxx} form parameter, an attempt |
| to open two or more files with the same full name is considered an error |
| and is not supported. The exception @code{Use_Error} will be |
| raised. Note that a file that is not explicitly closed by the program |
| remains open until the program terminates. |
| |
| @item |
| If the form parameter @code{shared=no} appears in the form string, the |
| file can be opened or created with its own separate stream identifier, |
| regardless of whether other files sharing the same external file are |
| opened. The exact effect depends on how the C stream routines handle |
| multiple accesses to the same external files using separate streams. |
| |
| @item |
| If the form parameter @code{shared=yes} appears in the form string for |
| each of two or more files opened using the same full name, the same |
| stream is shared between these files, and the semantics are as described |
| in Ada Reference Manual, Section A.14. |
| @end itemize |
| |
| When a program that opens multiple files with the same name is ported |
| from another Ada compiler to GNAT, the effect will be that |
| @code{Use_Error} is raised. |
| |
| The documentation of the original compiler and the documentation of the |
| program should then be examined to determine if file sharing was |
| expected, and @code{shared=xxx} parameters added to @code{Open} |
| and @code{Create} calls as required. |
| |
| When a program is ported from GNAT to some other Ada compiler, no |
| special attention is required unless the @code{shared=xxx} form |
| parameter is used in the program. In this case, you must examine the |
| documentation of the new compiler to see if it supports the required |
| file sharing semantics, and form strings modified appropriately. Of |
| course it may be the case that the program cannot be ported if the |
| target compiler does not support the required functionality. The best |
| approach in writing portable code is to avoid file sharing (and hence |
| the use of the @code{shared=xxx} parameter in the form string) |
| completely. |
| |
| One common use of file sharing in Ada 83 is the use of instantiations of |
| Sequential_IO on the same file with different types, to achieve |
| heterogeneous input-output. Although this approach will work in GNAT if |
| @code{shared=yes} is specified, it is preferable in Ada to use Stream_IO |
| for this purpose (using the stream attributes) |
| |
| @node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2cc} |
| @section Filenames encoding |
| |
| |
| An encoding form parameter can be used to specify the filename |
| encoding @code{encoding=xxx}. |
| |
| |
| @itemize * |
| |
| @item |
| If the form parameter @code{encoding=utf8} appears in the form string, the |
| filename must be encoded in UTF-8. |
| |
| @item |
| If the form parameter @code{encoding=8bits} appears in the form |
| string, the filename must be a standard 8bits string. |
| @end itemize |
| |
| In the absence of a @code{encoding=xxx} form parameter, the |
| encoding is controlled by the @code{GNAT_CODE_PAGE} environment |
| variable. And if not set @code{utf8} is assumed. |
| |
| |
| @table @asis |
| |
| @item @emph{CP_ACP} |
| |
| The current system Windows ANSI code page. |
| |
| @item @emph{CP_UTF8} |
| |
| UTF-8 encoding |
| @end table |
| |
| This encoding form parameter is only supported on the Windows |
| platform. On the other Operating Systems the run-time is supporting |
| UTF-8 natively. |
| |
| @node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2ce} |
| @section File content encoding |
| |
| |
| For text files it is possible to specify the encoding to use. This is |
| controlled by the by the @code{GNAT_CCS_ENCODING} environment |
| variable. And if not set @code{TEXT} is assumed. |
| |
| The possible values are those supported on Windows: |
| |
| |
| @table @asis |
| |
| @item @emph{TEXT} |
| |
| Translated text mode |
| |
| @item @emph{WTEXT} |
| |
| Translated unicode encoding |
| |
| @item @emph{U16TEXT} |
| |
| Unicode 16-bit encoding |
| |
| @item @emph{U8TEXT} |
| |
| Unicode 8-bit encoding |
| @end table |
| |
| This encoding is only supported on the Windows platform. |
| |
| @node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2d0} |
| @section Open Modes |
| |
| |
| @code{Open} and @code{Create} calls result in a call to @code{fopen} |
| using the mode shown in the following table: |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| @code{Open} and @code{Create} Call Modes |
| |
| @tab |
| |
| @tab |
| |
| @item |
| |
| @tab |
| |
| @strong{OPEN} |
| |
| @tab |
| |
| @strong{CREATE} |
| |
| @item |
| |
| Append_File |
| |
| @tab |
| |
| “r+” |
| |
| @tab |
| |
| “w+” |
| |
| @item |
| |
| In_File |
| |
| @tab |
| |
| “r” |
| |
| @tab |
| |
| “w+” |
| |
| @item |
| |
| Out_File (Direct_IO) |
| |
| @tab |
| |
| “r+” |
| |
| @tab |
| |
| “w” |
| |
| @item |
| |
| Out_File (all other cases) |
| |
| @tab |
| |
| “w” |
| |
| @tab |
| |
| “w” |
| |
| @item |
| |
| Inout_File |
| |
| @tab |
| |
| “r+” |
| |
| @tab |
| |
| “w+” |
| |
| @end multitable |
| |
| |
| If text file translation is required, then either @code{b} or @code{t} |
| is added to the mode, depending on the setting of Text. Text file |
| translation refers to the mapping of CR/LF sequences in an external file |
| to LF characters internally. This mapping only occurs in DOS and |
| DOS-like systems, and is not relevant to other systems. |
| |
| A special case occurs with Stream_IO. As shown in the above table, the |
| file is initially opened in @code{r} or @code{w} mode for the |
| @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation |
| subsequently requires switching from reading to writing or vice-versa, |
| then the file is reopened in @code{r+} mode to permit the required operation. |
| |
| @node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2d2} |
| @section Operations on C Streams |
| |
| |
| The package @code{Interfaces.C_Streams} provides an Ada program with direct |
| access to the C library functions for operations on C streams: |
| |
| @example |
| package Interfaces.C_Streams is |
| -- Note: the reason we do not use the types that are in |
| -- Interfaces.C is that we want to avoid dragging in the |
| -- code in this unit if possible. |
| subtype chars is System.Address; |
| -- Pointer to null-terminated array of characters |
| subtype FILEs is System.Address; |
| -- Corresponds to the C type FILE* |
| subtype voids is System.Address; |
| -- Corresponds to the C type void* |
| subtype int is Integer; |
| subtype long is Long_Integer; |
| -- Note: the above types are subtypes deliberately, and it |
| -- is part of this spec that the above correspondences are |
| -- guaranteed. This means that it is legitimate to, for |
| -- example, use Integer instead of int. We provide these |
| -- synonyms for clarity, but in some cases it may be |
| -- convenient to use the underlying types (for example to |
| -- avoid an unnecessary dependency of a spec on the spec |
| -- of this unit). |
| type size_t is mod 2 ** Standard'Address_Size; |
| NULL_Stream : constant FILEs; |
| -- Value returned (NULL in C) to indicate an |
| -- fdopen/fopen/tmpfile error |
| ---------------------------------- |
| -- Constants Defined in stdio.h -- |
| ---------------------------------- |
| EOF : constant int; |
| -- Used by a number of routines to indicate error or |
| -- end of file |
| IOFBF : constant int; |
| IOLBF : constant int; |
| IONBF : constant int; |
| -- Used to indicate buffering mode for setvbuf call |
| SEEK_CUR : constant int; |
| SEEK_END : constant int; |
| SEEK_SET : constant int; |
| -- Used to indicate origin for fseek call |
| function stdin return FILEs; |
| function stdout return FILEs; |
| function stderr return FILEs; |
| -- Streams associated with standard files |
| -------------------------- |
| -- Standard C functions -- |
| -------------------------- |
| -- The functions selected below are ones that are |
| -- available in UNIX (but not necessarily in ANSI C). |
| -- These are very thin interfaces |
| -- which copy exactly the C headers. For more |
| -- documentation on these functions, see the Microsoft C |
| -- "Run-Time Library Reference" (Microsoft Press, 1990, |
| -- ISBN 1-55615-225-6), which includes useful information |
| -- on system compatibility. |
| procedure clearerr (stream : FILEs); |
| function fclose (stream : FILEs) return int; |
| function fdopen (handle : int; mode : chars) return FILEs; |
| function feof (stream : FILEs) return int; |
| function ferror (stream : FILEs) return int; |
| function fflush (stream : FILEs) return int; |
| function fgetc (stream : FILEs) return int; |
| function fgets (strng : chars; n : int; stream : FILEs) |
| return chars; |
| function fileno (stream : FILEs) return int; |
| function fopen (filename : chars; Mode : chars) |
| return FILEs; |
| -- Note: to maintain target independence, use |
| -- text_translation_required, a boolean variable defined in |
| -- a-sysdep.c to deal with the target dependent text |
| -- translation requirement. If this variable is set, |
| -- then b/t should be appended to the standard mode |
| -- argument to set the text translation mode off or on |
| -- as required. |
| function fputc (C : int; stream : FILEs) return int; |
| function fputs (Strng : chars; Stream : FILEs) return int; |
| function fread |
| (buffer : voids; |
| size : size_t; |
| count : size_t; |
| stream : FILEs) |
| return size_t; |
| function freopen |
| (filename : chars; |
| mode : chars; |
| stream : FILEs) |
| return FILEs; |
| function fseek |
| (stream : FILEs; |
| offset : long; |
| origin : int) |
| return int; |
| function ftell (stream : FILEs) return long; |
| function fwrite |
| (buffer : voids; |
| size : size_t; |
| count : size_t; |
| stream : FILEs) |
| return size_t; |
| function isatty (handle : int) return int; |
| procedure mktemp (template : chars); |
| -- The return value (which is just a pointer to template) |
| -- is discarded |
| procedure rewind (stream : FILEs); |
| function rmtmp return int; |
| function setvbuf |
| (stream : FILEs; |
| buffer : chars; |
| mode : int; |
| size : size_t) |
| return int; |
| |
| function tmpfile return FILEs; |
| function ungetc (c : int; stream : FILEs) return int; |
| function unlink (filename : chars) return int; |
| --------------------- |
| -- Extra functions -- |
| --------------------- |
| -- These functions supply slightly thicker bindings than |
| -- those above. They are derived from functions in the |
| -- C Run-Time Library, but may do a bit more work than |
| -- just directly calling one of the Library functions. |
| function is_regular_file (handle : int) return int; |
| -- Tests if given handle is for a regular file (result 1) |
| -- or for a non-regular file (pipe or device, result 0). |
| --------------------------------- |
| -- Control of Text/Binary Mode -- |
| --------------------------------- |
| -- If text_translation_required is true, then the following |
| -- functions may be used to dynamically switch a file from |
| -- binary to text mode or vice versa. These functions have |
| -- no effect if text_translation_required is false (i.e., in |
| -- normal UNIX mode). Use fileno to get a stream handle. |
| procedure set_binary_mode (handle : int); |
| procedure set_text_mode (handle : int); |
| ---------------------------- |
| -- Full Path Name support -- |
| ---------------------------- |
| procedure full_name (nam : chars; buffer : chars); |
| -- Given a NUL terminated string representing a file |
| -- name, returns in buffer a NUL terminated string |
| -- representing the full path name for the file name. |
| -- On systems where it is relevant the drive is also |
| -- part of the full path name. It is the responsibility |
| -- of the caller to pass an actual parameter for buffer |
| -- that is big enough for any full path name. Use |
| -- max_path_len given below as the size of buffer. |
| max_path_len : integer; |
| -- Maximum length of an allowable full path name on the |
| -- system, including a terminating NUL character. |
| end Interfaces.C_Streams; |
| @end example |
| |
| @node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O |
| @anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d3}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d4} |
| @section Interfacing to C Streams |
| |
| |
| The packages in this section permit interfacing Ada files to C Stream |
| operations. |
| |
| @example |
| with Interfaces.C_Streams; |
| package Ada.Sequential_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Sequential_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Direct_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Direct_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Text_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Text_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Wide_Text_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Wide_Text_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Wide_Wide_Text_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Wide_Wide_Text_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Stream_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Stream_IO.C_Streams; |
| @end example |
| |
| In each of these six packages, the @code{C_Stream} function obtains the |
| @code{FILE} pointer from a currently opened Ada file. It is then |
| possible to use the @code{Interfaces.C_Streams} package to operate on |
| this stream, or the stream can be passed to a C program which can |
| operate on it directly. Of course the program is responsible for |
| ensuring that only appropriate sequences of operations are executed. |
| |
| One particular use of relevance to an Ada program is that the |
| @code{setvbuf} function can be used to control the buffering of the |
| stream used by an Ada file. In the absence of such a call the standard |
| default buffering is used. |
| |
| The @code{Open} procedures in these packages open a file giving an |
| existing C Stream instead of a file name. Typically this stream is |
| imported from a C program, allowing an Ada file to operate on an |
| existing C file. |
| |
| @node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top |
| @anchor{gnat_rm/the_gnat_library doc}@anchor{2d5}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d6}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10} |
| @chapter The GNAT Library |
| |
| |
| The GNAT library contains a number of general and special purpose packages. |
| It represents functionality that the GNAT developers have found useful, and |
| which is made available to GNAT users. The packages described here are fully |
| supported, and upwards compatibility will be maintained in future releases, |
| so you can use these facilities with the confidence that the same functionality |
| will be available in future releases. |
| |
| The chapter here simply gives a brief summary of the facilities available. |
| The full documentation is found in the spec file for the package. The full |
| sources of these library packages, including both spec and body, are provided |
| with all GNAT releases. For example, to find out the full specifications of |
| the SPITBOL pattern matching capability, including a full tutorial and |
| extensive examples, look in the @code{g-spipat.ads} file in the library. |
| |
| For each entry here, the package name (as it would appear in a @code{with} |
| clause) is given, followed by the name of the corresponding spec file in |
| parentheses. The packages are children in four hierarchies, @code{Ada}, |
| @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a |
| GNAT-specific hierarchy. |
| |
| Note that an application program should only use packages in one of these |
| four hierarchies if the package is defined in the Ada Reference Manual, |
| or is listed in this section of the GNAT Programmers Reference Manual. |
| All other units should be considered internal implementation units and |
| should not be directly @code{with}ed by application code. The use of |
| a @code{with} clause that references one of these internal implementation |
| units makes an application potentially dependent on changes in versions |
| of GNAT, and will generate a warning message. |
| |
| @menu |
| * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. |
| * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. |
| * Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. |
| * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. |
| * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. |
| * Ada.Containers.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. |
| |
| @end menu |
| |
| @node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id2}@anchor{2d8} |
| @section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) |
| |
| |
| @geindex Ada.Characters.Latin_9 (a-chlat9.ads) |
| |
| @geindex Latin_9 constants for Character |
| |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| RM-defined package @code{Ada.Characters.Latin_1} but with the |
| few modifications required for @code{Latin-9} |
| The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3.3(27)). |
| |
| @node Ada Characters Wide_Latin_1 a-cwila1 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Latin_9 a-chlat9 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d9}@anchor{gnat_rm/the_gnat_library id3}@anchor{2da} |
| @section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) |
| |
| |
| @geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) |
| |
| @geindex Latin_1 constants for Wide_Character |
| |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| RM-defined package @code{Ada.Characters.Latin_1} but with the |
| types of the constants being @code{Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3.3(27)). |
| |
| @node Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id4}@anchor{2dc} |
| @section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) |
| |
| |
| @geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) |
| |
| @geindex Latin_9 constants for Wide_Character |
| |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| GNAT defined package @code{Ada.Characters.Latin_9} but with the |
| types of the constants being @code{Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3.3(27)). |
| |
| @node Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2dd}@anchor{gnat_rm/the_gnat_library id5}@anchor{2de} |
| @section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) |
| |
| |
| @geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) |
| |
| @geindex Latin_1 constants for Wide_Wide_Character |
| |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| RM-defined package @code{Ada.Characters.Latin_1} but with the |
| types of the constants being @code{Wide_Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3.3(27)). |
| |
| @node Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2df}@anchor{gnat_rm/the_gnat_library id6}@anchor{2e0} |
| @section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) |
| |
| |
| @geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) |
| |
| @geindex Latin_9 constants for Wide_Wide_Character |
| |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| GNAT defined package @code{Ada.Characters.Latin_9} but with the |
| types of the constants being @code{Wide_Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3.3(27)). |
| |
| @node Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,Ada Containers Formal_Hashed_Maps a-cfhama ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2e1}@anchor{gnat_rm/the_gnat_library id7}@anchor{2e2} |
| @section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads}) |
| |
| |
| @geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) |
| |
| @geindex Formal container for doubly linked lists |
| |
| This child of @code{Ada.Containers} defines a modified version of the |
| Ada 2005 container for doubly linked lists, meant to facilitate formal |
| verification of code using such containers. The specification of this |
| unit is compatible with SPARK 2014. |
| |
| Note that although this container was designed with formal verification |
| in mind, it may well be generally useful in that it is a simplified more |
| efficient version than the one defined in the standard. In particular it |
| does not have the complex overhead required to detect cursor tampering. |
| |
| @node Ada Containers Formal_Hashed_Maps a-cfhama ads,Ada Containers Formal_Hashed_Sets a-cfhase ads,Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id8}@anchor{2e4} |
| @section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads}) |
| |
| |
| @geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) |
| |
| @geindex Formal container for hashed maps |
| |
| This child of @code{Ada.Containers} defines a modified version of the |
| Ada 2005 container for hashed maps, meant to facilitate formal |
| verification of code using such containers. The specification of this |
| unit is compatible with SPARK 2014. |
| |
| Note that although this container was designed with formal verification |
| in mind, it may well be generally useful in that it is a simplified more |
| efficient version than the one defined in the standard. In particular it |
| does not have the complex overhead required to detect cursor tampering. |
| |
| @node Ada Containers Formal_Hashed_Sets a-cfhase ads,Ada Containers Formal_Ordered_Maps a-cforma ads,Ada Containers Formal_Hashed_Maps a-cfhama ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id9}@anchor{2e6} |
| @section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads}) |
| |
| |
| @geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) |
| |
| @geindex Formal container for hashed sets |
| |
| This child of @code{Ada.Containers} defines a modified version of the |
| Ada 2005 container for hashed sets, meant to facilitate formal |
| verification of code using such containers. The specification of this |
| unit is compatible with SPARK 2014. |
| |
| Note that although this container was designed with formal verification |
| in mind, it may well be generally useful in that it is a simplified more |
| efficient version than the one defined in the standard. In particular it |
| does not have the complex overhead required to detect cursor tampering. |
| |
| @node Ada Containers Formal_Ordered_Maps a-cforma ads,Ada Containers Formal_Ordered_Sets a-cforse ads,Ada Containers Formal_Hashed_Sets a-cfhase ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id10}@anchor{2e8} |
| @section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads}) |
| |
| |
| @geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) |
| |
| @geindex Formal container for ordered maps |
| |
| This child of @code{Ada.Containers} defines a modified version of the |
| Ada 2005 container for ordered maps, meant to facilitate formal |
| verification of code using such containers. The specification of this |
| unit is compatible with SPARK 2014. |
| |
| Note that although this container was designed with formal verification |
| in mind, it may well be generally useful in that it is a simplified more |
| efficient version than the one defined in the standard. In particular it |
| does not have the complex overhead required to detect cursor tampering. |
| |
| @node Ada Containers Formal_Ordered_Sets a-cforse ads,Ada Containers Formal_Vectors a-cofove ads,Ada Containers Formal_Ordered_Maps a-cforma ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id11}@anchor{2ea} |
| @section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads}) |
| |
| |
| @geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) |
| |
| @geindex Formal container for ordered sets |
| |
| This child of @code{Ada.Containers} defines a modified version of the |
| Ada 2005 container for ordered sets, meant to facilitate formal |
| verification of code using such containers. The specification of this |
| unit is compatible with SPARK 2014. |
| |
| Note that although this container was designed with formal verification |
| in mind, it may well be generally useful in that it is a simplified more |
| efficient version than the one defined in the standard. In particular it |
| does not have the complex overhead required to detect cursor tampering. |
| |
| @node Ada Containers Formal_Vectors a-cofove ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Formal_Ordered_Sets a-cforse ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id12}@anchor{2ec} |
| @section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads}) |
| |
| |
| @geindex Ada.Containers.Formal_Vectors (a-cofove.ads) |
| |
| @geindex Formal container for vectors |
| |
| This child of @code{Ada.Containers} defines a modified version of the |
| Ada 2005 container for vectors, meant to facilitate formal |
| verification of code using such containers. The specification of this |
| unit is compatible with SPARK 2014. |
| |
| Note that although this container was designed with formal verification |
| in mind, it may well be generally useful in that it is a simplified more |
| efficient version than the one defined in the standard. In particular it |
| does not have the complex overhead required to detect cursor tampering. |
| |
| @node Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Formal_Vectors a-cofove ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id13}@anchor{2ee} |
| @section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads}) |
| |
| |
| @geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) |
| |
| @geindex Formal container for vectors |
| |
| This child of @code{Ada.Containers} defines a modified version of the |
| Ada 2005 container for vectors of indefinite elements, meant to |
| facilitate formal verification of code using such containers. The |
| specification of this unit is compatible with SPARK 2014. |
| |
| Note that although this container was designed with formal verification |
| in mind, it may well be generally useful in that it is a simplified more |
| efficient version than the one defined in the standard. In particular it |
| does not have the complex overhead required to detect cursor tampering. |
| |
| @node Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Functional_Sets a-cofuse ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f0} |
| @section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads}) |
| |
| |
| @geindex Ada.Containers.Functional_Vectors (a-cofuve.ads) |
| |
| @geindex Functional vectors |
| |
| This child of @code{Ada.Containers} defines immutable vectors. These |
| containers are unbounded and may contain indefinite elements. Furthermore, to |
| be usable in every context, they are neither controlled nor limited. As they |
| are functional, that is, no primitives are provided which would allow modifying |
| an existing container, these containers can still be used safely. |
| |
| Their API features functions creating new containers from existing ones. |
| As a consequence, these containers are highly inefficient. They are also |
| memory consuming, as the allocated memory is not reclaimed when the container |
| is no longer referenced. Thus, they should in general be used in ghost code |
| and annotations, so that they can be removed from the final executable. The |
| specification of this unit is compatible with SPARK 2014. |
| |
| @node Ada Containers Functional_Sets a-cofuse ads,Ada Containers Functional_Maps a-cofuma ads,Ada Containers Functional_Vectors a-cofuve ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f2} |
| @section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads}) |
| |
| |
| @geindex Ada.Containers.Functional_Sets (a-cofuse.ads) |
| |
| @geindex Functional sets |
| |
| This child of @code{Ada.Containers} defines immutable sets. These containers are |
| unbounded and may contain indefinite elements. Furthermore, to be usable in |
| every context, they are neither controlled nor limited. As they are functional, |
| that is, no primitives are provided which would allow modifying an existing |
| container, these containers can still be used safely. |
| |
| Their API features functions creating new containers from existing ones. |
| As a consequence, these containers are highly inefficient. They are also |
| memory consuming, as the allocated memory is not reclaimed when the container |
| is no longer referenced. Thus, they should in general be used in ghost code |
| and annotations, so that they can be removed from the final executable. The |
| specification of this unit is compatible with SPARK 2014. |
| |
| @node Ada Containers Functional_Maps a-cofuma ads,Ada Containers Bounded_Holders a-coboho ads,Ada Containers Functional_Sets a-cofuse ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id16}@anchor{2f4} |
| @section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads}) |
| |
| |
| @geindex Ada.Containers.Functional_Maps (a-cofuma.ads) |
| |
| @geindex Functional maps |
| |
| This child of @code{Ada.Containers} defines immutable maps. These containers are |
| unbounded and may contain indefinite elements. Furthermore, to be usable in |
| every context, they are neither controlled nor limited. As they are functional, |
| that is, no primitives are provided which would allow modifying an existing |
| container, these containers can still be used safely. |
| |
| Their API features functions creating new containers from existing ones. |
| As a consequence, these containers are highly inefficient. They are also |
| memory consuming, as the allocated memory is not reclaimed when the container |
| is no longer referenced. Thus, they should in general be used in ghost code |
| and annotations, so that they can be removed from the final executable. The |
| specification of this unit is compatible with SPARK 2014. |
| |
| @node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Containers Functional_Maps a-cofuma ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f6} |
| @section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) |
| |
| |
| @geindex Ada.Containers.Bounded_Holders (a-coboho.ads) |
| |
| @geindex Formal container for vectors |
| |
| This child of @code{Ada.Containers} defines a modified version of |
| Indefinite_Holders that avoids heap allocation. |
| |
| @node Ada Command_Line Environment a-colien ads,Ada Command_Line Remove a-colire ads,Ada Containers Bounded_Holders a-coboho ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f8} |
| @section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) |
| |
| |
| @geindex Ada.Command_Line.Environment (a-colien.ads) |
| |
| @geindex Environment entries |
| |
| This child of @code{Ada.Command_Line} |
| provides a mechanism for obtaining environment values on systems |
| where this concept makes sense. |
| |
| @node Ada Command_Line Remove a-colire ads,Ada Command_Line Response_File a-clrefi ads,Ada Command_Line Environment a-colien ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id19}@anchor{2fa} |
| @section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) |
| |
| |
| @geindex Ada.Command_Line.Remove (a-colire.ads) |
| |
| @geindex Removing command line arguments |
| |
| @geindex Command line |
| @geindex argument removal |
| |
| This child of @code{Ada.Command_Line} |
| provides a mechanism for logically removing |
| arguments from the argument list. Once removed, an argument is not visible |
| to further calls on the subprograms in @code{Ada.Command_Line} will not |
| see the removed argument. |
| |
| @node Ada Command_Line Response_File a-clrefi ads,Ada Direct_IO C_Streams a-diocst ads,Ada Command_Line Remove a-colire ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id20}@anchor{2fc} |
| @section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) |
| |
| |
| @geindex Ada.Command_Line.Response_File (a-clrefi.ads) |
| |
| @geindex Response file for command line |
| |
| @geindex Command line |
| @geindex response file |
| |
| @geindex Command line |
| @geindex handling long command lines |
| |
| This child of @code{Ada.Command_Line} provides a mechanism facilities for |
| getting command line arguments from a text file, called a “response file”. |
| Using a response file allow passing a set of arguments to an executable longer |
| than the maximum allowed by the system on the command line. |
| |
| @node Ada Direct_IO C_Streams a-diocst ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Command_Line Response_File a-clrefi ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id21}@anchor{2fe} |
| @section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) |
| |
| |
| @geindex Ada.Direct_IO.C_Streams (a-diocst.ads) |
| |
| @geindex C Streams |
| @geindex Interfacing with Direct_IO |
| |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Direct_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Direct_IO C_Streams a-diocst ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id22}@anchor{300} |
| @section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) |
| |
| |
| @geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) |
| |
| @geindex Null_Occurrence |
| @geindex testing for |
| |
| This child subprogram provides a way of testing for the null |
| exception occurrence (@code{Null_Occurrence}) without raising |
| an exception. |
| |
| @node Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Exceptions Traceback a-exctra ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id23}@anchor{302} |
| @section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) |
| |
| |
| @geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) |
| |
| @geindex Null_Occurrence |
| @geindex testing for |
| |
| This child subprogram is used for handling otherwise unhandled |
| exceptions (hence the name last chance), and perform clean ups before |
| terminating the program. Note that this subprogram never returns. |
| |
| @node Ada Exceptions Traceback a-exctra ads,Ada Sequential_IO C_Streams a-siocst ads,Ada Exceptions Last_Chance_Handler a-elchha ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id24}@anchor{304} |
| @section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) |
| |
| |
| @geindex Ada.Exceptions.Traceback (a-exctra.ads) |
| |
| @geindex Traceback for Exception Occurrence |
| |
| This child package provides the subprogram (@code{Tracebacks}) to |
| give a traceback array of addresses based on an exception |
| occurrence. |
| |
| @node Ada Sequential_IO C_Streams a-siocst ads,Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Exceptions Traceback a-exctra ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{305}@anchor{gnat_rm/the_gnat_library id25}@anchor{306} |
| @section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) |
| |
| |
| @geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) |
| |
| @geindex C Streams |
| @geindex Interfacing with Sequential_IO |
| |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Sequential_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Strings Unbounded Text_IO a-suteio ads,Ada Sequential_IO C_Streams a-siocst ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id26}@anchor{308} |
| @section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) |
| |
| |
| @geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) |
| |
| @geindex C Streams |
| @geindex Interfacing with Stream_IO |
| |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Stream_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada Strings Unbounded Text_IO a-suteio ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Streams Stream_IO C_Streams a-ssicst ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id27}@anchor{30a} |
| @section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) |
| |
| |
| @geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) |
| |
| @geindex Unbounded_String |
| @geindex IO support |
| |
| @geindex Text_IO |
| @geindex extensions for unbounded strings |
| |
| This package provides subprograms for Text_IO for unbounded |
| strings, avoiding the necessity for an intermediate operation |
| with ordinary strings. |
| |
| @node Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Strings Unbounded Text_IO a-suteio ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{30b}@anchor{gnat_rm/the_gnat_library id28}@anchor{30c} |
| @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) |
| |
| |
| @geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) |
| |
| @geindex Unbounded_Wide_String |
| @geindex IO support |
| |
| @geindex Text_IO |
| @geindex extensions for unbounded wide strings |
| |
| This package provides subprograms for Text_IO for unbounded |
| wide strings, avoiding the necessity for an intermediate operation |
| with ordinary wide strings. |
| |
| @node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Task_Initialization a-tasini ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id29}@anchor{30e} |
| @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) |
| |
| |
| @geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) |
| |
| @geindex Unbounded_Wide_Wide_String |
| @geindex IO support |
| |
| @geindex Text_IO |
| @geindex extensions for unbounded wide wide strings |
| |
| This package provides subprograms for Text_IO for unbounded |
| wide wide strings, avoiding the necessity for an intermediate operation |
| with ordinary wide wide strings. |
| |
| @node Ada Task_Initialization a-tasini ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id30}@anchor{310} |
| @section @code{Ada.Task_Initialization} (@code{a-tasini.ads}) |
| |
| |
| @geindex Ada.Task_Initialization (a-tasini.ads) |
| |
| This package provides a way to set a global initialization handler that |
| is automatically invoked whenever a task is activated. Handlers are |
| parameterless procedures. Note that such a handler is only invoked for |
| those tasks activated after the handler is set. |
| |
| @node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Task_Initialization a-tasini ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id31}@anchor{312} |
| @section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) |
| |
| |
| @geindex Ada.Text_IO.C_Streams (a-tiocst.ads) |
| |
| @geindex C Streams |
| @geindex Interfacing with `@w{`}Text_IO`@w{`} |
| |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Text_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Wide_Characters Unicode a-wichun ads,Ada Text_IO C_Streams a-tiocst ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id32}@anchor{314} |
| @section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) |
| |
| |
| @geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) |
| |
| @geindex Text_IO resetting standard files |
| |
| This procedure is used to reset the status of the standard files used |
| by Ada.Text_IO. This is useful in a situation (such as a restart in an |
| embedded application) where the status of the files may change during |
| execution (for example a standard input file may be redefined to be |
| interactive). |
| |
| @node Ada Wide_Characters Unicode a-wichun ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id33}@anchor{316} |
| @section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) |
| |
| |
| @geindex Ada.Wide_Characters.Unicode (a-wichun.ads) |
| |
| @geindex Unicode categorization |
| @geindex Wide_Character |
| |
| This package provides subprograms that allow categorization of |
| Wide_Character values according to Unicode categories. |
| |
| @node Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Characters Unicode a-wichun ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id34}@anchor{318} |
| @section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) |
| |
| |
| @geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) |
| |
| @geindex C Streams |
| @geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} |
| |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Wide_Text_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id35}@anchor{31a} |
| @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) |
| |
| |
| @geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) |
| |
| @geindex Wide_Text_IO resetting standard files |
| |
| This procedure is used to reset the status of the standard files used |
| by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an |
| embedded application) where the status of the files may change during |
| execution (for example a standard input file may be redefined to be |
| interactive). |
| |
| @node Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id36}@anchor{31c} |
| @section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) |
| |
| |
| @geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) |
| |
| @geindex Unicode categorization |
| @geindex Wide_Wide_Character |
| |
| This package provides subprograms that allow categorization of |
| Wide_Wide_Character values according to Unicode categories. |
| |
| @node Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id37}@anchor{31e} |
| @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) |
| |
| |
| @geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) |
| |
| @geindex C Streams |
| @geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} |
| |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,GNAT Altivec g-altive ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id38}@anchor{320} |
| @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) |
| |
| |
| @geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) |
| |
| @geindex Wide_Wide_Text_IO resetting standard files |
| |
| This procedure is used to reset the status of the standard files used |
| by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a |
| restart in an embedded application) where the status of the files may |
| change during execution (for example a standard input file may be |
| redefined to be interactive). |
| |
| @node GNAT Altivec g-altive ads,GNAT Altivec Conversions g-altcon ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id39}@anchor{322} |
| @section @code{GNAT.Altivec} (@code{g-altive.ads}) |
| |
| |
| @geindex GNAT.Altivec (g-altive.ads) |
| |
| @geindex AltiVec |
| |
| This is the root package of the GNAT AltiVec binding. It provides |
| definitions of constants and types common to all the versions of the |
| binding. |
| |
| @node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id40}@anchor{324} |
| @section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) |
| |
| |
| @geindex GNAT.Altivec.Conversions (g-altcon.ads) |
| |
| @geindex AltiVec |
| |
| This package provides the Vector/View conversion routines. |
| |
| @node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id41}@anchor{326} |
| @section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) |
| |
| |
| @geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) |
| |
| @geindex AltiVec |
| |
| This package exposes the Ada interface to the AltiVec operations on |
| vector objects. A soft emulation is included by default in the GNAT |
| library. The hard binding is provided as a separate package. This unit |
| is common to both bindings. |
| |
| @node GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Vector_Views g-alvevi ads,GNAT Altivec Vector_Operations g-alveop ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id42}@anchor{328} |
| @section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) |
| |
| |
| @geindex GNAT.Altivec.Vector_Types (g-alvety.ads) |
| |
| @geindex AltiVec |
| |
| This package exposes the various vector types part of the Ada binding |
| to AltiVec facilities. |
| |
| @node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id43}@anchor{32a} |
| @section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) |
| |
| |
| @geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) |
| |
| @geindex AltiVec |
| |
| This package provides public ‘View’ data types from/to which private |
| vector representations can be converted via |
| GNAT.Altivec.Conversions. This allows convenient access to individual |
| vector elements and provides a simple way to initialize vector |
| objects. |
| |
| @node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id44}@anchor{32c} |
| @section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) |
| |
| |
| @geindex GNAT.Array_Split (g-arrspl.ads) |
| |
| @geindex Array splitter |
| |
| Useful array-manipulation routines: given a set of separators, split |
| an array wherever the separators appear, and provide direct access |
| to the resulting slices. |
| |
| @node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id45}@anchor{32e} |
| @section @code{GNAT.AWK} (@code{g-awk.ads}) |
| |
| |
| @geindex GNAT.AWK (g-awk.ads) |
| |
| @geindex Parsing |
| |
| @geindex AWK |
| |
| Provides AWK-like parsing functions, with an easy interface for parsing one |
| or more files containing formatted data. The file is viewed as a database |
| where each record is a line and a field is a data element in this line. |
| |
| @node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT AWK g-awk ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id46}@anchor{330} |
| @section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) |
| |
| |
| @geindex GNAT.Bind_Environment (g-binenv.ads) |
| |
| @geindex Bind environment |
| |
| Provides access to key=value associations captured at bind time. |
| These associations can be specified using the @code{-V} binder command |
| line switch. |
| |
| @node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id47}@anchor{332} |
| @section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) |
| |
| |
| @geindex GNAT.Branch_Prediction (g-brapre.ads) |
| |
| @geindex Branch Prediction |
| |
| Provides routines giving hints to the branch predictor of the code generator. |
| |
| @node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id48}@anchor{334} |
| @section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) |
| |
| |
| @geindex GNAT.Bounded_Buffers (g-boubuf.ads) |
| |
| @geindex Parsing |
| |
| @geindex Bounded Buffers |
| |
| Provides a concurrent generic bounded buffer abstraction. Instances are |
| useful directly or as parts of the implementations of other abstractions, |
| such as mailboxes. |
| |
| @node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id49}@anchor{336} |
| @section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) |
| |
| |
| @geindex GNAT.Bounded_Mailboxes (g-boumai.ads) |
| |
| @geindex Parsing |
| |
| @geindex Mailboxes |
| |
| Provides a thread-safe asynchronous intertask mailbox communication facility. |
| |
| @node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id50}@anchor{338} |
| @section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) |
| |
| |
| @geindex GNAT.Bubble_Sort (g-bubsor.ads) |
| |
| @geindex Sorting |
| |
| @geindex Bubble sort |
| |
| Provides a general implementation of bubble sort usable for sorting arbitrary |
| data items. Exchange and comparison procedures are provided by passing |
| access-to-procedure values. |
| |
| @node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id51}@anchor{33a} |
| @section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) |
| |
| |
| @geindex GNAT.Bubble_Sort_A (g-busora.ads) |
| |
| @geindex Sorting |
| |
| @geindex Bubble sort |
| |
| Provides a general implementation of bubble sort usable for sorting arbitrary |
| data items. Move and comparison procedures are provided by passing |
| access-to-procedure values. This is an older version, retained for |
| compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. |
| |
| @node GNAT Bubble_Sort_G g-busorg ads,GNAT Byte_Order_Mark g-byorma ads,GNAT Bubble_Sort_A g-busora ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id52}@anchor{33c} |
| @section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) |
| |
| |
| @geindex GNAT.Bubble_Sort_G (g-busorg.ads) |
| |
| @geindex Sorting |
| |
| @geindex Bubble sort |
| |
| Similar to @code{Bubble_Sort_A} except that the move and sorting procedures |
| are provided as generic parameters, this improves efficiency, especially |
| if the procedures can be inlined, at the expense of duplicating code for |
| multiple instantiations. |
| |
| @node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id53}@anchor{33e} |
| @section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) |
| |
| |
| @geindex GNAT.Byte_Order_Mark (g-byorma.ads) |
| |
| @geindex UTF-8 representation |
| |
| @geindex Wide characte representations |
| |
| Provides a routine which given a string, reads the start of the string to |
| see whether it is one of the standard byte order marks (BOM’s) which signal |
| the encoding of the string. The routine includes detection of special XML |
| sequences for various UCS input formats. |
| |
| @node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id54}@anchor{340} |
| @section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) |
| |
| |
| @geindex GNAT.Byte_Swapping (g-bytswa.ads) |
| |
| @geindex Byte swapping |
| |
| @geindex Endianness |
| |
| General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. |
| Machine-specific implementations are available in some cases. |
| |
| @node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id55}@anchor{342} |
| @section @code{GNAT.Calendar} (@code{g-calend.ads}) |
| |
| |
| @geindex GNAT.Calendar (g-calend.ads) |
| |
| @geindex Calendar |
| |
| Extends the facilities provided by @code{Ada.Calendar} to include handling |
| of days of the week, an extended @code{Split} and @code{Time_Of} capability. |
| Also provides conversion of @code{Ada.Calendar.Time} values to and from the |
| C @code{timeval} format. |
| |
| @node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id56}@anchor{344} |
| @section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) |
| |
| |
| @geindex Calendar |
| |
| @geindex Time |
| |
| @geindex GNAT.Calendar.Time_IO (g-catiio.ads) |
| |
| @node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id57}@anchor{346} |
| @section @code{GNAT.CRC32} (@code{g-crc32.ads}) |
| |
| |
| @geindex GNAT.CRC32 (g-crc32.ads) |
| |
| @geindex CRC32 |
| |
| @geindex Cyclic Redundancy Check |
| |
| This package implements the CRC-32 algorithm. For a full description |
| of this algorithm see |
| @emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, |
| @cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, |
| Aug. 1988. Sarwate, D.V. |
| |
| @node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id58}@anchor{348} |
| @section @code{GNAT.Case_Util} (@code{g-casuti.ads}) |
| |
| |
| @geindex GNAT.Case_Util (g-casuti.ads) |
| |
| @geindex Casing utilities |
| |
| @geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) |
| |
| A set of simple routines for handling upper and lower casing of strings |
| without the overhead of the full casing tables |
| in @code{Ada.Characters.Handling}. |
| |
| @node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id59}@anchor{34a} |
| @section @code{GNAT.CGI} (@code{g-cgi.ads}) |
| |
| |
| @geindex GNAT.CGI (g-cgi.ads) |
| |
| @geindex CGI (Common Gateway Interface) |
| |
| This is a package for interfacing a GNAT program with a Web server via the |
| Common Gateway Interface (CGI). Basically this package parses the CGI |
| parameters, which are a set of key/value pairs sent by the Web server. It |
| builds a table whose index is the key and provides some services to deal |
| with this table. |
| |
| @node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id60}@anchor{34c} |
| @section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) |
| |
| |
| @geindex GNAT.CGI.Cookie (g-cgicoo.ads) |
| |
| @geindex CGI (Common Gateway Interface) cookie support |
| |
| @geindex Cookie support in CGI |
| |
| This is a package to interface a GNAT program with a Web server via the |
| Common Gateway Interface (CGI). It exports services to deal with Web |
| cookies (piece of information kept in the Web client software). |
| |
| @node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id61}@anchor{34e} |
| @section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) |
| |
| |
| @geindex GNAT.CGI.Debug (g-cgideb.ads) |
| |
| @geindex CGI (Common Gateway Interface) debugging |
| |
| This is a package to help debugging CGI (Common Gateway Interface) |
| programs written in Ada. |
| |
| @node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id62}@anchor{350} |
| @section @code{GNAT.Command_Line} (@code{g-comlin.ads}) |
| |
| |
| @geindex GNAT.Command_Line (g-comlin.ads) |
| |
| @geindex Command line |
| |
| Provides a high level interface to @code{Ada.Command_Line} facilities, |
| including the ability to scan for named switches with optional parameters |
| and expand file names using wildcard notations. |
| |
| @node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id63}@anchor{352} |
| @section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) |
| |
| |
| @geindex GNAT.Compiler_Version (g-comver.ads) |
| |
| @geindex Compiler Version |
| |
| @geindex Version |
| @geindex of compiler |
| |
| Provides a routine for obtaining the version of the compiler used to |
| compile the program. More accurately this is the version of the binder |
| used to bind the program (this will normally be the same as the version |
| of the compiler if a consistent tool set is used to compile all units |
| of a partition). |
| |
| @node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id64}@anchor{354} |
| @section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) |
| |
| |
| @geindex GNAT.Ctrl_C (g-ctrl_c.ads) |
| |
| @geindex Interrupt |
| |
| Provides a simple interface to handle Ctrl-C keyboard events. |
| |
| @node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id65}@anchor{356} |
| @section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) |
| |
| |
| @geindex GNAT.Current_Exception (g-curexc.ads) |
| |
| @geindex Current exception |
| |
| @geindex Exception retrieval |
| |
| Provides access to information on the current exception that has been raised |
| without the need for using the Ada 95 / Ada 2005 exception choice parameter |
| specification syntax. |
| This is particularly useful in simulating typical facilities for |
| obtaining information about exceptions provided by Ada 83 compilers. |
| |
| @node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id66}@anchor{358} |
| @section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) |
| |
| |
| @geindex GNAT.Debug_Pools (g-debpoo.ads) |
| |
| @geindex Debugging |
| |
| @geindex Debug pools |
| |
| @geindex Memory corruption debugging |
| |
| Provide a debugging storage pools that helps tracking memory corruption |
| problems. |
| See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}. |
| |
| @node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id67}@anchor{35a} |
| @section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) |
| |
| |
| @geindex GNAT.Debug_Utilities (g-debuti.ads) |
| |
| @geindex Debugging |
| |
| Provides a few useful utilities for debugging purposes, including conversion |
| to and from string images of address values. Supports both C and Ada formats |
| for hexadecimal literals. |
| |
| @node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id68}@anchor{35c} |
| @section @code{GNAT.Decode_String} (@code{g-decstr.ads}) |
| |
| |
| @geindex GNAT.Decode_String (g-decstr.ads) |
| |
| @geindex Decoding strings |
| |
| @geindex String decoding |
| |
| @geindex Wide character encoding |
| |
| @geindex UTF-8 |
| |
| @geindex Unicode |
| |
| A generic package providing routines for decoding wide character and wide wide |
| character strings encoded as sequences of 8-bit characters using a specified |
| encoding method. Includes validation routines, and also routines for stepping |
| to next or previous encoded character in an encoded string. |
| Useful in conjunction with Unicode character coding. Note there is a |
| preinstantiation for UTF-8. See next entry. |
| |
| @node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id69}@anchor{35e} |
| @section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) |
| |
| |
| @geindex GNAT.Decode_UTF8_String (g-deutst.ads) |
| |
| @geindex Decoding strings |
| |
| @geindex Decoding UTF-8 strings |
| |
| @geindex UTF-8 string decoding |
| |
| @geindex Wide character decoding |
| |
| @geindex UTF-8 |
| |
| @geindex Unicode |
| |
| A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. |
| |
| @node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id70}@anchor{360} |
| @section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) |
| |
| |
| @geindex GNAT.Directory_Operations (g-dirope.ads) |
| |
| @geindex Directory operations |
| |
| Provides a set of routines for manipulating directories, including changing |
| the current directory, making new directories, and scanning the files in a |
| directory. |
| |
| @node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id71}@anchor{362} |
| @section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) |
| |
| |
| @geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) |
| |
| @geindex Directory operations iteration |
| |
| A child unit of GNAT.Directory_Operations providing additional operations |
| for iterating through directories. |
| |
| @node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id72}@anchor{364} |
| @section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) |
| |
| |
| @geindex GNAT.Dynamic_HTables (g-dynhta.ads) |
| |
| @geindex Hash tables |
| |
| A generic implementation of hash tables that can be used to hash arbitrary |
| data. Provided in two forms, a simple form with built in hash functions, |
| and a more complex form in which the hash function is supplied. |
| |
| This package provides a facility similar to that of @code{GNAT.HTable}, |
| except that this package declares a type that can be used to define |
| dynamic instances of the hash table, while an instantiation of |
| @code{GNAT.HTable} creates a single instance of the hash table. |
| |
| @node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id73}@anchor{366} |
| @section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) |
| |
| |
| @geindex GNAT.Dynamic_Tables (g-dyntab.ads) |
| |
| @geindex Table implementation |
| |
| @geindex Arrays |
| @geindex extendable |
| |
| A generic package providing a single dimension array abstraction where the |
| length of the array can be dynamically modified. |
| |
| This package provides a facility similar to that of @code{GNAT.Table}, |
| except that this package declares a type that can be used to define |
| dynamic instances of the table, while an instantiation of |
| @code{GNAT.Table} creates a single instance of the table type. |
| |
| @node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id74}@anchor{368} |
| @section @code{GNAT.Encode_String} (@code{g-encstr.ads}) |
| |
| |
| @geindex GNAT.Encode_String (g-encstr.ads) |
| |
| @geindex Encoding strings |
| |
| @geindex String encoding |
| |
| @geindex Wide character encoding |
| |
| @geindex UTF-8 |
| |
| @geindex Unicode |
| |
| A generic package providing routines for encoding wide character and wide |
| wide character strings as sequences of 8-bit characters using a specified |
| encoding method. Useful in conjunction with Unicode character coding. |
| Note there is a preinstantiation for UTF-8. See next entry. |
| |
| @node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id75}@anchor{36a} |
| @section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) |
| |
| |
| @geindex GNAT.Encode_UTF8_String (g-enutst.ads) |
| |
| @geindex Encoding strings |
| |
| @geindex Encoding UTF-8 strings |
| |
| @geindex UTF-8 string encoding |
| |
| @geindex Wide character encoding |
| |
| @geindex UTF-8 |
| |
| @geindex Unicode |
| |
| A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. |
| |
| @node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id76}@anchor{36c} |
| @section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) |
| |
| |
| @geindex GNAT.Exception_Actions (g-excact.ads) |
| |
| @geindex Exception actions |
| |
| Provides callbacks when an exception is raised. Callbacks can be registered |
| for specific exceptions, or when any exception is raised. This |
| can be used for instance to force a core dump to ease debugging. |
| |
| @node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id77}@anchor{36e} |
| @section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) |
| |
| |
| @geindex GNAT.Exception_Traces (g-exctra.ads) |
| |
| @geindex Exception traces |
| |
| @geindex Debugging |
| |
| Provides an interface allowing to control automatic output upon exception |
| occurrences. |
| |
| @node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id78}@anchor{370} |
| @section @code{GNAT.Exceptions} (@code{g-except.ads}) |
| |
| |
| @geindex GNAT.Exceptions (g-except.ads) |
| |
| @geindex Exceptions |
| @geindex Pure |
| |
| @geindex Pure packages |
| @geindex exceptions |
| |
| Normally it is not possible to raise an exception with |
| a message from a subprogram in a pure package, since the |
| necessary types and subprograms are in @code{Ada.Exceptions} |
| which is not a pure unit. @code{GNAT.Exceptions} provides a |
| facility for getting around this limitation for a few |
| predefined exceptions, and for example allow raising |
| @code{Constraint_Error} with a message from a pure subprogram. |
| |
| @node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id79}@anchor{372} |
| @section @code{GNAT.Expect} (@code{g-expect.ads}) |
| |
| |
| @geindex GNAT.Expect (g-expect.ads) |
| |
| Provides a set of subprograms similar to what is available |
| with the standard Tcl Expect tool. |
| It allows you to easily spawn and communicate with an external process. |
| You can send commands or inputs to the process, and compare the output |
| with some expected regular expression. Currently @code{GNAT.Expect} |
| is implemented on all native GNAT ports. |
| It is not implemented for cross ports, and in particular is not |
| implemented for VxWorks or LynxOS. |
| |
| @node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id80}@anchor{374} |
| @section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) |
| |
| |
| @geindex GNAT.Expect.TTY (g-exptty.ads) |
| |
| As GNAT.Expect but using pseudo-terminal. |
| Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT |
| ports. It is not implemented for cross ports, and |
| in particular is not implemented for VxWorks or LynxOS. |
| |
| @node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id81}@anchor{376} |
| @section @code{GNAT.Float_Control} (@code{g-flocon.ads}) |
| |
| |
| @geindex GNAT.Float_Control (g-flocon.ads) |
| |
| @geindex Floating-Point Processor |
| |
| Provides an interface for resetting the floating-point processor into the |
| mode required for correct semantic operation in Ada. Some third party |
| library calls may cause this mode to be modified, and the Reset procedure |
| in this package can be used to reestablish the required mode. |
| |
| @node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id82}@anchor{378} |
| @section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) |
| |
| |
| @geindex GNAT.Formatted_String (g-forstr.ads) |
| |
| @geindex Formatted String |
| |
| Provides support for C/C++ printf() formatted strings. The format is |
| copied from the printf() routine and should therefore gives identical |
| output. Some generic routines are provided to be able to use types |
| derived from Integer, Float or enumerations as values for the |
| formatted string. |
| |
| @node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id83}@anchor{37a} |
| @section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) |
| |
| |
| @geindex GNAT.Heap_Sort (g-heasor.ads) |
| |
| @geindex Sorting |
| |
| Provides a general implementation of heap sort usable for sorting arbitrary |
| data items. Exchange and comparison procedures are provided by passing |
| access-to-procedure values. The algorithm used is a modified heap sort |
| that performs approximately N*log(N) comparisons in the worst case. |
| |
| @node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id84}@anchor{37c} |
| @section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) |
| |
| |
| @geindex GNAT.Heap_Sort_A (g-hesora.ads) |
| |
| @geindex Sorting |
| |
| Provides a general implementation of heap sort usable for sorting arbitrary |
| data items. Move and comparison procedures are provided by passing |
| access-to-procedure values. The algorithm used is a modified heap sort |
| that performs approximately N*log(N) comparisons in the worst case. |
| This differs from @code{GNAT.Heap_Sort} in having a less convenient |
| interface, but may be slightly more efficient. |
| |
| @node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id85}@anchor{37e} |
| @section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) |
| |
| |
| @geindex GNAT.Heap_Sort_G (g-hesorg.ads) |
| |
| @geindex Sorting |
| |
| Similar to @code{Heap_Sort_A} except that the move and sorting procedures |
| are provided as generic parameters, this improves efficiency, especially |
| if the procedures can be inlined, at the expense of duplicating code for |
| multiple instantiations. |
| |
| @node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id86}@anchor{380} |
| @section @code{GNAT.HTable} (@code{g-htable.ads}) |
| |
| |
| @geindex GNAT.HTable (g-htable.ads) |
| |
| @geindex Hash tables |
| |
| A generic implementation of hash tables that can be used to hash arbitrary |
| data. Provides two approaches, one a simple static approach, and the other |
| allowing arbitrary dynamic hash tables. |
| |
| @node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id87}@anchor{382} |
| @section @code{GNAT.IO} (@code{g-io.ads}) |
| |
| |
| @geindex GNAT.IO (g-io.ads) |
| |
| @geindex Simple I/O |
| |
| @geindex Input/Output facilities |
| |
| A simple preelaborable input-output package that provides a subset of |
| simple Text_IO functions for reading characters and strings from |
| Standard_Input, and writing characters, strings and integers to either |
| Standard_Output or Standard_Error. |
| |
| @node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id88}@anchor{384} |
| @section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) |
| |
| |
| @geindex GNAT.IO_Aux (g-io_aux.ads) |
| |
| @geindex Text_IO |
| |
| @geindex Input/Output facilities |
| |
| Provides some auxiliary functions for use with Text_IO, including a test |
| for whether a file exists, and functions for reading a line of text. |
| |
| @node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{385}@anchor{gnat_rm/the_gnat_library id89}@anchor{386} |
| @section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) |
| |
| |
| @geindex GNAT.Lock_Files (g-locfil.ads) |
| |
| @geindex File locking |
| |
| @geindex Locking using files |
| |
| Provides a general interface for using files as locks. Can be used for |
| providing program level synchronization. |
| |
| @node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{387}@anchor{gnat_rm/the_gnat_library id90}@anchor{388} |
| @section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) |
| |
| |
| @geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) |
| |
| @geindex Random number generation |
| |
| The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses |
| a modified version of the Blum-Blum-Shub generator. |
| |
| @node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{389}@anchor{gnat_rm/the_gnat_library id91}@anchor{38a} |
| @section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) |
| |
| |
| @geindex GNAT.MBBS_Float_Random (g-mbflra.ads) |
| |
| @geindex Random number generation |
| |
| The original implementation of @code{Ada.Numerics.Float_Random}. Uses |
| a modified version of the Blum-Blum-Shub generator. |
| |
| @node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{38b}@anchor{gnat_rm/the_gnat_library id92}@anchor{38c} |
| @section @code{GNAT.MD5} (@code{g-md5.ads}) |
| |
| |
| @geindex GNAT.MD5 (g-md5.ads) |
| |
| @geindex Message Digest MD5 |
| |
| Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and |
| the HMAC-MD5 message authentication function as described in RFC 2104 and |
| FIPS PUB 198. |
| |
| @node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{38d}@anchor{gnat_rm/the_gnat_library id93}@anchor{38e} |
| @section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) |
| |
| |
| @geindex GNAT.Memory_Dump (g-memdum.ads) |
| |
| @geindex Dump Memory |
| |
| Provides a convenient routine for dumping raw memory to either the |
| standard output or standard error files. Uses GNAT.IO for actual |
| output. |
| |
| @node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{38f}@anchor{gnat_rm/the_gnat_library id94}@anchor{390} |
| @section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) |
| |
| |
| @geindex GNAT.Most_Recent_Exception (g-moreex.ads) |
| |
| @geindex Exception |
| @geindex obtaining most recent |
| |
| Provides access to the most recently raised exception. Can be used for |
| various logging purposes, including duplicating functionality of some |
| Ada 83 implementation dependent extensions. |
| |
| @node GNAT OS_Lib g-os_lib ads,GNAT Perfect_Hash_Generators g-pehage ads,GNAT Most_Recent_Exception g-moreex ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{391}@anchor{gnat_rm/the_gnat_library id95}@anchor{392} |
| @section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) |
| |
| |
| @geindex GNAT.OS_Lib (g-os_lib.ads) |
| |
| @geindex Operating System interface |
| |
| @geindex Spawn capability |
| |
| Provides a range of target independent operating system interface functions, |
| including time/date management, file operations, subprocess management, |
| including a portable spawn procedure, and access to environment variables |
| and error return codes. |
| |
| @node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{393}@anchor{gnat_rm/the_gnat_library id96}@anchor{394} |
| @section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) |
| |
| |
| @geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) |
| |
| @geindex Hash functions |
| |
| Provides a generator of static minimal perfect hash functions. No |
| collisions occur and each item can be retrieved from the table in one |
| probe (perfect property). The hash table size corresponds to the exact |
| size of the key set and no larger (minimal property). The key set has to |
| be know in advance (static property). The hash functions are also order |
| preserving. If w2 is inserted after w1 in the generator, their |
| hashcode are in the same order. These hashing functions are very |
| convenient for use with realtime applications. |
| |
| @node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{395}@anchor{gnat_rm/the_gnat_library id97}@anchor{396} |
| @section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) |
| |
| |
| @geindex GNAT.Random_Numbers (g-rannum.ads) |
| |
| @geindex Random number generation |
| |
| Provides random number capabilities which extend those available in the |
| standard Ada library and are more convenient to use. |
| |
| @node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{25c}@anchor{gnat_rm/the_gnat_library id98}@anchor{397} |
| @section @code{GNAT.Regexp} (@code{g-regexp.ads}) |
| |
| |
| @geindex GNAT.Regexp (g-regexp.ads) |
| |
| @geindex Regular expressions |
| |
| @geindex Pattern matching |
| |
| A simple implementation of regular expressions, using a subset of regular |
| expression syntax copied from familiar Unix style utilities. This is the |
| simplest of the three pattern matching packages provided, and is particularly |
| suitable for ‘file globbing’ applications. |
| |
| @node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id99}@anchor{399} |
| @section @code{GNAT.Registry} (@code{g-regist.ads}) |
| |
| |
| @geindex GNAT.Registry (g-regist.ads) |
| |
| @geindex Windows Registry |
| |
| This is a high level binding to the Windows registry. It is possible to |
| do simple things like reading a key value, creating a new key. For full |
| registry API, but at a lower level of abstraction, refer to the Win32.Winreg |
| package provided with the Win32Ada binding |
| |
| @node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id100}@anchor{39b} |
| @section @code{GNAT.Regpat} (@code{g-regpat.ads}) |
| |
| |
| @geindex GNAT.Regpat (g-regpat.ads) |
| |
| @geindex Regular expressions |
| |
| @geindex Pattern matching |
| |
| A complete implementation of Unix-style regular expression matching, copied |
| from the original V7 style regular expression library written in C by |
| Henry Spencer (and binary compatible with this C library). |
| |
| @node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id101}@anchor{39d} |
| @section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) |
| |
| |
| @geindex GNAT.Rewrite_Data (g-rewdat.ads) |
| |
| @geindex Rewrite data |
| |
| A unit to rewrite on-the-fly string occurrences in a stream of |
| data. The implementation has a very minimal memory footprint as the |
| full content to be processed is not loaded into memory all at once. This makes |
| this interface usable for large files or socket streams. |
| |
| @node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id102}@anchor{39f} |
| @section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) |
| |
| |
| @geindex GNAT.Secondary_Stack_Info (g-sestin.ads) |
| |
| @geindex Secondary Stack Info |
| |
| Provide the capability to query the high water mark of the current task’s |
| secondary stack. |
| |
| @node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id103}@anchor{3a1} |
| @section @code{GNAT.Semaphores} (@code{g-semaph.ads}) |
| |
| |
| @geindex GNAT.Semaphores (g-semaph.ads) |
| |
| @geindex Semaphores |
| |
| Provides classic counting and binary semaphores using protected types. |
| |
| @node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a3} |
| @section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) |
| |
| |
| @geindex GNAT.Serial_Communications (g-sercom.ads) |
| |
| @geindex Serial_Communications |
| |
| Provides a simple interface to send and receive data over a serial |
| port. This is only supported on GNU/Linux and Windows. |
| |
| @node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a5} |
| @section @code{GNAT.SHA1} (@code{g-sha1.ads}) |
| |
| |
| @geindex GNAT.SHA1 (g-sha1.ads) |
| |
| @geindex Secure Hash Algorithm SHA-1 |
| |
| Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 |
| and RFC 3174, and the HMAC-SHA1 message authentication function as described |
| in RFC 2104 and FIPS PUB 198. |
| |
| @node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a7} |
| @section @code{GNAT.SHA224} (@code{g-sha224.ads}) |
| |
| |
| @geindex GNAT.SHA224 (g-sha224.ads) |
| |
| @geindex Secure Hash Algorithm SHA-224 |
| |
| Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, |
| and the HMAC-SHA224 message authentication function as described |
| in RFC 2104 and FIPS PUB 198. |
| |
| @node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a9} |
| @section @code{GNAT.SHA256} (@code{g-sha256.ads}) |
| |
| |
| @geindex GNAT.SHA256 (g-sha256.ads) |
| |
| @geindex Secure Hash Algorithm SHA-256 |
| |
| Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, |
| and the HMAC-SHA256 message authentication function as described |
| in RFC 2104 and FIPS PUB 198. |
| |
| @node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id108}@anchor{3ab} |
| @section @code{GNAT.SHA384} (@code{g-sha384.ads}) |
| |
| |
| @geindex GNAT.SHA384 (g-sha384.ads) |
| |
| @geindex Secure Hash Algorithm SHA-384 |
| |
| Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, |
| and the HMAC-SHA384 message authentication function as described |
| in RFC 2104 and FIPS PUB 198. |
| |
| @node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id109}@anchor{3ad} |
| @section @code{GNAT.SHA512} (@code{g-sha512.ads}) |
| |
| |
| @geindex GNAT.SHA512 (g-sha512.ads) |
| |
| @geindex Secure Hash Algorithm SHA-512 |
| |
| Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, |
| and the HMAC-SHA512 message authentication function as described |
| in RFC 2104 and FIPS PUB 198. |
| |
| @node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id110}@anchor{3af} |
| @section @code{GNAT.Signals} (@code{g-signal.ads}) |
| |
| |
| @geindex GNAT.Signals (g-signal.ads) |
| |
| @geindex Signals |
| |
| Provides the ability to manipulate the blocked status of signals on supported |
| targets. |
| |
| @node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b1} |
| @section @code{GNAT.Sockets} (@code{g-socket.ads}) |
| |
| |
| @geindex GNAT.Sockets (g-socket.ads) |
| |
| @geindex Sockets |
| |
| A high level and portable interface to develop sockets based applications. |
| This package is based on the sockets thin binding found in |
| @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented |
| on all native GNAT ports and on VxWorks cross prots. It is not implemented for |
| the LynxOS cross port. |
| |
| @node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b3} |
| @section @code{GNAT.Source_Info} (@code{g-souinf.ads}) |
| |
| |
| @geindex GNAT.Source_Info (g-souinf.ads) |
| |
| @geindex Source Information |
| |
| Provides subprograms that give access to source code information known at |
| compile time, such as the current file name and line number. Also provides |
| subprograms yielding the date and time of the current compilation (like the |
| C macros @code{__DATE__} and @code{__TIME__}) |
| |
| @node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b5} |
| @section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) |
| |
| |
| @geindex GNAT.Spelling_Checker (g-speche.ads) |
| |
| @geindex Spell checking |
| |
| Provides a function for determining whether one string is a plausible |
| near misspelling of another string. |
| |
| @node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b7} |
| @section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) |
| |
| |
| @geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) |
| |
| @geindex Spell checking |
| |
| Provides a generic function that can be instantiated with a string type for |
| determining whether one string is a plausible near misspelling of another |
| string. |
| |
| @node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b9} |
| @section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) |
| |
| |
| @geindex GNAT.Spitbol.Patterns (g-spipat.ads) |
| |
| @geindex SPITBOL pattern matching |
| |
| @geindex Pattern matching |
| |
| A complete implementation of SNOBOL4 style pattern matching. This is the |
| most elaborate of the pattern matching packages provided. It fully duplicates |
| the SNOBOL4 dynamic pattern construction and matching capabilities, using the |
| efficient algorithm developed by Robert Dewar for the SPITBOL system. |
| |
| @node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id116}@anchor{3bb} |
| @section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) |
| |
| |
| @geindex GNAT.Spitbol (g-spitbo.ads) |
| |
| @geindex SPITBOL interface |
| |
| The top level package of the collection of SPITBOL-style functionality, this |
| package provides basic SNOBOL4 string manipulation functions, such as |
| Pad, Reverse, Trim, Substr capability, as well as a generic table function |
| useful for constructing arbitrary mappings from strings in the style of |
| the SNOBOL4 TABLE function. |
| |
| @node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3bc}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bd} |
| @section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) |
| |
| |
| @geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) |
| |
| @geindex Sets of strings |
| |
| @geindex SPITBOL Tables |
| |
| A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} |
| for type @code{Standard.Boolean}, giving an implementation of sets of |
| string values. |
| |
| @node GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol Table_VString g-sptavs ads,GNAT Spitbol Table_Boolean g-sptabo ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id118}@anchor{3bf} |
| @section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) |
| |
| |
| @geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) |
| |
| @geindex Integer maps |
| |
| @geindex Maps |
| |
| @geindex SPITBOL Tables |
| |
| A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} |
| for type @code{Standard.Integer}, giving an implementation of maps |
| from string to integer values. |
| |
| @node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id119}@anchor{3c1} |
| @section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) |
| |
| |
| @geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) |
| |
| @geindex String maps |
| |
| @geindex Maps |
| |
| @geindex SPITBOL Tables |
| |
| A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for |
| a variable length string type, giving an implementation of general |
| maps from strings to strings. |
| |
| @node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c3} |
| @section @code{GNAT.SSE} (@code{g-sse.ads}) |
| |
| |
| @geindex GNAT.SSE (g-sse.ads) |
| |
| Root of a set of units aimed at offering Ada bindings to a subset of |
| the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of |
| targets. It exposes vector component types together with a general |
| introduction to the binding contents and use. |
| |
| @node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c5} |
| @section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) |
| |
| |
| @geindex GNAT.SSE.Vector_Types (g-ssvety.ads) |
| |
| SSE vector types for use with SSE related intrinsics. |
| |
| @node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c7} |
| @section @code{GNAT.String_Hash} (@code{g-strhas.ads}) |
| |
| |
| @geindex GNAT.String_Hash (g-strhas.ads) |
| |
| @geindex Hash functions |
| |
| Provides a generic hash function working on arrays of scalars. Both the scalar |
| type and the hash result type are parameters. |
| |
| @node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c9} |
| @section @code{GNAT.Strings} (@code{g-string.ads}) |
| |
| |
| @geindex GNAT.Strings (g-string.ads) |
| |
| Common String access types and related subprograms. Basically it |
| defines a string access and an array of string access types. |
| |
| @node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id124}@anchor{3cb} |
| @section @code{GNAT.String_Split} (@code{g-strspl.ads}) |
| |
| |
| @geindex GNAT.String_Split (g-strspl.ads) |
| |
| @geindex String splitter |
| |
| Useful string manipulation routines: given a set of separators, split |
| a string wherever the separators appear, and provide direct access |
| to the resulting slices. This package is instantiated from |
| @code{GNAT.Array_Split}. |
| |
| @node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id125}@anchor{3cd} |
| @section @code{GNAT.Table} (@code{g-table.ads}) |
| |
| |
| @geindex GNAT.Table (g-table.ads) |
| |
| @geindex Table implementation |
| |
| @geindex Arrays |
| @geindex extendable |
| |
| A generic package providing a single dimension array abstraction where the |
| length of the array can be dynamically modified. |
| |
| This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, |
| except that this package declares a single instance of the table type, |
| while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be |
| used to define dynamic instances of the table. |
| |
| @node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id126}@anchor{3cf} |
| @section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) |
| |
| |
| @geindex GNAT.Task_Lock (g-tasloc.ads) |
| |
| @geindex Task synchronization |
| |
| @geindex Task locking |
| |
| @geindex Locking |
| |
| A very simple facility for locking and unlocking sections of code using a |
| single global task lock. Appropriate for use in situations where contention |
| between tasks is very rarely expected. |
| |
| @node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id127}@anchor{3d1} |
| @section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) |
| |
| |
| @geindex GNAT.Time_Stamp (g-timsta.ads) |
| |
| @geindex Time stamp |
| |
| @geindex Current time |
| |
| Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that |
| represents the current date and time in ISO 8601 format. This is a very simple |
| routine with minimal code and there are no dependencies on any other unit. |
| |
| @node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d3} |
| @section @code{GNAT.Threads} (@code{g-thread.ads}) |
| |
| |
| @geindex GNAT.Threads (g-thread.ads) |
| |
| @geindex Foreign threads |
| |
| @geindex Threads |
| @geindex foreign |
| |
| Provides facilities for dealing with foreign threads which need to be known |
| by the GNAT run-time system. Consult the documentation of this package for |
| further details if your program has threads that are created by a non-Ada |
| environment which then accesses Ada code. |
| |
| @node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3d4}@anchor{gnat_rm/the_gnat_library id129}@anchor{3d5} |
| @section @code{GNAT.Traceback} (@code{g-traceb.ads}) |
| |
| |
| @geindex GNAT.Traceback (g-traceb.ads) |
| |
| @geindex Trace back facilities |
| |
| Provides a facility for obtaining non-symbolic traceback information, useful |
| in various debugging situations. |
| |
| @node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3d6}@anchor{gnat_rm/the_gnat_library id130}@anchor{3d7} |
| @section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) |
| |
| |
| @geindex GNAT.Traceback.Symbolic (g-trasym.ads) |
| |
| @geindex Trace back facilities |
| |
| @node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3d8}@anchor{gnat_rm/the_gnat_library id131}@anchor{3d9} |
| @section @code{GNAT.UTF_32} (@code{g-table.ads}) |
| |
| |
| @geindex GNAT.UTF_32 (g-table.ads) |
| |
| @geindex Wide character codes |
| |
| This is a package intended to be used in conjunction with the |
| @code{Wide_Character} type in Ada 95 and the |
| @code{Wide_Wide_Character} type in Ada 2005 (available |
| in @code{GNAT} in Ada 2005 mode). This package contains |
| Unicode categorization routines, as well as lexical |
| categorization routines corresponding to the Ada 2005 |
| lexical rules for identifiers and strings, and also a |
| lower case to upper case fold routine corresponding to |
| the Ada 2005 rules for identifier equivalence. |
| |
| @node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3da}@anchor{gnat_rm/the_gnat_library id132}@anchor{3db} |
| @section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) |
| |
| |
| @geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) |
| |
| @geindex Spell checking |
| |
| Provides a function for determining whether one wide wide string is a plausible |
| near misspelling of another wide wide string, where the strings are represented |
| using the UTF_32_String type defined in System.Wch_Cnv. |
| |
| @node GNAT Wide_Spelling_Checker g-wispch ads,GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Spelling_Checker g-u3spch ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3dc}@anchor{gnat_rm/the_gnat_library id133}@anchor{3dd} |
| @section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) |
| |
| |
| @geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) |
| |
| @geindex Spell checking |
| |
| Provides a function for determining whether one wide string is a plausible |
| near misspelling of another wide string. |
| |
| @node GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Spelling_Checker g-wispch ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3de}@anchor{gnat_rm/the_gnat_library id134}@anchor{3df} |
| @section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) |
| |
| |
| @geindex GNAT.Wide_String_Split (g-wistsp.ads) |
| |
| @geindex Wide_String splitter |
| |
| Useful wide string manipulation routines: given a set of separators, split |
| a wide string wherever the separators appear, and provide direct access |
| to the resulting slices. This package is instantiated from |
| @code{GNAT.Array_Split}. |
| |
| @node GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Wide_String_Split g-zistsp ads,GNAT Wide_String_Split g-wistsp ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3e0}@anchor{gnat_rm/the_gnat_library id135}@anchor{3e1} |
| @section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) |
| |
| |
| @geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) |
| |
| @geindex Spell checking |
| |
| Provides a function for determining whether one wide wide string is a plausible |
| near misspelling of another wide wide string. |
| |
| @node GNAT Wide_Wide_String_Split g-zistsp ads,Interfaces C Extensions i-cexten ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3e2}@anchor{gnat_rm/the_gnat_library id136}@anchor{3e3} |
| @section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) |
| |
| |
| @geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) |
| |
| @geindex Wide_Wide_String splitter |
| |
| Useful wide wide string manipulation routines: given a set of separators, split |
| a wide wide string wherever the separators appear, and provide direct access |
| to the resulting slices. This package is instantiated from |
| @code{GNAT.Array_Split}. |
| |
| @node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id137}@anchor{3e4}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3e5} |
| @section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) |
| |
| |
| @geindex Interfaces.C.Extensions (i-cexten.ads) |
| |
| This package contains additional C-related definitions, intended |
| for use with either manually or automatically generated bindings |
| to C libraries. |
| |
| @node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id138}@anchor{3e6}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e7} |
| @section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) |
| |
| |
| @geindex Interfaces.C.Streams (i-cstrea.ads) |
| |
| @geindex C streams |
| @geindex interfacing |
| |
| This package is a binding for the most commonly used operations |
| on C streams. |
| |
| @node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id139}@anchor{3e8}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e9} |
| @section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) |
| |
| |
| @geindex Interfaces.Packed_Decimal (i-pacdec.ads) |
| |
| @geindex IBM Packed Format |
| |
| @geindex Packed Decimal |
| |
| This package provides a set of routines for conversions to and |
| from a packed decimal format compatible with that used on IBM |
| mainframes. |
| |
| @node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id140}@anchor{3ea}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3eb} |
| @section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) |
| |
| |
| @geindex Interfaces.VxWorks (i-vxwork.ads) |
| |
| @geindex Interfacing to VxWorks |
| |
| @geindex VxWorks |
| @geindex interfacing |
| |
| This package provides a limited binding to the VxWorks API. |
| In particular, it interfaces with the |
| VxWorks hardware interrupt facilities. |
| |
| @node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id141}@anchor{3ec}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3ed} |
| @section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) |
| |
| |
| @geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) |
| |
| @geindex Interfacing to VxWorks |
| |
| @geindex VxWorks |
| @geindex interfacing |
| |
| This package provides a way for users to replace the use of |
| intConnect() with a custom routine for installing interrupt |
| handlers. |
| |
| @node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id142}@anchor{3ee}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3ef} |
| @section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) |
| |
| |
| @geindex Interfaces.VxWorks.IO (i-vxwoio.ads) |
| |
| @geindex Interfacing to VxWorks' I/O |
| |
| @geindex VxWorks |
| @geindex I/O interfacing |
| |
| @geindex VxWorks |
| @geindex Get_Immediate |
| |
| @geindex Get_Immediate |
| @geindex VxWorks |
| |
| This package provides a binding to the ioctl (IO/Control) |
| function of VxWorks, defining a set of option values and |
| function codes. A particular use of this package is |
| to enable the use of Get_Immediate under VxWorks. |
| |
| @node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id143}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3f1} |
| @section @code{System.Address_Image} (@code{s-addima.ads}) |
| |
| |
| @geindex System.Address_Image (s-addima.ads) |
| |
| @geindex Address image |
| |
| @geindex Image |
| @geindex of an address |
| |
| This function provides a useful debugging |
| function that gives an (implementation dependent) |
| string which identifies an address. |
| |
| @node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id144}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3f3} |
| @section @code{System.Assertions} (@code{s-assert.ads}) |
| |
| |
| @geindex System.Assertions (s-assert.ads) |
| |
| @geindex Assertions |
| |
| @geindex Assert_Failure |
| @geindex exception |
| |
| This package provides the declaration of the exception raised |
| by an run-time assertion failure, as well as the routine that |
| is used internally to raise this assertion. |
| |
| @node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id145}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3f5} |
| @section @code{System.Atomic_Counters} (@code{s-atocou.ads}) |
| |
| |
| @geindex System.Atomic_Counters (s-atocou.ads) |
| |
| This package provides the declaration of an atomic counter type, |
| together with efficient routines (using hardware |
| synchronization primitives) for incrementing, decrementing, |
| and testing of these counters. This package is implemented |
| on most targets, including all Alpha, ia64, PowerPC, SPARC V9, |
| x86, and x86_64 platforms. |
| |
| @node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id146}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f7} |
| @section @code{System.Memory} (@code{s-memory.ads}) |
| |
| |
| @geindex System.Memory (s-memory.ads) |
| |
| @geindex Memory allocation |
| |
| This package provides the interface to the low level routines used |
| by the generated code for allocation and freeing storage for the |
| default storage pool (analogous to the C routines malloc and free. |
| It also provides a reallocation interface analogous to the C routine |
| realloc. The body of this unit may be modified to provide alternative |
| allocation mechanisms for the default pool, and in addition, direct |
| calls to this unit may be made for low level allocation uses (for |
| example see the body of @code{GNAT.Tables}). |
| |
| @node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id147}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f9} |
| @section @code{System.Multiprocessors} (@code{s-multip.ads}) |
| |
| |
| @geindex System.Multiprocessors (s-multip.ads) |
| |
| @geindex Multiprocessor interface |
| |
| This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but |
| in GNAT we also make it available in Ada 95 and Ada 2005 (where it is |
| technically an implementation-defined addition). |
| |
| @node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id148}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3fb} |
| @section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) |
| |
| |
| @geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) |
| |
| @geindex Multiprocessor interface |
| |
| This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but |
| in GNAT we also make it available in Ada 95 and Ada 2005 (where it is |
| technically an implementation-defined addition). |
| |
| @node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id149}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3fd} |
| @section @code{System.Partition_Interface} (@code{s-parint.ads}) |
| |
| |
| @geindex System.Partition_Interface (s-parint.ads) |
| |
| @geindex Partition interfacing functions |
| |
| This package provides facilities for partition interfacing. It |
| is used primarily in a distribution context when using Annex E |
| with @code{GLADE}. |
| |
| @node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id150}@anchor{3fe}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3ff} |
| @section @code{System.Pool_Global} (@code{s-pooglo.ads}) |
| |
| |
| @geindex System.Pool_Global (s-pooglo.ads) |
| |
| @geindex Storage pool |
| @geindex global |
| |
| @geindex Global storage pool |
| |
| This package provides a storage pool that is equivalent to the default |
| storage pool used for access types for which no pool is specifically |
| declared. It uses malloc/free to allocate/free and does not attempt to |
| do any automatic reclamation. |
| |
| @node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id151}@anchor{400}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{401} |
| @section @code{System.Pool_Local} (@code{s-pooloc.ads}) |
| |
| |
| @geindex System.Pool_Local (s-pooloc.ads) |
| |
| @geindex Storage pool |
| @geindex local |
| |
| @geindex Local storage pool |
| |
| This package provides a storage pool that is intended for use with locally |
| defined access types. It uses malloc/free for allocate/free, and maintains |
| a list of allocated blocks, so that all storage allocated for the pool can |
| be freed automatically when the pool is finalized. |
| |
| @node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id152}@anchor{402}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{403} |
| @section @code{System.Restrictions} (@code{s-restri.ads}) |
| |
| |
| @geindex System.Restrictions (s-restri.ads) |
| |
| @geindex Run-time restrictions access |
| |
| This package provides facilities for accessing at run time |
| the status of restrictions specified at compile time for |
| the partition. Information is available both with regard |
| to actual restrictions specified, and with regard to |
| compiler determined information on which restrictions |
| are violated by one or more packages in the partition. |
| |
| @node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id153}@anchor{404}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{405} |
| @section @code{System.Rident} (@code{s-rident.ads}) |
| |
| |
| @geindex System.Rident (s-rident.ads) |
| |
| @geindex Restrictions definitions |
| |
| This package provides definitions of the restrictions |
| identifiers supported by GNAT, and also the format of |
| the restrictions provided in package System.Restrictions. |
| It is not normally necessary to @code{with} this generic package |
| since the necessary instantiation is included in |
| package System.Restrictions. |
| |
| @node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id154}@anchor{406}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{407} |
| @section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) |
| |
| |
| @geindex System.Strings.Stream_Ops (s-ststop.ads) |
| |
| @geindex Stream operations |
| |
| @geindex String stream operations |
| |
| This package provides a set of stream subprograms for standard string types. |
| It is intended primarily to support implicit use of such subprograms when |
| stream attributes are applied to string types, but the subprograms in this |
| package can be used directly by application programs. |
| |
| @node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id155}@anchor{408}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{409} |
| @section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) |
| |
| |
| @geindex System.Unsigned_Types (s-unstyp.ads) |
| |
| This package contains definitions of standard unsigned types that |
| correspond in size to the standard signed types declared in Standard, |
| and (unlike the types in Interfaces) have corresponding names. It |
| also contains some related definitions for other specialized types |
| used by the compiler in connection with packed array types. |
| |
| @node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id156}@anchor{40a}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{40b} |
| @section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) |
| |
| |
| @geindex System.Wch_Cnv (s-wchcnv.ads) |
| |
| @geindex Wide Character |
| @geindex Representation |
| |
| @geindex Wide String |
| @geindex Conversion |
| |
| @geindex Representation of wide characters |
| |
| This package provides routines for converting between |
| wide and wide wide characters and a representation as a value of type |
| @code{Standard.String}, using a specified wide character |
| encoding method. It uses definitions in |
| package @code{System.Wch_Con}. |
| |
| @node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library |
| @anchor{gnat_rm/the_gnat_library id157}@anchor{40c}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{40d} |
| @section @code{System.Wch_Con} (@code{s-wchcon.ads}) |
| |
| |
| @geindex System.Wch_Con (s-wchcon.ads) |
| |
| This package provides definitions and descriptions of |
| the various methods used for encoding wide characters |
| in ordinary strings. These definitions are used by |
| the package @code{System.Wch_Cnv}. |
| |
| @node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top |
| @anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{40e}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{40f}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11} |
| @chapter Interfacing to Other Languages |
| |
| |
| The facilities in Annex B of the Ada Reference Manual are fully |
| implemented in GNAT, and in addition, a full interface to C++ is |
| provided. |
| |
| @menu |
| * Interfacing to C:: |
| * Interfacing to C++:: |
| * Interfacing to COBOL:: |
| * Interfacing to Fortran:: |
| * Interfacing to non-GNAT Ada code:: |
| |
| @end menu |
| |
| @node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages |
| @anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{410}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{411} |
| @section Interfacing to C |
| |
| |
| Interfacing to C with GNAT can use one of two approaches: |
| |
| |
| @itemize * |
| |
| @item |
| The types in the package @code{Interfaces.C} may be used. |
| |
| @item |
| Standard Ada types may be used directly. This may be less portable to |
| other compilers, but will work on all GNAT compilers, which guarantee |
| correspondence between the C and Ada types. |
| @end itemize |
| |
| Pragma @code{Convention C} may be applied to Ada types, but mostly has no |
| effect, since this is the default. The following table shows the |
| correspondence between Ada scalar types and the corresponding C types. |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| Ada Type |
| |
| @tab |
| |
| C Type |
| |
| @item |
| |
| @code{Integer} |
| |
| @tab |
| |
| @code{int} |
| |
| @item |
| |
| @code{Short_Integer} |
| |
| @tab |
| |
| @code{short} |
| |
| @item |
| |
| @code{Short_Short_Integer} |
| |
| @tab |
| |
| @code{signed char} |
| |
| @item |
| |
| @code{Long_Integer} |
| |
| @tab |
| |
| @code{long} |
| |
| @item |
| |
| @code{Long_Long_Integer} |
| |
| @tab |
| |
| @code{long long} |
| |
| @item |
| |
| @code{Short_Float} |
| |
| @tab |
| |
| @code{float} |
| |
| @item |
| |
| @code{Float} |
| |
| @tab |
| |
| @code{float} |
| |
| @item |
| |
| @code{Long_Float} |
| |
| @tab |
| |
| @code{double} |
| |
| @item |
| |
| @code{Long_Long_Float} |
| |
| @tab |
| |
| This is the longest floating-point type supported by the hardware. |
| |
| @end multitable |
| |
| |
| Additionally, there are the following general correspondences between Ada |
| and C types: |
| |
| |
| @itemize * |
| |
| @item |
| Ada enumeration types map to C enumeration types directly if pragma |
| @code{Convention C} is specified, which causes them to have a length of |
| 32 bits, except for boolean types which map to C99 @code{bool} and for |
| which the length is 8 bits. |
| Without pragma @code{Convention C}, Ada enumeration types map to |
| 8, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, |
| @code{int}, respectively) depending on the number of values passed. |
| This is the only case in which pragma @code{Convention C} affects the |
| representation of an Ada type. |
| |
| @item |
| Ada access types map to C pointers, except for the case of pointers to |
| unconstrained types in Ada, which have no direct C equivalent. |
| |
| @item |
| Ada arrays map directly to C arrays. |
| |
| @item |
| Ada records map directly to C structures. |
| |
| @item |
| Packed Ada records map to C structures where all members are bit fields |
| of the length corresponding to the @code{type'Size} value in Ada. |
| @end itemize |
| |
| @node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages |
| @anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{48}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{412} |
| @section Interfacing to C++ |
| |
| |
| The interface to C++ makes use of the following pragmas, which are |
| primarily intended to be constructed automatically using a binding generator |
| tool, although it is possible to construct them by hand. |
| |
| Using these pragmas it is possible to achieve complete |
| inter-operability between Ada tagged types and C++ class definitions. |
| See @ref{7,,Implementation Defined Pragmas}, for more details. |
| |
| |
| @table @asis |
| |
| @item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})} |
| |
| The argument denotes an entity in the current declarative region that is |
| declared as a tagged or untagged record type. It indicates that the type |
| corresponds to an externally declared C++ class type, and is to be laid |
| out the same way that C++ would lay out the type. |
| |
| Note: Pragma @code{CPP_Class} is currently obsolete. It is supported |
| for backward compatibility but its functionality is available |
| using pragma @code{Import} with @code{Convention} = @code{CPP}. |
| |
| @item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})} |
| |
| This pragma identifies an imported function (imported in the usual way |
| with pragma @code{Import}) as corresponding to a C++ constructor. |
| @end table |
| |
| A few restrictions are placed on the use of the @code{Access} attribute |
| in conjunction with subprograms subject to convention @code{CPP}: the |
| attribute may be used neither on primitive operations of a tagged |
| record type with convention @code{CPP}, imported or not, nor on |
| subprograms imported with pragma @code{CPP_Constructor}. |
| |
| In addition, C++ exceptions are propagated and can be handled in an |
| @code{others} choice of an exception handler. The corresponding Ada |
| occurrence has no message, and the simple name of the exception identity |
| contains @code{Foreign_Exception}. Finalization and awaiting dependent |
| tasks works properly when such foreign exceptions are propagated. |
| |
| It is also possible to import a C++ exception using the following syntax: |
| |
| @example |
| LOCAL_NAME : exception; |
| pragma Import (Cpp, |
| [Entity =>] LOCAL_NAME, |
| [External_Name =>] static_string_EXPRESSION); |
| @end example |
| |
| The @code{External_Name} is the name of the C++ RTTI symbol. You can then |
| cover a specific C++ exception in an exception handler. |
| |
| @node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages |
| @anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{413}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{414} |
| @section Interfacing to COBOL |
| |
| |
| Interfacing to COBOL is achieved as described in section B.4 of |
| the Ada Reference Manual. |
| |
| @node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages |
| @anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{415}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{416} |
| @section Interfacing to Fortran |
| |
| |
| Interfacing to Fortran is achieved as described in section B.5 of the |
| Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a |
| multi-dimensional array causes the array to be stored in column-major |
| order as required for convenient interface to Fortran. |
| |
| @node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages |
| @anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{417}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{418} |
| @section Interfacing to non-GNAT Ada code |
| |
| |
| It is possible to specify the convention @code{Ada} in a pragma |
| @code{Import} or pragma @code{Export}. However this refers to |
| the calling conventions used by GNAT, which may or may not be |
| similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 |
| compiler to allow interoperation. |
| |
| If arguments types are kept simple, and if the foreign compiler generally |
| follows system calling conventions, then it may be possible to integrate |
| files compiled by other Ada compilers, provided that the elaboration |
| issues are adequately addressed (for example by eliminating the |
| need for any load time elaboration). |
| |
| In particular, GNAT running on VMS is designed to |
| be highly compatible with the DEC Ada 83 compiler, so this is one |
| case in which it is possible to import foreign units of this type, |
| provided that the data items passed are restricted to simple scalar |
| values or simple record types without variants, or simple array |
| types with fixed bounds. |
| |
| @node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top |
| @anchor{gnat_rm/specialized_needs_annexes doc}@anchor{419}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{41a}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12} |
| @chapter Specialized Needs Annexes |
| |
| |
| Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not |
| required in all implementations. However, as described in this chapter, |
| GNAT implements all of these annexes: |
| |
| |
| @table @asis |
| |
| @item @emph{Systems Programming (Annex C)} |
| |
| The Systems Programming Annex is fully implemented. |
| |
| @item @emph{Real-Time Systems (Annex D)} |
| |
| The Real-Time Systems Annex is fully implemented. |
| |
| @item @emph{Distributed Systems (Annex E)} |
| |
| Stub generation is fully implemented in the GNAT compiler. In addition, |
| a complete compatible PCS is available as part of the GLADE system, |
| a separate product. When the two |
| products are used in conjunction, this annex is fully implemented. |
| |
| @item @emph{Information Systems (Annex F)} |
| |
| The Information Systems annex is fully implemented. |
| |
| @item @emph{Numerics (Annex G)} |
| |
| The Numerics Annex is fully implemented. |
| |
| @item @emph{Safety and Security / High-Integrity Systems (Annex H)} |
| |
| The Safety and Security Annex (termed the High-Integrity Systems Annex |
| in Ada 2005) is fully implemented. |
| @end table |
| |
| @node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top |
| @anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{41c}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13} |
| @chapter Implementation of Specific Ada Features |
| |
| |
| This chapter describes the GNAT implementation of several Ada language |
| facilities. |
| |
| @menu |
| * Machine Code Insertions:: |
| * GNAT Implementation of Tasking:: |
| * GNAT Implementation of Shared Passive Packages:: |
| * Code Generation for Array Aggregates:: |
| * The Size of Discriminated Records with Default Discriminants:: |
| * Image Values For Nonscalar Types:: |
| * Strict Conformance to the Ada Reference Manual:: |
| |
| @end menu |
| |
| @node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features |
| @anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{167} |
| @section Machine Code Insertions |
| |
| |
| @geindex Machine Code insertions |
| |
| Package @code{Machine_Code} provides machine code support as described |
| in the Ada Reference Manual in two separate forms: |
| |
| |
| @itemize * |
| |
| @item |
| Machine code statements, consisting of qualified expressions that |
| fit the requirements of RM section 13.8. |
| |
| @item |
| An intrinsic callable procedure, providing an alternative mechanism of |
| including machine instructions in a subprogram. |
| @end itemize |
| |
| The two features are similar, and both are closely related to the mechanism |
| provided by the asm instruction in the GNU C compiler. Full understanding |
| and use of the facilities in this package requires understanding the asm |
| instruction, see the section on Extended Asm in |
| @cite{Using_the_GNU_Compiler_Collection_(GCC)}. |
| |
| Calls to the function @code{Asm} and the procedure @code{Asm} have identical |
| semantic restrictions and effects as described below. Both are provided so |
| that the procedure call can be used as a statement, and the function call |
| can be used to form a code_statement. |
| |
| Consider this C @code{asm} instruction: |
| |
| @example |
| asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); |
| @end example |
| |
| The equivalent can be written for GNAT as: |
| |
| @example |
| Asm ("fsinx %1 %0", |
| My_Float'Asm_Output ("=f", result), |
| My_Float'Asm_Input ("f", angle)); |
| @end example |
| |
| The first argument to @code{Asm} is the assembler template, and is |
| identical to what is used in GNU C. This string must be a static |
| expression. The second argument is the output operand list. It is |
| either a single @code{Asm_Output} attribute reference, or a list of such |
| references enclosed in parentheses (technically an array aggregate of |
| such references). |
| |
| The @code{Asm_Output} attribute denotes a function that takes two |
| parameters. The first is a string, the second is the name of a variable |
| of the type designated by the attribute prefix. The first (string) |
| argument is required to be a static expression and designates the |
| constraint (see the section on Constraints in |
| @cite{Using_the_GNU_Compiler_Collection_(GCC)}) |
| for the parameter; e.g., what kind of register is required. The second |
| argument is the variable to be written or updated with the |
| result. The possible values for constraint are the same as those used in |
| the RTL, and are dependent on the configuration file used to build the |
| GCC back end. If there are no output operands, then this argument may |
| either be omitted, or explicitly given as @code{No_Output_Operands}. |
| No support is provided for GNU C’s symbolic names for output parameters. |
| |
| The second argument of @code{my_float'Asm_Output} functions as |
| though it were an @code{out} parameter, which is a little curious, but |
| all names have the form of expressions, so there is no syntactic |
| irregularity, even though normally functions would not be permitted |
| @code{out} parameters. The third argument is the list of input |
| operands. It is either a single @code{Asm_Input} attribute reference, or |
| a list of such references enclosed in parentheses (technically an array |
| aggregate of such references). |
| |
| The @code{Asm_Input} attribute denotes a function that takes two |
| parameters. The first is a string, the second is an expression of the |
| type designated by the prefix. The first (string) argument is required |
| to be a static expression, and is the constraint for the parameter, |
| (e.g., what kind of register is required). The second argument is the |
| value to be used as the input argument. The possible values for the |
| constraint are the same as those used in the RTL, and are dependent on |
| the configuration file used to built the GCC back end. |
| No support is provided for GNU C’s symbolic names for input parameters. |
| |
| If there are no input operands, this argument may either be omitted, or |
| explicitly given as @code{No_Input_Operands}. The fourth argument, not |
| present in the above example, is a list of register names, called the |
| @emph{clobber} argument. This argument, if given, must be a static string |
| expression, and is a space or comma separated list of names of registers |
| that must be considered destroyed as a result of the @code{Asm} call. If |
| this argument is the null string (the default value), then the code |
| generator assumes that no additional registers are destroyed. |
| In addition to registers, the special clobbers @code{memory} and |
| @code{cc} as described in the GNU C docs are both supported. |
| |
| The fifth argument, not present in the above example, called the |
| @emph{volatile} argument, is by default @code{False}. It can be set to |
| the literal value @code{True} to indicate to the code generator that all |
| optimizations with respect to the instruction specified should be |
| suppressed, and in particular an instruction that has outputs |
| will still be generated, even if none of the outputs are |
| used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} |
| for the full description. |
| Generally it is strongly advisable to use Volatile for any ASM statement |
| that is missing either input or output operands or to avoid unwanted |
| optimizations. A warning is generated if this advice is not followed. |
| |
| No support is provided for GNU C’s @code{asm goto} feature. |
| |
| The @code{Asm} subprograms may be used in two ways. First the procedure |
| forms can be used anywhere a procedure call would be valid, and |
| correspond to what the RM calls ‘intrinsic’ routines. Such calls can |
| be used to intersperse machine instructions with other Ada statements. |
| Second, the function forms, which return a dummy value of the limited |
| private type @code{Asm_Insn}, can be used in code statements, and indeed |
| this is the only context where such calls are allowed. Code statements |
| appear as aggregates of the form: |
| |
| @example |
| Asm_Insn'(Asm (...)); |
| Asm_Insn'(Asm_Volatile (...)); |
| @end example |
| |
| In accordance with RM rules, such code statements are allowed only |
| within subprograms whose entire body consists of such statements. It is |
| not permissible to intermix such statements with other Ada statements. |
| |
| Typically the form using intrinsic procedure calls is more convenient |
| and more flexible. The code statement form is provided to meet the RM |
| suggestion that such a facility should be made available. The following |
| is the exact syntax of the call to @code{Asm}. As usual, if named notation |
| is used, the arguments may be given in arbitrary order, following the |
| normal rules for use of positional and named arguments: |
| |
| @example |
| ASM_CALL ::= Asm ( |
| [Template =>] static_string_EXPRESSION |
| [,[Outputs =>] OUTPUT_OPERAND_LIST ] |
| [,[Inputs =>] INPUT_OPERAND_LIST ] |
| [,[Clobber =>] static_string_EXPRESSION ] |
| [,[Volatile =>] static_boolean_EXPRESSION] ) |
| |
| OUTPUT_OPERAND_LIST ::= |
| [PREFIX.]No_Output_Operands |
| | OUTPUT_OPERAND_ATTRIBUTE |
| | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) |
| |
| OUTPUT_OPERAND_ATTRIBUTE ::= |
| SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) |
| |
| INPUT_OPERAND_LIST ::= |
| [PREFIX.]No_Input_Operands |
| | INPUT_OPERAND_ATTRIBUTE |
| | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) |
| |
| INPUT_OPERAND_ATTRIBUTE ::= |
| SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) |
| @end example |
| |
| The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} |
| are declared in the package @code{Machine_Code} and must be referenced |
| according to normal visibility rules. In particular if there is no |
| @code{use} clause for this package, then appropriate package name |
| qualification is required. |
| |
| @node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features |
| @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{41e}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{41f} |
| @section GNAT Implementation of Tasking |
| |
| |
| This chapter outlines the basic GNAT approach to tasking (in particular, |
| a multi-layered library for portability) and discusses issues related |
| to compliance with the Real-Time Systems Annex. |
| |
| @menu |
| * Mapping Ada Tasks onto the Underlying Kernel Threads:: |
| * Ensuring Compliance with the Real-Time Annex:: |
| * Support for Locking Policies:: |
| |
| @end menu |
| |
| @node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking |
| @anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{420}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{421} |
| @subsection Mapping Ada Tasks onto the Underlying Kernel Threads |
| |
| |
| GNAT’s run-time support comprises two layers: |
| |
| |
| @itemize * |
| |
| @item |
| GNARL (GNAT Run-time Layer) |
| |
| @item |
| GNULL (GNAT Low-level Library) |
| @end itemize |
| |
| In GNAT, Ada’s tasking services rely on a platform and OS independent |
| layer known as GNARL. This code is responsible for implementing the |
| correct semantics of Ada’s task creation, rendezvous, protected |
| operations etc. |
| |
| GNARL decomposes Ada’s tasking semantics into simpler lower level |
| operations such as create a thread, set the priority of a thread, |
| yield, create a lock, lock/unlock, etc. The spec for these low-level |
| operations constitutes GNULLI, the GNULL Interface. This interface is |
| directly inspired from the POSIX real-time API. |
| |
| If the underlying executive or OS implements the POSIX standard |
| faithfully, the GNULL Interface maps as is to the services offered by |
| the underlying kernel. Otherwise, some target dependent glue code maps |
| the services offered by the underlying kernel to the semantics expected |
| by GNARL. |
| |
| Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the |
| key point is that each Ada task is mapped on a thread in the underlying |
| kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. |
| |
| In addition Ada task priorities map onto the underlying thread priorities. |
| Mapping Ada tasks onto the underlying kernel threads has several advantages: |
| |
| |
| @itemize * |
| |
| @item |
| The underlying scheduler is used to schedule the Ada tasks. This |
| makes Ada tasks as efficient as kernel threads from a scheduling |
| standpoint. |
| |
| @item |
| Interaction with code written in C containing threads is eased |
| since at the lowest level Ada tasks and C threads map onto the same |
| underlying kernel concept. |
| |
| @item |
| When an Ada task is blocked during I/O the remaining Ada tasks are |
| able to proceed. |
| |
| @item |
| On multiprocessor systems Ada tasks can execute in parallel. |
| @end itemize |
| |
| Some threads libraries offer a mechanism to fork a new process, with the |
| child process duplicating the threads from the parent. |
| GNAT does not |
| support this functionality when the parent contains more than one task. |
| |
| @geindex Forking a new process |
| |
| @node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking |
| @anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{422}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{423} |
| @subsection Ensuring Compliance with the Real-Time Annex |
| |
| |
| @geindex Real-Time Systems Annex compliance |
| |
| Although mapping Ada tasks onto |
| the underlying threads has significant advantages, it does create some |
| complications when it comes to respecting the scheduling semantics |
| specified in the real-time annex (Annex D). |
| |
| For instance the Annex D requirement for the @code{FIFO_Within_Priorities} |
| scheduling policy states: |
| |
| @quotation |
| |
| @emph{When the active priority of a ready task that is not running |
| changes, or the setting of its base priority takes effect, the |
| task is removed from the ready queue for its old active priority |
| and is added at the tail of the ready queue for its new active |
| priority, except in the case where the active priority is lowered |
| due to the loss of inherited priority, in which case the task is |
| added at the head of the ready queue for its new active priority.} |
| @end quotation |
| |
| While most kernels do put tasks at the end of the priority queue when |
| a task changes its priority, (which respects the main |
| FIFO_Within_Priorities requirement), almost none keep a thread at the |
| beginning of its priority queue when its priority drops from the loss |
| of inherited priority. |
| |
| As a result most vendors have provided incomplete Annex D implementations. |
| |
| The GNAT run-time, has a nice cooperative solution to this problem |
| which ensures that accurate FIFO_Within_Priorities semantics are |
| respected. |
| |
| The principle is as follows. When an Ada task T is about to start |
| running, it checks whether some other Ada task R with the same |
| priority as T has been suspended due to the loss of priority |
| inheritance. If this is the case, T yields and is placed at the end of |
| its priority queue. When R arrives at the front of the queue it |
| executes. |
| |
| Note that this simple scheme preserves the relative order of the tasks |
| that were ready to execute in the priority queue where R has been |
| placed at the end. |
| |
| @c Support_for_Locking_Policies |
| |
| @node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking |
| @anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{424} |
| @subsection Support for Locking Policies |
| |
| |
| This section specifies which policies specified by pragma Locking_Policy |
| are supported on which platforms. |
| |
| GNAT supports the standard @code{Ceiling_Locking} policy, and the |
| implementation defined @code{Inheritance_Locking} and |
| @code{Concurrent_Readers_Locking} policies. |
| |
| @code{Ceiling_Locking} is supported on all platforms if the operating system |
| supports it. In particular, @code{Ceiling_Locking} is not supported on |
| VxWorks. |
| @code{Inheritance_Locking} is supported on |
| Linux, |
| Darwin (Mac OS X), |
| LynxOS 178, |
| and VxWorks. |
| @code{Concurrent_Readers_Locking} is supported on Linux. |
| |
| Notes about @code{Ceiling_Locking} on Linux: |
| If the process is running as ‘root’, ceiling locking is used. |
| If the capabilities facility is installed |
| (“sudo apt-get –assume-yes install libcap-dev” on Ubuntu, |
| for example), |
| and the program is linked against that library |
| (“-largs -lcap”), |
| and the executable file has the cap_sys_nice capability |
| (“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”), |
| then ceiling locking is used. |
| Otherwise, the @code{Ceiling_Locking} policy is ignored. |
| |
| @node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features |
| @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{426} |
| @section GNAT Implementation of Shared Passive Packages |
| |
| |
| @geindex Shared passive packages |
| |
| GNAT fully implements the |
| @geindex pragma Shared_Passive |
| pragma |
| @code{Shared_Passive} for |
| the purpose of designating shared passive packages. |
| This allows the use of passive partitions in the |
| context described in the Ada Reference Manual; i.e., for communication |
| between separate partitions of a distributed application using the |
| features in Annex E. |
| |
| @geindex Annex E |
| |
| @geindex Distribution Systems Annex |
| |
| However, the implementation approach used by GNAT provides for more |
| extensive usage as follows: |
| |
| |
| @table @asis |
| |
| @item @emph{Communication between separate programs} |
| |
| This allows separate programs to access the data in passive |
| partitions, using protected objects for synchronization where |
| needed. The only requirement is that the two programs have a |
| common shared file system. It is even possible for programs |
| running on different machines with different architectures |
| (e.g., different endianness) to communicate via the data in |
| a passive partition. |
| |
| @item @emph{Persistence between program runs} |
| |
| The data in a passive package can persist from one run of a |
| program to another, so that a later program sees the final |
| values stored by a previous run of the same program. |
| @end table |
| |
| The implementation approach used is to store the data in files. A |
| separate stream file is created for each object in the package, and |
| an access to an object causes the corresponding file to be read or |
| written. |
| |
| @geindex SHARED_MEMORY_DIRECTORY environment variable |
| |
| The environment variable @code{SHARED_MEMORY_DIRECTORY} should be |
| set to the directory to be used for these files. |
| The files in this directory |
| have names that correspond to their fully qualified names. For |
| example, if we have the package |
| |
| @example |
| package X is |
| pragma Shared_Passive (X); |
| Y : Integer; |
| Z : Float; |
| end X; |
| @end example |
| |
| and the environment variable is set to @code{/stemp/}, then the files created |
| will have the names: |
| |
| @example |
| /stemp/x.y |
| /stemp/x.z |
| @end example |
| |
| These files are created when a value is initially written to the object, and |
| the files are retained until manually deleted. This provides the persistence |
| semantics. If no file exists, it means that no partition has assigned a value |
| to the variable; in this case the initial value declared in the package |
| will be used. This model ensures that there are no issues in synchronizing |
| the elaboration process, since elaboration of passive packages elaborates the |
| initial values, but does not create the files. |
| |
| The files are written using normal @code{Stream_IO} access. |
| If you want to be able |
| to communicate between programs or partitions running on different |
| architectures, then you should use the XDR versions of the stream attribute |
| routines, since these are architecture independent. |
| |
| If active synchronization is required for access to the variables in the |
| shared passive package, then as described in the Ada Reference Manual, the |
| package may contain protected objects used for this purpose. In this case |
| a lock file (whose name is @code{___lock} (three underscores) |
| is created in the shared memory directory. |
| |
| @geindex ___lock file (for shared passive packages) |
| |
| This is used to provide the required locking |
| semantics for proper protected object synchronization. |
| |
| @node Code Generation for Array Aggregates,The Size of Discriminated Records with Default Discriminants,GNAT Implementation of Shared Passive Packages,Implementation of Specific Ada Features |
| @anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{428} |
| @section Code Generation for Array Aggregates |
| |
| |
| Aggregates have a rich syntax and allow the user to specify the values of |
| complex data structures by means of a single construct. As a result, the |
| code generated for aggregates can be quite complex and involve loops, case |
| statements and multiple assignments. In the simplest cases, however, the |
| compiler will recognize aggregates whose components and constraints are |
| fully static, and in those cases the compiler will generate little or no |
| executable code. The following is an outline of the code that GNAT generates |
| for various aggregate constructs. For further details, you will find it |
| useful to examine the output produced by the -gnatG flag to see the expanded |
| source that is input to the code generator. You may also want to examine |
| the assembly code generated at various levels of optimization. |
| |
| The code generated for aggregates depends on the context, the component values, |
| and the type. In the context of an object declaration the code generated is |
| generally simpler than in the case of an assignment. As a general rule, static |
| component values and static subtypes also lead to simpler code. |
| |
| @menu |
| * Static constant aggregates with static bounds:: |
| * Constant aggregates with unconstrained nominal types:: |
| * Aggregates with static bounds:: |
| * Aggregates with nonstatic bounds:: |
| * Aggregates in assignment statements:: |
| |
| @end menu |
| |
| @node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates |
| @anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{429}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{42a} |
| @subsection Static constant aggregates with static bounds |
| |
| |
| For the declarations: |
| |
| @example |
| type One_Dim is array (1..10) of integer; |
| ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); |
| @end example |
| |
| GNAT generates no executable code: the constant ar0 is placed in static memory. |
| The same is true for constant aggregates with named associations: |
| |
| @example |
| Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); |
| Cr3 : constant One_Dim := (others => 7777); |
| @end example |
| |
| The same is true for multidimensional constant arrays such as: |
| |
| @example |
| type two_dim is array (1..3, 1..3) of integer; |
| Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); |
| @end example |
| |
| The same is true for arrays of one-dimensional arrays: the following are |
| static: |
| |
| @example |
| type ar1b is array (1..3) of boolean; |
| type ar_ar is array (1..3) of ar1b; |
| None : constant ar1b := (others => false); -- fully static |
| None2 : constant ar_ar := (1..3 => None); -- fully static |
| @end example |
| |
| However, for multidimensional aggregates with named associations, GNAT will |
| generate assignments and loops, even if all associations are static. The |
| following two declarations generate a loop for the first dimension, and |
| individual component assignments for the second dimension: |
| |
| @example |
| Zero1: constant two_dim := (1..3 => (1..3 => 0)); |
| Zero2: constant two_dim := (others => (others => 0)); |
| @end example |
| |
| @node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates |
| @anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{42b}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{42c} |
| @subsection Constant aggregates with unconstrained nominal types |
| |
| |
| In such cases the aggregate itself establishes the subtype, so that |
| associations with @code{others} cannot be used. GNAT determines the |
| bounds for the actual subtype of the aggregate, and allocates the |
| aggregate statically as well. No code is generated for the following: |
| |
| @example |
| type One_Unc is array (natural range <>) of integer; |
| Cr_Unc : constant One_Unc := (12,24,36); |
| @end example |
| |
| @node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates |
| @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{42d}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{42e} |
| @subsection Aggregates with static bounds |
| |
| |
| In all previous examples the aggregate was the initial (and immutable) value |
| of a constant. If the aggregate initializes a variable, then code is generated |
| for it as a combination of individual assignments and loops over the target |
| object. The declarations |
| |
| @example |
| Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); |
| Cr_Var2 : One_Dim := (others > -1); |
| @end example |
| |
| generate the equivalent of |
| |
| @example |
| Cr_Var1 (1) := 2; |
| Cr_Var1 (2) := 3; |
| Cr_Var1 (3) := 5; |
| Cr_Var1 (4) := 11; |
| |
| for I in Cr_Var2'range loop |
| Cr_Var2 (I) := -1; |
| end loop; |
| @end example |
| |
| @node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates |
| @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{42f}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{430} |
| @subsection Aggregates with nonstatic bounds |
| |
| |
| If the bounds of the aggregate are not statically compatible with the bounds |
| of the nominal subtype of the target, then constraint checks have to be |
| generated on the bounds. For a multidimensional array, constraint checks may |
| have to be applied to sub-arrays individually, if they do not have statically |
| compatible subtypes. |
| |
| @node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates |
| @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{431}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{432} |
| @subsection Aggregates in assignment statements |
| |
| |
| In general, aggregate assignment requires the construction of a temporary, |
| and a copy from the temporary to the target of the assignment. This is because |
| it is not always possible to convert the assignment into a series of individual |
| component assignments. For example, consider the simple case: |
| |
| @example |
| A := (A(2), A(1)); |
| @end example |
| |
| This cannot be converted into: |
| |
| @example |
| A(1) := A(2); |
| A(2) := A(1); |
| @end example |
| |
| So the aggregate has to be built first in a separate location, and then |
| copied into the target. GNAT recognizes simple cases where this intermediate |
| step is not required, and the assignments can be performed in place, directly |
| into the target. The following sufficient criteria are applied: |
| |
| |
| @itemize * |
| |
| @item |
| The bounds of the aggregate are static, and the associations are static. |
| |
| @item |
| The components of the aggregate are static constants, names of |
| simple variables that are not renamings, or expressions not involving |
| indexed components whose operands obey these rules. |
| @end itemize |
| |
| If any of these conditions are violated, the aggregate will be built in |
| a temporary (created either by the front-end or the code generator) and then |
| that temporary will be copied onto the target. |
| |
| @node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features |
| @anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{433}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{434} |
| @section The Size of Discriminated Records with Default Discriminants |
| |
| |
| If a discriminated type @code{T} has discriminants with default values, it is |
| possible to declare an object of this type without providing an explicit |
| constraint: |
| |
| @example |
| type Size is range 1..100; |
| |
| type Rec (D : Size := 15) is record |
| Name : String (1..D); |
| end T; |
| |
| Word : Rec; |
| @end example |
| |
| Such an object is said to be @emph{unconstrained}. |
| The discriminant of the object |
| can be modified by a full assignment to the object, as long as it preserves the |
| relation between the value of the discriminant, and the value of the components |
| that depend on it: |
| |
| @example |
| Word := (3, "yes"); |
| |
| Word := (5, "maybe"); |
| |
| Word := (5, "no"); -- raises Constraint_Error |
| @end example |
| |
| In order to support this behavior efficiently, an unconstrained object is |
| given the maximum size that any value of the type requires. In the case |
| above, @code{Word} has storage for the discriminant and for |
| a @code{String} of length 100. |
| It is important to note that unconstrained objects do not require dynamic |
| allocation. It would be an improper implementation to place on the heap those |
| components whose size depends on discriminants. (This improper implementation |
| was used by some Ada83 compilers, where the @code{Name} component above |
| would have |
| been stored as a pointer to a dynamic string). Following the principle that |
| dynamic storage management should never be introduced implicitly, |
| an Ada compiler should reserve the full size for an unconstrained declared |
| object, and place it on the stack. |
| |
| This maximum size approach |
| has been a source of surprise to some users, who expect the default |
| values of the discriminants to determine the size reserved for an |
| unconstrained object: “If the default is 15, why should the object occupy |
| a larger size?” |
| The answer, of course, is that the discriminant may be later modified, |
| and its full range of values must be taken into account. This is why the |
| declaration: |
| |
| @example |
| type Rec (D : Positive := 15) is record |
| Name : String (1..D); |
| end record; |
| |
| Too_Large : Rec; |
| @end example |
| |
| is flagged by the compiler with a warning: |
| an attempt to create @code{Too_Large} will raise @code{Storage_Error}, |
| because the required size includes @code{Positive'Last} |
| bytes. As the first example indicates, the proper approach is to declare an |
| index type of ‘reasonable’ range so that unconstrained objects are not too |
| large. |
| |
| One final wrinkle: if the object is declared to be @code{aliased}, or if it is |
| created in the heap by means of an allocator, then it is @emph{not} |
| unconstrained: |
| it is constrained by the default values of the discriminants, and those values |
| cannot be modified by full assignment. This is because in the presence of |
| aliasing all views of the object (which may be manipulated by different tasks, |
| say) must be consistent, so it is imperative that the object, once created, |
| remain invariant. |
| |
| @node Image Values For Nonscalar Types,Strict Conformance to the Ada Reference Manual,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features |
| @anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{435}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{436} |
| @section Image Values For Nonscalar Types |
| |
| |
| Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes |
| for nonscalar types; earlier Ada versions defined these attributes only |
| for scalar types. Ada RM 4.10 provides some general guidance regarding |
| the default implementation of these attributes and the GNAT compiler |
| follows that guidance. However, beyond that the precise details of the |
| image text generated in these cases are deliberately not documented and are |
| subject to change. In particular, users should not rely on formatting details |
| (such as spaces or line breaking), record field order, image values for access |
| types, image values for types that have ancestor or subcomponent types |
| declared in non-Ada2022 code, image values for predefined types, or the |
| compiler’s choices regarding the implementation permissions described in |
| Ada RM 4.10. This list is not intended to be exhaustive. If more precise |
| control of image text is required for some type T, then T’Put_Image should be |
| explicitly specified. |
| |
| @node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features |
| @anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{437}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{438} |
| @section Strict Conformance to the Ada Reference Manual |
| |
| |
| The dynamic semantics defined by the Ada Reference Manual impose a set of |
| run-time checks to be generated. By default, the GNAT compiler will insert many |
| run-time checks into the compiled code, including most of those required by the |
| Ada Reference Manual. However, there are two checks that are not enabled in |
| the default mode for efficiency reasons: checks for access before elaboration |
| on subprogram calls, and stack overflow checking (most operating systems do not |
| perform this check by default). |
| |
| Strict conformance to the Ada Reference Manual can be achieved by adding two |
| compiler options for dynamic checks for access-before-elaboration on subprogram |
| calls and generic instantiations (@emph{-gnatE}), and stack overflow checking |
| (@emph{-fstack-check}). |
| |
| Note that the result of a floating point arithmetic operation in overflow and |
| invalid situations, when the @code{Machine_Overflows} attribute of the result |
| type is @code{False}, is to generate IEEE NaN and infinite values. This is the |
| case for machines compliant with the IEEE floating-point standard, but on |
| machines that are not fully compliant with this standard, such as Alpha, the |
| @emph{-mieee} compiler flag must be used for achieving IEEE confirming |
| behavior (although at the cost of a significant performance penalty), so |
| infinite and NaN values are properly generated. |
| |
| @node Implementation of Ada 2012 Features,Security Hardening Features,Implementation of Specific Ada Features,Top |
| @anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{439}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{43a}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14} |
| @chapter Implementation of Ada 2012 Features |
| |
| |
| @geindex Ada 2012 implementation status |
| |
| @geindex -gnat12 option (gcc) |
| |
| @geindex pragma Ada_2012 |
| |
| @geindex configuration pragma Ada_2012 |
| |
| @geindex Ada_2012 configuration pragma |
| |
| This chapter contains a complete list of Ada 2012 features that have been |
| implemented. |
| Generally, these features are only |
| available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, |
| which is the default behavior, |
| or if the configuration pragma @code{Ada_2012} is used. |
| |
| However, new pragmas, attributes, and restrictions are |
| unconditionally available, since the Ada 95 standard allows the addition of |
| new pragmas, attributes, and restrictions (there are exceptions, which are |
| documented in the individual descriptions), and also certain packages |
| were made available in earlier versions of Ada. |
| |
| An ISO date (YYYY-MM-DD) appears in parentheses on the description line. |
| This date shows the implementation date of the feature. Any wavefront |
| subsequent to this date will contain the indicated feature, as will any |
| subsequent releases. A date of 0000-00-00 means that GNAT has always |
| implemented the feature, or implemented it as soon as it appeared as a |
| binding interpretation. |
| |
| Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada |
| standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. |
| The features are ordered based on the relevant sections of the Ada |
| Reference Manual (“RM”). When a given AI relates to multiple points |
| in the RM, the earliest is used. |
| |
| A complete description of the AIs may be found in |
| @indicateurl{http://www.ada-auth.org/ai05-summary.html}. |
| |
| @geindex AI-0176 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0176 Quantified expressions (2010-09-29)} |
| |
| Both universally and existentially quantified expressions are implemented. |
| They use the new syntax for iterators proposed in AI05-139-2, as well as |
| the standard Ada loop syntax. |
| |
| RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) |
| @end itemize |
| |
| @geindex AI-0079 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0079 Allow other_format characters in source (2010-07-10)} |
| |
| Wide characters in the unicode category @emph{other_format} are now allowed in |
| source programs between tokens, but not within a token such as an identifier. |
| |
| RM References: 2.01 (4/2) 2.02 (7) |
| @end itemize |
| |
| @geindex AI-0091 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} |
| |
| Wide characters in the unicode category @emph{other_format} are not permitted |
| within an identifier, since this can be a security problem. The error |
| message for this case has been improved to be more specific, but GNAT has |
| never allowed such characters to appear in identifiers. |
| |
| RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2) |
| @end itemize |
| |
| @geindex AI-0100 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0100 Placement of pragmas (2010-07-01)} |
| |
| This AI is an earlier version of AI-163. It simplifies the rules |
| for legal placement of pragmas. In the case of lists that allow pragmas, if |
| the list may have no elements, then the list may consist solely of pragmas. |
| |
| RM References: 2.08 (7) |
| @end itemize |
| |
| @geindex AI-0163 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0163 Pragmas in place of null (2010-07-01)} |
| |
| A statement sequence may be composed entirely of pragmas. It is no longer |
| necessary to add a dummy @code{null} statement to make the sequence legal. |
| |
| RM References: 2.08 (7) 2.08 (16) |
| @end itemize |
| |
| @geindex AI-0080 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0080 ‘View of’ not needed if clear from context (0000-00-00)} |
| |
| This is an editorial change only, described as non-testable in the AI. |
| |
| RM References: 3.01 (7) |
| @end itemize |
| |
| @geindex AI-0183 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0183 Aspect specifications (2010-08-16)} |
| |
| Aspect specifications have been fully implemented except for pre and post- |
| conditions, and type invariants, which have their own separate AI’s. All |
| forms of declarations listed in the AI are supported. The following is a |
| list of the aspects supported (with GNAT implementation aspects marked) |
| @end itemize |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} |
| @headitem |
| |
| Supported Aspect |
| |
| @tab |
| |
| Source |
| |
| @item |
| |
| @code{Ada_2005} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Ada_2012} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Address} |
| |
| @tab |
| |
| @item |
| |
| @code{Alignment} |
| |
| @tab |
| |
| @item |
| |
| @code{Atomic} |
| |
| @tab |
| |
| @item |
| |
| @code{Atomic_Components} |
| |
| @tab |
| |
| @item |
| |
| @code{Bit_Order} |
| |
| @tab |
| |
| @item |
| |
| @code{Component_Size} |
| |
| @tab |
| |
| @item |
| |
| @code{Contract_Cases} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Discard_Names} |
| |
| @tab |
| |
| @item |
| |
| @code{External_Tag} |
| |
| @tab |
| |
| @item |
| |
| @code{Favor_Top_Level} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Inline} |
| |
| @tab |
| |
| @item |
| |
| @code{Inline_Always} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Invariant} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Machine_Radix} |
| |
| @tab |
| |
| @item |
| |
| @code{No_Return} |
| |
| @tab |
| |
| @item |
| |
| @code{Object_Size} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Pack} |
| |
| @tab |
| |
| @item |
| |
| @code{Persistent_BSS} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Post} |
| |
| @tab |
| |
| @item |
| |
| @code{Pre} |
| |
| @tab |
| |
| @item |
| |
| @code{Predicate} |
| |
| @tab |
| |
| @item |
| |
| @code{Preelaborable_Initialization} |
| |
| @tab |
| |
| @item |
| |
| @code{Pure_Function} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Remote_Access_Type} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Shared} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Size} |
| |
| @tab |
| |
| @item |
| |
| @code{Storage_Pool} |
| |
| @tab |
| |
| @item |
| |
| @code{Storage_Size} |
| |
| @tab |
| |
| @item |
| |
| @code{Stream_Size} |
| |
| @tab |
| |
| @item |
| |
| @code{Suppress} |
| |
| @tab |
| |
| @item |
| |
| @code{Suppress_Debug_Info} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Test_Case} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Thread_Local_Storage} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Type_Invariant} |
| |
| @tab |
| |
| @item |
| |
| @code{Unchecked_Union} |
| |
| @tab |
| |
| @item |
| |
| @code{Universal_Aliasing} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Unmodified} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Unreferenced} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Unreferenced_Objects} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Unsuppress} |
| |
| @tab |
| |
| @item |
| |
| @code{Value_Size} |
| |
| @tab |
| |
| – GNAT |
| |
| @item |
| |
| @code{Volatile} |
| |
| @tab |
| |
| @item |
| |
| @code{Volatile_Components} |
| |
| @tab |
| |
| @item |
| |
| @code{Warnings} |
| |
| @tab |
| |
| – GNAT |
| |
| @end multitable |
| |
| |
| @quotation |
| |
| Note that for aspects with an expression, e.g. @code{Size}, the expression is |
| treated like a default expression (visibility is analyzed at the point of |
| occurrence of the aspect, but evaluation of the expression occurs at the |
| freeze point of the entity involved). |
| |
| RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) |
| 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 |
| (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) |
| 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) |
| 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) |
| 13.03.01 (0) |
| @end quotation |
| |
| @geindex AI-0128 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0128 Inequality is a primitive operation (0000-00-00)} |
| |
| If an equality operator (“=”) is declared for a type, then the implicitly |
| declared inequality operator (“/=”) is a primitive operation of the type. |
| This is the only reasonable interpretation, and is the one always implemented |
| by GNAT, but the RM was not entirely clear in making this point. |
| |
| RM References: 3.02.03 (6) 6.06 (6) |
| @end itemize |
| |
| @geindex AI-0003 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0003 Qualified expressions as names (2010-07-11)} |
| |
| In Ada 2012, a qualified expression is considered to be syntactically a name, |
| meaning that constructs such as @code{A'(F(X)).B} are now legal. This is |
| useful in disambiguating some cases of overloading. |
| |
| RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) |
| 5.04 (7) |
| @end itemize |
| |
| @geindex AI-0120 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0120 Constant instance of protected object (0000-00-00)} |
| |
| This is an RM editorial change only. The section that lists objects that are |
| constant failed to include the current instance of a protected object |
| within a protected function. This has always been treated as a constant |
| in GNAT. |
| |
| RM References: 3.03 (21) |
| @end itemize |
| |
| @geindex AI-0008 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0008 General access to constrained objects (0000-00-00)} |
| |
| The wording in the RM implied that if you have a general access to a |
| constrained object, it could be used to modify the discriminants. This was |
| obviously not intended. @code{Constraint_Error} should be raised, and GNAT |
| has always done so in this situation. |
| |
| RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) |
| @end itemize |
| |
| @geindex AI-0093 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0093 Additional rules use immutably limited (0000-00-00)} |
| |
| This is an editorial change only, to make more widespread use of the Ada 2012 |
| ‘immutably limited’. |
| |
| RM References: 3.03 (23.4/3) |
| @end itemize |
| |
| @geindex AI-0096 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0096 Deriving from formal private types (2010-07-20)} |
| |
| In general it is illegal for a type derived from a formal limited type to be |
| nonlimited. This AI makes an exception to this rule: derivation is legal |
| if it appears in the private part of the generic, and the formal type is not |
| tagged. If the type is tagged, the legality check must be applied to the |
| private part of the package. |
| |
| RM References: 3.04 (5.1/2) 6.02 (7) |
| @end itemize |
| |
| @geindex AI-0181 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} |
| |
| From Ada 2005 on, soft hyphen is considered a non-graphic character, which |
| means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the |
| @code{Image} and @code{Value} attributes for the character types. Strictly |
| speaking this is an inconsistency with Ada 95, but in practice the use of |
| these attributes is so obscure that it will not cause problems. |
| |
| RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) |
| @end itemize |
| |
| @geindex AI-0182 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)} |
| |
| This AI allows @code{Character'Value} to accept the string @code{'?'} where |
| @code{?} is any character including non-graphic control characters. GNAT has |
| always accepted such strings. It also allows strings such as |
| @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this |
| permission and raises @code{Constraint_Error}, as is certainly still |
| permitted. |
| |
| RM References: 3.05 (56/2) |
| @end itemize |
| |
| @geindex AI-0214 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} |
| |
| Ada 2012 relaxes the restriction that forbids discriminants of tagged types |
| to have default expressions by allowing them when the type is limited. It |
| is often useful to define a default value for a discriminant even though |
| it can’t be changed by assignment. |
| |
| RM References: 3.07 (9.1/2) 3.07.02 (3) |
| @end itemize |
| |
| @geindex AI-0102 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} |
| |
| It is illegal to assign an anonymous access constant to an anonymous access |
| variable. The RM did not have a clear rule to prevent this, but GNAT has |
| always generated an error for this usage. |
| |
| RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) |
| @end itemize |
| |
| @geindex AI-0158 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0158 Generalizing membership tests (2010-09-16)} |
| |
| This AI extends the syntax of membership tests to simplify complex conditions |
| that can be expressed as membership in a subset of values of any type. It |
| introduces syntax for a list of expressions that may be used in loop contexts |
| as well. |
| |
| RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) |
| @end itemize |
| |
| @geindex AI-0173 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} |
| |
| The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked |
| with the tag of an abstract type, and @code{False} otherwise. |
| |
| RM References: 3.09 (7.4/2) 3.09 (12.4/2) |
| @end itemize |
| |
| @geindex AI-0076 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0076 function with controlling result (0000-00-00)} |
| |
| This is an editorial change only. The RM defines calls with controlling |
| results, but uses the term ‘function with controlling result’ without an |
| explicit definition. |
| |
| RM References: 3.09.02 (2/2) |
| @end itemize |
| |
| @geindex AI-0126 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0126 Dispatching with no declared operation (0000-00-00)} |
| |
| This AI clarifies dispatching rules, and simply confirms that dispatching |
| executes the operation of the parent type when there is no explicitly or |
| implicitly declared operation for the descendant type. This has always been |
| the case in all versions of GNAT. |
| |
| RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) |
| @end itemize |
| |
| @geindex AI-0097 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0097 Treatment of abstract null extension (2010-07-19)} |
| |
| The RM as written implied that in some cases it was possible to create an |
| object of an abstract type, by having an abstract extension inherit a non- |
| abstract constructor from its parent type. This mistake has been corrected |
| in GNAT and in the RM, and this construct is now illegal. |
| |
| RM References: 3.09.03 (4/2) |
| @end itemize |
| |
| @geindex AI-0203 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0203 Extended return cannot be abstract (0000-00-00)} |
| |
| A return_subtype_indication cannot denote an abstract subtype. GNAT has never |
| permitted such usage. |
| |
| RM References: 3.09.03 (8/3) |
| @end itemize |
| |
| @geindex AI-0198 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0198 Inheriting abstract operators (0000-00-00)} |
| |
| This AI resolves a conflict between two rules involving inherited abstract |
| operations and predefined operators. If a derived numeric type inherits |
| an abstract operator, it overrides the predefined one. This interpretation |
| was always the one implemented in GNAT. |
| |
| RM References: 3.09.03 (4/3) |
| @end itemize |
| |
| @geindex AI-0073 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0073 Functions returning abstract types (2010-07-10)} |
| |
| This AI covers a number of issues regarding returning abstract types. In |
| particular generic functions cannot have abstract result types or access |
| result types designated an abstract type. There are some other cases which |
| are detailed in the AI. Note that this binding interpretation has not been |
| retrofitted to operate before Ada 2012 mode, since it caused a significant |
| number of regressions. |
| |
| RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) |
| @end itemize |
| |
| @geindex AI-0070 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0070 Elaboration of interface types (0000-00-00)} |
| |
| This is an editorial change only, there are no testable consequences short of |
| checking for the absence of generated code for an interface declaration. |
| |
| RM References: 3.09.04 (18/2) |
| @end itemize |
| |
| @geindex AI-0208 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0208 Characteristics of incomplete views (0000-00-00)} |
| |
| The wording in the Ada 2005 RM concerning characteristics of incomplete views |
| was incorrect and implied that some programs intended to be legal were now |
| illegal. GNAT had never considered such programs illegal, so it has always |
| implemented the intent of this AI. |
| |
| RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) |
| @end itemize |
| |
| @geindex AI-0162 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} |
| |
| Incomplete types are made more useful by allowing them to be completed by |
| private types and private extensions. |
| |
| RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) |
| @end itemize |
| |
| @geindex AI-0098 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} |
| |
| An unintentional omission in the RM implied some inconsistent restrictions on |
| the use of anonymous access to subprogram values. These restrictions were not |
| intentional, and have never been enforced by GNAT. |
| |
| RM References: 3.10.01 (6) 3.10.01 (9.2/2) |
| @end itemize |
| |
| @geindex AI-0199 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} |
| |
| A choice list in a record aggregate can include several components of |
| (distinct) anonymous access types as long as they have matching designated |
| subtypes. |
| |
| RM References: 4.03.01 (16) |
| @end itemize |
| |
| @geindex AI-0220 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0220 Needed components for aggregates (0000-00-00)} |
| |
| This AI addresses a wording problem in the RM that appears to permit some |
| complex cases of aggregates with nonstatic discriminants. GNAT has always |
| implemented the intended semantics. |
| |
| RM References: 4.03.01 (17) |
| @end itemize |
| |
| @geindex AI-0147 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0147 Conditional expressions (2009-03-29)} |
| |
| Conditional expressions are permitted. The form of such an expression is: |
| |
| @example |
| (if expr then expr @{elsif expr then expr@} [else expr]) |
| @end example |
| |
| The parentheses can be omitted in contexts where parentheses are present |
| anyway, such as subprogram arguments and pragma arguments. If the @strong{else} |
| clause is omitted, @strong{else} @emph{True} is assumed; |
| thus @code{(if A then B)} is a way to conveniently represent |
| @emph{(A implies B)} in standard logic. |
| |
| RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) |
| 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) |
| @end itemize |
| |
| @geindex AI-0037 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} |
| |
| This AI confirms that an association of the form @code{Indx => <>} in an |
| array aggregate must raise @code{Constraint_Error} if @code{Indx} |
| is out of range. The RM specified a range check on other associations, but |
| not when the value of the association was defaulted. GNAT has always inserted |
| a constraint check on the index value. |
| |
| RM References: 4.03.03 (29) |
| @end itemize |
| |
| @geindex AI-0123 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0123 Composability of equality (2010-04-13)} |
| |
| Equality of untagged record composes, so that the predefined equality for a |
| composite type that includes a component of some untagged record type |
| @code{R} uses the equality operation of @code{R} (which may be user-defined |
| or predefined). This makes the behavior of untagged records identical to that |
| of tagged types in this respect. |
| |
| This change is an incompatibility with previous versions of Ada, but it |
| corrects a non-uniformity that was often a source of confusion. Analysis of |
| a large number of industrial programs indicates that in those rare cases |
| where a composite type had an untagged record component with a user-defined |
| equality, either there was no use of the composite equality, or else the code |
| expected the same composability as for tagged types, and thus had a bug that |
| would be fixed by this change. |
| |
| RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) |
| 8.05.04 (8) |
| @end itemize |
| |
| @geindex AI-0088 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0088 The value of exponentiation (0000-00-00)} |
| |
| This AI clarifies the equivalence rule given for the dynamic semantics of |
| exponentiation: the value of the operation can be obtained by repeated |
| multiplication, but the operation can be implemented otherwise (for example |
| using the familiar divide-by-two-and-square algorithm, even if this is less |
| accurate), and does not imply repeated reads of a volatile base. |
| |
| RM References: 4.05.06 (11) |
| @end itemize |
| |
| @geindex AI-0188 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0188 Case expressions (2010-01-09)} |
| |
| Case expressions are permitted. This allows use of constructs such as: |
| |
| @example |
| X := (case Y is when 1 => 2, when 2 => 3, when others => 31) |
| @end example |
| |
| RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) |
| @end itemize |
| |
| @geindex AI-0104 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} |
| |
| The assignment @code{Ptr := new not null Some_Ptr;} will raise |
| @code{Constraint_Error} because the default value of the allocated object is |
| @strong{null}. This useless construct is illegal in Ada 2012. |
| |
| RM References: 4.08 (2) |
| @end itemize |
| |
| @geindex AI-0157 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} |
| |
| Allocation and Deallocation from an empty storage pool (i.e. allocation or |
| deallocation of a pointer for which a static storage size clause of zero |
| has been given) is now illegal and is detected as such. GNAT |
| previously gave a warning but not an error. |
| |
| RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) |
| @end itemize |
| |
| @geindex AI-0179 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0179 Statement not required after label (2010-04-10)} |
| |
| It is not necessary to have a statement following a label, so a label |
| can appear at the end of a statement sequence without the need for putting a |
| null statement afterwards, but it is not allowable to have only labels and |
| no real statements in a statement sequence. |
| |
| RM References: 5.01 (2) |
| @end itemize |
| |
| @geindex AI-0139-2 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} |
| |
| The new syntax for iterating over arrays and containers is now implemented. |
| Iteration over containers is for now limited to read-only iterators. Only |
| default iterators are supported, with the syntax: @code{for Elem of C}. |
| |
| RM References: 5.05 |
| @end itemize |
| |
| @geindex AI-0134 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0134 Profiles must match for full conformance (0000-00-00)} |
| |
| For full conformance, the profiles of anonymous-access-to-subprogram |
| parameters must match. GNAT has always enforced this rule. |
| |
| RM References: 6.03.01 (18) |
| @end itemize |
| |
| @geindex AI-0207 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0207 Mode conformance and access constant (0000-00-00)} |
| |
| This AI confirms that access_to_constant indication must match for mode |
| conformance. This was implemented in GNAT when the qualifier was originally |
| introduced in Ada 2005. |
| |
| RM References: 6.03.01 (16/2) |
| @end itemize |
| |
| @geindex AI-0046 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} |
| |
| For full conformance, in the case of access parameters, the null exclusion |
| must match (either both or neither must have @code{not null}). |
| |
| RM References: 6.03.02 (18) |
| @end itemize |
| |
| @geindex AI-0118 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0118 The association of parameter associations (0000-00-00)} |
| |
| This AI clarifies the rules for named associations in subprogram calls and |
| generic instantiations. The rules have been in place since Ada 83. |
| |
| RM References: 6.04.01 (2) 12.03 (9) |
| @end itemize |
| |
| @geindex AI-0196 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} |
| |
| Null exclusion checks are not made for @code{out} parameters when |
| evaluating the actual parameters. GNAT has never generated these checks. |
| |
| RM References: 6.04.01 (13) |
| @end itemize |
| |
| @geindex AI-0015 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0015 Constant return objects (0000-00-00)} |
| |
| The return object declared in an @emph{extended_return_statement} may be |
| declared constant. This was always intended, and GNAT has always allowed it. |
| |
| RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) |
| 6.05 (5.7/2) |
| @end itemize |
| |
| @geindex AI-0032 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0032 Extended return for class-wide functions (0000-00-00)} |
| |
| If a function returns a class-wide type, the object of an extended return |
| statement can be declared with a specific type that is covered by the class- |
| wide type. This has been implemented in GNAT since the introduction of |
| extended returns. Note AI-0103 complements this AI by imposing matching |
| rules for constrained return types. |
| |
| RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) |
| 6.05 (8/2) |
| @end itemize |
| |
| @geindex AI-0103 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0103 Static matching for extended return (2010-07-23)} |
| |
| If the return subtype of a function is an elementary type or a constrained |
| type, the subtype indication in an extended return statement must match |
| statically this return subtype. |
| |
| RM References: 6.05 (5.2/2) |
| @end itemize |
| |
| @geindex AI-0058 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} |
| |
| The RM had some incorrect wording implying wrong treatment of abnormal |
| completion in an extended return. GNAT has always implemented the intended |
| correct semantics as described by this AI. |
| |
| RM References: 6.05 (22/2) |
| @end itemize |
| |
| @geindex AI-0050 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} |
| |
| The implementation permissions for raising @code{Constraint_Error} early on a function call |
| when it was clear an exception would be raised were over-permissive and allowed |
| mishandling of discriminants in some cases. GNAT did |
| not take advantage of these incorrect permissions in any case. |
| |
| RM References: 6.05 (24/2) |
| @end itemize |
| |
| @geindex AI-0125 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} |
| |
| In Ada 2012, the declaration of a primitive operation of a type extension |
| or private extension can also override an inherited primitive that is not |
| visible at the point of this declaration. |
| |
| RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) |
| @end itemize |
| |
| @geindex AI-0062 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} |
| |
| A full constant may have a null exclusion even if its associated deferred |
| constant does not. GNAT has always allowed this. |
| |
| RM References: 7.04 (6/2) 7.04 (7.1/2) |
| @end itemize |
| |
| @geindex AI-0178 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0178 Incomplete views are limited (0000-00-00)} |
| |
| This AI clarifies the role of incomplete views and plugs an omission in the |
| RM. GNAT always correctly restricted the use of incomplete views and types. |
| |
| RM References: 7.05 (3/2) 7.05 (6/2) |
| @end itemize |
| |
| @geindex AI-0087 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} |
| |
| The actual for a formal nonlimited derived type cannot be limited. In |
| particular, a formal derived type that extends a limited interface but which |
| is not explicitly limited cannot be instantiated with a limited type. |
| |
| RM References: 7.05 (5/2) 12.05.01 (5.1/2) |
| @end itemize |
| |
| @geindex AI-0099 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} |
| |
| This AI clarifies that ‘needs finalization’ is part of dynamic semantics, |
| and therefore depends on the run-time characteristics of an object (i.e. its |
| tag) and not on its nominal type. As the AI indicates: “we do not expect |
| this to affect any implementation’’. |
| |
| RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) |
| @end itemize |
| |
| @geindex AI-0064 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0064 Redundant finalization rule (0000-00-00)} |
| |
| This is an editorial change only. The intended behavior is already checked |
| by an existing ACATS test, which GNAT has always executed correctly. |
| |
| RM References: 7.06.01 (17.1/1) |
| @end itemize |
| |
| @geindex AI-0026 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} |
| |
| Record representation clauses concerning Unchecked_Union types cannot mention |
| the discriminant of the type. The type of a component declared in the variant |
| part of an Unchecked_Union cannot be controlled, have controlled components, |
| nor have protected or task parts. If an Unchecked_Union type is declared |
| within the body of a generic unit or its descendants, then the type of a |
| component declared in the variant part cannot be a formal private type or a |
| formal private extension declared within the same generic unit. |
| |
| RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) |
| @end itemize |
| |
| @geindex AI-0205 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0205 Extended return declares visible name (0000-00-00)} |
| |
| This AI corrects a simple omission in the RM. Return objects have always |
| been visible within an extended return statement. |
| |
| RM References: 8.03 (17) |
| @end itemize |
| |
| @geindex AI-0042 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0042 Overriding versus implemented-by (0000-00-00)} |
| |
| This AI fixes a wording gap in the RM. An operation of a synchronized |
| interface can be implemented by a protected or task entry, but the abstract |
| operation is not being overridden in the usual sense, and it must be stated |
| separately that this implementation is legal. This has always been the case |
| in GNAT. |
| |
| RM References: 9.01 (9.2/2) 9.04 (11.1/2) |
| @end itemize |
| |
| @geindex AI-0030 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} |
| |
| Requeue is permitted to a protected, synchronized or task interface primitive |
| providing it is known that the overriding operation is an entry. Otherwise |
| the requeue statement has the same effect as a procedure call. Use of pragma |
| @code{Implemented} provides a way to impose a static requirement on the |
| overriding operation by adhering to one of the implementation kinds: entry, |
| protected procedure or any of the above. |
| |
| RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) |
| 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) |
| @end itemize |
| |
| @geindex AI-0201 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0201 Independence of atomic object components (2010-07-22)} |
| |
| If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} |
| attribute, then individual components may not be addressable by independent |
| tasks. However, if the representation clause has no effect (is confirming), |
| then independence is not compromised. Furthermore, in GNAT, specification of |
| other appropriately addressable component sizes (e.g. 16 for 8-bit |
| characters) also preserves independence. GNAT now gives very clear warnings |
| both for the declaration of such a type, and for any assignment to its components. |
| |
| RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) |
| @end itemize |
| |
| @geindex AI-0009 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} |
| |
| This AI introduces the new pragmas @code{Independent} and |
| @code{Independent_Components}, |
| which control guaranteeing independence of access to objects and components. |
| The AI also requires independence not unaffected by confirming rep clauses. |
| |
| RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) |
| C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) |
| @end itemize |
| |
| @geindex AI-0072 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0072 Task signalling using ‘Terminated (0000-00-00)} |
| |
| This AI clarifies that task signalling for reading @code{'Terminated} only |
| occurs if the result is True. GNAT semantics has always been consistent with |
| this notion of task signalling. |
| |
| RM References: 9.10 (6.1/1) |
| @end itemize |
| |
| @geindex AI-0108 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} |
| |
| This AI confirms that an incomplete type from a limited view does not have |
| discriminants. This has always been the case in GNAT. |
| |
| RM References: 10.01.01 (12.3/2) |
| @end itemize |
| |
| @geindex AI-0129 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0129 Limited views and incomplete types (0000-00-00)} |
| |
| This AI clarifies the description of limited views: a limited view of a |
| package includes only one view of a type that has an incomplete declaration |
| and a full declaration (there is no possible ambiguity in a client package). |
| This AI also fixes an omission: a nested package in the private part has no |
| limited view. GNAT always implemented this correctly. |
| |
| RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) |
| @end itemize |
| |
| @geindex AI-0077 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} |
| |
| This AI clarifies that a declaration does not include a context clause, |
| and confirms that it is illegal to have a context in which both a limited |
| and a nonlimited view of a package are accessible. Such double visibility |
| was always rejected by GNAT. |
| |
| RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) |
| @end itemize |
| |
| @geindex AI-0122 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0122 Private with and children of generics (0000-00-00)} |
| |
| This AI clarifies the visibility of private children of generic units within |
| instantiations of a parent. GNAT has always handled this correctly. |
| |
| RM References: 10.01.02 (12/2) |
| @end itemize |
| |
| @geindex AI-0040 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0040 Limited with clauses on descendant (0000-00-00)} |
| |
| This AI confirms that a limited with clause in a child unit cannot name |
| an ancestor of the unit. This has always been checked in GNAT. |
| |
| RM References: 10.01.02 (20/2) |
| @end itemize |
| |
| @geindex AI-0132 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0132 Placement of library unit pragmas (0000-00-00)} |
| |
| This AI fills a gap in the description of library unit pragmas. The pragma |
| clearly must apply to a library unit, even if it does not carry the name |
| of the enclosing unit. GNAT has always enforced the required check. |
| |
| RM References: 10.01.05 (7) |
| @end itemize |
| |
| @geindex AI-0034 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0034 Categorization of limited views (0000-00-00)} |
| |
| The RM makes certain limited with clauses illegal because of categorization |
| considerations, when the corresponding normal with would be legal. This is |
| not intended, and GNAT has always implemented the recommended behavior. |
| |
| RM References: 10.02.01 (11/1) 10.02.01 (17/2) |
| @end itemize |
| |
| @geindex AI-0035 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} |
| |
| This AI remedies some inconsistencies in the legality rules for Pure units. |
| Derived access types are legal in a pure unit (on the assumption that the |
| rule for a zero storage pool size has been enforced on the ancestor type). |
| The rules are enforced in generic instances and in subunits. GNAT has always |
| implemented the recommended behavior. |
| |
| RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) |
| @end itemize |
| |
| @geindex AI-0219 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} |
| |
| This AI refines the rules for the cases with limited parameters which do not |
| allow the implementations to omit ‘redundant’. GNAT now properly conforms |
| to the requirements of this binding interpretation. |
| |
| RM References: 10.02.01 (18/2) |
| @end itemize |
| |
| @geindex AI-0043 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0043 Rules about raising exceptions (0000-00-00)} |
| |
| This AI covers various omissions in the RM regarding the raising of |
| exceptions. GNAT has always implemented the intended semantics. |
| |
| RM References: 11.04.01 (10.1/2) 11 (2) |
| @end itemize |
| |
| @geindex AI-0200 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} |
| |
| This AI plugs a gap in the RM which appeared to allow some obviously intended |
| illegal instantiations. GNAT has never allowed these instantiations. |
| |
| RM References: 12.07 (16) |
| @end itemize |
| |
| @geindex AI-0112 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} |
| |
| This AI concerns giving names to various representation aspects, but the |
| practical effect is simply to make the use of duplicate |
| @code{Atomic[_Components]}, |
| @code{Volatile[_Components]}, and |
| @code{Independent[_Components]} pragmas illegal, and GNAT |
| now performs this required check. |
| |
| RM References: 13.01 (8) |
| @end itemize |
| |
| @geindex AI-0106 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} |
| |
| The RM appeared to allow representation pragmas on generic formal parameters, |
| but this was not intended, and GNAT has never permitted this usage. |
| |
| RM References: 13.01 (9.1/1) |
| @end itemize |
| |
| @geindex AI-0012 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} |
| |
| It is now illegal to give an inappropriate component size or a pragma |
| @code{Pack} that attempts to change the component size in the case of atomic |
| or aliased components. Previously GNAT ignored such an attempt with a |
| warning. |
| |
| RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) |
| @end itemize |
| |
| @geindex AI-0039 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} |
| |
| The RM permitted the use of dynamic expressions (such as @code{ptr.all})` |
| for stream attributes, but these were never useful and are now illegal. GNAT |
| has always regarded such expressions as illegal. |
| |
| RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) |
| @end itemize |
| |
| @geindex AI-0095 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} |
| |
| The prefix of @code{'Address} cannot statically denote a subprogram with |
| convention @code{Intrinsic}. The use of the @code{Address} attribute raises |
| @code{Program_Error} if the prefix denotes a subprogram with convention |
| @code{Intrinsic}. |
| |
| RM References: 13.03 (11/1) |
| @end itemize |
| |
| @geindex AI-0116 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0116 Alignment of class-wide objects (0000-00-00)} |
| |
| This AI requires that the alignment of a class-wide object be no greater |
| than the alignment of any type in the class. GNAT has always followed this |
| recommendation. |
| |
| RM References: 13.03 (29) 13.11 (16) |
| @end itemize |
| |
| @geindex AI-0146 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0146 Type invariants (2009-09-21)} |
| |
| Type invariants may be specified for private types using the aspect notation. |
| Aspect @code{Type_Invariant} may be specified for any private type, |
| @code{Type_Invariant'Class} can |
| only be specified for tagged types, and is inherited by any descendent of the |
| tagged types. The invariant is a boolean expression that is tested for being |
| true in the following situations: conversions to the private type, object |
| declarations for the private type that are default initialized, and |
| [@strong{in}] @strong{out} |
| parameters and returned result on return from any primitive operation for |
| the type that is visible to a client. |
| GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and |
| @code{Invariant'Class} for @code{Type_Invariant'Class}. |
| |
| RM References: 13.03.03 (00) |
| @end itemize |
| |
| @geindex AI-0078 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} |
| |
| In Ada 2012, compilers are required to support unchecked conversion where the |
| target alignment is a multiple of the source alignment. GNAT always supported |
| this case (and indeed all cases of differing alignments, doing copies where |
| required if the alignment was reduced). |
| |
| RM References: 13.09 (7) |
| @end itemize |
| |
| @geindex AI-0195 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} |
| |
| The handling of invalid values is now designated to be implementation |
| defined. This is a documentation change only, requiring Annex M in the GNAT |
| Reference Manual to document this handling. |
| In GNAT, checks for invalid values are made |
| only when necessary to avoid erroneous behavior. Operations like assignments |
| which cannot cause erroneous behavior ignore the possibility of invalid |
| values and do not do a check. The date given above applies only to the |
| documentation change, this behavior has always been implemented by GNAT. |
| |
| RM References: 13.09.01 (10) |
| @end itemize |
| |
| @geindex AI-0193 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0193 Alignment of allocators (2010-09-16)} |
| |
| This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, |
| analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead |
| of size. |
| |
| RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) |
| 13.11.01 (2) 13.11.01 (3) |
| @end itemize |
| |
| @geindex AI-0177 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0177 Parameterized expressions (2010-07-10)} |
| |
| The new Ada 2012 notion of parameterized expressions is implemented. The form |
| is: |
| |
| @example |
| function-specification is (expression) |
| @end example |
| |
| This is exactly equivalent to the |
| corresponding function body that returns the expression, but it can appear |
| in a package spec. Note that the expression must be parenthesized. |
| |
| RM References: 13.11.01 (3/2) |
| @end itemize |
| |
| @geindex AI-0033 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} |
| |
| Neither of these two pragmas may appear within a generic template, because |
| the generic might be instantiated at other than the library level. |
| |
| RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) |
| @end itemize |
| |
| @geindex AI-0161 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} |
| |
| A new restriction @code{No_Default_Stream_Attributes} prevents the use of any |
| of the default stream attributes for elementary types. If this restriction is |
| in force, then it is necessary to provide explicit subprograms for any |
| stream attributes used. |
| |
| RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) |
| @end itemize |
| |
| @geindex AI-0194 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} |
| |
| The @code{Stream_Size} attribute returns the default number of bits in the |
| stream representation of the given type. |
| This value is not affected by the presence |
| of stream subprogram attributes for the type. GNAT has always implemented |
| this interpretation. |
| |
| RM References: 13.13.02 (1.2/2) |
| @end itemize |
| |
| @geindex AI-0109 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0109 Redundant check in S’Class’Input (0000-00-00)} |
| |
| This AI is an editorial change only. It removes the need for a tag check |
| that can never fail. |
| |
| RM References: 13.13.02 (34/2) |
| @end itemize |
| |
| @geindex AI-0007 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0007 Stream read and private scalar types (0000-00-00)} |
| |
| The RM as written appeared to limit the possibilities of declaring read |
| attribute procedures for private scalar types. This limitation was not |
| intended, and has never been enforced by GNAT. |
| |
| RM References: 13.13.02 (50/2) 13.13.02 (51/2) |
| @end itemize |
| |
| @geindex AI-0065 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0065 Remote access types and external streaming (0000-00-00)} |
| |
| This AI clarifies the fact that all remote access types support external |
| streaming. This fixes an obvious oversight in the definition of the |
| language, and GNAT always implemented the intended correct rules. |
| |
| RM References: 13.13.02 (52/2) |
| @end itemize |
| |
| @geindex AI-0019 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} |
| |
| The RM suggests that primitive subprograms of a specific tagged type are |
| frozen when the tagged type is frozen. This would be an incompatible change |
| and is not intended. GNAT has never attempted this kind of freezing and its |
| behavior is consistent with the recommendation of this AI. |
| |
| RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) |
| @end itemize |
| |
| @geindex AI-0017 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0017 Freezing and incomplete types (0000-00-00)} |
| |
| So-called ‘Taft-amendment types’ (i.e., types that are completed in package |
| bodies) are not frozen by the occurrence of bodies in the |
| enclosing declarative part. GNAT always implemented this properly. |
| |
| RM References: 13.14 (3/1) |
| @end itemize |
| |
| @geindex AI-0060 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0060 Extended definition of remote access types (0000-00-00)} |
| |
| This AI extends the definition of remote access types to include access |
| to limited, synchronized, protected or task class-wide interface types. |
| GNAT already implemented this extension. |
| |
| RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) |
| @end itemize |
| |
| @geindex AI-0114 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0114 Classification of letters (0000-00-00)} |
| |
| The code points 170 (@code{FEMININE ORDINAL INDICATOR}), |
| 181 (@code{MICRO SIGN}), and |
| 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered |
| lower case letters by Unicode. |
| However, they are not allowed in identifiers, and they |
| return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. |
| This behavior is consistent with that defined in Ada 95. |
| |
| RM References: A.03.02 (59) A.04.06 (7) |
| @end itemize |
| |
| @geindex AI-0185 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} |
| |
| Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide |
| classification functions for @code{Wide_Character} and |
| @code{Wide_Wide_Character}, as well as providing |
| case folding routines for @code{Wide_[Wide_]Character} and |
| @code{Wide_[Wide_]String}. |
| |
| RM References: A.03.05 (0) A.03.06 (0) |
| @end itemize |
| |
| @geindex AI-0031 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} |
| |
| A new version of @code{Find_Token} is added to all relevant string packages, |
| with an extra parameter @code{From}. Instead of starting at the first |
| character of the string, the search for a matching Token starts at the |
| character indexed by the value of @code{From}. |
| These procedures are available in all versions of Ada |
| but if used in versions earlier than Ada 2012 they will generate a warning |
| that an Ada 2012 subprogram is being used. |
| |
| RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) |
| A.04.05 (46) |
| @end itemize |
| |
| @geindex AI-0056 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0056 Index on null string returns zero (0000-00-00)} |
| |
| The wording in the Ada 2005 RM implied an incompatible handling of the |
| @code{Index} functions, resulting in raising an exception instead of |
| returning zero in some situations. |
| This was not intended and has been corrected. |
| GNAT always returned zero, and is thus consistent with this AI. |
| |
| RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) |
| @end itemize |
| |
| @geindex AI-0137 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0137 String encoding package (2010-03-25)} |
| |
| The packages @code{Ada.Strings.UTF_Encoding}, together with its child |
| packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, |
| and @code{Wide_Wide_Strings} have been |
| implemented. These packages (whose documentation can be found in the spec |
| files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, |
| @code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of |
| @code{String}, @code{Wide_String}, and @code{Wide_Wide_String} |
| values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and |
| UTF-16), as well as conversions between the different UTF encodings. With |
| the exception of @code{Wide_Wide_Strings}, these packages are available in |
| Ada 95 and Ada 2005 mode as well as Ada 2012 mode. |
| The @code{Wide_Wide_Strings} package |
| is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 |
| mode since it uses @code{Wide_Wide_Character}). |
| |
| RM References: A.04.11 |
| @end itemize |
| |
| @geindex AI-0038 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0038 Minor errors in Text_IO (0000-00-00)} |
| |
| These are minor errors in the description on three points. The intent on |
| all these points has always been clear, and GNAT has always implemented the |
| correct intended semantics. |
| |
| RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24) |
| @end itemize |
| |
| @geindex AI-0044 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0044 Restrictions on container instantiations (0000-00-00)} |
| |
| This AI places restrictions on allowed instantiations of generic containers. |
| These restrictions are not checked by the compiler, so there is nothing to |
| change in the implementation. This affects only the RM documentation. |
| |
| RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2) |
| @end itemize |
| |
| @geindex AI-0127 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0127 Adding Locale Capabilities (2010-09-29)} |
| |
| This package provides an interface for identifying the current locale. |
| |
| RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 |
| A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 |
| @end itemize |
| |
| @geindex AI-0002 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} |
| |
| The compiler is not required to support exporting an Ada subprogram with |
| convention C if there are parameters or a return type of an unconstrained |
| array type (such as @code{String}). GNAT allows such declarations but |
| generates warnings. It is possible, but complicated, to write the |
| corresponding C code and certainly such code would be specific to GNAT and |
| non-portable. |
| |
| RM References: B.01 (17) B.03 (62) B.03 (71.1/2) |
| @end itemize |
| |
| @geindex AI05-0216 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} |
| |
| It is clearly the intention that @code{No_Task_Hierarchy} is intended to |
| forbid tasks declared locally within subprograms, or functions returning task |
| objects, and that is the implementation that GNAT has always provided. |
| However the language in the RM was not sufficiently clear on this point. |
| Thus this is a documentation change in the RM only. |
| |
| RM References: D.07 (3/3) |
| @end itemize |
| |
| @geindex AI-0211 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} |
| |
| The restriction @code{No_Relative_Delays} forbids any calls to the subprogram |
| @code{Ada.Real_Time.Timing_Events.Set_Handler}. |
| |
| RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) |
| @end itemize |
| |
| @geindex AI-0190 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} |
| |
| This AI introduces a new pragma @code{Default_Storage_Pool}, which can be |
| used to control storage pools globally. |
| In particular, you can force every access |
| type that is used for allocation (@strong{new}) to have an explicit storage pool, |
| or you can declare a pool globally to be used for all access types that lack |
| an explicit one. |
| |
| RM References: D.07 (8) |
| @end itemize |
| |
| @geindex AI-0189 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} |
| |
| This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, |
| which says that no dynamic allocation will occur once elaboration is |
| completed. |
| In general this requires a run-time check, which is not required, and which |
| GNAT does not attempt. But the static cases of allocators in a task body or |
| in the body of the main program are detected and flagged at compile or bind |
| time. |
| |
| RM References: D.07 (19.1/2) H.04 (23.3/2) |
| @end itemize |
| |
| @geindex AI-0171 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} |
| |
| A new package @code{System.Multiprocessors} is added, together with the |
| definition of pragma @code{CPU} for controlling task affinity. A new no |
| dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, |
| is added to the Ravenscar profile. |
| |
| RM References: D.13.01 (4/2) D.16 |
| @end itemize |
| |
| @geindex AI-0210 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0210 Correct Timing_Events metric (0000-00-00)} |
| |
| This is a documentation only issue regarding wording of metric requirements, |
| that does not affect the implementation of the compiler. |
| |
| RM References: D.15 (24/2) |
| @end itemize |
| |
| @geindex AI-0206 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} |
| |
| Remote types packages are now allowed to depend on preelaborated packages. |
| This was formerly considered illegal. |
| |
| RM References: E.02.02 (6) |
| @end itemize |
| |
| @geindex AI-0152 (Ada 2012 feature) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} |
| |
| Restriction @code{No_Anonymous_Allocators} prevents the use of allocators |
| where the type of the returned value is an anonymous access type. |
| |
| RM References: H.04 (8/1) |
| @end itemize |
| |
| @node Security Hardening Features,Obsolescent Features,Implementation of Ada 2012 Features,Top |
| @anchor{gnat_rm/security_hardening_features doc}@anchor{43b}@anchor{gnat_rm/security_hardening_features id1}@anchor{43c}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15} |
| @chapter Security Hardening Features |
| |
| |
| This chapter describes Ada extensions aimed at security hardening that |
| are provided by GNAT. |
| |
| @c Register Scrubbing: |
| |
| @menu |
| * Register Scrubbing:: |
| * Stack Scrubbing:: |
| |
| @end menu |
| |
| @node Register Scrubbing,Stack Scrubbing,,Security Hardening Features |
| @anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{43d} |
| @section Register Scrubbing |
| |
| |
| GNAT can generate code to zero-out hardware registers before returning |
| from a subprogram. |
| |
| It can be enabled with the @emph{-fzero-call-used-regs} command line |
| option, to affect all subprograms in a compilation, and with a |
| @code{Machine_Attribute} pragma, to affect only specific subprograms. |
| |
| @example |
| procedure Foo; |
| pragma Machine_Attribute (Foo, "zero_call_used_regs", "used"); |
| -- Before returning, Foo scrubs only call-clobbered registers |
| -- that it uses itself. |
| |
| function Bar return Integer; |
| pragma Machine_Attribute (Bar, "zero_call_used_regs", "all"); |
| -- Before returning, Bar scrubs all call-clobbered registers. |
| @end example |
| |
| For usage and more details on the command line option, and on the |
| @code{zero_call_used_regs} attribute, see @cite{Using the GNU Compiler Collection (GCC)}. |
| |
| @c Stack Scrubbing: |
| |
| @node Stack Scrubbing,,Register Scrubbing,Security Hardening Features |
| @anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{43e} |
| @section Stack Scrubbing |
| |
| |
| GNAT can generate code to zero-out stack frames used by subprograms. |
| |
| It can be activated with the @code{Machine_Attribute} pragma, on |
| specific subprograms and variables. |
| |
| @example |
| function Foo returns Integer; |
| pragma Machine_Attribute (Foo, "strub"); |
| -- Foo and its callers are modified so as to scrub the stack |
| -- space used by Foo after it returns. |
| |
| procedure Bar; |
| pragma Machine_Attribute (Bar, "strub", "internal"); |
| -- Bar is turned into a wrapper for its original body, |
| -- and they scrub the stack used by the original body. |
| |
| Var : Integer; |
| pragma Machine_Attribute (Var, "strub"); |
| -- Reading from Var in a subprogram enables stack scrubbing |
| -- of the stack space used by the subprogram. |
| @end example |
| |
| There are also @emph{-fstrub} command line options to control default |
| settings. For usage and more details on the command line option, and |
| on the @code{strub} attribute, see @cite{Using the GNU Compiler Collection (GCC)}. |
| |
| Note that Ada secondary stacks are not scrubbed. The restriction |
| @code{No_Secondary_Stack} avoids their use, and thus their accidental |
| preservation of data that should be scrubbed. |
| |
| Also note that the machine attribute is not integrated in the Ada type |
| system. Though it may modify subprogram and variable interfaces, it |
| is not fully reflected in Ada types, @code{Access} attributes, renaming |
| and overriding. Every access type, renaming, and overriding and |
| overridden dispatching operations that may refer to an entity with an |
| attribute-modified interface must be annotated with the same |
| interface-modifying attribute, or with an interface-compatible one. |
| |
| Even then, the pragma is currently only functional when applied to |
| subprograms and scalar variables; other uses, such as directly on |
| types and subtypes, may be silently ignored. Specifically, it is not |
| currently recommended to rely on any effects this pragma might be |
| expected to have when calling subprograms through access-to-subprogram |
| variables. |
| |
| @node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top |
| @anchor{gnat_rm/obsolescent_features doc}@anchor{43f}@anchor{gnat_rm/obsolescent_features id1}@anchor{440}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16} |
| @chapter Obsolescent Features |
| |
| |
| This chapter describes features that are provided by GNAT, but are |
| considered obsolescent since there are preferred ways of achieving |
| the same effect. These features are provided solely for historical |
| compatibility purposes. |
| |
| @menu |
| * pragma No_Run_Time:: |
| * pragma Ravenscar:: |
| * pragma Restricted_Run_Time:: |
| * pragma Task_Info:: |
| * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. |
| |
| @end menu |
| |
| @node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features |
| @anchor{gnat_rm/obsolescent_features id2}@anchor{441}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{442} |
| @section pragma No_Run_Time |
| |
| |
| The pragma @code{No_Run_Time} is used to achieve an affect similar |
| to the use of the “Zero Foot Print” configurable run time, but without |
| requiring a specially configured run time. The result of using this |
| pragma, which must be used for all units in a partition, is to restrict |
| the use of any language features requiring run-time support code. The |
| preferred usage is to use an appropriately configured run-time that |
| includes just those features that are to be made accessible. |
| |
| @node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features |
| @anchor{gnat_rm/obsolescent_features id3}@anchor{443}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{444} |
| @section pragma Ravenscar |
| |
| |
| The pragma @code{Ravenscar} has exactly the same effect as pragma |
| @code{Profile (Ravenscar)}. The latter usage is preferred since it |
| is part of the new Ada 2005 standard. |
| |
| @node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features |
| @anchor{gnat_rm/obsolescent_features id4}@anchor{445}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{446} |
| @section pragma Restricted_Run_Time |
| |
| |
| The pragma @code{Restricted_Run_Time} has exactly the same effect as |
| pragma @code{Profile (Restricted)}. The latter usage is |
| preferred since the Ada 2005 pragma @code{Profile} is intended for |
| this kind of implementation dependent addition. |
| |
| @node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features |
| @anchor{gnat_rm/obsolescent_features id5}@anchor{447}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{448} |
| @section pragma Task_Info |
| |
| |
| The functionality provided by pragma @code{Task_Info} is now part of the |
| Ada language. The @code{CPU} aspect and the package |
| @code{System.Multiprocessors} offer a less system-dependent way to specify |
| task affinity or to query the number of processors. |
| |
| Syntax |
| |
| @example |
| pragma Task_Info (EXPRESSION); |
| @end example |
| |
| This pragma appears within a task definition (like pragma |
| @code{Priority}) and applies to the task in which it appears. The |
| argument must be of type @code{System.Task_Info.Task_Info_Type}. |
| The @code{Task_Info} pragma provides system dependent control over |
| aspects of tasking implementation, for example, the ability to map |
| tasks to specific processors. For details on the facilities available |
| for the version of GNAT that you are using, see the documentation |
| in the spec of package System.Task_Info in the runtime |
| library. |
| |
| @node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features |
| @anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{449}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{44a} |
| @section package System.Task_Info (@code{s-tasinf.ads}) |
| |
| |
| This package provides target dependent functionality that is used |
| to support the @code{Task_Info} pragma. The predefined Ada package |
| @code{System.Multiprocessors} and the @code{CPU} aspect now provide a |
| standard replacement for GNAT’s @code{Task_Info} functionality. |
| |
| @node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top |
| @anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{44b}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{44c} |
| @chapter Compatibility and Porting Guide |
| |
| |
| This chapter presents some guidelines for developing portable Ada code, |
| describes the compatibility issues that may arise between |
| GNAT and other Ada compilation systems (including those for Ada 83), |
| and shows how GNAT can expedite porting |
| applications developed in other Ada environments. |
| |
| @menu |
| * Writing Portable Fixed-Point Declarations:: |
| * Compatibility with Ada 83:: |
| * Compatibility between Ada 95 and Ada 2005:: |
| * Implementation-dependent characteristics:: |
| * Compatibility with Other Ada Systems:: |
| * Representation Clauses:: |
| * Compatibility with HP Ada 83:: |
| |
| @end menu |
| |
| @node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide |
| @anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{44d}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{44e} |
| @section Writing Portable Fixed-Point Declarations |
| |
| |
| The Ada Reference Manual gives an implementation freedom to choose bounds |
| that are narrower by @code{Small} from the given bounds. |
| For example, if we write |
| |
| @example |
| type F1 is delta 1.0 range -128.0 .. +128.0; |
| @end example |
| |
| then the implementation is allowed to choose -128.0 .. +127.0 if it |
| likes, but is not required to do so. |
| |
| This leads to possible portability problems, so let’s have a closer |
| look at this, and figure out how to avoid these problems. |
| |
| First, why does this freedom exist, and why would an implementation |
| take advantage of it? To answer this, take a closer look at the type |
| declaration for @code{F1} above. If the compiler uses the given bounds, |
| it would need 9 bits to hold the largest positive value (and typically |
| that means 16 bits on all machines). But if the implementation chooses |
| the +127.0 bound then it can fit values of the type in 8 bits. |
| |
| Why not make the user write +127.0 if that’s what is wanted? |
| The rationale is that if you are thinking of fixed point |
| as a kind of ‘poor man’s floating-point’, then you don’t want |
| to be thinking about the scaled integers that are used in its |
| representation. Let’s take another example: |
| |
| @example |
| type F2 is delta 2.0**(-15) range -1.0 .. +1.0; |
| @end example |
| |
| Looking at this declaration, it seems casually as though |
| it should fit in 16 bits, but again that extra positive value |
| +1.0 has the scaled integer equivalent of 2**15 which is one too |
| big for signed 16 bits. The implementation can treat this as: |
| |
| @example |
| type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); |
| @end example |
| |
| and the Ada language design team felt that this was too annoying |
| to require. We don’t need to debate this decision at this point, |
| since it is well established (the rule about narrowing the ranges |
| dates to Ada 83). |
| |
| But the important point is that an implementation is not required |
| to do this narrowing, so we have a potential portability problem. |
| We could imagine three types of implementation: |
| |
| |
| @enumerate a |
| |
| @item |
| those that narrow the range automatically if they can figure |
| out that the narrower range will allow storage in a smaller machine unit, |
| |
| @item |
| those that will narrow only if forced to by a @code{'Size} clause, and |
| |
| @item |
| those that will never narrow. |
| @end enumerate |
| |
| Now if we are language theoreticians, we can imagine a fourth |
| approach: to narrow all the time, e.g. to treat |
| |
| @example |
| type F3 is delta 1.0 range -10.0 .. +23.0; |
| @end example |
| |
| as though it had been written: |
| |
| @example |
| type F3 is delta 1.0 range -9.0 .. +22.0; |
| @end example |
| |
| But although technically allowed, such a behavior would be hostile and silly, |
| and no real compiler would do this. All real compilers will fall into one of |
| the categories (a), (b) or (c) above. |
| |
| So, how do you get the compiler to do what you want? The answer is give the |
| actual bounds you want, and then use a @code{'Small} clause and a |
| @code{'Size} clause to absolutely pin down what the compiler does. |
| E.g., for @code{F2} above, we will write: |
| |
| @example |
| My_Small : constant := 2.0**(-15); |
| My_First : constant := -1.0; |
| My_Last : constant := +1.0 - My_Small; |
| |
| type F2 is delta My_Small range My_First .. My_Last; |
| @end example |
| |
| and then add |
| |
| @example |
| for F2'Small use my_Small; |
| for F2'Size use 16; |
| @end example |
| |
| In practice all compilers will do the same thing here and will give you |
| what you want, so the above declarations are fully portable. If you really |
| want to play language lawyer and guard against ludicrous behavior by the |
| compiler you could add |
| |
| @example |
| Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); |
| Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); |
| @end example |
| |
| One or other or both are allowed to be illegal if the compiler is |
| behaving in a silly manner, but at least the silly compiler will not |
| get away with silently messing with your (very clear) intentions. |
| |
| If you follow this scheme you will be guaranteed that your fixed-point |
| types will be portable. |
| |
| @node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide |
| @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{44f}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{450} |
| @section Compatibility with Ada 83 |
| |
| |
| @geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) |
| |
| Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 |
| are highly upwards compatible with Ada 83. In |
| particular, the design intention was that the difficulties associated |
| with moving from Ada 83 to later versions of the standard should be no greater |
| than those that occur when moving from one Ada 83 system to another. |
| |
| However, there are a number of points at which there are minor |
| incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains |
| full details of these issues as they relate to Ada 95, |
| and should be consulted for a complete treatment. |
| In practice the |
| following subsections treat the most likely issues to be encountered. |
| |
| @menu |
| * Legal Ada 83 programs that are illegal in Ada 95:: |
| * More deterministic semantics:: |
| * Changed semantics:: |
| * Other language compatibility issues:: |
| |
| @end menu |
| |
| @node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 |
| @anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{451}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{452} |
| @subsection Legal Ada 83 programs that are illegal in Ada 95 |
| |
| |
| Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in |
| Ada 95 and later versions of the standard: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Character literals} |
| |
| Some uses of character literals are ambiguous. Since Ada 95 has introduced |
| @code{Wide_Character} as a new predefined character type, some uses of |
| character literals that were legal in Ada 83 are illegal in Ada 95. |
| For example: |
| |
| @example |
| for Char in 'A' .. 'Z' loop ... end loop; |
| @end example |
| |
| The problem is that ‘A’ and ‘Z’ could be from either |
| @code{Character} or @code{Wide_Character}. The simplest correction |
| is to make the type explicit; e.g.: |
| |
| @example |
| for Char in Character range 'A' .. 'Z' loop ... end loop; |
| @end example |
| |
| @item |
| @emph{New reserved words} |
| |
| The identifiers @code{abstract}, @code{aliased}, @code{protected}, |
| @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. |
| Existing Ada 83 code using any of these identifiers must be edited to |
| use some alternative name. |
| |
| @item |
| @emph{Freezing rules} |
| |
| The rules in Ada 95 are slightly different with regard to the point at |
| which entities are frozen, and representation pragmas and clauses are |
| not permitted past the freeze point. This shows up most typically in |
| the form of an error message complaining that a representation item |
| appears too late, and the appropriate corrective action is to move |
| the item nearer to the declaration of the entity to which it refers. |
| |
| A particular case is that representation pragmas |
| cannot be applied to a subprogram body. If necessary, a separate subprogram |
| declaration must be introduced to which the pragma can be applied. |
| |
| @item |
| @emph{Optional bodies for library packages} |
| |
| In Ada 83, a package that did not require a package body was nevertheless |
| allowed to have one. This lead to certain surprises in compiling large |
| systems (situations in which the body could be unexpectedly ignored by the |
| binder). In Ada 95, if a package does not require a body then it is not |
| permitted to have a body. To fix this problem, simply remove a redundant |
| body if it is empty, or, if it is non-empty, introduce a dummy declaration |
| into the spec that makes the body required. One approach is to add a private |
| part to the package declaration (if necessary), and define a parameterless |
| procedure called @code{Requires_Body}, which must then be given a dummy |
| procedure body in the package body, which then becomes required. |
| Another approach (assuming that this does not introduce elaboration |
| circularities) is to add an @code{Elaborate_Body} pragma to the package spec, |
| since one effect of this pragma is to require the presence of a package body. |
| |
| @item |
| @emph{Numeric_Error is the same exception as Constraint_Error} |
| |
| In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. |
| This means that it is illegal to have separate exception handlers for |
| the two exceptions. The fix is simply to remove the handler for the |
| @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise |
| @code{Constraint_Error} in place of @code{Numeric_Error} in all cases). |
| |
| @item |
| @emph{Indefinite subtypes in generics} |
| |
| In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) |
| as the actual for a generic formal private type, but then the instantiation |
| would be illegal if there were any instances of declarations of variables |
| of this type in the generic body. In Ada 95, to avoid this clear violation |
| of the methodological principle known as the ‘contract model’, |
| the generic declaration explicitly indicates whether |
| or not such instantiations are permitted. If a generic formal parameter |
| has explicit unknown discriminants, indicated by using @code{(<>)} after the |
| subtype name, then it can be instantiated with indefinite types, but no |
| stand-alone variables can be declared of this type. Any attempt to declare |
| such a variable will result in an illegality at the time the generic is |
| declared. If the @code{(<>)} notation is not used, then it is illegal |
| to instantiate the generic with an indefinite type. |
| This is the potential incompatibility issue when porting Ada 83 code to Ada 95. |
| It will show up as a compile time error, and |
| the fix is usually simply to add the @code{(<>)} to the generic declaration. |
| @end itemize |
| |
| @node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 |
| @anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{453}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{454} |
| @subsection More deterministic semantics |
| |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Conversions} |
| |
| Conversions from real types to integer types round away from 0. In Ada 83 |
| the conversion Integer(2.5) could deliver either 2 or 3 as its value. This |
| implementation freedom was intended to support unbiased rounding in |
| statistical applications, but in practice it interfered with portability. |
| In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 |
| is required. Numeric code may be affected by this change in semantics. |
| Note, though, that this issue is no worse than already existed in Ada 83 |
| when porting code from one vendor to another. |
| |
| @item |
| @emph{Tasking} |
| |
| The Real-Time Annex introduces a set of policies that define the behavior of |
| features that were implementation dependent in Ada 83, such as the order in |
| which open select branches are executed. |
| @end itemize |
| |
| @node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 |
| @anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{455}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{456} |
| @subsection Changed semantics |
| |
| |
| The worst kind of incompatibility is one where a program that is legal in |
| Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not |
| possible in Ada 83. Fortunately this is extremely rare, but the one |
| situation that you should be alert to is the change in the predefined type |
| @code{Character} from 7-bit ASCII to 8-bit Latin-1. |
| |
| @quotation |
| |
| @geindex Latin-1 |
| @end quotation |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Range of type `@w{`}Character`@w{`}} |
| |
| The range of @code{Standard.Character} is now the full 256 characters |
| of Latin-1, whereas in most Ada 83 implementations it was restricted |
| to 128 characters. Although some of the effects of |
| this change will be manifest in compile-time rejection of legal |
| Ada 83 programs it is possible for a working Ada 83 program to have |
| a different effect in Ada 95, one that was not permitted in Ada 83. |
| As an example, the expression |
| @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now |
| delivers @code{255} as its value. |
| In general, you should look at the logic of any |
| character-processing Ada 83 program and see whether it needs to be adapted |
| to work correctly with Latin-1. Note that the predefined Ada 95 API has a |
| character handling package that may be relevant if code needs to be adapted |
| to account for the additional Latin-1 elements. |
| The desirable fix is to |
| modify the program to accommodate the full character set, but in some cases |
| it may be convenient to define a subtype or derived type of Character that |
| covers only the restricted range. |
| @end itemize |
| |
| @node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 |
| @anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{457}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{458} |
| @subsection Other language compatibility issues |
| |
| |
| |
| @itemize * |
| |
| @item |
| @emph{-gnat83} switch |
| |
| All implementations of GNAT provide a switch that causes GNAT to operate |
| in Ada 83 mode. In this mode, some but not all compatibility problems |
| of the type described above are handled automatically. For example, the |
| new reserved words introduced in Ada 95 and Ada 2005 are treated simply |
| as identifiers as in Ada 83. However, |
| in practice, it is usually advisable to make the necessary modifications |
| to the program to remove the need for using this switch. |
| See the @code{Compiling Different Versions of Ada} section in |
| the @cite{GNAT User’s Guide}. |
| |
| @item |
| Support for removed Ada 83 pragmas and attributes |
| |
| A number of pragmas and attributes from Ada 83 were removed from Ada 95, |
| generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 |
| compilers are allowed, but not required, to implement these missing |
| elements. In contrast with some other compilers, GNAT implements all |
| such pragmas and attributes, eliminating this compatibility concern. These |
| include @code{pragma Interface} and the floating point type attributes |
| (@code{Emax}, @code{Mantissa}, etc.), among other items. |
| @end itemize |
| |
| @node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide |
| @anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{459}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{45a} |
| @section Compatibility between Ada 95 and Ada 2005 |
| |
| |
| @geindex Compatibility between Ada 95 and Ada 2005 |
| |
| Although Ada 2005 was designed to be upwards compatible with Ada 95, there are |
| a number of incompatibilities. Several are enumerated below; |
| for a complete description please see the |
| @cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in |
| @cite{Rationale for Ada 2005}. |
| |
| |
| @itemize * |
| |
| @item |
| @emph{New reserved words.} |
| |
| The words @code{interface}, @code{overriding} and @code{synchronized} are |
| reserved in Ada 2005. |
| A pre-Ada 2005 program that uses any of these as an identifier will be |
| illegal. |
| |
| @item |
| @emph{New declarations in predefined packages.} |
| |
| A number of packages in the predefined environment contain new declarations: |
| @code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, |
| @code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, |
| @code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, |
| @code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, |
| @code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. |
| If an Ada 95 program does a @code{with} and @code{use} of any of these |
| packages, the new declarations may cause name clashes. |
| |
| @item |
| @emph{Access parameters.} |
| |
| A nondispatching subprogram with an access parameter cannot be renamed |
| as a dispatching operation. This was permitted in Ada 95. |
| |
| @item |
| @emph{Access types, discriminants, and constraints.} |
| |
| Rule changes in this area have led to some incompatibilities; for example, |
| constrained subtypes of some access types are not permitted in Ada 2005. |
| |
| @item |
| @emph{Aggregates for limited types.} |
| |
| The allowance of aggregates for limited types in Ada 2005 raises the |
| possibility of ambiguities in legal Ada 95 programs, since additional types |
| now need to be considered in expression resolution. |
| |
| @item |
| @emph{Fixed-point multiplication and division.} |
| |
| Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which |
| were legal in Ada 95 and invoked the predefined versions of these operations, |
| are now ambiguous. |
| The ambiguity may be resolved either by applying a type conversion to the |
| expression, or by explicitly invoking the operation from package |
| @code{Standard}. |
| |
| @item |
| @emph{Return-by-reference types.} |
| |
| The Ada 95 return-by-reference mechanism has been removed. Instead, the user |
| can declare a function returning a value from an anonymous access type. |
| @end itemize |
| |
| @node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide |
| @anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{45b}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{45c} |
| @section Implementation-dependent characteristics |
| |
| |
| Although the Ada language defines the semantics of each construct as |
| precisely as practical, in some situations (for example for reasons of |
| efficiency, or where the effect is heavily dependent on the host or target |
| platform) the implementation is allowed some freedom. In porting Ada 83 |
| code to GNAT, you need to be aware of whether / how the existing code |
| exercised such implementation dependencies. Such characteristics fall into |
| several categories, and GNAT offers specific support in assisting the |
| transition from certain Ada 83 compilers. |
| |
| @menu |
| * Implementation-defined pragmas:: |
| * Implementation-defined attributes:: |
| * Libraries:: |
| * Elaboration order:: |
| * Target-specific aspects:: |
| |
| @end menu |
| |
| @node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics |
| @anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{45d}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{45e} |
| @subsection Implementation-defined pragmas |
| |
| |
| Ada compilers are allowed to supplement the language-defined pragmas, and |
| these are a potential source of non-portability. All GNAT-defined pragmas |
| are described in @ref{7,,Implementation Defined Pragmas}, |
| and these include several that are specifically |
| intended to correspond to other vendors’ Ada 83 pragmas. |
| For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. |
| For compatibility with HP Ada 83, GNAT supplies the pragmas |
| @code{Extend_System}, @code{Ident}, @code{Inline_Generic}, |
| @code{Interface_Name}, @code{Passive}, @code{Suppress_All}, |
| and @code{Volatile}. |
| Other relevant pragmas include @code{External} and @code{Link_With}. |
| Some vendor-specific |
| Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are |
| recognized, thus |
| avoiding compiler rejection of units that contain such pragmas; they are not |
| relevant in a GNAT context and hence are not otherwise implemented. |
| |
| @node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics |
| @anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{45f}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{460} |
| @subsection Implementation-defined attributes |
| |
| |
| Analogous to pragmas, the set of attributes may be extended by an |
| implementation. All GNAT-defined attributes are described in |
| @ref{8,,Implementation Defined Attributes}, |
| and these include several that are specifically intended |
| to correspond to other vendors’ Ada 83 attributes. For migrating from VADS, |
| the attribute @code{VADS_Size} may be useful. For compatibility with HP |
| Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and |
| @code{Type_Class}. |
| |
| @node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics |
| @anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{461}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{462} |
| @subsection Libraries |
| |
| |
| Vendors may supply libraries to supplement the standard Ada API. If Ada 83 |
| code uses vendor-specific libraries then there are several ways to manage |
| this in Ada 95 and later versions of the standard: |
| |
| |
| @itemize * |
| |
| @item |
| If the source code for the libraries (specs and bodies) are |
| available, then the libraries can be migrated in the same way as the |
| application. |
| |
| @item |
| If the source code for the specs but not the bodies are |
| available, then you can reimplement the bodies. |
| |
| @item |
| Some features introduced by Ada 95 obviate the need for library support. For |
| example most Ada 83 vendors supplied a package for unsigned integers. The |
| Ada 95 modular type feature is the preferred way to handle this need, so |
| instead of migrating or reimplementing the unsigned integer package it may |
| be preferable to retrofit the application using modular types. |
| @end itemize |
| |
| @node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics |
| @anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{463}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{464} |
| @subsection Elaboration order |
| |
| |
| The implementation can choose any elaboration order consistent with the unit |
| dependency relationship. This freedom means that some orders can result in |
| Program_Error being raised due to an ‘Access Before Elaboration’: an attempt |
| to invoke a subprogram before its body has been elaborated, or to instantiate |
| a generic before the generic body has been elaborated. By default GNAT |
| attempts to choose a safe order (one that will not encounter access before |
| elaboration problems) by implicitly inserting @code{Elaborate} or |
| @code{Elaborate_All} pragmas where |
| needed. However, this can lead to the creation of elaboration circularities |
| and a resulting rejection of the program by gnatbind. This issue is |
| thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix |
| in the @cite{GNAT User’s Guide}. |
| In brief, there are several |
| ways to deal with this situation: |
| |
| |
| @itemize * |
| |
| @item |
| Modify the program to eliminate the circularities, e.g., by moving |
| elaboration-time code into explicitly-invoked procedures |
| |
| @item |
| Constrain the elaboration order by including explicit @code{Elaborate_Body} or |
| @code{Elaborate} pragmas, and then inhibit the generation of implicit |
| @code{Elaborate_All} |
| pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally |
| (by selectively suppressing elaboration checks via pragma |
| @code{Suppress(Elaboration_Check)} when it is safe to do so). |
| @end itemize |
| |
| @node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics |
| @anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{465}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{466} |
| @subsection Target-specific aspects |
| |
| |
| Low-level applications need to deal with machine addresses, data |
| representations, interfacing with assembler code, and similar issues. If |
| such an Ada 83 application is being ported to different target hardware (for |
| example where the byte endianness has changed) then you will need to |
| carefully examine the program logic; the porting effort will heavily depend |
| on the robustness of the original design. Moreover, Ada 95 (and thus |
| Ada 2005 and Ada 2012) are sometimes |
| incompatible with typical Ada 83 compiler practices regarding implicit |
| packing, the meaning of the Size attribute, and the size of access values. |
| GNAT’s approach to these issues is described in @ref{467,,Representation Clauses}. |
| |
| @node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide |
| @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{468}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{469} |
| @section Compatibility with Other Ada Systems |
| |
| |
| If programs avoid the use of implementation dependent and |
| implementation defined features, as documented in the |
| @cite{Ada Reference Manual}, there should be a high degree of portability between |
| GNAT and other Ada systems. The following are specific items which |
| have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 |
| compilers, but do not affect porting code to GNAT. |
| (As of January 2007, GNAT is the only compiler available for Ada 2005; |
| the following issues may or may not arise for Ada 2005 programs |
| when other compilers appear.) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Ada 83 Pragmas and Attributes} |
| |
| Ada 95 compilers are allowed, but not required, to implement the missing |
| Ada 83 pragmas and attributes that are no longer defined in Ada 95. |
| GNAT implements all such pragmas and attributes, eliminating this as |
| a compatibility concern, but some other Ada 95 compilers reject these |
| pragmas and attributes. |
| |
| @item |
| @emph{Specialized Needs Annexes} |
| |
| GNAT implements the full set of special needs annexes. At the |
| current time, it is the only Ada 95 compiler to do so. This means that |
| programs making use of these features may not be portable to other Ada |
| 95 compilation systems. |
| |
| @item |
| @emph{Representation Clauses} |
| |
| Some other Ada 95 compilers implement only the minimal set of |
| representation clauses required by the Ada 95 reference manual. GNAT goes |
| far beyond this minimal set, as described in the next section. |
| @end itemize |
| |
| @node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide |
| @anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{46a}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{467} |
| @section Representation Clauses |
| |
| |
| The Ada 83 reference manual was quite vague in describing both the minimal |
| required implementation of representation clauses, and also their precise |
| effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the |
| minimal set of capabilities required is still quite limited. |
| |
| GNAT implements the full required set of capabilities in |
| Ada 95 and Ada 2005, but also goes much further, and in particular |
| an effort has been made to be compatible with existing Ada 83 usage to the |
| greatest extent possible. |
| |
| A few cases exist in which Ada 83 compiler behavior is incompatible with |
| the requirements in Ada 95 (and thus also Ada 2005). These are instances of |
| intentional or accidental dependence on specific implementation dependent |
| characteristics of these Ada 83 compilers. The following is a list of |
| the cases most likely to arise in existing Ada 83 code. |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Implicit Packing} |
| |
| Some Ada 83 compilers allowed a Size specification to cause implicit |
| packing of an array or record. This could cause expensive implicit |
| conversions for change of representation in the presence of derived |
| types, and the Ada design intends to avoid this possibility. |
| Subsequent AI’s were issued to make it clear that such implicit |
| change of representation in response to a Size clause is inadvisable, |
| and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) |
| Reference Manuals as implementation advice that is followed by GNAT. |
| The problem will show up as an error |
| message rejecting the size clause. The fix is simply to provide |
| the explicit pragma @code{Pack}, or for more fine tuned control, provide |
| a Component_Size clause. |
| |
| @item |
| @emph{Meaning of Size Attribute} |
| |
| The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as |
| the minimal number of bits required to hold values of the type. For example, |
| on a 32-bit machine, the size of @code{Natural} will typically be 31 and not |
| 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and |
| some 32 in this situation. This problem will usually show up as a compile |
| time error, but not always. It is a good idea to check all uses of the |
| ‘Size attribute when porting Ada 83 code. The GNAT specific attribute |
| Object_Size can provide a useful way of duplicating the behavior of |
| some Ada 83 compiler systems. |
| |
| @item |
| @emph{Size of Access Types} |
| |
| A common assumption in Ada 83 code is that an access type is in fact a pointer, |
| and that therefore it will be the same size as a System.Address value. This |
| assumption is true for GNAT in most cases with one exception. For the case of |
| a pointer to an unconstrained array type (where the bounds may vary from one |
| value of the access type to another), the default is to use a ‘fat pointer’, |
| which is represented as two separate pointers, one to the bounds, and one to |
| the array. This representation has a number of advantages, including improved |
| efficiency. However, it may cause some difficulties in porting existing Ada 83 |
| code which makes the assumption that, for example, pointers fit in 32 bits on |
| a machine with 32-bit addressing. |
| |
| To get around this problem, GNAT also permits the use of ‘thin pointers’ for |
| access types in this case (where the designated type is an unconstrained array |
| type). These thin pointers are indeed the same size as a System.Address value. |
| To specify a thin pointer, use a size clause for the type, for example: |
| |
| @example |
| type X is access all String; |
| for X'Size use Standard'Address_Size; |
| @end example |
| |
| which will cause the type X to be represented using a single pointer. |
| When using this representation, the bounds are right behind the array. |
| This representation is slightly less efficient, and does not allow quite |
| such flexibility in the use of foreign pointers or in using the |
| Unrestricted_Access attribute to create pointers to non-aliased objects. |
| But for any standard portable use of the access type it will work in |
| a functionally correct manner and allow porting of existing code. |
| Note that another way of forcing a thin pointer representation |
| is to use a component size clause for the element size in an array, |
| or a record representation clause for an access field in a record. |
| |
| See the documentation of Unrestricted_Access in the GNAT RM for a |
| full discussion of possible problems using this attribute in conjunction |
| with thin pointers. |
| @end itemize |
| |
| @node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide |
| @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{46b}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{46c} |
| @section Compatibility with HP Ada 83 |
| |
| |
| All the HP Ada 83 pragmas and attributes are recognized, although only a subset |
| of them can sensibly be implemented. The description of pragmas in |
| @ref{7,,Implementation Defined Pragmas} indicates whether or not they are |
| applicable to GNAT. |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Default floating-point representation} |
| |
| In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, |
| it is VMS format. |
| |
| @item |
| @emph{System} |
| |
| the package System in GNAT exactly corresponds to the definition in the |
| Ada 95 reference manual, which means that it excludes many of the |
| HP Ada 83 extensions. However, a separate package Aux_DEC is provided |
| that contains the additional definitions, and a special pragma, |
| Extend_System allows this package to be treated transparently as an |
| extension of package System. |
| @end itemize |
| |
| @node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top |
| @anchor{share/gnu_free_documentation_license doc}@anchor{46d}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{46e} |
| @chapter GNU Free Documentation License |
| |
| |
| Version 1.3, 3 November 2008 |
| |
| Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc |
| @indicateurl{http://fsf.org/} |
| |
| Everyone is permitted to copy and distribute verbatim copies of this |
| license document, but changing it is not allowed. |
| |
| @strong{Preamble} |
| |
| The purpose of this License is to make a manual, textbook, or other |
| functional and useful document “free” in the sense of freedom: to |
| assure everyone the effective freedom to copy and redistribute it, |
| with or without modifying it, either commercially or noncommercially. |
| Secondarily, this License preserves for the author and publisher a way |
| to get credit for their work, while not being considered responsible |
| for modifications made by others. |
| |
| This License is a kind of “copyleft”, which means that derivative |
| works of the document must themselves be free in the same sense. It |
| complements the GNU General Public License, which is a copyleft |
| license designed for free software. |
| |
| We have designed this License in order to use it for manuals for free |
| software, because free software needs free documentation: a free |
| program should come with manuals providing the same freedoms that the |
| software does. But this License is not limited to software manuals; |
| it can be used for any textual work, regardless of subject matter or |
| whether it is published as a printed book. We recommend this License |
| principally for works whose purpose is instruction or reference. |
| |
| @strong{1. APPLICABILITY AND DEFINITIONS} |
| |
| This License applies to any manual or other work, in any medium, that |
| contains a notice placed by the copyright holder saying it can be |
| distributed under the terms of this License. Such a notice grants a |
| world-wide, royalty-free license, unlimited in duration, to use that |
| work under the conditions stated herein. The @strong{Document}, below, |
| refers to any such manual or work. Any member of the public is a |
| licensee, and is addressed as “@strong{you}”. You accept the license if you |
| copy, modify or distribute the work in a way requiring permission |
| under copyright law. |
| |
| A “@strong{Modified Version}” of the Document means any work containing the |
| Document or a portion of it, either copied verbatim, or with |
| modifications and/or translated into another language. |
| |
| A “@strong{Secondary Section}” is a named appendix or a front-matter section of |
| the Document that deals exclusively with the relationship of the |
| publishers or authors of the Document to the Document’s overall subject |
| (or to related matters) and contains nothing that could fall directly |
| within that overall subject. (Thus, if the Document is in part a |
| textbook of mathematics, a Secondary Section may not explain any |
| mathematics.) The relationship could be a matter of historical |
| connection with the subject or with related matters, or of legal, |
| commercial, philosophical, ethical or political position regarding |
| them. |
| |
| The “@strong{Invariant Sections}” are certain Secondary Sections whose titles |
| are designated, as being those of Invariant Sections, in the notice |
| that says that the Document is released under this License. If a |
| section does not fit the above definition of Secondary then it is not |
| allowed to be designated as Invariant. The Document may contain zero |
| Invariant Sections. If the Document does not identify any Invariant |
| Sections then there are none. |
| |
| The “@strong{Cover Texts}” are certain short passages of text that are listed, |
| as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
| the Document is released under this License. A Front-Cover Text may |
| be at most 5 words, and a Back-Cover Text may be at most 25 words. |
| |
| A “@strong{Transparent}” copy of the Document means a machine-readable copy, |
| represented in a format whose specification is available to the |
| general public, that is suitable for revising the document |
| straightforwardly with generic text editors or (for images composed of |
| pixels) generic paint programs or (for drawings) some widely available |
| drawing editor, and that is suitable for input to text formatters or |
| for automatic translation to a variety of formats suitable for input |
| to text formatters. A copy made in an otherwise Transparent file |
| format whose markup, or absence of markup, has been arranged to thwart |
| or discourage subsequent modification by readers is not Transparent. |
| An image format is not Transparent if used for any substantial amount |
| of text. A copy that is not “Transparent” is called @strong{Opaque}. |
| |
| Examples of suitable formats for Transparent copies include plain |
| ASCII without markup, Texinfo input format, LaTeX input format, SGML |
| or XML using a publicly available DTD, and standard-conforming simple |
| HTML, PostScript or PDF designed for human modification. Examples of |
| transparent image formats include PNG, XCF and JPG. Opaque formats |
| include proprietary formats that can be read and edited only by |
| proprietary word processors, SGML or XML for which the DTD and/or |
| processing tools are not generally available, and the |
| machine-generated HTML, PostScript or PDF produced by some word |
| processors for output purposes only. |
| |
| The “@strong{Title Page}” means, for a printed book, the title page itself, |
| plus such following pages as are needed to hold, legibly, the material |
| this License requires to appear in the title page. For works in |
| formats which do not have any title page as such, “Title Page” means |
| the text near the most prominent appearance of the work’s title, |
| preceding the beginning of the body of the text. |
| |
| The “@strong{publisher}” means any person or entity that distributes |
| copies of the Document to the public. |
| |
| A section “@strong{Entitled XYZ}” means a named subunit of the Document whose |
| title either is precisely XYZ or contains XYZ in parentheses following |
| text that translates XYZ in another language. (Here XYZ stands for a |
| specific section name mentioned below, such as “@strong{Acknowledgements}”, |
| “@strong{Dedications}”, “@strong{Endorsements}”, or “@strong{History}”.) |
| To “@strong{Preserve the Title}” |
| of such a section when you modify the Document means that it remains a |
| section “Entitled XYZ” according to this definition. |
| |
| The Document may include Warranty Disclaimers next to the notice which |
| states that this License applies to the Document. These Warranty |
| Disclaimers are considered to be included by reference in this |
| License, but only as regards disclaiming warranties: any other |
| implication that these Warranty Disclaimers may have is void and has |
| no effect on the meaning of this License. |
| |
| @strong{2. VERBATIM COPYING} |
| |
| You may copy and distribute the Document in any medium, either |
| commercially or noncommercially, provided that this License, the |
| copyright notices, and the license notice saying this License applies |
| to the Document are reproduced in all copies, and that you add no other |
| conditions whatsoever to those of this License. You may not use |
| technical measures to obstruct or control the reading or further |
| copying of the copies you make or distribute. However, you may accept |
| compensation in exchange for copies. If you distribute a large enough |
| number of copies you must also follow the conditions in section 3. |
| |
| You may also lend copies, under the same conditions stated above, and |
| you may publicly display copies. |
| |
| @strong{3. COPYING IN QUANTITY} |
| |
| If you publish printed copies (or copies in media that commonly have |
| printed covers) of the Document, numbering more than 100, and the |
| Document’s license notice requires Cover Texts, you must enclose the |
| copies in covers that carry, clearly and legibly, all these Cover |
| Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
| the back cover. Both covers must also clearly and legibly identify |
| you as the publisher of these copies. The front cover must present |
| the full title with all words of the title equally prominent and |
| visible. You may add other material on the covers in addition. |
| Copying with changes limited to the covers, as long as they preserve |
| the title of the Document and satisfy these conditions, can be treated |
| as verbatim copying in other respects. |
| |
| If the required texts for either cover are too voluminous to fit |
| legibly, you should put the first ones listed (as many as fit |
| reasonably) on the actual cover, and continue the rest onto adjacent |
| pages. |
| |
| If you publish or distribute Opaque copies of the Document numbering |
| more than 100, you must either include a machine-readable Transparent |
| copy along with each Opaque copy, or state in or with each Opaque copy |
| a computer-network location from which the general network-using |
| public has access to download using public-standard network protocols |
| a complete Transparent copy of the Document, free of added material. |
| If you use the latter option, you must take reasonably prudent steps, |
| when you begin distribution of Opaque copies in quantity, to ensure |
| that this Transparent copy will remain thus accessible at the stated |
| location until at least one year after the last time you distribute an |
| Opaque copy (directly or through your agents or retailers) of that |
| edition to the public. |
| |
| It is requested, but not required, that you contact the authors of the |
| Document well before redistributing any large number of copies, to give |
| them a chance to provide you with an updated version of the Document. |
| |
| @strong{4. MODIFICATIONS} |
| |
| You may copy and distribute a Modified Version of the Document under |
| the conditions of sections 2 and 3 above, provided that you release |
| the Modified Version under precisely this License, with the Modified |
| Version filling the role of the Document, thus licensing distribution |
| and modification of the Modified Version to whoever possesses a copy |
| of it. In addition, you must do these things in the Modified Version: |
| |
| |
| @enumerate A |
| |
| @item |
| Use in the Title Page (and on the covers, if any) a title distinct |
| from that of the Document, and from those of previous versions |
| (which should, if there were any, be listed in the History section |
| of the Document). You may use the same title as a previous version |
| if the original publisher of that version gives permission. |
| |
| @item |
| List on the Title Page, as authors, one or more persons or entities |
| responsible for authorship of the modifications in the Modified |
| Version, together with at least five of the principal authors of the |
| Document (all of its principal authors, if it has fewer than five), |
| unless they release you from this requirement. |
| |
| @item |
| State on the Title page the name of the publisher of the |
| Modified Version, as the publisher. |
| |
| @item |
| Preserve all the copyright notices of the Document. |
| |
| @item |
| Add an appropriate copyright notice for your modifications |
| adjacent to the other copyright notices. |
| |
| @item |
| Include, immediately after the copyright notices, a license notice |
| giving the public permission to use the Modified Version under the |
| terms of this License, in the form shown in the Addendum below. |
| |
| @item |
| Preserve in that license notice the full lists of Invariant Sections |
| and required Cover Texts given in the Document’s license notice. |
| |
| @item |
| Include an unaltered copy of this License. |
| |
| @item |
| Preserve the section Entitled “History”, Preserve its Title, and add |
| to it an item stating at least the title, year, new authors, and |
| publisher of the Modified Version as given on the Title Page. If |
| there is no section Entitled “History” in the Document, create one |
| stating the title, year, authors, and publisher of the Document as |
| given on its Title Page, then add an item describing the Modified |
| Version as stated in the previous sentence. |
| |
| @item |
| Preserve the network location, if any, given in the Document for |
| public access to a Transparent copy of the Document, and likewise |
| the network locations given in the Document for previous versions |
| it was based on. These may be placed in the “History” section. |
| You may omit a network location for a work that was published at |
| least four years before the Document itself, or if the original |
| publisher of the version it refers to gives permission. |
| |
| @item |
| For any section Entitled “Acknowledgements” or “Dedications”, |
| Preserve the Title of the section, and preserve in the section all |
| the substance and tone of each of the contributor acknowledgements |
| and/or dedications given therein. |
| |
| @item |
| Preserve all the Invariant Sections of the Document, |
| unaltered in their text and in their titles. Section numbers |
| or the equivalent are not considered part of the section titles. |
| |
| @item |
| Delete any section Entitled “Endorsements”. Such a section |
| may not be included in the Modified Version. |
| |
| @item |
| Do not retitle any existing section to be Entitled “Endorsements” |
| or to conflict in title with any Invariant Section. |
| |
| @item |
| Preserve any Warranty Disclaimers. |
| @end enumerate |
| |
| If the Modified Version includes new front-matter sections or |
| appendices that qualify as Secondary Sections and contain no material |
| copied from the Document, you may at your option designate some or all |
| of these sections as invariant. To do this, add their titles to the |
| list of Invariant Sections in the Modified Version’s license notice. |
| These titles must be distinct from any other section titles. |
| |
| You may add a section Entitled “Endorsements”, provided it contains |
| nothing but endorsements of your Modified Version by various |
| parties—for example, statements of peer review or that the text has |
| been approved by an organization as the authoritative definition of a |
| standard. |
| |
| You may add a passage of up to five words as a Front-Cover Text, and a |
| passage of up to 25 words as a Back-Cover Text, to the end of the list |
| of Cover Texts in the Modified Version. Only one passage of |
| Front-Cover Text and one of Back-Cover Text may be added by (or |
| through arrangements made by) any one entity. If the Document already |
| includes a cover text for the same cover, previously added by you or |
| by arrangement made by the same entity you are acting on behalf of, |
| you may not add another; but you may replace the old one, on explicit |
| permission from the previous publisher that added the old one. |
| |
| The author(s) and publisher(s) of the Document do not by this License |
| give permission to use their names for publicity for or to assert or |
| imply endorsement of any Modified Version. |
| |
| @strong{5. COMBINING DOCUMENTS} |
| |
| You may combine the Document with other documents released under this |
| License, under the terms defined in section 4 above for modified |
| versions, provided that you include in the combination all of the |
| Invariant Sections of all of the original documents, unmodified, and |
| list them all as Invariant Sections of your combined work in its |
| license notice, and that you preserve all their Warranty Disclaimers. |
| |
| The combined work need only contain one copy of this License, and |
| multiple identical Invariant Sections may be replaced with a single |
| copy. If there are multiple Invariant Sections with the same name but |
| different contents, make the title of each such section unique by |
| adding at the end of it, in parentheses, the name of the original |
| author or publisher of that section if known, or else a unique number. |
| Make the same adjustment to the section titles in the list of |
| Invariant Sections in the license notice of the combined work. |
| |
| In the combination, you must combine any sections Entitled “History” |
| in the various original documents, forming one section Entitled |
| “History”; likewise combine any sections Entitled “Acknowledgements”, |
| and any sections Entitled “Dedications”. You must delete all sections |
| Entitled “Endorsements”. |
| |
| @strong{6. COLLECTIONS OF DOCUMENTS} |
| |
| You may make a collection consisting of the Document and other documents |
| released under this License, and replace the individual copies of this |
| License in the various documents with a single copy that is included in |
| the collection, provided that you follow the rules of this License for |
| verbatim copying of each of the documents in all other respects. |
| |
| You may extract a single document from such a collection, and distribute |
| it individually under this License, provided you insert a copy of this |
| License into the extracted document, and follow this License in all |
| other respects regarding verbatim copying of that document. |
| |
| @strong{7. AGGREGATION WITH INDEPENDENT WORKS} |
| |
| A compilation of the Document or its derivatives with other separate |
| and independent documents or works, in or on a volume of a storage or |
| distribution medium, is called an “aggregate” if the copyright |
| resulting from the compilation is not used to limit the legal rights |
| of the compilation’s users beyond what the individual works permit. |
| When the Document is included in an aggregate, this License does not |
| apply to the other works in the aggregate which are not themselves |
| derivative works of the Document. |
| |
| If the Cover Text requirement of section 3 is applicable to these |
| copies of the Document, then if the Document is less than one half of |
| the entire aggregate, the Document’s Cover Texts may be placed on |
| covers that bracket the Document within the aggregate, or the |
| electronic equivalent of covers if the Document is in electronic form. |
| Otherwise they must appear on printed covers that bracket the whole |
| aggregate. |
| |
| @strong{8. TRANSLATION} |
| |
| Translation is considered a kind of modification, so you may |
| distribute translations of the Document under the terms of section 4. |
| Replacing Invariant Sections with translations requires special |
| permission from their copyright holders, but you may include |
| translations of some or all Invariant Sections in addition to the |
| original versions of these Invariant Sections. You may include a |
| translation of this License, and all the license notices in the |
| Document, and any Warranty Disclaimers, provided that you also include |
| the original English version of this License and the original versions |
| of those notices and disclaimers. In case of a disagreement between |
| the translation and the original version of this License or a notice |
| or disclaimer, the original version will prevail. |
| |
| If a section in the Document is Entitled “Acknowledgements”, |
| “Dedications”, or “History”, the requirement (section 4) to Preserve |
| its Title (section 1) will typically require changing the actual |
| title. |
| |
| @strong{9. TERMINATION} |
| |
| You may not copy, modify, sublicense, or distribute the Document |
| except as expressly provided under this License. Any attempt |
| otherwise to copy, modify, sublicense, or distribute it is void, and |
| will automatically terminate your rights under this License. |
| |
| However, if you cease all violation of this License, then your license |
| from a particular copyright holder is reinstated (a) provisionally, |
| unless and until the copyright holder explicitly and finally |
| terminates your license, and (b) permanently, if the copyright holder |
| fails to notify you of the violation by some reasonable means prior to |
| 60 days after the cessation. |
| |
| Moreover, your license from a particular copyright holder is |
| reinstated permanently if the copyright holder notifies you of the |
| violation by some reasonable means, this is the first time you have |
| received notice of violation of this License (for any work) from that |
| copyright holder, and you cure the violation prior to 30 days after |
| your receipt of the notice. |
| |
| Termination of your rights under this section does not terminate the |
| licenses of parties who have received copies or rights from you under |
| this License. If your rights have been terminated and not permanently |
| reinstated, receipt of a copy of some or all of the same material does |
| not give you any rights to use it. |
| |
| @strong{10. FUTURE REVISIONS OF THIS LICENSE} |
| |
| The Free Software Foundation may publish new, revised versions |
| of the GNU Free Documentation License from time to time. Such new |
| versions will be similar in spirit to the present version, but may |
| differ in detail to address new problems or concerns. See |
| @indicateurl{http://www.gnu.org/copyleft/}. |
| |
| Each version of the License is given a distinguishing version number. |
| If the Document specifies that a particular numbered version of this |
| License “or any later version” applies to it, you have the option of |
| following the terms and conditions either of that specified version or |
| of any later version that has been published (not as a draft) by the |
| Free Software Foundation. If the Document does not specify a version |
| number of this License, you may choose any version ever published (not |
| as a draft) by the Free Software Foundation. If the Document |
| specifies that a proxy can decide which future versions of this |
| License can be used, that proxy’s public statement of acceptance of a |
| version permanently authorizes you to choose that version for the |
| Document. |
| |
| @strong{11. RELICENSING} |
| |
| “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any |
| World Wide Web server that publishes copyrightable works and also |
| provides prominent facilities for anybody to edit those works. A |
| public wiki that anybody can edit is an example of such a server. A |
| “Massive Multiauthor Collaboration” (or “MMC”) contained in the |
| site means any set of copyrightable works thus published on the MMC |
| site. |
| |
| “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 |
| license published by Creative Commons Corporation, a not-for-profit |
| corporation with a principal place of business in San Francisco, |
| California, as well as future copyleft versions of that license |
| published by that same organization. |
| |
| “Incorporate” means to publish or republish a Document, in whole or |
| in part, as part of another Document. |
| |
| An MMC is “eligible for relicensing” if it is licensed under this |
| License, and if all works that were first published under this License |
| somewhere other than this MMC, and subsequently incorporated in whole |
| or in part into the MMC, (1) had no cover texts or invariant sections, |
| and (2) were thus incorporated prior to November 1, 2008. |
| |
| The operator of an MMC Site may republish an MMC contained in the site |
| under CC-BY-SA on the same site at any time before August 1, 2009, |
| provided the MMC is eligible for relicensing. |
| |
| @strong{ADDENDUM: How to use this License for your documents} |
| |
| To use this License in a document you have written, include a copy of |
| the License in the document and put the following copyright and |
| license notices just after the title page: |
| |
| @quotation |
| |
| Copyright © YEAR YOUR NAME. |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. |
| A copy of the license is included in the section entitled “GNU |
| Free Documentation License”. |
| @end quotation |
| |
| If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, |
| replace the “with … Texts.” line with this: |
| |
| @quotation |
| |
| with the Invariant Sections being LIST THEIR TITLES, with the |
| Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. |
| @end quotation |
| |
| If you have Invariant Sections without Cover Texts, or some other |
| combination of the three, merge those two alternatives to suit the |
| situation. |
| |
| If your document contains nontrivial examples of program code, we |
| recommend releasing these examples in parallel under your choice of |
| free software license, such as the GNU General Public License, |
| to permit their use in free software. |
| |
| @node Index,,GNU Free Documentation License,Top |
| @unnumbered Index |
| |
| |
| @printindex ge |
| |
| |
| @c %**end of body |
| @bye |
