1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gnat_rm.info 4@documentencoding UTF-8 5@ifinfo 6@*Generated by Sphinx 4.3.0.@* 7@end ifinfo 8@settitle GNAT Reference Manual 9@defindex ge 10@paragraphindent 0 11@exampleindent 4 12@finalout 13@dircategory GNU Ada Tools 14@direntry 15* gnat_rm: (gnat_rm.info). gnat_rm 16@end direntry 17 18@definfoenclose strong,`,' 19@definfoenclose emph,`,' 20@c %**end of header 21 22@copying 23@quotation 24GNAT Reference Manual , Nov 30, 2021 25 26AdaCore 27 28Copyright @copyright{} 2008-2021, Free Software Foundation 29@end quotation 30 31@end copying 32 33@titlepage 34@title GNAT Reference Manual 35@insertcopying 36@end titlepage 37@contents 38 39@c %** start of user preamble 40 41@c %** end of user preamble 42 43@ifnottex 44@node Top 45@top GNAT Reference Manual 46@insertcopying 47@end ifnottex 48 49@c %**start of body 50@anchor{gnat_rm doc}@anchor{0} 51@emph{GNAT, The GNU Ada Development Environment} 52 53 54@include gcc-common.texi 55GCC version @value{version-GCC}@* 56AdaCore 57 58Permission is granted to copy, distribute and/or modify this document 59under the terms of the GNU Free Documentation License, Version 1.3 or 60any later version published by the Free Software Foundation; with no 61Invariant Sections, with the Front-Cover Texts being “GNAT Reference 62Manual”, and with no Back-Cover Texts. A copy of the license is 63included in the section entitled @ref{1,,GNU Free Documentation License}. 64 65@menu 66* About This Guide:: 67* Implementation Defined Pragmas:: 68* Implementation Defined Aspects:: 69* Implementation Defined Attributes:: 70* Standard and Implementation Defined Restrictions:: 71* Implementation Advice:: 72* Implementation Defined Characteristics:: 73* Intrinsic Subprograms:: 74* Representation Clauses and Pragmas:: 75* Standard Library Routines:: 76* The Implementation of Standard I/O:: 77* The GNAT Library:: 78* Interfacing to Other Languages:: 79* Specialized Needs Annexes:: 80* Implementation of Specific Ada Features:: 81* Implementation of Ada 2012 Features:: 82* Security Hardening Features:: 83* Obsolescent Features:: 84* Compatibility and Porting Guide:: 85* GNU Free Documentation License:: 86* Index:: 87 88@detailmenu 89 --- The Detailed Node Listing --- 90 91About This Guide 92 93* What This Reference Manual Contains:: 94* Conventions:: 95* Related Information:: 96 97Implementation Defined Pragmas 98 99* Pragma Abort_Defer:: 100* Pragma Abstract_State:: 101* Pragma Ada_83:: 102* Pragma Ada_95:: 103* Pragma Ada_05:: 104* Pragma Ada_2005:: 105* Pragma Ada_12:: 106* Pragma Ada_2012:: 107* Pragma Aggregate_Individually_Assign:: 108* Pragma Allow_Integer_Address:: 109* Pragma Annotate:: 110* Pragma Assert:: 111* Pragma Assert_And_Cut:: 112* Pragma Assertion_Policy:: 113* Pragma Assume:: 114* Pragma Assume_No_Invalid_Values:: 115* Pragma Async_Readers:: 116* Pragma Async_Writers:: 117* Pragma Attribute_Definition:: 118* Pragma C_Pass_By_Copy:: 119* Pragma Check:: 120* Pragma Check_Float_Overflow:: 121* Pragma Check_Name:: 122* Pragma Check_Policy:: 123* Pragma Comment:: 124* Pragma Common_Object:: 125* Pragma Compile_Time_Error:: 126* Pragma Compile_Time_Warning:: 127* Pragma Compiler_Unit:: 128* Pragma Compiler_Unit_Warning:: 129* Pragma Complete_Representation:: 130* Pragma Complex_Representation:: 131* Pragma Component_Alignment:: 132* Pragma Constant_After_Elaboration:: 133* Pragma Contract_Cases:: 134* Pragma Convention_Identifier:: 135* Pragma CPP_Class:: 136* Pragma CPP_Constructor:: 137* Pragma CPP_Virtual:: 138* Pragma CPP_Vtable:: 139* Pragma CPU:: 140* Pragma Deadline_Floor:: 141* Pragma Default_Initial_Condition:: 142* Pragma Debug:: 143* Pragma Debug_Policy:: 144* Pragma Default_Scalar_Storage_Order:: 145* Pragma Default_Storage_Pool:: 146* Pragma Depends:: 147* Pragma Detect_Blocking:: 148* Pragma Disable_Atomic_Synchronization:: 149* Pragma Dispatching_Domain:: 150* Pragma Effective_Reads:: 151* Pragma Effective_Writes:: 152* Pragma Elaboration_Checks:: 153* Pragma Eliminate:: 154* Pragma Enable_Atomic_Synchronization:: 155* Pragma Export_Function:: 156* Pragma Export_Object:: 157* Pragma Export_Procedure:: 158* Pragma Export_Valued_Procedure:: 159* Pragma Extend_System:: 160* Pragma Extensions_Allowed:: 161* Pragma Extensions_Visible:: 162* Pragma External:: 163* Pragma External_Name_Casing:: 164* Pragma Fast_Math:: 165* Pragma Favor_Top_Level:: 166* Pragma Finalize_Storage_Only:: 167* Pragma Float_Representation:: 168* Pragma Ghost:: 169* Pragma Global:: 170* Pragma Ident:: 171* Pragma Ignore_Pragma:: 172* Pragma Implementation_Defined:: 173* Pragma Implemented:: 174* Pragma Implicit_Packing:: 175* Pragma Import_Function:: 176* Pragma Import_Object:: 177* Pragma Import_Procedure:: 178* Pragma Import_Valued_Procedure:: 179* Pragma Independent:: 180* Pragma Independent_Components:: 181* Pragma Initial_Condition:: 182* Pragma Initialize_Scalars:: 183* Pragma Initializes:: 184* Pragma Inline_Always:: 185* Pragma Inline_Generic:: 186* Pragma Interface:: 187* Pragma Interface_Name:: 188* Pragma Interrupt_Handler:: 189* Pragma Interrupt_State:: 190* Pragma Invariant:: 191* Pragma Keep_Names:: 192* Pragma License:: 193* Pragma Link_With:: 194* Pragma Linker_Alias:: 195* Pragma Linker_Constructor:: 196* Pragma Linker_Destructor:: 197* Pragma Linker_Section:: 198* Pragma Lock_Free:: 199* Pragma Loop_Invariant:: 200* Pragma Loop_Optimize:: 201* Pragma Loop_Variant:: 202* Pragma Machine_Attribute:: 203* Pragma Main:: 204* Pragma Main_Storage:: 205* Pragma Max_Queue_Length:: 206* Pragma No_Body:: 207* Pragma No_Caching:: 208* Pragma No_Component_Reordering:: 209* Pragma No_Elaboration_Code_All:: 210* Pragma No_Heap_Finalization:: 211* Pragma No_Inline:: 212* Pragma No_Return:: 213* Pragma No_Strict_Aliasing:: 214* Pragma No_Tagged_Streams:: 215* Pragma Normalize_Scalars:: 216* Pragma Obsolescent:: 217* Pragma Optimize_Alignment:: 218* Pragma Ordered:: 219* Pragma Overflow_Mode:: 220* Pragma Overriding_Renamings:: 221* Pragma Partition_Elaboration_Policy:: 222* Pragma Part_Of:: 223* Pragma Passive:: 224* Pragma Persistent_BSS:: 225* Pragma Post:: 226* Pragma Postcondition:: 227* Pragma Post_Class:: 228* Pragma Pre:: 229* Pragma Precondition:: 230* Pragma Predicate:: 231* Pragma Predicate_Failure:: 232* Pragma Preelaborable_Initialization:: 233* Pragma Prefix_Exception_Messages:: 234* Pragma Pre_Class:: 235* Pragma Priority_Specific_Dispatching:: 236* Pragma Profile:: 237* Pragma Profile_Warnings:: 238* Pragma Propagate_Exceptions:: 239* Pragma Provide_Shift_Operators:: 240* Pragma Psect_Object:: 241* Pragma Pure_Function:: 242* Pragma Rational:: 243* Pragma Ravenscar:: 244* Pragma Refined_Depends:: 245* Pragma Refined_Global:: 246* Pragma Refined_Post:: 247* Pragma Refined_State:: 248* Pragma Relative_Deadline:: 249* Pragma Remote_Access_Type:: 250* Pragma Rename_Pragma:: 251* Pragma Restricted_Run_Time:: 252* Pragma Restriction_Warnings:: 253* Pragma Reviewable:: 254* Pragma Secondary_Stack_Size:: 255* Pragma Share_Generic:: 256* Pragma Shared:: 257* Pragma Short_Circuit_And_Or:: 258* Pragma Short_Descriptors:: 259* Pragma Simple_Storage_Pool_Type:: 260* Pragma Source_File_Name:: 261* Pragma Source_File_Name_Project:: 262* Pragma Source_Reference:: 263* Pragma SPARK_Mode:: 264* Pragma Static_Elaboration_Desired:: 265* Pragma Stream_Convert:: 266* Pragma Style_Checks:: 267* Pragma Subtitle:: 268* Pragma Suppress:: 269* Pragma Suppress_All:: 270* Pragma Suppress_Debug_Info:: 271* Pragma Suppress_Exception_Locations:: 272* Pragma Suppress_Initialization:: 273* Pragma Task_Name:: 274* Pragma Task_Storage:: 275* Pragma Test_Case:: 276* Pragma Thread_Local_Storage:: 277* Pragma Time_Slice:: 278* Pragma Title:: 279* Pragma Type_Invariant:: 280* Pragma Type_Invariant_Class:: 281* Pragma Unchecked_Union:: 282* Pragma Unevaluated_Use_Of_Old:: 283* Pragma Unimplemented_Unit:: 284* Pragma Universal_Aliasing:: 285* Pragma Unmodified:: 286* Pragma Unreferenced:: 287* Pragma Unreferenced_Objects:: 288* Pragma Unreserve_All_Interrupts:: 289* Pragma Unsuppress:: 290* Pragma Use_VADS_Size:: 291* Pragma Unused:: 292* Pragma Validity_Checks:: 293* Pragma Volatile:: 294* Pragma Volatile_Full_Access:: 295* Pragma Volatile_Function:: 296* Pragma Warning_As_Error:: 297* Pragma Warnings:: 298* Pragma Weak_External:: 299* Pragma Wide_Character_Encoding:: 300 301Implementation Defined Aspects 302 303* Aspect Abstract_State:: 304* Aspect Annotate:: 305* Aspect Async_Readers:: 306* Aspect Async_Writers:: 307* Aspect Constant_After_Elaboration:: 308* Aspect Contract_Cases:: 309* Aspect Depends:: 310* Aspect Default_Initial_Condition:: 311* Aspect Dimension:: 312* Aspect Dimension_System:: 313* Aspect Disable_Controlled:: 314* Aspect Effective_Reads:: 315* Aspect Effective_Writes:: 316* Aspect Extensions_Visible:: 317* Aspect Favor_Top_Level:: 318* Aspect Ghost:: 319* Aspect Global:: 320* Aspect Initial_Condition:: 321* Aspect Initializes:: 322* Aspect Inline_Always:: 323* Aspect Invariant:: 324* Aspect Invariant’Class:: 325* Aspect Iterable:: 326* Aspect Linker_Section:: 327* Aspect Lock_Free:: 328* Aspect Max_Queue_Length:: 329* Aspect No_Caching:: 330* Aspect No_Elaboration_Code_All:: 331* Aspect No_Inline:: 332* Aspect No_Tagged_Streams:: 333* Aspect No_Task_Parts:: 334* Aspect Object_Size:: 335* Aspect Obsolescent:: 336* Aspect Part_Of:: 337* Aspect Persistent_BSS:: 338* Aspect Predicate:: 339* Aspect Pure_Function:: 340* Aspect Refined_Depends:: 341* Aspect Refined_Global:: 342* Aspect Refined_Post:: 343* Aspect Refined_State:: 344* Aspect Relaxed_Initialization:: 345* Aspect Remote_Access_Type:: 346* Aspect Secondary_Stack_Size:: 347* Aspect Scalar_Storage_Order:: 348* Aspect Shared:: 349* Aspect Simple_Storage_Pool:: 350* Aspect Simple_Storage_Pool_Type:: 351* Aspect SPARK_Mode:: 352* Aspect Suppress_Debug_Info:: 353* Aspect Suppress_Initialization:: 354* Aspect Test_Case:: 355* Aspect Thread_Local_Storage:: 356* Aspect Universal_Aliasing:: 357* Aspect Unmodified:: 358* Aspect Unreferenced:: 359* Aspect Unreferenced_Objects:: 360* Aspect Value_Size:: 361* Aspect Volatile_Full_Access:: 362* Aspect Volatile_Function:: 363* Aspect Warnings:: 364 365Implementation Defined Attributes 366 367* Attribute Abort_Signal:: 368* Attribute Address_Size:: 369* Attribute Asm_Input:: 370* Attribute Asm_Output:: 371* Attribute Atomic_Always_Lock_Free:: 372* Attribute Bit:: 373* Attribute Bit_Position:: 374* Attribute Code_Address:: 375* Attribute Compiler_Version:: 376* Attribute Constrained:: 377* Attribute Default_Bit_Order:: 378* Attribute Default_Scalar_Storage_Order:: 379* Attribute Deref:: 380* Attribute Descriptor_Size:: 381* Attribute Elaborated:: 382* Attribute Elab_Body:: 383* Attribute Elab_Spec:: 384* Attribute Elab_Subp_Body:: 385* Attribute Emax:: 386* Attribute Enabled:: 387* Attribute Enum_Rep:: 388* Attribute Enum_Val:: 389* Attribute Epsilon:: 390* Attribute Fast_Math:: 391* Attribute Finalization_Size:: 392* Attribute Fixed_Value:: 393* Attribute From_Any:: 394* Attribute Has_Access_Values:: 395* Attribute Has_Discriminants:: 396* Attribute Has_Tagged_Values:: 397* Attribute Img:: 398* Attribute Initialized:: 399* Attribute Integer_Value:: 400* Attribute Invalid_Value:: 401* Attribute Iterable:: 402* Attribute Large:: 403* Attribute Library_Level:: 404* Attribute Lock_Free:: 405* Attribute Loop_Entry:: 406* Attribute Machine_Size:: 407* Attribute Mantissa:: 408* Attribute Maximum_Alignment:: 409* Attribute Max_Integer_Size:: 410* Attribute Mechanism_Code:: 411* Attribute Null_Parameter:: 412* Attribute Object_Size:: 413* Attribute Old:: 414* Attribute Passed_By_Reference:: 415* Attribute Pool_Address:: 416* Attribute Range_Length:: 417* Attribute Restriction_Set:: 418* Attribute Result:: 419* Attribute Safe_Emax:: 420* Attribute Safe_Large:: 421* Attribute Safe_Small:: 422* Attribute Scalar_Storage_Order:: 423* Attribute Simple_Storage_Pool:: 424* Attribute Small:: 425* Attribute Small_Denominator:: 426* Attribute Small_Numerator:: 427* Attribute Storage_Unit:: 428* Attribute Stub_Type:: 429* Attribute System_Allocator_Alignment:: 430* Attribute Target_Name:: 431* Attribute To_Address:: 432* Attribute To_Any:: 433* Attribute Type_Class:: 434* Attribute Type_Key:: 435* Attribute TypeCode:: 436* Attribute Unconstrained_Array:: 437* Attribute Universal_Literal_String:: 438* Attribute Unrestricted_Access:: 439* Attribute Update:: 440* Attribute Valid_Image:: 441* Attribute Valid_Scalars:: 442* Attribute VADS_Size:: 443* Attribute Value_Size:: 444* Attribute Wchar_T_Size:: 445* Attribute Word_Size:: 446 447Standard and Implementation Defined Restrictions 448 449* Partition-Wide Restrictions:: 450* Program Unit Level Restrictions:: 451 452Partition-Wide Restrictions 453 454* Immediate_Reclamation:: 455* Max_Asynchronous_Select_Nesting:: 456* Max_Entry_Queue_Length:: 457* Max_Protected_Entries:: 458* Max_Select_Alternatives:: 459* Max_Storage_At_Blocking:: 460* Max_Task_Entries:: 461* Max_Tasks:: 462* No_Abort_Statements:: 463* No_Access_Parameter_Allocators:: 464* No_Access_Subprograms:: 465* No_Allocators:: 466* No_Anonymous_Allocators:: 467* No_Asynchronous_Control:: 468* No_Calendar:: 469* No_Coextensions:: 470* No_Default_Initialization:: 471* No_Delay:: 472* No_Dependence:: 473* No_Direct_Boolean_Operators:: 474* No_Dispatch:: 475* No_Dispatching_Calls:: 476* No_Dynamic_Attachment:: 477* No_Dynamic_Priorities:: 478* No_Entry_Calls_In_Elaboration_Code:: 479* No_Enumeration_Maps:: 480* No_Exception_Handlers:: 481* No_Exception_Propagation:: 482* No_Exception_Registration:: 483* No_Exceptions:: 484* No_Finalization:: 485* No_Fixed_Point:: 486* No_Floating_Point:: 487* No_Implicit_Conditionals:: 488* No_Implicit_Dynamic_Code:: 489* No_Implicit_Heap_Allocations:: 490* No_Implicit_Protected_Object_Allocations:: 491* No_Implicit_Task_Allocations:: 492* No_Initialize_Scalars:: 493* No_IO:: 494* No_Local_Allocators:: 495* No_Local_Protected_Objects:: 496* No_Local_Timing_Events:: 497* No_Long_Long_Integers:: 498* No_Multiple_Elaboration:: 499* No_Nested_Finalization:: 500* No_Protected_Type_Allocators:: 501* No_Protected_Types:: 502* No_Recursion:: 503* No_Reentrancy:: 504* No_Relative_Delay:: 505* No_Requeue_Statements:: 506* No_Secondary_Stack:: 507* No_Select_Statements:: 508* No_Specific_Termination_Handlers:: 509* No_Specification_of_Aspect:: 510* No_Standard_Allocators_After_Elaboration:: 511* No_Standard_Storage_Pools:: 512* No_Stream_Optimizations:: 513* No_Streams:: 514* No_Task_Allocators:: 515* No_Task_At_Interrupt_Priority:: 516* No_Task_Attributes_Package:: 517* No_Task_Hierarchy:: 518* No_Task_Termination:: 519* No_Tasking:: 520* No_Terminate_Alternatives:: 521* No_Unchecked_Access:: 522* No_Unchecked_Conversion:: 523* No_Unchecked_Deallocation:: 524* No_Use_Of_Entity:: 525* Pure_Barriers:: 526* Simple_Barriers:: 527* Static_Priorities:: 528* Static_Storage_Size:: 529 530Program Unit Level Restrictions 531 532* No_Elaboration_Code:: 533* No_Dynamic_Accessibility_Checks:: 534* No_Dynamic_Sized_Objects:: 535* No_Entry_Queue:: 536* No_Implementation_Aspect_Specifications:: 537* No_Implementation_Attributes:: 538* No_Implementation_Identifiers:: 539* No_Implementation_Pragmas:: 540* No_Implementation_Restrictions:: 541* No_Implementation_Units:: 542* No_Implicit_Aliasing:: 543* No_Implicit_Loops:: 544* No_Obsolescent_Features:: 545* No_Wide_Characters:: 546* Static_Dispatch_Tables:: 547* SPARK_05:: 548 549Implementation Advice 550 551* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 552* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 553* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 554* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 555* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 556* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 557* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 558* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 559* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 560* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 561* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 562* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. 563* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 564* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 565* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 566* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 567* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 568* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 569* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 570* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 571* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 572* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 573* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 574* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 575* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 576* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 577* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 578* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 579* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 580* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 581* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 582* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 583* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 584* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 585* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 586* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 587* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 588* RM A.18; Containers: RM A 18 Containers. 589* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 590* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 591* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 592* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 593* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 594* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 595* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 596* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 597* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 598* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 599* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 600* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 601* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 602* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 603* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 604* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 605* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 606* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 607* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 608* RM F(7); COBOL Support: RM F 7 COBOL Support. 609* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 610* RM G; Numerics: RM G Numerics. 611* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 612* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 613* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 614* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 615* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 616 617Intrinsic Subprograms 618 619* Intrinsic Operators:: 620* Compilation_ISO_Date:: 621* Compilation_Date:: 622* Compilation_Time:: 623* Enclosing_Entity:: 624* Exception_Information:: 625* Exception_Message:: 626* Exception_Name:: 627* File:: 628* Line:: 629* Shifts and Rotates:: 630* Source_Location:: 631 632Representation Clauses and Pragmas 633 634* Alignment Clauses:: 635* Size Clauses:: 636* Storage_Size Clauses:: 637* Size of Variant Record Objects:: 638* Biased Representation:: 639* Value_Size and Object_Size Clauses:: 640* Component_Size Clauses:: 641* Bit_Order Clauses:: 642* Effect of Bit_Order on Byte Ordering:: 643* Pragma Pack for Arrays:: 644* Pragma Pack for Records:: 645* Record Representation Clauses:: 646* Handling of Records with Holes:: 647* Enumeration Clauses:: 648* Address Clauses:: 649* Use of Address Clauses for Memory-Mapped I/O:: 650* Effect of Convention on Representation:: 651* Conventions and Anonymous Access Types:: 652* Determining the Representations chosen by GNAT:: 653 654The Implementation of Standard I/O 655 656* Standard I/O Packages:: 657* FORM Strings:: 658* Direct_IO:: 659* Sequential_IO:: 660* Text_IO:: 661* Wide_Text_IO:: 662* Wide_Wide_Text_IO:: 663* Stream_IO:: 664* Text Translation:: 665* Shared Files:: 666* Filenames encoding:: 667* File content encoding:: 668* Open Modes:: 669* Operations on C Streams:: 670* Interfacing to C Streams:: 671 672Text_IO 673 674* Stream Pointer Positioning:: 675* Reading and Writing Non-Regular Files:: 676* Get_Immediate:: 677* Treating Text_IO Files as Streams:: 678* Text_IO Extensions:: 679* Text_IO Facilities for Unbounded Strings:: 680 681Wide_Text_IO 682 683* Stream Pointer Positioning: Stream Pointer Positioning<2>. 684* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 685 686Wide_Wide_Text_IO 687 688* Stream Pointer Positioning: Stream Pointer Positioning<3>. 689* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 690 691The GNAT Library 692 693* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 694* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 695* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 696* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 697* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 698* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 699* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 700* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 701* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 702* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 703* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 704* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 705* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 706* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 707* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 708* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 709* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 710* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 711* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 712* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 713* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 714* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 715* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 716* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 717* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 718* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 719* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 720* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 721* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. 722* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 723* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 724* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 725* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 726* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 727* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 728* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 729* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 730* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 731* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 732* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 733* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 734* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 735* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 736* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 737* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 738* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 739* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 740* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 741* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 742* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 743* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 744* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 745* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 746* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 747* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 748* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 749* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 750* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 751* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 752* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 753* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 754* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 755* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 756* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 757* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 758* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 759* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 760* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 761* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 762* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 763* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 764* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 765* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 766* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 767* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 768* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 769* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 770* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 771* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 772* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 773* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 774* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 775* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 776* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 777* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 778* GNAT.IO (g-io.ads): GNAT IO g-io ads. 779* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 780* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 781* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 782* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 783* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 784* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 785* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 786* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 787* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 788* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 789* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 790* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 791* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 792* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 793* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 794* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 795* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 796* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 797* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 798* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 799* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 800* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 801* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 802* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 803* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 804* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 805* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 806* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 807* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 808* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 809* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 810* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 811* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 812* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 813* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 814* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 815* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 816* GNAT.Table (g-table.ads): GNAT Table g-table ads. 817* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 818* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 819* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 820* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 821* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 822* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 823* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 824* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 825* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 826* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 827* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 828* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 829* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 830* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 831* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 832* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 833* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 834* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 835* System.Assertions (s-assert.ads): System Assertions s-assert ads. 836* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 837* System.Memory (s-memory.ads): System Memory s-memory ads. 838* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 839* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 840* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 841* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 842* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 843* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 844* System.Rident (s-rident.ads): System Rident s-rident ads. 845* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 846* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 847* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 848* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 849 850Interfacing to Other Languages 851 852* Interfacing to C:: 853* Interfacing to C++:: 854* Interfacing to COBOL:: 855* Interfacing to Fortran:: 856* Interfacing to non-GNAT Ada code:: 857 858Implementation of Specific Ada Features 859 860* Machine Code Insertions:: 861* GNAT Implementation of Tasking:: 862* GNAT Implementation of Shared Passive Packages:: 863* Code Generation for Array Aggregates:: 864* The Size of Discriminated Records with Default Discriminants:: 865* Image Values For Nonscalar Types:: 866* Strict Conformance to the Ada Reference Manual:: 867 868GNAT Implementation of Tasking 869 870* Mapping Ada Tasks onto the Underlying Kernel Threads:: 871* Ensuring Compliance with the Real-Time Annex:: 872* Support for Locking Policies:: 873 874Code Generation for Array Aggregates 875 876* Static constant aggregates with static bounds:: 877* Constant aggregates with unconstrained nominal types:: 878* Aggregates with static bounds:: 879* Aggregates with nonstatic bounds:: 880* Aggregates in assignment statements:: 881 882Security Hardening Features 883 884* Register Scrubbing:: 885* Stack Scrubbing:: 886* Hardened Conditionals:: 887 888Obsolescent Features 889 890* pragma No_Run_Time:: 891* pragma Ravenscar:: 892* pragma Restricted_Run_Time:: 893* pragma Task_Info:: 894* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 895 896Compatibility and Porting Guide 897 898* Writing Portable Fixed-Point Declarations:: 899* Compatibility with Ada 83:: 900* Compatibility between Ada 95 and Ada 2005:: 901* Implementation-dependent characteristics:: 902* Compatibility with Other Ada Systems:: 903* Representation Clauses:: 904* Compatibility with HP Ada 83:: 905 906Compatibility with Ada 83 907 908* Legal Ada 83 programs that are illegal in Ada 95:: 909* More deterministic semantics:: 910* Changed semantics:: 911* Other language compatibility issues:: 912 913Implementation-dependent characteristics 914 915* Implementation-defined pragmas:: 916* Implementation-defined attributes:: 917* Libraries:: 918* Elaboration order:: 919* Target-specific aspects:: 920 921@end detailmenu 922@end menu 923 924@node About This Guide,Implementation Defined Pragmas,Top,Top 925@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} 926@chapter About This Guide 927 928 929 930This manual contains useful information in writing programs using the 931GNAT compiler. It includes information on implementation dependent 932characteristics of GNAT, including all the information required by 933Annex M of the Ada language standard. 934 935GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be 936invoked in Ada 83 compatibility mode. 937By default, GNAT assumes Ada 2012, 938but you can override with a compiler switch 939to explicitly specify the language version. 940(Please refer to the @emph{GNAT User’s Guide} for details on these switches.) 941Throughout this manual, references to ‘Ada’ without a year suffix 942apply to all the Ada versions of the language. 943 944Ada is designed to be highly portable. 945In general, a program will have the same effect even when compiled by 946different compilers on different platforms. 947However, since Ada is designed to be used in a 948wide variety of applications, it also contains a number of system 949dependent features to be used in interfacing to the external world. 950 951@geindex Implementation-dependent features 952 953@geindex Portability 954 955Note: Any program that makes use of implementation-dependent features 956may be non-portable. You should follow good programming practice and 957isolate and clearly document any sections of your program that make use 958of these features in a non-portable manner. 959 960@menu 961* What This Reference Manual Contains:: 962* Conventions:: 963* Related Information:: 964 965@end menu 966 967@node What This Reference Manual Contains,Conventions,,About This Guide 968@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} 969@section What This Reference Manual Contains 970 971 972This reference manual contains the following chapters: 973 974 975@itemize * 976 977@item 978@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent 979pragmas, which can be used to extend and enhance the functionality of the 980compiler. 981 982@item 983@ref{8,,Implementation Defined Attributes}, lists GNAT 984implementation-dependent attributes, which can be used to extend and 985enhance the functionality of the compiler. 986 987@item 988@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT 989implementation-dependent restrictions, which can be used to extend and 990enhance the functionality of the compiler. 991 992@item 993@ref{a,,Implementation Advice}, provides information on generally 994desirable behavior which are not requirements that all compilers must 995follow since it cannot be provided on all systems, or which may be 996undesirable on some systems. 997 998@item 999@ref{b,,Implementation Defined Characteristics}, provides a guide to 1000minimizing implementation dependent features. 1001 1002@item 1003@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms 1004implemented by GNAT, and how they can be imported into user 1005application programs. 1006 1007@item 1008@ref{d,,Representation Clauses and Pragmas}, describes in detail the 1009way that GNAT represents data, and in particular the exact set 1010of representation clauses and pragmas that is accepted. 1011 1012@item 1013@ref{e,,Standard Library Routines}, provides a listing of packages and a 1014brief description of the functionality that is provided by Ada’s 1015extensive set of standard library routines as implemented by GNAT. 1016 1017@item 1018@ref{f,,The Implementation of Standard I/O}, details how the GNAT 1019implementation of the input-output facilities. 1020 1021@item 1022@ref{10,,The GNAT Library}, is a catalog of packages that complement 1023the Ada predefined library. 1024 1025@item 1026@ref{11,,Interfacing to Other Languages}, describes how programs 1027written in Ada using GNAT can be interfaced to other programming 1028languages. 1029 1030@item 1031@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all 1032of the specialized needs annexes. 1033 1034@item 1035@ref{13,,Implementation of Specific Ada Features}, discusses issues related 1036to GNAT’s implementation of machine code insertions, tasking, and several 1037other features. 1038 1039@item 1040@ref{14,,Implementation of Ada 2012 Features}, describes the status of the 1041GNAT implementation of the Ada 2012 language standard. 1042 1043@item 1044@ref{15,,Security Hardening Features} documents GNAT extensions aimed 1045at security hardening. 1046 1047@item 1048@ref{16,,Obsolescent Features} documents implementation dependent features, 1049including pragmas and attributes, which are considered obsolescent, since 1050there are other preferred ways of achieving the same results. These 1051obsolescent forms are retained for backwards compatibility. 1052 1053@item 1054@ref{17,,Compatibility and Porting Guide} presents some guidelines for 1055developing portable Ada code, describes the compatibility issues that 1056may arise between GNAT and other Ada compilation systems (including those 1057for Ada 83), and shows how GNAT can expedite porting applications 1058developed in other Ada environments. 1059 1060@item 1061@ref{1,,GNU Free Documentation License} contains the license for this document. 1062@end itemize 1063 1064@geindex Ada 95 Language Reference Manual 1065 1066@geindex Ada 2005 Language Reference Manual 1067 1068This reference manual assumes a basic familiarity with the Ada 95 language, as 1069described in the 1070@cite{International Standard ANSI/ISO/IEC-8652:1995}. 1071It does not require knowledge of the new features introduced by Ada 2005 or 1072Ada 2012. 1073All three reference manuals are included in the GNAT documentation 1074package. 1075 1076@node Conventions,Related Information,What This Reference Manual Contains,About This Guide 1077@anchor{gnat_rm/about_this_guide conventions}@anchor{18} 1078@section Conventions 1079 1080 1081@geindex Conventions 1082@geindex typographical 1083 1084@geindex Typographical conventions 1085 1086Following are examples of the typographical and graphic conventions used 1087in this guide: 1088 1089 1090@itemize * 1091 1092@item 1093@code{Functions}, @code{utility program names}, @code{standard names}, 1094and @code{classes}. 1095 1096@item 1097@code{Option flags} 1098 1099@item 1100@code{File names} 1101 1102@item 1103@code{Variables} 1104 1105@item 1106@emph{Emphasis} 1107 1108@item 1109[optional information or parameters] 1110 1111@item 1112Examples are described by text 1113 1114@example 1115and then shown this way. 1116@end example 1117 1118@item 1119Commands that are entered by the user are shown as preceded by a prompt string 1120comprising the @code{$} character followed by a space. 1121@end itemize 1122 1123@node Related Information,,Conventions,About This Guide 1124@anchor{gnat_rm/about_this_guide related-information}@anchor{19} 1125@section Related Information 1126 1127 1128See the following documents for further information on GNAT: 1129 1130 1131@itemize * 1132 1133@item 1134@cite{GNAT User’s Guide for Native Platforms}, 1135which provides information on how to use the 1136GNAT development environment. 1137 1138@item 1139@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. 1140 1141@item 1142@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 1143of the Ada 95 standard. The annotations describe 1144detailed aspects of the design decision, and in particular contain useful 1145sections on Ada 83 compatibility. 1146 1147@item 1148@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. 1149 1150@item 1151@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 1152of the Ada 2005 standard. The annotations describe 1153detailed aspects of the design decision. 1154 1155@item 1156@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. 1157 1158@item 1159@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, 1160which contains specific information on compatibility between GNAT and 1161DEC Ada 83 systems. 1162 1163@item 1164@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which 1165describes in detail the pragmas and attributes provided by the DEC Ada 83 1166compiler system. 1167@end itemize 1168 1169@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top 1170@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} 1171@chapter Implementation Defined Pragmas 1172 1173 1174Ada defines a set of pragmas that can be used to supply additional 1175information to the compiler. These language defined pragmas are 1176implemented in GNAT and work as described in the Ada Reference Manual. 1177 1178In addition, Ada allows implementations to define additional pragmas 1179whose meaning is defined by the implementation. GNAT provides a number 1180of these implementation-defined pragmas, which can be used to extend 1181and enhance the functionality of the compiler. This section of the GNAT 1182Reference Manual describes these additional pragmas. 1183 1184Note that any program using these pragmas might not be portable to other 1185compilers (although GNAT implements this set of pragmas on all 1186platforms). Therefore if portability to other compilers is an important 1187consideration, the use of these pragmas should be minimized. 1188 1189@menu 1190* Pragma Abort_Defer:: 1191* Pragma Abstract_State:: 1192* Pragma Ada_83:: 1193* Pragma Ada_95:: 1194* Pragma Ada_05:: 1195* Pragma Ada_2005:: 1196* Pragma Ada_12:: 1197* Pragma Ada_2012:: 1198* Pragma Aggregate_Individually_Assign:: 1199* Pragma Allow_Integer_Address:: 1200* Pragma Annotate:: 1201* Pragma Assert:: 1202* Pragma Assert_And_Cut:: 1203* Pragma Assertion_Policy:: 1204* Pragma Assume:: 1205* Pragma Assume_No_Invalid_Values:: 1206* Pragma Async_Readers:: 1207* Pragma Async_Writers:: 1208* Pragma Attribute_Definition:: 1209* Pragma C_Pass_By_Copy:: 1210* Pragma Check:: 1211* Pragma Check_Float_Overflow:: 1212* Pragma Check_Name:: 1213* Pragma Check_Policy:: 1214* Pragma Comment:: 1215* Pragma Common_Object:: 1216* Pragma Compile_Time_Error:: 1217* Pragma Compile_Time_Warning:: 1218* Pragma Compiler_Unit:: 1219* Pragma Compiler_Unit_Warning:: 1220* Pragma Complete_Representation:: 1221* Pragma Complex_Representation:: 1222* Pragma Component_Alignment:: 1223* Pragma Constant_After_Elaboration:: 1224* Pragma Contract_Cases:: 1225* Pragma Convention_Identifier:: 1226* Pragma CPP_Class:: 1227* Pragma CPP_Constructor:: 1228* Pragma CPP_Virtual:: 1229* Pragma CPP_Vtable:: 1230* Pragma CPU:: 1231* Pragma Deadline_Floor:: 1232* Pragma Default_Initial_Condition:: 1233* Pragma Debug:: 1234* Pragma Debug_Policy:: 1235* Pragma Default_Scalar_Storage_Order:: 1236* Pragma Default_Storage_Pool:: 1237* Pragma Depends:: 1238* Pragma Detect_Blocking:: 1239* Pragma Disable_Atomic_Synchronization:: 1240* Pragma Dispatching_Domain:: 1241* Pragma Effective_Reads:: 1242* Pragma Effective_Writes:: 1243* Pragma Elaboration_Checks:: 1244* Pragma Eliminate:: 1245* Pragma Enable_Atomic_Synchronization:: 1246* Pragma Export_Function:: 1247* Pragma Export_Object:: 1248* Pragma Export_Procedure:: 1249* Pragma Export_Valued_Procedure:: 1250* Pragma Extend_System:: 1251* Pragma Extensions_Allowed:: 1252* Pragma Extensions_Visible:: 1253* Pragma External:: 1254* Pragma External_Name_Casing:: 1255* Pragma Fast_Math:: 1256* Pragma Favor_Top_Level:: 1257* Pragma Finalize_Storage_Only:: 1258* Pragma Float_Representation:: 1259* Pragma Ghost:: 1260* Pragma Global:: 1261* Pragma Ident:: 1262* Pragma Ignore_Pragma:: 1263* Pragma Implementation_Defined:: 1264* Pragma Implemented:: 1265* Pragma Implicit_Packing:: 1266* Pragma Import_Function:: 1267* Pragma Import_Object:: 1268* Pragma Import_Procedure:: 1269* Pragma Import_Valued_Procedure:: 1270* Pragma Independent:: 1271* Pragma Independent_Components:: 1272* Pragma Initial_Condition:: 1273* Pragma Initialize_Scalars:: 1274* Pragma Initializes:: 1275* Pragma Inline_Always:: 1276* Pragma Inline_Generic:: 1277* Pragma Interface:: 1278* Pragma Interface_Name:: 1279* Pragma Interrupt_Handler:: 1280* Pragma Interrupt_State:: 1281* Pragma Invariant:: 1282* Pragma Keep_Names:: 1283* Pragma License:: 1284* Pragma Link_With:: 1285* Pragma Linker_Alias:: 1286* Pragma Linker_Constructor:: 1287* Pragma Linker_Destructor:: 1288* Pragma Linker_Section:: 1289* Pragma Lock_Free:: 1290* Pragma Loop_Invariant:: 1291* Pragma Loop_Optimize:: 1292* Pragma Loop_Variant:: 1293* Pragma Machine_Attribute:: 1294* Pragma Main:: 1295* Pragma Main_Storage:: 1296* Pragma Max_Queue_Length:: 1297* Pragma No_Body:: 1298* Pragma No_Caching:: 1299* Pragma No_Component_Reordering:: 1300* Pragma No_Elaboration_Code_All:: 1301* Pragma No_Heap_Finalization:: 1302* Pragma No_Inline:: 1303* Pragma No_Return:: 1304* Pragma No_Strict_Aliasing:: 1305* Pragma No_Tagged_Streams:: 1306* Pragma Normalize_Scalars:: 1307* Pragma Obsolescent:: 1308* Pragma Optimize_Alignment:: 1309* Pragma Ordered:: 1310* Pragma Overflow_Mode:: 1311* Pragma Overriding_Renamings:: 1312* Pragma Partition_Elaboration_Policy:: 1313* Pragma Part_Of:: 1314* Pragma Passive:: 1315* Pragma Persistent_BSS:: 1316* Pragma Post:: 1317* Pragma Postcondition:: 1318* Pragma Post_Class:: 1319* Pragma Pre:: 1320* Pragma Precondition:: 1321* Pragma Predicate:: 1322* Pragma Predicate_Failure:: 1323* Pragma Preelaborable_Initialization:: 1324* Pragma Prefix_Exception_Messages:: 1325* Pragma Pre_Class:: 1326* Pragma Priority_Specific_Dispatching:: 1327* Pragma Profile:: 1328* Pragma Profile_Warnings:: 1329* Pragma Propagate_Exceptions:: 1330* Pragma Provide_Shift_Operators:: 1331* Pragma Psect_Object:: 1332* Pragma Pure_Function:: 1333* Pragma Rational:: 1334* Pragma Ravenscar:: 1335* Pragma Refined_Depends:: 1336* Pragma Refined_Global:: 1337* Pragma Refined_Post:: 1338* Pragma Refined_State:: 1339* Pragma Relative_Deadline:: 1340* Pragma Remote_Access_Type:: 1341* Pragma Rename_Pragma:: 1342* Pragma Restricted_Run_Time:: 1343* Pragma Restriction_Warnings:: 1344* Pragma Reviewable:: 1345* Pragma Secondary_Stack_Size:: 1346* Pragma Share_Generic:: 1347* Pragma Shared:: 1348* Pragma Short_Circuit_And_Or:: 1349* Pragma Short_Descriptors:: 1350* Pragma Simple_Storage_Pool_Type:: 1351* Pragma Source_File_Name:: 1352* Pragma Source_File_Name_Project:: 1353* Pragma Source_Reference:: 1354* Pragma SPARK_Mode:: 1355* Pragma Static_Elaboration_Desired:: 1356* Pragma Stream_Convert:: 1357* Pragma Style_Checks:: 1358* Pragma Subtitle:: 1359* Pragma Suppress:: 1360* Pragma Suppress_All:: 1361* Pragma Suppress_Debug_Info:: 1362* Pragma Suppress_Exception_Locations:: 1363* Pragma Suppress_Initialization:: 1364* Pragma Task_Name:: 1365* Pragma Task_Storage:: 1366* Pragma Test_Case:: 1367* Pragma Thread_Local_Storage:: 1368* Pragma Time_Slice:: 1369* Pragma Title:: 1370* Pragma Type_Invariant:: 1371* Pragma Type_Invariant_Class:: 1372* Pragma Unchecked_Union:: 1373* Pragma Unevaluated_Use_Of_Old:: 1374* Pragma Unimplemented_Unit:: 1375* Pragma Universal_Aliasing:: 1376* Pragma Unmodified:: 1377* Pragma Unreferenced:: 1378* Pragma Unreferenced_Objects:: 1379* Pragma Unreserve_All_Interrupts:: 1380* Pragma Unsuppress:: 1381* Pragma Use_VADS_Size:: 1382* Pragma Unused:: 1383* Pragma Validity_Checks:: 1384* Pragma Volatile:: 1385* Pragma Volatile_Full_Access:: 1386* Pragma Volatile_Function:: 1387* Pragma Warning_As_Error:: 1388* Pragma Warnings:: 1389* Pragma Weak_External:: 1390* Pragma Wide_Character_Encoding:: 1391 1392@end menu 1393 1394@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas 1395@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c} 1396@section Pragma Abort_Defer 1397 1398 1399@geindex Deferring aborts 1400 1401Syntax: 1402 1403@example 1404pragma Abort_Defer; 1405@end example 1406 1407This pragma must appear at the start of the statement sequence of a 1408handled sequence of statements (right after the @code{begin}). It has 1409the effect of deferring aborts for the sequence of statements (but not 1410for the declarations or handlers, if any, associated with this statement 1411sequence). This can also be useful for adding a polling point in Ada code, 1412where asynchronous abort of tasks is checked when leaving the statement 1413sequence, and is lighter than, for example, using @code{delay 0.0;}, since with 1414zero-cost exception handling, propagating exceptions (implicitly used to 1415implement task abort) cannot be done reliably in an asynchronous way. 1416 1417An example of usage would be: 1418 1419@example 1420-- Add a polling point to check for task aborts 1421 1422begin 1423 pragma Abort_Defer; 1424end; 1425@end example 1426 1427@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas 1428@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e} 1429@section Pragma Abstract_State 1430 1431 1432Syntax: 1433 1434@example 1435pragma Abstract_State (ABSTRACT_STATE_LIST); 1436 1437ABSTRACT_STATE_LIST ::= 1438 null 1439 | STATE_NAME_WITH_OPTIONS 1440 | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) 1441 1442STATE_NAME_WITH_OPTIONS ::= 1443 STATE_NAME 1444 | (STATE_NAME with OPTION_LIST) 1445 1446OPTION_LIST ::= OPTION @{, OPTION@} 1447 1448OPTION ::= 1449 SIMPLE_OPTION 1450 | NAME_VALUE_OPTION 1451 1452SIMPLE_OPTION ::= Ghost | Synchronous 1453 1454NAME_VALUE_OPTION ::= 1455 Part_Of => ABSTRACT_STATE 1456 | External [=> EXTERNAL_PROPERTY_LIST] 1457 1458EXTERNAL_PROPERTY_LIST ::= 1459 EXTERNAL_PROPERTY 1460 | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) 1461 1462EXTERNAL_PROPERTY ::= 1463 Async_Readers [=> boolean_EXPRESSION] 1464 | Async_Writers [=> boolean_EXPRESSION] 1465 | Effective_Reads [=> boolean_EXPRESSION] 1466 | Effective_Writes [=> boolean_EXPRESSION] 1467 others => boolean_EXPRESSION 1468 1469STATE_NAME ::= defining_identifier 1470 1471ABSTRACT_STATE ::= name 1472@end example 1473 1474For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in 1475the SPARK 2014 Reference Manual, section 7.1.4. 1476 1477@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas 1478@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f} 1479@section Pragma Ada_83 1480 1481 1482Syntax: 1483 1484@example 1485pragma Ada_83; 1486@end example 1487 1488A configuration pragma that establishes Ada 83 mode for the unit to 1489which it applies, regardless of the mode set by the command line 1490switches. In Ada 83 mode, GNAT attempts to be as compatible with 1491the syntax and semantics of Ada 83, as defined in the original Ada 149283 Reference Manual as possible. In particular, the keywords added by Ada 95 1493and Ada 2005 are not recognized, optional package bodies are allowed, 1494and generics may name types with unknown discriminants without using 1495the @code{(<>)} notation. In addition, some but not all of the additional 1496restrictions of Ada 83 are enforced. 1497 1498Ada 83 mode is intended for two purposes. Firstly, it allows existing 1499Ada 83 code to be compiled and adapted to GNAT with less effort. 1500Secondly, it aids in keeping code backwards compatible with Ada 83. 1501However, there is no guarantee that code that is processed correctly 1502by GNAT in Ada 83 mode will in fact compile and execute with an Ada 150383 compiler, since GNAT does not enforce all the additional checks 1504required by Ada 83. 1505 1506@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas 1507@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20} 1508@section Pragma Ada_95 1509 1510 1511Syntax: 1512 1513@example 1514pragma Ada_95; 1515@end example 1516 1517A configuration pragma that establishes Ada 95 mode for the unit to which 1518it applies, regardless of the mode set by the command line switches. 1519This mode is set automatically for the @code{Ada} and @code{System} 1520packages and their children, so you need not specify it in these 1521contexts. This pragma is useful when writing a reusable component that 1522itself uses Ada 95 features, but which is intended to be usable from 1523either Ada 83 or Ada 95 programs. 1524 1525@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas 1526@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21} 1527@section Pragma Ada_05 1528 1529 1530Syntax: 1531 1532@example 1533pragma Ada_05; 1534pragma Ada_05 (local_NAME); 1535@end example 1536 1537A configuration pragma that establishes Ada 2005 mode for the unit to which 1538it applies, regardless of the mode set by the command line switches. 1539This pragma is useful when writing a reusable component that 1540itself uses Ada 2005 features, but which is intended to be usable from 1541either Ada 83 or Ada 95 programs. 1542 1543The one argument form (which is not a configuration pragma) 1544is used for managing the transition from 1545Ada 95 to Ada 2005 in the run-time library. If an entity is marked 1546as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 1547mode will generate a warning. In addition, in Ada_83 or Ada_95 1548mode, a preference rule is established which does not choose 1549such an entity unless it is unambiguously specified. This avoids 1550extra subprograms marked this way from generating ambiguities in 1551otherwise legal pre-Ada_2005 programs. The one argument form is 1552intended for exclusive use in the GNAT run-time library. 1553 1554@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas 1555@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22} 1556@section Pragma Ada_2005 1557 1558 1559Syntax: 1560 1561@example 1562pragma Ada_2005; 1563@end example 1564 1565This configuration pragma is a synonym for pragma Ada_05 and has the 1566same syntax and effect. 1567 1568@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas 1569@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23} 1570@section Pragma Ada_12 1571 1572 1573Syntax: 1574 1575@example 1576pragma Ada_12; 1577pragma Ada_12 (local_NAME); 1578@end example 1579 1580A configuration pragma that establishes Ada 2012 mode for the unit to which 1581it applies, regardless of the mode set by the command line switches. 1582This mode is set automatically for the @code{Ada} and @code{System} 1583packages and their children, so you need not specify it in these 1584contexts. This pragma is useful when writing a reusable component that 1585itself uses Ada 2012 features, but which is intended to be usable from 1586Ada 83, Ada 95, or Ada 2005 programs. 1587 1588The one argument form, which is not a configuration pragma, 1589is used for managing the transition from Ada 15902005 to Ada 2012 in the run-time library. If an entity is marked 1591as Ada_2012 only, then referencing the entity in any pre-Ada_2012 1592mode will generate a warning. In addition, in any pre-Ada_2012 1593mode, a preference rule is established which does not choose 1594such an entity unless it is unambiguously specified. This avoids 1595extra subprograms marked this way from generating ambiguities in 1596otherwise legal pre-Ada_2012 programs. The one argument form is 1597intended for exclusive use in the GNAT run-time library. 1598 1599@node Pragma Ada_2012,Pragma Aggregate_Individually_Assign,Pragma Ada_12,Implementation Defined Pragmas 1600@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24} 1601@section Pragma Ada_2012 1602 1603 1604Syntax: 1605 1606@example 1607pragma Ada_2012; 1608@end example 1609 1610This configuration pragma is a synonym for pragma Ada_12 and has the 1611same syntax and effect. 1612 1613@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2012,Implementation Defined Pragmas 1614@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{25} 1615@section Pragma Aggregate_Individually_Assign 1616 1617 1618Syntax: 1619 1620@example 1621pragma Aggregate_Individually_Assign; 1622@end example 1623 1624Where possible, GNAT will store the binary representation of a record aggregate 1625in memory for space and performance reasons. This configuration pragma changes 1626this behavior so that record aggregates are instead always converted into 1627individual assignment statements. 1628 1629@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas 1630@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{26} 1631@section Pragma Allow_Integer_Address 1632 1633 1634Syntax: 1635 1636@example 1637pragma Allow_Integer_Address; 1638@end example 1639 1640In almost all versions of GNAT, @code{System.Address} is a private 1641type in accordance with the implementation advice in the RM. This 1642means that integer values, 1643in particular integer literals, are not allowed as address values. 1644If the configuration pragma 1645@code{Allow_Integer_Address} is given, then integer expressions may 1646be used anywhere a value of type @code{System.Address} is required. 1647The effect is to introduce an implicit unchecked conversion from the 1648integer value to type @code{System.Address}. The reverse case of using 1649an address where an integer type is required is handled analogously. 1650The following example compiles without errors: 1651 1652@example 1653pragma Allow_Integer_Address; 1654with System; use System; 1655package AddrAsInt is 1656 X : Integer; 1657 Y : Integer; 1658 for X'Address use 16#1240#; 1659 for Y use at 16#3230#; 1660 m : Address := 16#4000#; 1661 n : constant Address := 4000; 1662 p : constant Address := Address (X + Y); 1663 v : Integer := y'Address; 1664 w : constant Integer := Integer (Y'Address); 1665 type R is new integer; 1666 RR : R := 1000; 1667 Z : Integer; 1668 for Z'Address use RR; 1669end AddrAsInt; 1670@end example 1671 1672Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} 1673is not a private type. In implementations of @code{GNAT} where 1674System.Address is a visible integer type, 1675this pragma serves no purpose but is ignored 1676rather than rejected to allow common sets of sources to be used 1677in the two situations. 1678 1679@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas 1680@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{27}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{28} 1681@section Pragma Annotate 1682 1683 1684Syntax: 1685 1686@example 1687pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); 1688 1689ARG ::= NAME | EXPRESSION 1690@end example 1691 1692This pragma is used to annotate programs. IDENTIFIER identifies 1693the type of annotation. GNAT verifies that it is an identifier, but does 1694not otherwise analyze it. The second optional identifier is also left 1695unanalyzed, and by convention is used to control the action of the tool to 1696which the annotation is addressed. The remaining ARG arguments 1697can be either string literals or more generally expressions. 1698String literals (and concatenations of string literals) are assumed to be 1699either of type 1700@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} 1701depending on the character literals they contain. 1702All other kinds of arguments are analyzed as expressions, and must be 1703unambiguous. The last argument if present must have the identifier 1704@code{Entity} and GNAT verifies that a local name is given. 1705 1706The analyzed pragma is retained in the tree, but not otherwise processed 1707by any part of the GNAT compiler, except to generate corresponding note 1708lines in the generated ALI file. For the format of these note lines, see 1709the compiler source file lib-writ.ads. This pragma is intended for use by 1710external tools, including ASIS. The use of pragma Annotate does not 1711affect the compilation process in any way. This pragma may be used as 1712a configuration pragma. 1713 1714@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas 1715@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{29} 1716@section Pragma Assert 1717 1718 1719Syntax: 1720 1721@example 1722pragma Assert ( 1723 boolean_EXPRESSION 1724 [, string_EXPRESSION]); 1725@end example 1726 1727The effect of this pragma depends on whether the corresponding command 1728line switch is set to activate assertions. The pragma expands into code 1729equivalent to the following: 1730 1731@example 1732if assertions-enabled then 1733 if not boolean_EXPRESSION then 1734 System.Assertions.Raise_Assert_Failure 1735 (string_EXPRESSION); 1736 end if; 1737end if; 1738@end example 1739 1740The string argument, if given, is the message that will be associated 1741with the exception occurrence if the exception is raised. If no second 1742argument is given, the default message is @code{file}:@code{nnn}, 1743where @code{file} is the name of the source file containing the assert, 1744and @code{nnn} is the line number of the assert. 1745 1746Note that, as with the @code{if} statement to which it is equivalent, the 1747type of the expression is either @code{Standard.Boolean}, or any type derived 1748from this standard type. 1749 1750Assert checks can be either checked or ignored. By default they are ignored. 1751They will be checked if either the command line switch @emph{-gnata} is 1752used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used 1753to enable @code{Assert_Checks}. 1754 1755If assertions are ignored, then there 1756is no run-time effect (and in particular, any side effects from the 1757expression will not occur at run time). (The expression is still 1758analyzed at compile time, and may cause types to be frozen if they are 1759mentioned here for the first time). 1760 1761If assertions are checked, then the given expression is tested, and if 1762it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 1763which results in the raising of @code{Assert_Failure} with the given message. 1764 1765You should generally avoid side effects in the expression arguments of 1766this pragma, because these side effects will turn on and off with the 1767setting of the assertions mode, resulting in assertions that have an 1768effect on the program. However, the expressions are analyzed for 1769semantic correctness whether or not assertions are enabled, so turning 1770assertions on and off cannot affect the legality of a program. 1771 1772Note that the implementation defined policy @code{DISABLE}, given in a 1773pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. 1774 1775Note: this is a standard language-defined pragma in versions 1776of Ada from 2005 on. In GNAT, it is implemented in all versions 1777of Ada, and the DISABLE policy is an implementation-defined 1778addition. 1779 1780@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas 1781@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2a} 1782@section Pragma Assert_And_Cut 1783 1784 1785Syntax: 1786 1787@example 1788pragma Assert_And_Cut ( 1789 boolean_EXPRESSION 1790 [, string_EXPRESSION]); 1791@end example 1792 1793The effect of this pragma is identical to that of pragma @code{Assert}, 1794except that in an @code{Assertion_Policy} pragma, the identifier 1795@code{Assert_And_Cut} is used to control whether it is ignored or checked 1796(or disabled). 1797 1798The intention is that this be used within a subprogram when the 1799given test expresion sums up all the work done so far in the 1800subprogram, so that the rest of the subprogram can be verified 1801(informally or formally) using only the entry preconditions, 1802and the expression in this pragma. This allows dividing up 1803a subprogram into sections for the purposes of testing or 1804formal verification. The pragma also serves as useful 1805documentation. 1806 1807@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas 1808@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2b} 1809@section Pragma Assertion_Policy 1810 1811 1812Syntax: 1813 1814@example 1815pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); 1816 1817pragma Assertion_Policy ( 1818 ASSERTION_KIND => POLICY_IDENTIFIER 1819 @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); 1820 1821ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1822 1823RM_ASSERTION_KIND ::= Assert | 1824 Static_Predicate | 1825 Dynamic_Predicate | 1826 Pre | 1827 Pre'Class | 1828 Post | 1829 Post'Class | 1830 Type_Invariant | 1831 Type_Invariant'Class | 1832 Default_Initial_Condition 1833 1834ID_ASSERTION_KIND ::= Assertions | 1835 Assert_And_Cut | 1836 Assume | 1837 Contract_Cases | 1838 Debug | 1839 Ghost | 1840 Initial_Condition | 1841 Invariant | 1842 Invariant'Class | 1843 Loop_Invariant | 1844 Loop_Variant | 1845 Postcondition | 1846 Precondition | 1847 Predicate | 1848 Refined_Post | 1849 Statement_Assertions | 1850 Subprogram_Variant 1851 1852POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible 1853@end example 1854 1855This is a standard Ada 2012 pragma that is available as an 1856implementation-defined pragma in earlier versions of Ada. 1857The assertion kinds @code{RM_ASSERTION_KIND} are those defined in 1858the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} 1859are implementation defined additions recognized by the GNAT compiler. 1860 1861The pragma applies in both cases to pragmas and aspects with matching 1862names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} 1863applies to both the @code{Precondition} pragma 1864and the aspect @code{Precondition}. Note that the identifiers for 1865pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not 1866Pre_Class and Post_Class), since these pragmas are intended to be 1867identical to the corresponding aspects). 1868 1869If the policy is @code{CHECK}, then assertions are enabled, i.e. 1870the corresponding pragma or aspect is activated. 1871If the policy is @code{IGNORE}, then assertions are ignored, i.e. 1872the corresponding pragma or aspect is deactivated. 1873This pragma overrides the effect of the @emph{-gnata} switch on the 1874command line. 1875If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, 1876however, if the @emph{-gnatp} switch is specified all assertions are ignored. 1877 1878The implementation defined policy @code{DISABLE} is like 1879@code{IGNORE} except that it completely disables semantic 1880checking of the corresponding pragma or aspect. This is 1881useful when the pragma or aspect argument references subprograms 1882in a with’ed package which is replaced by a dummy package 1883for the final build. 1884 1885The implementation defined assertion kind @code{Assertions} applies to all 1886assertion kinds. The form with no assertion kind given implies this 1887choice, so it applies to all assertion kinds (RM defined, and 1888implementation defined). 1889 1890The implementation defined assertion kind @code{Statement_Assertions} 1891applies to @code{Assert}, @code{Assert_And_Cut}, 1892@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. 1893 1894@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas 1895@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2c} 1896@section Pragma Assume 1897 1898 1899Syntax: 1900 1901@example 1902pragma Assume ( 1903 boolean_EXPRESSION 1904 [, string_EXPRESSION]); 1905@end example 1906 1907The effect of this pragma is identical to that of pragma @code{Assert}, 1908except that in an @code{Assertion_Policy} pragma, the identifier 1909@code{Assume} is used to control whether it is ignored or checked 1910(or disabled). 1911 1912The intention is that this be used for assumptions about the 1913external environment. So you cannot expect to verify formally 1914or informally that the condition is met, this must be 1915established by examining things outside the program itself. 1916For example, we may have code that depends on the size of 1917@code{Long_Long_Integer} being at least 64. So we could write: 1918 1919@example 1920pragma Assume (Long_Long_Integer'Size >= 64); 1921@end example 1922 1923This assumption cannot be proved from the program itself, 1924but it acts as a useful run-time check that the assumption 1925is met, and documents the need to ensure that it is met by 1926reference to information outside the program. 1927 1928@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas 1929@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2d} 1930@section Pragma Assume_No_Invalid_Values 1931 1932 1933@geindex Invalid representations 1934 1935@geindex Invalid values 1936 1937Syntax: 1938 1939@example 1940pragma Assume_No_Invalid_Values (On | Off); 1941@end example 1942 1943This is a configuration pragma that controls the assumptions made by the 1944compiler about the occurrence of invalid representations (invalid values) 1945in the code. 1946 1947The default behavior (corresponding to an Off argument for this pragma), is 1948to assume that values may in general be invalid unless the compiler can 1949prove they are valid. Consider the following example: 1950 1951@example 1952V1 : Integer range 1 .. 10; 1953V2 : Integer range 11 .. 20; 1954... 1955for J in V2 .. V1 loop 1956 ... 1957end loop; 1958@end example 1959 1960if V1 and V2 have valid values, then the loop is known at compile 1961time not to execute since the lower bound must be greater than the 1962upper bound. However in default mode, no such assumption is made, 1963and the loop may execute. If @code{Assume_No_Invalid_Values (On)} 1964is given, the compiler will assume that any occurrence of a variable 1965other than in an explicit @code{'Valid} test always has a valid 1966value, and the loop above will be optimized away. 1967 1968The use of @code{Assume_No_Invalid_Values (On)} is appropriate if 1969you know your code is free of uninitialized variables and other 1970possible sources of invalid representations, and may result in 1971more efficient code. A program that accesses an invalid representation 1972with this pragma in effect is erroneous, so no guarantees can be made 1973about its behavior. 1974 1975It is peculiar though permissible to use this pragma in conjunction 1976with validity checking (-gnatVa). In such cases, accessing invalid 1977values will generally give an exception, though formally the program 1978is erroneous so there are no guarantees that this will always be the 1979case, and it is recommended that these two options not be used together. 1980 1981@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas 1982@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2e}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{2f} 1983@section Pragma Async_Readers 1984 1985 1986Syntax: 1987 1988@example 1989pragma Async_Readers [ (boolean_EXPRESSION) ]; 1990@end example 1991 1992For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in 1993the SPARK 2014 Reference Manual, section 7.1.2. 1994 1995@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas 1996@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{30}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{31} 1997@section Pragma Async_Writers 1998 1999 2000Syntax: 2001 2002@example 2003pragma Async_Writers [ (boolean_EXPRESSION) ]; 2004@end example 2005 2006For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in 2007the SPARK 2014 Reference Manual, section 7.1.2. 2008 2009@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas 2010@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{32} 2011@section Pragma Attribute_Definition 2012 2013 2014Syntax: 2015 2016@example 2017pragma Attribute_Definition 2018 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 2019 [Entity =>] LOCAL_NAME, 2020 [Expression =>] EXPRESSION | NAME); 2021@end example 2022 2023If @code{Attribute} is a known attribute name, this pragma is equivalent to 2024the attribute definition clause: 2025 2026@example 2027for Entity'Attribute use Expression; 2028@end example 2029 2030If @code{Attribute} is not a recognized attribute name, the pragma is 2031ignored, and a warning is emitted. This allows source 2032code to be written that takes advantage of some new attribute, while remaining 2033compilable with earlier compilers. 2034 2035@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas 2036@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{33} 2037@section Pragma C_Pass_By_Copy 2038 2039 2040@geindex Passing by copy 2041 2042Syntax: 2043 2044@example 2045pragma C_Pass_By_Copy 2046 ([Max_Size =>] static_integer_EXPRESSION); 2047@end example 2048 2049Normally the default mechanism for passing C convention records to C 2050convention subprograms is to pass them by reference, as suggested by RM 2051B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 2052this default, by requiring that record formal parameters be passed by 2053copy if all of the following conditions are met: 2054 2055 2056@itemize * 2057 2058@item 2059The size of the record type does not exceed the value specified for 2060@code{Max_Size}. 2061 2062@item 2063The record type has @code{Convention C}. 2064 2065@item 2066The formal parameter has this record type, and the subprogram has a 2067foreign (non-Ada) convention. 2068@end itemize 2069 2070If these conditions are met the argument is passed by copy; i.e., in a 2071manner consistent with what C expects if the corresponding formal in the 2072C prototype is a struct (rather than a pointer to a struct). 2073 2074You can also pass records by copy by specifying the convention 2075@code{C_Pass_By_Copy} for the record type, or by using the extended 2076@code{Import} and @code{Export} pragmas, which allow specification of 2077passing mechanisms on a parameter by parameter basis. 2078 2079@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas 2080@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{34} 2081@section Pragma Check 2082 2083 2084@geindex Assertions 2085 2086@geindex Named assertions 2087 2088Syntax: 2089 2090@example 2091pragma Check ( 2092 [Name =>] CHECK_KIND, 2093 [Check =>] Boolean_EXPRESSION 2094 [, [Message =>] string_EXPRESSION] ); 2095 2096CHECK_KIND ::= IDENTIFIER | 2097 Pre'Class | 2098 Post'Class | 2099 Type_Invariant'Class | 2100 Invariant'Class 2101@end example 2102 2103This pragma is similar to the predefined pragma @code{Assert} except that an 2104extra identifier argument is present. In conjunction with pragma 2105@code{Check_Policy}, this can be used to define groups of assertions that can 2106be independently controlled. The identifier @code{Assertion} is special, it 2107refers to the normal set of pragma @code{Assert} statements. 2108 2109Checks introduced by this pragma are normally deactivated by default. They can 2110be activated either by the command line option @emph{-gnata}, which turns on 2111all checks, or individually controlled using pragma @code{Check_Policy}. 2112 2113The identifiers @code{Assertions} and @code{Statement_Assertions} are not 2114permitted as check kinds, since this would cause confusion with the use 2115of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} 2116pragmas, where they are used to refer to sets of assertions. 2117 2118@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas 2119@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{35} 2120@section Pragma Check_Float_Overflow 2121 2122 2123@geindex Floating-point overflow 2124 2125Syntax: 2126 2127@example 2128pragma Check_Float_Overflow; 2129@end example 2130 2131In Ada, the predefined floating-point types (@code{Short_Float}, 2132@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are 2133defined to be @emph{unconstrained}. This means that even though each 2134has a well-defined base range, an operation that delivers a result 2135outside this base range is not required to raise an exception. 2136This implementation permission accommodates the notion 2137of infinities in IEEE floating-point, and corresponds to the 2138efficient execution mode on most machines. GNAT will not raise 2139overflow exceptions on these machines; instead it will generate 2140infinities and NaN’s as defined in the IEEE standard. 2141 2142Generating infinities, although efficient, is not always desirable. 2143Often the preferable approach is to check for overflow, even at the 2144(perhaps considerable) expense of run-time performance. 2145This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit 2146range constraints – and indeed such a subtype 2147can have the same base range as its base type. For example: 2148 2149@example 2150subtype My_Float is Float range Float'Range; 2151@end example 2152 2153Here @code{My_Float} has the same range as 2154@code{Float} but is constrained, so operations on 2155@code{My_Float} values will be checked for overflow 2156against this range. 2157 2158This style will achieve the desired goal, but 2159it is often more convenient to be able to simply use 2160the standard predefined floating-point types as long 2161as overflow checking could be guaranteed. 2162The @code{Check_Float_Overflow} 2163configuration pragma achieves this effect. If a unit is compiled 2164subject to this configuration pragma, then all operations 2165on predefined floating-point types including operations on 2166base types of these floating-point types will be treated as 2167though those types were constrained, and overflow checks 2168will be generated. The @code{Constraint_Error} 2169exception is raised if the result is out of range. 2170 2171This mode can also be set by use of the compiler 2172switch @emph{-gnateF}. 2173 2174@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas 2175@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{36} 2176@section Pragma Check_Name 2177 2178 2179@geindex Defining check names 2180 2181@geindex Check names 2182@geindex defining 2183 2184Syntax: 2185 2186@example 2187pragma Check_Name (check_name_IDENTIFIER); 2188@end example 2189 2190This is a configuration pragma that defines a new implementation 2191defined check name (unless IDENTIFIER matches one of the predefined 2192check names, in which case the pragma has no effect). Check names 2193are global to a partition, so if two or more configuration pragmas 2194are present in a partition mentioning the same name, only one new 2195check name is introduced. 2196 2197An implementation defined check name introduced with this pragma may 2198be used in only three contexts: @code{pragma Suppress}, 2199@code{pragma Unsuppress}, 2200and as the prefix of a @code{Check_Name'Enabled} attribute reference. For 2201any of these three cases, the check name must be visible. A check 2202name is visible if it is in the configuration pragmas applying to 2203the current unit, or if it appears at the start of any unit that 2204is part of the dependency set of the current unit (e.g., units that 2205are mentioned in @code{with} clauses). 2206 2207Check names introduced by this pragma are subject to control by compiler 2208switches (in particular -gnatp) in the usual manner. 2209 2210@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas 2211@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{37} 2212@section Pragma Check_Policy 2213 2214 2215@geindex Controlling assertions 2216 2217@geindex Assertions 2218@geindex control 2219 2220@geindex Check pragma control 2221 2222@geindex Named assertions 2223 2224Syntax: 2225 2226@example 2227pragma Check_Policy 2228 ([Name =>] CHECK_KIND, 2229 [Policy =>] POLICY_IDENTIFIER); 2230 2231pragma Check_Policy ( 2232 CHECK_KIND => POLICY_IDENTIFIER 2233 @{, CHECK_KIND => POLICY_IDENTIFIER@}); 2234 2235ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 2236 2237CHECK_KIND ::= IDENTIFIER | 2238 Pre'Class | 2239 Post'Class | 2240 Type_Invariant'Class | 2241 Invariant'Class 2242 2243The identifiers Name and Policy are not allowed as CHECK_KIND values. This 2244avoids confusion between the two possible syntax forms for this pragma. 2245 2246POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 2247@end example 2248 2249This pragma is used to set the checking policy for assertions (specified 2250by aspects or pragmas), the @code{Debug} pragma, or additional checks 2251to be checked using the @code{Check} pragma. It may appear either as 2252a configuration pragma, or within a declarative part of package. In the 2253latter case, it applies from the point where it appears to the end of 2254the declarative region (like pragma @code{Suppress}). 2255 2256The @code{Check_Policy} pragma is similar to the 2257predefined @code{Assertion_Policy} pragma, 2258and if the check kind corresponds to one of the assertion kinds that 2259are allowed by @code{Assertion_Policy}, then the effect is identical. 2260 2261If the first argument is Debug, then the policy applies to Debug pragmas, 2262disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or 2263@code{IGNORE}, and allowing them to execute with normal semantics if 2264the policy is @code{ON} or @code{CHECK}. In addition if the policy is 2265@code{DISABLE}, then the procedure call in @code{Debug} pragmas will 2266be totally ignored and not analyzed semantically. 2267 2268Finally the first argument may be some other identifier than the above 2269possibilities, in which case it controls a set of named assertions 2270that can be checked using pragma @code{Check}. For example, if the pragma: 2271 2272@example 2273pragma Check_Policy (Critical_Error, OFF); 2274@end example 2275 2276is given, then subsequent @code{Check} pragmas whose first argument is also 2277@code{Critical_Error} will be disabled. 2278 2279The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} 2280to turn on corresponding checks. The default for a set of checks for which no 2281@code{Check_Policy} is given is @code{OFF} unless the compiler switch 2282@emph{-gnata} is given, which turns on all checks by default. 2283 2284The check policy settings @code{CHECK} and @code{IGNORE} are recognized 2285as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for 2286compatibility with the standard @code{Assertion_Policy} pragma. The check 2287policy setting @code{DISABLE} causes the second argument of a corresponding 2288@code{Check} pragma to be completely ignored and not analyzed. 2289 2290@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas 2291@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{38} 2292@section Pragma Comment 2293 2294 2295Syntax: 2296 2297@example 2298pragma Comment (static_string_EXPRESSION); 2299@end example 2300 2301This is almost identical in effect to pragma @code{Ident}. It allows the 2302placement of a comment into the object file and hence into the 2303executable file if the operating system permits such usage. The 2304difference is that @code{Comment}, unlike @code{Ident}, has 2305no limitations on placement of the pragma (it can be placed 2306anywhere in the main source unit), and if more than one pragma 2307is used, all comments are retained. 2308 2309@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas 2310@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{39} 2311@section Pragma Common_Object 2312 2313 2314Syntax: 2315 2316@example 2317pragma Common_Object ( 2318 [Internal =>] LOCAL_NAME 2319 [, [External =>] EXTERNAL_SYMBOL] 2320 [, [Size =>] EXTERNAL_SYMBOL] ); 2321 2322EXTERNAL_SYMBOL ::= 2323 IDENTIFIER 2324| static_string_EXPRESSION 2325@end example 2326 2327This pragma enables the shared use of variables stored in overlaid 2328linker areas corresponding to the use of @code{COMMON} 2329in Fortran. The single 2330object @code{LOCAL_NAME} is assigned to the area designated by 2331the @code{External} argument. 2332You may define a record to correspond to a series 2333of fields. The @code{Size} argument 2334is syntax checked in GNAT, but otherwise ignored. 2335 2336@code{Common_Object} is not supported on all platforms. If no 2337support is available, then the code generator will issue a message 2338indicating that the necessary attribute for implementation of this 2339pragma is not available. 2340 2341@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas 2342@anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3a}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3b} 2343@section Pragma Compile_Time_Error 2344 2345 2346Syntax: 2347 2348@example 2349pragma Compile_Time_Error 2350 (boolean_EXPRESSION, static_string_EXPRESSION); 2351@end example 2352 2353This pragma can be used to generate additional compile time 2354error messages. It 2355is particularly useful in generics, where errors can be issued for 2356specific problematic instantiations. The first parameter is a boolean 2357expression. The pragma ensures that the value of an expression 2358is known at compile time, and has the value False. The set of expressions 2359whose values are known at compile time includes all static boolean 2360expressions, and also other values which the compiler can determine 2361at compile time (e.g., the size of a record type set by an explicit 2362size representation clause, or the value of a variable which was 2363initialized to a constant and is known not to have been modified). 2364If these conditions are not met, an error message is generated using 2365the value given as the second argument. This string value may contain 2366embedded ASCII.LF characters to break the message into multiple lines. 2367 2368@node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas 2369@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3c} 2370@section Pragma Compile_Time_Warning 2371 2372 2373Syntax: 2374 2375@example 2376pragma Compile_Time_Warning 2377 (boolean_EXPRESSION, static_string_EXPRESSION); 2378@end example 2379 2380Same as pragma Compile_Time_Error, except a warning is issued instead 2381of an error message. If switch @emph{-gnatw_C} is used, a warning is only issued 2382if the value of the expression is known to be True at compile time, not when 2383the value of the expression is not known at compile time. 2384Note that if this pragma is used in a package that 2385is with’ed by a client, the client will get the warning even though it 2386is issued by a with’ed package (normally warnings in with’ed units are 2387suppressed, but this is a special exception to that rule). 2388 2389One typical use is within a generic where compile time known characteristics 2390of formal parameters are tested, and warnings given appropriately. Another use 2391with a first parameter of True is to warn a client about use of a package, 2392for example that it is not fully implemented. 2393 2394In previous versions of the compiler, combining @emph{-gnatwe} with 2395Compile_Time_Warning resulted in a fatal error. Now the compiler always emits 2396a warning. You can use @ref{3a,,Pragma Compile_Time_Error} to force the generation of 2397an error. 2398 2399@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas 2400@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3d} 2401@section Pragma Compiler_Unit 2402 2403 2404Syntax: 2405 2406@example 2407pragma Compiler_Unit; 2408@end example 2409 2410This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 2411retained so that old versions of the GNAT run-time that use this pragma can 2412be compiled with newer versions of the compiler. 2413 2414@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas 2415@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{3e} 2416@section Pragma Compiler_Unit_Warning 2417 2418 2419Syntax: 2420 2421@example 2422pragma Compiler_Unit_Warning; 2423@end example 2424 2425This pragma is intended only for internal use in the GNAT run-time library. 2426It indicates that the unit is used as part of the compiler build. The effect 2427is to generate warnings for the use of constructs (for example, conditional 2428expressions) that would cause trouble when bootstrapping using an older 2429version of GNAT. For the exact list of restrictions, see the compiler sources 2430and references to Check_Compiler_Unit. 2431 2432@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas 2433@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3f} 2434@section Pragma Complete_Representation 2435 2436 2437Syntax: 2438 2439@example 2440pragma Complete_Representation; 2441@end example 2442 2443This pragma must appear immediately within a record representation 2444clause. Typical placements are before the first component clause 2445or after the last component clause. The effect is to give an error 2446message if any component is missing a component clause. This pragma 2447may be used to ensure that a record representation clause is 2448complete, and that this invariant is maintained if fields are 2449added to the record in the future. 2450 2451@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas 2452@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{40} 2453@section Pragma Complex_Representation 2454 2455 2456Syntax: 2457 2458@example 2459pragma Complex_Representation 2460 ([Entity =>] LOCAL_NAME); 2461@end example 2462 2463The @code{Entity} argument must be the name of a record type which has 2464two fields of the same floating-point type. The effect of this pragma is 2465to force gcc to use the special internal complex representation form for 2466this record, which may be more efficient. Note that this may result in 2467the code for this type not conforming to standard ABI (application 2468binary interface) requirements for the handling of record types. For 2469example, in some environments, there is a requirement for passing 2470records by pointer, and the use of this pragma may result in passing 2471this type in floating-point registers. 2472 2473@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas 2474@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{41} 2475@section Pragma Component_Alignment 2476 2477 2478@geindex Alignments of components 2479 2480@geindex Pragma Component_Alignment 2481 2482Syntax: 2483 2484@example 2485pragma Component_Alignment ( 2486 [Form =>] ALIGNMENT_CHOICE 2487 [, [Name =>] type_LOCAL_NAME]); 2488 2489ALIGNMENT_CHOICE ::= 2490 Component_Size 2491| Component_Size_4 2492| Storage_Unit 2493| Default 2494@end example 2495 2496Specifies the alignment of components in array or record types. 2497The meaning of the @code{Form} argument is as follows: 2498 2499@quotation 2500 2501@geindex Component_Size (in pragma Component_Alignment) 2502@end quotation 2503 2504 2505@table @asis 2506 2507@item @emph{Component_Size} 2508 2509Aligns scalar components and subcomponents of the array or record type 2510on boundaries appropriate to their inherent size (naturally 2511aligned). For example, 1-byte components are aligned on byte boundaries, 25122-byte integer components are aligned on 2-byte boundaries, 4-byte 2513integer components are aligned on 4-byte boundaries and so on. These 2514alignment rules correspond to the normal rules for C compilers on all 2515machines except the VAX. 2516 2517@geindex Component_Size_4 (in pragma Component_Alignment) 2518 2519@item @emph{Component_Size_4} 2520 2521Naturally aligns components with a size of four or fewer 2522bytes. Components that are larger than 4 bytes are placed on the next 25234-byte boundary. 2524 2525@geindex Storage_Unit (in pragma Component_Alignment) 2526 2527@item @emph{Storage_Unit} 2528 2529Specifies that array or record components are byte aligned, i.e., 2530aligned on boundaries determined by the value of the constant 2531@code{System.Storage_Unit}. 2532 2533@geindex Default (in pragma Component_Alignment) 2534 2535@item @emph{Default} 2536 2537Specifies that array or record components are aligned on default 2538boundaries, appropriate to the underlying hardware or operating system or 2539both. The @code{Default} choice is the same as @code{Component_Size} (natural 2540alignment). 2541@end table 2542 2543If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must 2544refer to a local record or array type, and the specified alignment 2545choice applies to the specified type. The use of 2546@code{Component_Alignment} together with a pragma @code{Pack} causes the 2547@code{Component_Alignment} pragma to be ignored. The use of 2548@code{Component_Alignment} together with a record representation clause 2549is only effective for fields not specified by the representation clause. 2550 2551If the @code{Name} parameter is absent, the pragma can be used as either 2552a configuration pragma, in which case it applies to one or more units in 2553accordance with the normal rules for configuration pragmas, or it can be 2554used within a declarative part, in which case it applies to types that 2555are declared within this declarative part, or within any nested scope 2556within this declarative part. In either case it specifies the alignment 2557to be applied to any record or array type which has otherwise standard 2558representation. 2559 2560If the alignment for a record or array type is not specified (using 2561pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 2562clause), the GNAT uses the default alignment as described previously. 2563 2564@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas 2565@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{42}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{43} 2566@section Pragma Constant_After_Elaboration 2567 2568 2569Syntax: 2570 2571@example 2572pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; 2573@end example 2574 2575For the semantics of this pragma, see the entry for aspect 2576@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. 2577 2578@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas 2579@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{44}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{45} 2580@section Pragma Contract_Cases 2581 2582 2583@geindex Contract cases 2584 2585Syntax: 2586 2587@example 2588pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE)); 2589 2590CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE 2591 2592CASE_GUARD ::= boolean_EXPRESSION | others 2593 2594CONSEQUENCE ::= boolean_EXPRESSION 2595@end example 2596 2597The @code{Contract_Cases} pragma allows defining fine-grain specifications 2598that can complement or replace the contract given by a precondition and a 2599postcondition. Additionally, the @code{Contract_Cases} pragma can be used 2600by testing and formal verification tools. The compiler checks its validity and, 2601depending on the assertion policy at the point of declaration of the pragma, 2602it may insert a check in the executable. For code generation, the contract 2603cases 2604 2605@example 2606pragma Contract_Cases ( 2607 Cond1 => Pred1, 2608 Cond2 => Pred2); 2609@end example 2610 2611are equivalent to 2612 2613@example 2614C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 2615C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 2616pragma Precondition ((C1 and not C2) or (C2 and not C1)); 2617pragma Postcondition (if C1 then Pred1); 2618pragma Postcondition (if C2 then Pred2); 2619@end example 2620 2621The precondition ensures that one and only one of the case guards is 2622satisfied on entry to the subprogram. 2623The postcondition ensures that for the case guard that was True on entry, 2624the corresponding consequence is True on exit. Other consequence expressions 2625are not evaluated. 2626 2627A precondition @code{P} and postcondition @code{Q} can also be 2628expressed as contract cases: 2629 2630@example 2631pragma Contract_Cases (P => Q); 2632@end example 2633 2634The placement and visibility rules for @code{Contract_Cases} pragmas are 2635identical to those described for preconditions and postconditions. 2636 2637The compiler checks that boolean expressions given in case guards and 2638consequences are valid, where the rules for case guards are the same as 2639the rule for an expression in @code{Precondition} and the rules for 2640consequences are the same as the rule for an expression in 2641@code{Postcondition}. In particular, attributes @code{'Old} and 2642@code{'Result} can only be used within consequence expressions. 2643The case guard for the last contract case may be @code{others}, to denote 2644any case not captured by the previous cases. The 2645following is an example of use within a package spec: 2646 2647@example 2648package Math_Functions is 2649 ... 2650 function Sqrt (Arg : Float) return Float; 2651 pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, 2652 Arg >= 100.0 => Sqrt'Result >= 10.0, 2653 others => Sqrt'Result = 0.0)); 2654 ... 2655end Math_Functions; 2656@end example 2657 2658The meaning of contract cases is that only one case should apply at each 2659call, as determined by the corresponding case guard evaluating to True, 2660and that the consequence for this case should hold when the subprogram 2661returns. 2662 2663@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas 2664@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{46} 2665@section Pragma Convention_Identifier 2666 2667 2668@geindex Conventions 2669@geindex synonyms 2670 2671Syntax: 2672 2673@example 2674pragma Convention_Identifier ( 2675 [Name =>] IDENTIFIER, 2676 [Convention =>] convention_IDENTIFIER); 2677@end example 2678 2679This pragma provides a mechanism for supplying synonyms for existing 2680convention identifiers. The @code{Name} identifier can subsequently 2681be used as a synonym for the given convention in other pragmas (including 2682for example pragma @code{Import} or another @code{Convention_Identifier} 2683pragma). As an example of the use of this, suppose you had legacy code 2684which used Fortran77 as the identifier for Fortran. Then the pragma: 2685 2686@example 2687pragma Convention_Identifier (Fortran77, Fortran); 2688@end example 2689 2690would allow the use of the convention identifier @code{Fortran77} in 2691subsequent code, avoiding the need to modify the sources. As another 2692example, you could use this to parameterize convention requirements 2693according to systems. Suppose you needed to use @code{Stdcall} on 2694windows systems, and @code{C} on some other system, then you could 2695define a convention identifier @code{Library} and use a single 2696@code{Convention_Identifier} pragma to specify which convention 2697would be used system-wide. 2698 2699@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas 2700@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{47} 2701@section Pragma CPP_Class 2702 2703 2704@geindex Interfacing with C++ 2705 2706Syntax: 2707 2708@example 2709pragma CPP_Class ([Entity =>] LOCAL_NAME); 2710@end example 2711 2712The argument denotes an entity in the current declarative region that is 2713declared as a record type. It indicates that the type corresponds to an 2714externally declared C++ class type, and is to be laid out the same way 2715that C++ would lay out the type. If the C++ class has virtual primitives 2716then the record must be declared as a tagged record type. 2717 2718Types for which @code{CPP_Class} is specified do not have assignment or 2719equality operators defined (such operations can be imported or declared 2720as subprograms as required). Initialization is allowed only by constructor 2721functions (see pragma @code{CPP_Constructor}). Such types are implicitly 2722limited if not explicitly declared as limited or derived from a limited 2723type, and an error is issued in that case. 2724 2725See @ref{48,,Interfacing to C++} for related information. 2726 2727Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 2728for backward compatibility but its functionality is available 2729using pragma @code{Import} with @code{Convention} = @code{CPP}. 2730 2731@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas 2732@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{49} 2733@section Pragma CPP_Constructor 2734 2735 2736@geindex Interfacing with C++ 2737 2738Syntax: 2739 2740@example 2741pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2742 [, [External_Name =>] static_string_EXPRESSION ] 2743 [, [Link_Name =>] static_string_EXPRESSION ]); 2744@end example 2745 2746This pragma identifies an imported function (imported in the usual way 2747with pragma @code{Import}) as corresponding to a C++ constructor. If 2748@code{External_Name} and @code{Link_Name} are not specified then the 2749@code{Entity} argument is a name that must have been previously mentioned 2750in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name 2751must be of one of the following forms: 2752 2753 2754@itemize * 2755 2756@item 2757@strong{function} @code{Fname} @strong{return} T` 2758 2759@item 2760@strong{function} @code{Fname} @strong{return} T’Class 2761 2762@item 2763@strong{function} @code{Fname} (…) @strong{return} T` 2764 2765@item 2766@strong{function} @code{Fname} (…) @strong{return} T’Class 2767@end itemize 2768 2769where @code{T} is a limited record type imported from C++ with pragma 2770@code{Import} and @code{Convention} = @code{CPP}. 2771 2772The first two forms import the default constructor, used when an object 2773of type @code{T} is created on the Ada side with no explicit constructor. 2774The latter two forms cover all the non-default constructors of the type. 2775See the GNAT User’s Guide for details. 2776 2777If no constructors are imported, it is impossible to create any objects 2778on the Ada side and the type is implicitly declared abstract. 2779 2780Pragma @code{CPP_Constructor} is intended primarily for automatic generation 2781using an automatic binding generator tool (such as the @code{-fdump-ada-spec} 2782GCC switch). 2783See @ref{48,,Interfacing to C++} for more related information. 2784 2785Note: The use of functions returning class-wide types for constructors is 2786currently obsolete. They are supported for backward compatibility. The 2787use of functions returning the type T leave the Ada sources more clear 2788because the imported C++ constructors always return an object of type T; 2789that is, they never return an object whose type is a descendant of type T. 2790 2791@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas 2792@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{4a} 2793@section Pragma CPP_Virtual 2794 2795 2796@geindex Interfacing to C++ 2797 2798This pragma is now obsolete and, other than generating a warning if warnings 2799on obsolescent features are enabled, is completely ignored. 2800It is retained for compatibility 2801purposes. It used to be required to ensure compoatibility with C++, but 2802is no longer required for that purpose because GNAT generates 2803the same object layout as the G++ compiler by default. 2804 2805See @ref{48,,Interfacing to C++} for related information. 2806 2807@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas 2808@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4b} 2809@section Pragma CPP_Vtable 2810 2811 2812@geindex Interfacing with C++ 2813 2814This pragma is now obsolete and, other than generating a warning if warnings 2815on obsolescent features are enabled, is completely ignored. 2816It used to be required to ensure compatibility with C++, but 2817is no longer required for that purpose because GNAT generates 2818the same object layout as the G++ compiler by default. 2819 2820See @ref{48,,Interfacing to C++} for related information. 2821 2822@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas 2823@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4c} 2824@section Pragma CPU 2825 2826 2827Syntax: 2828 2829@example 2830pragma CPU (EXPRESSION); 2831@end example 2832 2833This pragma is standard in Ada 2012, but is available in all earlier 2834versions of Ada as an implementation-defined pragma. 2835See Ada 2012 Reference Manual for details. 2836 2837@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas 2838@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4d} 2839@section Pragma Deadline_Floor 2840 2841 2842Syntax: 2843 2844@example 2845pragma Deadline_Floor (time_span_EXPRESSION); 2846@end example 2847 2848This pragma applies only to protected types and specifies the floor 2849deadline inherited by a task when the task enters a protected object. 2850It is effective only when the EDF scheduling policy is used. 2851 2852@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas 2853@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4e}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4f} 2854@section Pragma Default_Initial_Condition 2855 2856 2857Syntax: 2858 2859@example 2860pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; 2861@end example 2862 2863For the semantics of this pragma, see the entry for aspect 2864@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. 2865 2866@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas 2867@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{50} 2868@section Pragma Debug 2869 2870 2871Syntax: 2872 2873@example 2874pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 2875 2876PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 2877 PROCEDURE_NAME 2878| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 2879@end example 2880 2881The procedure call argument has the syntactic form of an expression, meeting 2882the syntactic requirements for pragmas. 2883 2884If debug pragmas are not enabled or if the condition is present and evaluates 2885to False, this pragma has no effect. If debug pragmas are enabled, the 2886semantics of the pragma is exactly equivalent to the procedure call statement 2887corresponding to the argument with a terminating semicolon. Pragmas are 2888permitted in sequences of declarations, so you can use pragma @code{Debug} to 2889intersperse calls to debug procedures in the middle of declarations. Debug 2890pragmas can be enabled either by use of the command line switch @emph{-gnata} 2891or by use of the pragma @code{Check_Policy} with a first argument of 2892@code{Debug}. 2893 2894@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas 2895@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{51} 2896@section Pragma Debug_Policy 2897 2898 2899Syntax: 2900 2901@example 2902pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 2903@end example 2904 2905This pragma is equivalent to a corresponding @code{Check_Policy} pragma 2906with a first argument of @code{Debug}. It is retained for historical 2907compatibility reasons. 2908 2909@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas 2910@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{52} 2911@section Pragma Default_Scalar_Storage_Order 2912 2913 2914@geindex Default_Scalar_Storage_Order 2915 2916@geindex Scalar_Storage_Order 2917 2918Syntax: 2919 2920@example 2921pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); 2922@end example 2923 2924Normally if no explicit @code{Scalar_Storage_Order} is given for a record 2925type or array type, then the scalar storage order defaults to the ordinary 2926default for the target. But this default may be overridden using this pragma. 2927The pragma may appear as a configuration pragma, or locally within a package 2928spec or declarative part. In the latter case, it applies to all subsequent 2929types declared within that package spec or declarative part. 2930 2931The following example shows the use of this pragma: 2932 2933@example 2934pragma Default_Scalar_Storage_Order (High_Order_First); 2935with System; use System; 2936package DSSO1 is 2937 type H1 is record 2938 a : Integer; 2939 end record; 2940 2941 type L2 is record 2942 a : Integer; 2943 end record; 2944 for L2'Scalar_Storage_Order use Low_Order_First; 2945 2946 type L2a is new L2; 2947 2948 package Inner is 2949 type H3 is record 2950 a : Integer; 2951 end record; 2952 2953 pragma Default_Scalar_Storage_Order (Low_Order_First); 2954 2955 type L4 is record 2956 a : Integer; 2957 end record; 2958 end Inner; 2959 2960 type H4a is new Inner.L4; 2961 2962 type H5 is record 2963 a : Integer; 2964 end record; 2965end DSSO1; 2966@end example 2967 2968In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar 2969storage order, and record types with names starting with @emph{H} have @code{High_Order_First}. 2970Note that in the case of @code{H4a}, the order is not inherited 2971from the parent type. Only an explicitly set @code{Scalar_Storage_Order} 2972gets inherited on type derivation. 2973 2974If this pragma is used as a configuration pragma which appears within a 2975configuration pragma file (as opposed to appearing explicitly at the start 2976of a single unit), then the binder will require that all units in a partition 2977be compiled in a similar manner, other than run-time units, which are not 2978affected by this pragma. Note that the use of this form is discouraged because 2979it may significantly degrade the run-time performance of the software, instead 2980the default scalar storage order ought to be changed only on a local basis. 2981 2982@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas 2983@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{53} 2984@section Pragma Default_Storage_Pool 2985 2986 2987@geindex Default_Storage_Pool 2988 2989Syntax: 2990 2991@example 2992pragma Default_Storage_Pool (storage_pool_NAME | null); 2993@end example 2994 2995This pragma is standard in Ada 2012, but is available in all earlier 2996versions of Ada as an implementation-defined pragma. 2997See Ada 2012 Reference Manual for details. 2998 2999@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas 3000@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{54}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{55} 3001@section Pragma Depends 3002 3003 3004Syntax: 3005 3006@example 3007pragma Depends (DEPENDENCY_RELATION); 3008 3009DEPENDENCY_RELATION ::= 3010 null 3011 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 3012 3013DEPENDENCY_CLAUSE ::= 3014 OUTPUT_LIST =>[+] INPUT_LIST 3015 | NULL_DEPENDENCY_CLAUSE 3016 3017NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 3018 3019OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 3020 3021INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 3022 3023OUTPUT ::= NAME | FUNCTION_RESULT 3024INPUT ::= NAME 3025 3026where FUNCTION_RESULT is a function Result attribute_reference 3027@end example 3028 3029For the semantics of this pragma, see the entry for aspect @code{Depends} in the 3030SPARK 2014 Reference Manual, section 6.1.5. 3031 3032@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas 3033@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{56} 3034@section Pragma Detect_Blocking 3035 3036 3037Syntax: 3038 3039@example 3040pragma Detect_Blocking; 3041@end example 3042 3043This is a standard pragma in Ada 2005, that is available in all earlier 3044versions of Ada as an implementation-defined pragma. 3045 3046This is a configuration pragma that forces the detection of potentially 3047blocking operations within a protected operation, and to raise Program_Error 3048if that happens. 3049 3050@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas 3051@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{57} 3052@section Pragma Disable_Atomic_Synchronization 3053 3054 3055@geindex Atomic Synchronization 3056 3057Syntax: 3058 3059@example 3060pragma Disable_Atomic_Synchronization [(Entity)]; 3061@end example 3062 3063Ada requires that accesses (reads or writes) of an atomic variable be 3064regarded as synchronization points in the case of multiple tasks. 3065Particularly in the case of multi-processors this may require special 3066handling, e.g. the generation of memory barriers. This capability may 3067be turned off using this pragma in cases where it is known not to be 3068required. 3069 3070The placement and scope rules for this pragma are the same as those 3071for @code{pragma Suppress}. In particular it can be used as a 3072configuration pragma, or in a declaration sequence where it applies 3073till the end of the scope. If an @code{Entity} argument is present, 3074the action applies only to that entity. 3075 3076@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas 3077@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{58} 3078@section Pragma Dispatching_Domain 3079 3080 3081Syntax: 3082 3083@example 3084pragma Dispatching_Domain (EXPRESSION); 3085@end example 3086 3087This pragma is standard in Ada 2012, but is available in all earlier 3088versions of Ada as an implementation-defined pragma. 3089See Ada 2012 Reference Manual for details. 3090 3091@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas 3092@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{59}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{5a} 3093@section Pragma Effective_Reads 3094 3095 3096Syntax: 3097 3098@example 3099pragma Effective_Reads [ (boolean_EXPRESSION) ]; 3100@end example 3101 3102For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in 3103the SPARK 2014 Reference Manual, section 7.1.2. 3104 3105@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas 3106@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5b}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5c} 3107@section Pragma Effective_Writes 3108 3109 3110Syntax: 3111 3112@example 3113pragma Effective_Writes [ (boolean_EXPRESSION) ]; 3114@end example 3115 3116For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} 3117in the SPARK 2014 Reference Manual, section 7.1.2. 3118 3119@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas 3120@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5d} 3121@section Pragma Elaboration_Checks 3122 3123 3124@geindex Elaboration control 3125 3126Syntax: 3127 3128@example 3129pragma Elaboration_Checks (Dynamic | Static); 3130@end example 3131 3132This is a configuration pragma which specifies the elaboration model to be 3133used during compilation. For more information on the elaboration models of 3134GNAT, consult the chapter on elaboration order handling in the @emph{GNAT User’s 3135Guide}. 3136 3137The pragma may appear in the following contexts: 3138 3139 3140@itemize * 3141 3142@item 3143Configuration pragmas file 3144 3145@item 3146Prior to the context clauses of a compilation unit’s initial declaration 3147@end itemize 3148 3149Any other placement of the pragma will result in a warning and the effects of 3150the offending pragma will be ignored. 3151 3152If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in 3153effect. If the pragma argument is @code{Static}, then the static elaboration model 3154is in effect. 3155 3156@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas 3157@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5e} 3158@section Pragma Eliminate 3159 3160 3161@geindex Elimination of unused subprograms 3162 3163Syntax: 3164 3165@example 3166pragma Eliminate ( 3167 [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , 3168 [ Entity => ] IDENTIFIER | 3169 SELECTED_COMPONENT | 3170 STRING_LITERAL 3171 [, Source_Location => SOURCE_TRACE ] ); 3172 3173 SOURCE_TRACE ::= STRING_LITERAL 3174@end example 3175 3176This pragma indicates that the given entity is not used in the program to be 3177compiled and built, thus allowing the compiler to 3178eliminate the code or data associated with the named entity. Any reference to 3179an eliminated entity causes a compile-time or link-time error. 3180 3181The pragma has the following semantics, where @code{U} is the unit specified by 3182the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} 3183argument: 3184 3185 3186@itemize * 3187 3188@item 3189@code{E} must be a subprogram that is explicitly declared either: 3190 3191o Within @code{U}, or 3192 3193o Within a generic package that is instantiated in @code{U}, or 3194 3195o As an instance of generic subprogram instantiated in @code{U}. 3196 3197Otherwise the pragma is ignored. 3198 3199@item 3200If @code{E} is overloaded within @code{U} then, in the absence of a 3201@code{Source_Location} argument, all overloadings are eliminated. 3202 3203@item 3204If @code{E} is overloaded within @code{U} and only some overloadings 3205are to be eliminated, then each overloading to be eliminated 3206must be specified in a corresponding pragma @code{Eliminate} 3207with a @code{Source_Location} argument identifying the line where the 3208declaration appears, as described below. 3209 3210@item 3211If @code{E} is declared as the result of a generic instantiation, then 3212a @code{Source_Location} argument is needed, as described below 3213@end itemize 3214 3215Pragma @code{Eliminate} allows a program to be compiled in a system-independent 3216manner, so that unused entities are eliminated but without 3217needing to modify the source text. Normally the required set of 3218@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. 3219 3220Any source file change that removes, splits, or 3221adds lines may make the set of @code{Eliminate} pragmas invalid because their 3222@code{Source_Location} argument values may get out of date. 3223 3224Pragma @code{Eliminate} may be used where the referenced entity is a dispatching 3225operation. In this case all the subprograms to which the given operation can 3226dispatch are considered to be unused (are never called as a result of a direct 3227or a dispatching call). 3228 3229The string literal given for the source location specifies the line number 3230of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: 3231 3232@example 3233SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] 3234 3235LBRACKET ::= '[' 3236RBRACKET ::= ']' 3237 3238SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 3239 3240LINE_NUMBER ::= DIGIT @{DIGIT@} 3241@end example 3242 3243Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. 3244 3245The source trace that is given as the @code{Source_Location} must obey the 3246following rules (or else the pragma is ignored), where @code{U} is 3247the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the 3248subprogram specified by the @code{Entity} argument: 3249 3250 3251@itemize * 3252 3253@item 3254@code{FILE_NAME} is the short name (with no directory 3255information) of the Ada source file for @code{U}, using the required syntax 3256for the underlying file system (e.g. case is significant if the underlying 3257operating system is case sensitive). 3258If @code{U} is a package and @code{E} is a subprogram declared in the package 3259specification and its full declaration appears in the package body, 3260then the relevant source file is the one for the package specification; 3261analogously if @code{U} is a generic package. 3262 3263@item 3264If @code{E} is not declared in a generic instantiation (this includes 3265generic subprogram instances), the source trace includes only one source 3266line reference. @code{LINE_NUMBER} gives the line number of the occurrence 3267of the declaration of @code{E} within the source file (as a decimal literal 3268without an exponent or point). 3269 3270@item 3271If @code{E} is declared by a generic instantiation, its source trace 3272(from left to right) starts with the source location of the 3273declaration of @code{E} in the generic unit and ends with the source 3274location of the instantiation, given in square brackets. This approach is 3275applied recursively with nested instantiations: the rightmost (nested 3276most deeply in square brackets) element of the source trace is the location 3277of the outermost instantiation, and the leftmost element (that is, outside 3278of any square brackets) is the location of the declaration of @code{E} in 3279the generic unit. 3280@end itemize 3281 3282Examples: 3283 3284@quotation 3285 3286@example 3287pragma Eliminate (Pkg0, Proc); 3288-- Eliminate (all overloadings of) Proc in Pkg0 3289 3290pragma Eliminate (Pkg1, Proc, 3291 Source_Location => "pkg1.ads:8"); 3292-- Eliminate overloading of Proc at line 8 in pkg1.ads 3293 3294-- Assume the following file contents: 3295-- gen_pkg.ads 3296-- 1: generic 3297-- 2: type T is private; 3298-- 3: package Gen_Pkg is 3299-- 4: procedure Proc(N : T); 3300-- ... ... 3301-- ... end Gen_Pkg; 3302-- 3303-- q.adb 3304-- 1: with Gen_Pkg; 3305-- 2: procedure Q is 3306-- 3: package Inst_Pkg is new Gen_Pkg(Integer); 3307-- ... -- No calls on Inst_Pkg.Proc 3308-- ... end Q; 3309 3310-- The following pragma eliminates Inst_Pkg.Proc from Q 3311pragma Eliminate (Q, Proc, 3312 Source_Location => "gen_pkg.ads:4[q.adb:3]"); 3313@end example 3314@end quotation 3315 3316@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas 3317@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5f} 3318@section Pragma Enable_Atomic_Synchronization 3319 3320 3321@geindex Atomic Synchronization 3322 3323Syntax: 3324 3325@example 3326pragma Enable_Atomic_Synchronization [(Entity)]; 3327@end example 3328 3329Ada requires that accesses (reads or writes) of an atomic variable be 3330regarded as synchronization points in the case of multiple tasks. 3331Particularly in the case of multi-processors this may require special 3332handling, e.g. the generation of memory barriers. This synchronization 3333is performed by default, but can be turned off using 3334@code{pragma Disable_Atomic_Synchronization}. The 3335@code{Enable_Atomic_Synchronization} pragma can be used to turn 3336it back on. 3337 3338The placement and scope rules for this pragma are the same as those 3339for @code{pragma Unsuppress}. In particular it can be used as a 3340configuration pragma, or in a declaration sequence where it applies 3341till the end of the scope. If an @code{Entity} argument is present, 3342the action applies only to that entity. 3343 3344@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas 3345@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{60} 3346@section Pragma Export_Function 3347 3348 3349@geindex Argument passing mechanisms 3350 3351Syntax: 3352 3353@example 3354pragma Export_Function ( 3355 [Internal =>] LOCAL_NAME 3356 [, [External =>] EXTERNAL_SYMBOL] 3357 [, [Parameter_Types =>] PARAMETER_TYPES] 3358 [, [Result_Type =>] result_SUBTYPE_MARK] 3359 [, [Mechanism =>] MECHANISM] 3360 [, [Result_Mechanism =>] MECHANISM_NAME]); 3361 3362EXTERNAL_SYMBOL ::= 3363 IDENTIFIER 3364| static_string_EXPRESSION 3365| "" 3366 3367PARAMETER_TYPES ::= 3368 null 3369| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3370 3371TYPE_DESIGNATOR ::= 3372 subtype_NAME 3373| subtype_Name ' Access 3374 3375MECHANISM ::= 3376 MECHANISM_NAME 3377| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3378 3379MECHANISM_ASSOCIATION ::= 3380 [formal_parameter_NAME =>] MECHANISM_NAME 3381 3382MECHANISM_NAME ::= Value | Reference 3383@end example 3384 3385Use this pragma to make a function externally callable and optionally 3386provide information on mechanisms to be used for passing parameter and 3387result values. We recommend, for the purposes of improving portability, 3388this pragma always be used in conjunction with a separate pragma 3389@code{Export}, which must precede the pragma @code{Export_Function}. 3390GNAT does not require a separate pragma @code{Export}, but if none is 3391present, @code{Convention Ada} is assumed, which is usually 3392not what is wanted, so it is usually appropriate to use this 3393pragma in conjunction with a @code{Export} or @code{Convention} 3394pragma that specifies the desired foreign convention. 3395Pragma @code{Export_Function} 3396(and @code{Export}, if present) must appear in the same declarative 3397region as the function to which they apply. 3398 3399The @code{internal_name} must uniquely designate the function to which the 3400pragma applies. If more than one function name exists of this name in 3401the declarative part you must use the @code{Parameter_Types} and 3402@code{Result_Type} parameters to achieve the required 3403unique designation. The @cite{subtype_mark}s in these parameters must 3404exactly match the subtypes in the corresponding function specification, 3405using positional notation to match parameters with subtype marks. 3406The form with an @code{'Access} attribute can be used to match an 3407anonymous access parameter. 3408 3409@geindex Suppressing external name 3410 3411Special treatment is given if the EXTERNAL is an explicit null 3412string or a static string expressions that evaluates to the null 3413string. In this case, no external name is generated. This form 3414still allows the specification of parameter mechanisms. 3415 3416@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas 3417@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{61} 3418@section Pragma Export_Object 3419 3420 3421Syntax: 3422 3423@example 3424pragma Export_Object 3425 [Internal =>] LOCAL_NAME 3426 [, [External =>] EXTERNAL_SYMBOL] 3427 [, [Size =>] EXTERNAL_SYMBOL] 3428 3429EXTERNAL_SYMBOL ::= 3430 IDENTIFIER 3431| static_string_EXPRESSION 3432@end example 3433 3434This pragma designates an object as exported, and apart from the 3435extended rules for external symbols, is identical in effect to the use of 3436the normal @code{Export} pragma applied to an object. You may use a 3437separate Export pragma (and you probably should from the point of view 3438of portability), but it is not required. @code{Size} is syntax checked, 3439but otherwise ignored by GNAT. 3440 3441@node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas 3442@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{62} 3443@section Pragma Export_Procedure 3444 3445 3446Syntax: 3447 3448@example 3449pragma Export_Procedure ( 3450 [Internal =>] LOCAL_NAME 3451 [, [External =>] EXTERNAL_SYMBOL] 3452 [, [Parameter_Types =>] PARAMETER_TYPES] 3453 [, [Mechanism =>] MECHANISM]); 3454 3455EXTERNAL_SYMBOL ::= 3456 IDENTIFIER 3457| static_string_EXPRESSION 3458| "" 3459 3460PARAMETER_TYPES ::= 3461 null 3462| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3463 3464TYPE_DESIGNATOR ::= 3465 subtype_NAME 3466| subtype_Name ' Access 3467 3468MECHANISM ::= 3469 MECHANISM_NAME 3470| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3471 3472MECHANISM_ASSOCIATION ::= 3473 [formal_parameter_NAME =>] MECHANISM_NAME 3474 3475MECHANISM_NAME ::= Value | Reference 3476@end example 3477 3478This pragma is identical to @code{Export_Function} except that it 3479applies to a procedure rather than a function and the parameters 3480@code{Result_Type} and @code{Result_Mechanism} are not permitted. 3481GNAT does not require a separate pragma @code{Export}, but if none is 3482present, @code{Convention Ada} is assumed, which is usually 3483not what is wanted, so it is usually appropriate to use this 3484pragma in conjunction with a @code{Export} or @code{Convention} 3485pragma that specifies the desired foreign convention. 3486 3487@geindex Suppressing external name 3488 3489Special treatment is given if the EXTERNAL is an explicit null 3490string or a static string expressions that evaluates to the null 3491string. In this case, no external name is generated. This form 3492still allows the specification of parameter mechanisms. 3493 3494@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas 3495@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{63} 3496@section Pragma Export_Valued_Procedure 3497 3498 3499Syntax: 3500 3501@example 3502pragma Export_Valued_Procedure ( 3503 [Internal =>] LOCAL_NAME 3504 [, [External =>] EXTERNAL_SYMBOL] 3505 [, [Parameter_Types =>] PARAMETER_TYPES] 3506 [, [Mechanism =>] MECHANISM]); 3507 3508EXTERNAL_SYMBOL ::= 3509 IDENTIFIER 3510| static_string_EXPRESSION 3511| "" 3512 3513PARAMETER_TYPES ::= 3514 null 3515| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3516 3517TYPE_DESIGNATOR ::= 3518 subtype_NAME 3519| subtype_Name ' Access 3520 3521MECHANISM ::= 3522 MECHANISM_NAME 3523| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3524 3525MECHANISM_ASSOCIATION ::= 3526 [formal_parameter_NAME =>] MECHANISM_NAME 3527 3528MECHANISM_NAME ::= Value | Reference 3529@end example 3530 3531This pragma is identical to @code{Export_Procedure} except that the 3532first parameter of @code{LOCAL_NAME}, which must be present, must be of 3533mode @code{out}, and externally the subprogram is treated as a function 3534with this parameter as the result of the function. GNAT provides for 3535this capability to allow the use of @code{out} and @code{in out} 3536parameters in interfacing to external functions (which are not permitted 3537in Ada functions). 3538GNAT does not require a separate pragma @code{Export}, but if none is 3539present, @code{Convention Ada} is assumed, which is almost certainly 3540not what is wanted since the whole point of this pragma is to interface 3541with foreign language functions, so it is usually appropriate to use this 3542pragma in conjunction with a @code{Export} or @code{Convention} 3543pragma that specifies the desired foreign convention. 3544 3545@geindex Suppressing external name 3546 3547Special treatment is given if the EXTERNAL is an explicit null 3548string or a static string expressions that evaluates to the null 3549string. In this case, no external name is generated. This form 3550still allows the specification of parameter mechanisms. 3551 3552@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas 3553@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{64} 3554@section Pragma Extend_System 3555 3556 3557@geindex System 3558@geindex extending 3559 3560@geindex DEC Ada 83 3561 3562Syntax: 3563 3564@example 3565pragma Extend_System ([Name =>] IDENTIFIER); 3566@end example 3567 3568This pragma is used to provide backwards compatibility with other 3569implementations that extend the facilities of package @code{System}. In 3570GNAT, @code{System} contains only the definitions that are present in 3571the Ada RM. However, other implementations, notably the DEC Ada 83 3572implementation, provide many extensions to package @code{System}. 3573 3574For each such implementation accommodated by this pragma, GNAT provides a 3575package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 3576implementation, which provides the required additional definitions. You 3577can use this package in two ways. You can @code{with} it in the normal 3578way and access entities either by selection or using a @code{use} 3579clause. In this case no special processing is required. 3580 3581However, if existing code contains references such as 3582@code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended 3583definitions provided in package @code{System}, you may use this pragma 3584to extend visibility in @code{System} in a non-standard way that 3585provides greater compatibility with the existing code. Pragma 3586@code{Extend_System} is a configuration pragma whose single argument is 3587the name of the package containing the extended definition 3588(e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under 3589control of this pragma will be processed using special visibility 3590processing that looks in package @code{System.Aux_@emph{xxx}} where 3591@code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in 3592package @code{System}, but not found in package @code{System}. 3593 3594You can use this pragma either to access a predefined @code{System} 3595extension supplied with the compiler, for example @code{Aux_DEC} or 3596you can construct your own extension unit following the above 3597definition. Note that such a package is a child of @code{System} 3598and thus is considered part of the implementation. 3599To compile it you will have to use the @emph{-gnatg} switch 3600for compiling System units, as explained in the 3601GNAT User’s Guide. 3602 3603@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas 3604@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{65} 3605@section Pragma Extensions_Allowed 3606 3607 3608@geindex Ada Extensions 3609 3610@geindex GNAT Extensions 3611 3612Syntax: 3613 3614@example 3615pragma Extensions_Allowed (On | Off); 3616@end example 3617 3618This configuration pragma enables or disables the implementation 3619extension mode (the use of Off as a parameter cancels the effect 3620of the @emph{-gnatX} command switch). 3621 3622In extension mode, the latest version of the Ada language is 3623implemented (currently Ada 2022), and in addition a number 3624of GNAT specific extensions are recognized as follows: 3625 3626 3627@itemize * 3628 3629@item 3630Constrained attribute for generic objects 3631 3632The @code{Constrained} attribute is permitted for objects of 3633generic types. The result indicates if the corresponding actual 3634is constrained. 3635 3636@item 3637@code{Static} aspect on intrinsic functions 3638 3639The Ada 202x @code{Static} aspect can be specified on Intrinsic imported 3640functions and the compiler will evaluate some of these intrinsic statically, 3641in particular the @code{Shift_Left} and @code{Shift_Right} intrinsics. 3642 3643@item 3644@code{'Reduce} attribute 3645 3646This attribute part of the Ada 202x language definition is provided for 3647now under -gnatX to confirm and potentially refine its usage and syntax. 3648 3649@item 3650@code{[]} aggregates 3651 3652This new aggregate syntax for arrays and containers is provided under -gnatX 3653to experiment and confirm this new language syntax. 3654 3655@item 3656Additional @code{when} constructs 3657 3658In addition to the @code{exit when CONDITION} control structure, several 3659additional constructs are allowed following this format. Including 3660@code{return when CONDITION}, @code{goto when CONDITION}, and 3661@code{raise [with EXCEPTION_MESSAGE] when CONDITION.} 3662 3663Some examples: 3664 3665@example 3666return Result when Variable > 10; 3667 3668raise Program_Error with "Element is null" when Element = null; 3669 3670goto End_Of_Subprogram when Variable = -1; 3671@end example 3672 3673@item 3674Casing on composite values (aka pattern matching) 3675 3676The selector for a case statement may be of a composite type, subject to 3677some restrictions (described below). Aggregate syntax is used for choices 3678of such a case statement; however, in cases where a “normal” aggregate would 3679require a discrete value, a discrete subtype may be used instead; box 3680notation can also be used to match all values. 3681 3682Consider this example: 3683 3684@example 3685type Rec is record 3686 F1, F2 : Integer; 3687end record; 3688 3689procedure Caser_1 (X : Rec) is 3690begin 3691 case X is 3692 when (F1 => Positive, F2 => Positive) => 3693 Do_This; 3694 when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) => 3695 Do_That; 3696 when others => 3697 Do_The_Other_Thing; 3698 end case; 3699end Caser_1; 3700@end example 3701 3702If Caser_1 is called and both components of X are positive, then 3703Do_This will be called; otherwise, if either component is nonnegative 3704then Do_That will be called; otherwise, Do_The_Other_Thing will be called. 3705 3706If the set of values that match the choice(s) of an earlier alternative 3707overlaps the corresponding set of a later alternative, then the first 3708set shall be a proper subset of the second (and the later alternative 3709will not be executed if the earlier alternative “matches”). All possible 3710values of the composite type shall be covered. The composite type of the 3711selector shall be an array or record type that is neither limited 3712class-wide. 3713 3714If a subcomponent’s subtype does not meet certain restrictions, then 3715the only value that can be specified for that subcomponent in a case 3716choice expression is a “box” component association (which matches all 3717possible values for the subcomponent). This restriction applies if 3718 3719 3720@itemize - 3721 3722@item 3723the component subtype is not a record, array, or discrete type; or 3724 3725@item 3726the component subtype is subject to a non-static constraint or 3727has a predicate; or 3728 3729@item 3730the component type is an enumeration type that is subject to an 3731enumeration representation clause; or 3732 3733@item 3734the component type is a multidimensional array type or an 3735array type with a nonstatic index subtype. 3736@end itemize 3737 3738Support for casing on arrays (and on records that contain arrays) is 3739currently subject to some restrictions. Non-positional 3740array aggregates are not supported as (or within) case choices. Likewise 3741for array type and subtype names. The current implementation exceeds 3742compile-time capacity limits in some annoyingly common scenarios; the 3743message generated in such cases is usually “Capacity exceeded in compiling 3744case statement with composite selector type”. 3745 3746In addition, pattern bindings are supported. This is a mechanism 3747for binding a name to a component of a matching value for use within 3748an alternative of a case statement. For a component association 3749that occurs within a case choice, the expression may be followed by 3750“is <identifier>”. In the special case of a “box” component association, 3751the identifier may instead be provided within the box. Either of these 3752indicates that the given identifer denotes (a constant view of) the matching 3753subcomponent of the case selector. Binding is not yet supported for arrays 3754or subcomponents thereof. 3755 3756Consider this example (which uses type Rec from the previous example): 3757 3758@example 3759procedure Caser_2 (X : Rec) is 3760begin 3761 case X is 3762 when (F1 => Positive is Abc, F2 => Positive) => 3763 Do_This (Abc) 3764 when (F1 => Natural is N1, F2 => <N2>) | 3765 (F1 => <N2>, F2 => Natural is N1) => 3766 Do_That (Param_1 => N1, Param_2 => N2); 3767 when others => 3768 Do_The_Other_Thing; 3769 end case; 3770end Caser_2; 3771@end example 3772 3773This example is the same as the previous one with respect to 3774determining whether Do_This, Do_That, or Do_The_Other_Thing will 3775be called. But for this version, Do_This takes a parameter and Do_That 3776takes two parameters. If Do_This is called, the actual parameter in the 3777call will be X.F1. 3778 3779If Do_That is called, the situation is more complex because there are two 3780choices for that alternative. If Do_That is called because the first choice 3781matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero 3782or negative), then the actual parameters of the call will be (in order) 3783X.F1 and X.F2. If Do_That is called because the second choice matched (and 3784the first one did not), then the actual parameters will be reversed. 3785 3786Within the choice list for single alternative, each choice must 3787define the same set of bindings and the component subtypes for 3788for a given identifer must all statically match. Currently, the case 3789of a binding for a nondiscrete component is not implemented. 3790 3791@item 3792Fixed lower bounds for array types and subtypes 3793 3794Unconstrained array types and subtypes can be specified with a lower bound 3795that is fixed to a certain value, by writing an index range that uses the 3796syntax “<lower-bound-expression> .. <>”. This guarantees that all objects 3797of the type or subtype will have the specified lower bound. 3798 3799For example, a matrix type with fixed lower bounds of zero for each 3800dimension can be declared by the following: 3801 3802@example 3803type Matrix is 3804 array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; 3805@end example 3806 3807Objects of type Matrix declared with an index constraint must have index 3808ranges starting at zero: 3809 3810@example 3811M1 : Matrix (0 .. 9, 0 .. 19); 3812M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE 3813@end example 3814 3815Similarly, a subtype of String can be declared that specifies the lower 3816bound of objects of that subtype to be 1: 3817 3818@quotation 3819 3820@example 3821subtype String_1 is String (1 .. <>); 3822@end example 3823@end quotation 3824 3825If a string slice is passed to a formal of subtype String_1 in a call to 3826a subprogram S, the slice’s bounds will “slide” so that the lower bound 3827is 1. Within S, the lower bound of the formal is known to be 1, so, unlike 3828a normal unconstrained String formal, there is no need to worry about 3829accounting for other possible lower-bound values. Sliding of bounds also 3830occurs in other contexts, such as for object declarations with an 3831unconstrained subtype with fixed lower bound, as well as in subtype 3832conversions. 3833 3834Use of this feature increases safety by simplifying code, and can also 3835improve the efficiency of indexing operations, since the compiler statically 3836knows the lower bound of unconstrained array formals when the formal’s 3837subtype has index ranges with static fixed lower bounds. 3838 3839@item 3840Prefixed-view notation for calls to primitive subprograms of untagged types 3841 3842Since Ada 2005, calls to primitive subprograms of a tagged type that 3843have a “prefixed view” (see RM 4.1.3(9.2)) have been allowed to be 3844written using the form of a selected_component, with the first actual 3845parameter given as the prefix and the name of the subprogram as a 3846selector. This prefixed-view notation for calls is extended so as to 3847also allow such syntax for calls to primitive subprograms of untagged 3848types. The primitives of an untagged type T that have a prefixed view 3849are those where the first formal parameter of the subprogram either 3850is of type T or is an anonymous access parameter whose designated type 3851is T. For a type that has a component that happens to have the same 3852simple name as one of the type’s primitive subprograms, where the 3853component is visible at the point of a selected_component using that 3854name, preference is given to the component in a selected_component 3855(as is currently the case for tagged types with such component names). 3856 3857@item 3858Expression defaults for generic formal functions 3859 3860The declaration of a generic formal function is allowed to specify 3861an expression as a default, using the syntax of an expression function. 3862 3863Here is an example of this feature: 3864 3865@example 3866generic 3867 type T is private; 3868 with function Copy (Item : T) return T is (Item); -- Defaults to Item 3869package Stacks is 3870 3871 type Stack is limited private; 3872 3873 procedure Push (S : in out Stack; X : T); -- Calls Copy on X 3874 3875 function Pop (S : in out Stack) return T; -- Calls Copy to return item 3876 3877private 3878 -- ... 3879end Stacks; 3880@end example 3881@end itemize 3882 3883@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas 3884@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{66}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{67} 3885@section Pragma Extensions_Visible 3886 3887 3888Syntax: 3889 3890@example 3891pragma Extensions_Visible [ (boolean_EXPRESSION) ]; 3892@end example 3893 3894For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} 3895in the SPARK 2014 Reference Manual, section 6.1.7. 3896 3897@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas 3898@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{68} 3899@section Pragma External 3900 3901 3902Syntax: 3903 3904@example 3905pragma External ( 3906 [ Convention =>] convention_IDENTIFIER, 3907 [ Entity =>] LOCAL_NAME 3908 [, [External_Name =>] static_string_EXPRESSION ] 3909 [, [Link_Name =>] static_string_EXPRESSION ]); 3910@end example 3911 3912This pragma is identical in syntax and semantics to pragma 3913@code{Export} as defined in the Ada Reference Manual. It is 3914provided for compatibility with some Ada 83 compilers that 3915used this pragma for exactly the same purposes as pragma 3916@code{Export} before the latter was standardized. 3917 3918@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas 3919@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{69} 3920@section Pragma External_Name_Casing 3921 3922 3923@geindex Dec Ada 83 casing compatibility 3924 3925@geindex External Names 3926@geindex casing 3927 3928@geindex Casing of External names 3929 3930Syntax: 3931 3932@example 3933pragma External_Name_Casing ( 3934 Uppercase | Lowercase 3935 [, Uppercase | Lowercase | As_Is]); 3936@end example 3937 3938This pragma provides control over the casing of external names associated 3939with Import and Export pragmas. There are two cases to consider: 3940 3941 3942@itemize * 3943 3944@item 3945Implicit external names 3946 3947Implicit external names are derived from identifiers. The most common case 3948arises when a standard Ada Import or Export pragma is used with only two 3949arguments, as in: 3950 3951@example 3952pragma Import (C, C_Routine); 3953@end example 3954 3955Since Ada is a case-insensitive language, the spelling of the identifier in 3956the Ada source program does not provide any information on the desired 3957casing of the external name, and so a convention is needed. In GNAT the 3958default treatment is that such names are converted to all lower case 3959letters. This corresponds to the normal C style in many environments. 3960The first argument of pragma @code{External_Name_Casing} can be used to 3961control this treatment. If @code{Uppercase} is specified, then the name 3962will be forced to all uppercase letters. If @code{Lowercase} is specified, 3963then the normal default of all lower case letters will be used. 3964 3965This same implicit treatment is also used in the case of extended DEC Ada 83 3966compatible Import and Export pragmas where an external name is explicitly 3967specified using an identifier rather than a string. 3968 3969@item 3970Explicit external names 3971 3972Explicit external names are given as string literals. The most common case 3973arises when a standard Ada Import or Export pragma is used with three 3974arguments, as in: 3975 3976@example 3977pragma Import (C, C_Routine, "C_routine"); 3978@end example 3979 3980In this case, the string literal normally provides the exact casing required 3981for the external name. The second argument of pragma 3982@code{External_Name_Casing} may be used to modify this behavior. 3983If @code{Uppercase} is specified, then the name 3984will be forced to all uppercase letters. If @code{Lowercase} is specified, 3985then the name will be forced to all lowercase letters. A specification of 3986@code{As_Is} provides the normal default behavior in which the casing is 3987taken from the string provided. 3988@end itemize 3989 3990This pragma may appear anywhere that a pragma is valid. In particular, it 3991can be used as a configuration pragma in the @code{gnat.adc} file, in which 3992case it applies to all subsequent compilations, or it can be used as a program 3993unit pragma, in which case it only applies to the current unit, or it can 3994be used more locally to control individual Import/Export pragmas. 3995 3996It was primarily intended for use with OpenVMS systems, where many 3997compilers convert all symbols to upper case by default. For interfacing to 3998such compilers (e.g., the DEC C compiler), it may be convenient to use 3999the pragma: 4000 4001@example 4002pragma External_Name_Casing (Uppercase, Uppercase); 4003@end example 4004 4005to enforce the upper casing of all external symbols. 4006 4007@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas 4008@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6a} 4009@section Pragma Fast_Math 4010 4011 4012Syntax: 4013 4014@example 4015pragma Fast_Math; 4016@end example 4017 4018This is a configuration pragma which activates a mode in which speed is 4019considered more important for floating-point operations than absolutely 4020accurate adherence to the requirements of the standard. Currently the 4021following operations are affected: 4022 4023 4024@table @asis 4025 4026@item @emph{Complex Multiplication} 4027 4028The normal simple formula for complex multiplication can result in intermediate 4029overflows for numbers near the end of the range. The Ada standard requires that 4030this situation be detected and corrected by scaling, but in Fast_Math mode such 4031cases will simply result in overflow. Note that to take advantage of this you 4032must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} 4033under control of the pragma, rather than use the preinstantiated versions. 4034@end table 4035 4036@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas 4037@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6b}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6c} 4038@section Pragma Favor_Top_Level 4039 4040 4041Syntax: 4042 4043@example 4044pragma Favor_Top_Level (type_NAME); 4045@end example 4046 4047The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram 4048type. This pragma is an efficiency hint to the compiler, regarding the use of 4049@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. 4050The pragma means that nested subprograms are not used with this type, or are 4051rare, so that the generated code should be efficient in the top-level case. 4052When this pragma is used, dynamically generated trampolines may be used on some 4053targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. 4054 4055@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas 4056@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6d} 4057@section Pragma Finalize_Storage_Only 4058 4059 4060Syntax: 4061 4062@example 4063pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 4064@end example 4065 4066The argument of pragma @code{Finalize_Storage_Only} must denote a local type which 4067is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The 4068pragma suppresses the call to @code{Finalize} for declared library-level objects 4069of the argument type. This is mostly useful for types where finalization is 4070only used to deal with storage reclamation since in most environments it is 4071not necessary to reclaim memory just before terminating execution, hence the 4072name. Note that this pragma does not suppress Finalize calls for library-level 4073heap-allocated objects (see pragma @code{No_Heap_Finalization}). 4074 4075@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas 4076@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6e} 4077@section Pragma Float_Representation 4078 4079 4080Syntax: 4081 4082@example 4083pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 4084 4085FLOAT_REP ::= VAX_Float | IEEE_Float 4086@end example 4087 4088In the one argument form, this pragma is a configuration pragma which 4089allows control over the internal representation chosen for the predefined 4090floating point types declared in the packages @code{Standard} and 4091@code{System}. This pragma is only provided for compatibility and has no effect. 4092 4093The two argument form specifies the representation to be used for 4094the specified floating-point type. The argument must 4095be @code{IEEE_Float} to specify the use of IEEE format, as follows: 4096 4097 4098@itemize * 4099 4100@item 4101For a digits value of 6, 32-bit IEEE short format will be used. 4102 4103@item 4104For a digits value of 15, 64-bit IEEE long format will be used. 4105 4106@item 4107No other value of digits is permitted. 4108@end itemize 4109 4110@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas 4111@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6f}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{70} 4112@section Pragma Ghost 4113 4114 4115Syntax: 4116 4117@example 4118pragma Ghost [ (boolean_EXPRESSION) ]; 4119@end example 4120 4121For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK 41222014 Reference Manual, section 6.9. 4123 4124@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas 4125@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{72} 4126@section Pragma Global 4127 4128 4129Syntax: 4130 4131@example 4132pragma Global (GLOBAL_SPECIFICATION); 4133 4134GLOBAL_SPECIFICATION ::= 4135 null 4136 | (GLOBAL_LIST) 4137 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 4138 4139MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 4140 4141MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 4142GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 4143GLOBAL_ITEM ::= NAME 4144@end example 4145 4146For the semantics of this pragma, see the entry for aspect @code{Global} in the 4147SPARK 2014 Reference Manual, section 6.1.4. 4148 4149@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas 4150@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{73} 4151@section Pragma Ident 4152 4153 4154Syntax: 4155 4156@example 4157pragma Ident (static_string_EXPRESSION); 4158@end example 4159 4160This pragma is identical in effect to pragma @code{Comment}. It is provided 4161for compatibility with other Ada compilers providing this pragma. 4162 4163@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas 4164@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{74} 4165@section Pragma Ignore_Pragma 4166 4167 4168Syntax: 4169 4170@example 4171pragma Ignore_Pragma (pragma_IDENTIFIER); 4172@end example 4173 4174This is a configuration pragma 4175that takes a single argument that is a simple identifier. Any subsequent 4176use of a pragma whose pragma identifier matches this argument will be 4177silently ignored. This may be useful when legacy code or code intended 4178for compilation with some other compiler contains pragmas that match the 4179name, but not the exact implementation, of a GNAT pragma. The use of this 4180pragma allows such pragmas to be ignored, which may be useful in CodePeer 4181mode, or during porting of legacy code. 4182 4183@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas 4184@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{75} 4185@section Pragma Implementation_Defined 4186 4187 4188Syntax: 4189 4190@example 4191pragma Implementation_Defined (local_NAME); 4192@end example 4193 4194This pragma marks a previously declared entity as implementation-defined. 4195For an overloaded entity, applies to the most recent homonym. 4196 4197@example 4198pragma Implementation_Defined; 4199@end example 4200 4201The form with no arguments appears anywhere within a scope, most 4202typically a package spec, and indicates that all entities that are 4203defined within the package spec are Implementation_Defined. 4204 4205This pragma is used within the GNAT runtime library to identify 4206implementation-defined entities introduced in language-defined units, 4207for the purpose of implementing the No_Implementation_Identifiers 4208restriction. 4209 4210@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas 4211@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{76} 4212@section Pragma Implemented 4213 4214 4215Syntax: 4216 4217@example 4218pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 4219 4220implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 4221@end example 4222 4223This is an Ada 2012 representation pragma which applies to protected, task 4224and synchronized interface primitives. The use of pragma Implemented provides 4225a way to impose a static requirement on the overriding operation by adhering 4226to one of the three implementation kinds: entry, protected procedure or any of 4227the above. This pragma is available in all earlier versions of Ada as an 4228implementation-defined pragma. 4229 4230@example 4231type Synch_Iface is synchronized interface; 4232procedure Prim_Op (Obj : in out Iface) is abstract; 4233pragma Implemented (Prim_Op, By_Protected_Procedure); 4234 4235protected type Prot_1 is new Synch_Iface with 4236 procedure Prim_Op; -- Legal 4237end Prot_1; 4238 4239protected type Prot_2 is new Synch_Iface with 4240 entry Prim_Op; -- Illegal 4241end Prot_2; 4242 4243task type Task_Typ is new Synch_Iface with 4244 entry Prim_Op; -- Illegal 4245end Task_Typ; 4246@end example 4247 4248When applied to the procedure_or_entry_NAME of a requeue statement, pragma 4249Implemented determines the runtime behavior of the requeue. Implementation kind 4250By_Entry guarantees that the action of requeueing will proceed from an entry to 4251another entry. Implementation kind By_Protected_Procedure transforms the 4252requeue into a dispatching call, thus eliminating the chance of blocking. Kind 4253By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 4254the target’s overriding subprogram kind. 4255 4256@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas 4257@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{77} 4258@section Pragma Implicit_Packing 4259 4260 4261@geindex Rational Profile 4262 4263Syntax: 4264 4265@example 4266pragma Implicit_Packing; 4267@end example 4268 4269This is a configuration pragma that requests implicit packing for packed 4270arrays for which a size clause is given but no explicit pragma Pack or 4271specification of Component_Size is present. It also applies to records 4272where no record representation clause is present. Consider this example: 4273 4274@example 4275type R is array (0 .. 7) of Boolean; 4276for R'Size use 8; 4277@end example 4278 4279In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 4280does not change the layout of a composite object. So the Size clause in the 4281above example is normally rejected, since the default layout of the array uses 42828-bit components, and thus the array requires a minimum of 64 bits. 4283 4284If this declaration is compiled in a region of code covered by an occurrence 4285of the configuration pragma Implicit_Packing, then the Size clause in this 4286and similar examples will cause implicit packing and thus be accepted. For 4287this implicit packing to occur, the type in question must be an array of small 4288components whose size is known at compile time, and the Size clause must 4289specify the exact size that corresponds to the number of elements in the array 4290multiplied by the size in bits of the component type (both single and 4291multi-dimensioned arrays can be controlled with this pragma). 4292 4293@geindex Array packing 4294 4295Similarly, the following example shows the use in the record case 4296 4297@example 4298type r is record 4299 a, b, c, d, e, f, g, h : boolean; 4300 chr : character; 4301end record; 4302for r'size use 16; 4303@end example 4304 4305Without a pragma Pack, each Boolean field requires 8 bits, so the 4306minimum size is 72 bits, but with a pragma Pack, 16 bits would be 4307sufficient. The use of pragma Implicit_Packing allows this record 4308declaration to compile without an explicit pragma Pack. 4309 4310@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas 4311@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{78} 4312@section Pragma Import_Function 4313 4314 4315Syntax: 4316 4317@example 4318pragma Import_Function ( 4319 [Internal =>] LOCAL_NAME, 4320 [, [External =>] EXTERNAL_SYMBOL] 4321 [, [Parameter_Types =>] PARAMETER_TYPES] 4322 [, [Result_Type =>] SUBTYPE_MARK] 4323 [, [Mechanism =>] MECHANISM] 4324 [, [Result_Mechanism =>] MECHANISM_NAME]); 4325 4326EXTERNAL_SYMBOL ::= 4327 IDENTIFIER 4328| static_string_EXPRESSION 4329 4330PARAMETER_TYPES ::= 4331 null 4332| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4333 4334TYPE_DESIGNATOR ::= 4335 subtype_NAME 4336| subtype_Name ' Access 4337 4338MECHANISM ::= 4339 MECHANISM_NAME 4340| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4341 4342MECHANISM_ASSOCIATION ::= 4343 [formal_parameter_NAME =>] MECHANISM_NAME 4344 4345MECHANISM_NAME ::= 4346 Value 4347| Reference 4348@end example 4349 4350This pragma is used in conjunction with a pragma @code{Import} to 4351specify additional information for an imported function. The pragma 4352@code{Import} (or equivalent pragma @code{Interface}) must precede the 4353@code{Import_Function} pragma and both must appear in the same 4354declarative part as the function specification. 4355 4356The @code{Internal} argument must uniquely designate 4357the function to which the 4358pragma applies. If more than one function name exists of this name in 4359the declarative part you must use the @code{Parameter_Types} and 4360@code{Result_Type} parameters to achieve the required unique 4361designation. Subtype marks in these parameters must exactly match the 4362subtypes in the corresponding function specification, using positional 4363notation to match parameters with subtype marks. 4364The form with an @code{'Access} attribute can be used to match an 4365anonymous access parameter. 4366 4367You may optionally use the @code{Mechanism} and @code{Result_Mechanism} 4368parameters to specify passing mechanisms for the 4369parameters and result. If you specify a single mechanism name, it 4370applies to all parameters. Otherwise you may specify a mechanism on a 4371parameter by parameter basis using either positional or named 4372notation. If the mechanism is not specified, the default mechanism 4373is used. 4374 4375@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas 4376@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{79} 4377@section Pragma Import_Object 4378 4379 4380Syntax: 4381 4382@example 4383pragma Import_Object 4384 [Internal =>] LOCAL_NAME 4385 [, [External =>] EXTERNAL_SYMBOL] 4386 [, [Size =>] EXTERNAL_SYMBOL]); 4387 4388EXTERNAL_SYMBOL ::= 4389 IDENTIFIER 4390| static_string_EXPRESSION 4391@end example 4392 4393This pragma designates an object as imported, and apart from the 4394extended rules for external symbols, is identical in effect to the use of 4395the normal @code{Import} pragma applied to an object. Unlike the 4396subprogram case, you need not use a separate @code{Import} pragma, 4397although you may do so (and probably should do so from a portability 4398point of view). @code{size} is syntax checked, but otherwise ignored by 4399GNAT. 4400 4401@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas 4402@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7a} 4403@section Pragma Import_Procedure 4404 4405 4406Syntax: 4407 4408@example 4409pragma Import_Procedure ( 4410 [Internal =>] LOCAL_NAME 4411 [, [External =>] EXTERNAL_SYMBOL] 4412 [, [Parameter_Types =>] PARAMETER_TYPES] 4413 [, [Mechanism =>] MECHANISM]); 4414 4415EXTERNAL_SYMBOL ::= 4416 IDENTIFIER 4417| static_string_EXPRESSION 4418 4419PARAMETER_TYPES ::= 4420 null 4421| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4422 4423TYPE_DESIGNATOR ::= 4424 subtype_NAME 4425| subtype_Name ' Access 4426 4427MECHANISM ::= 4428 MECHANISM_NAME 4429| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4430 4431MECHANISM_ASSOCIATION ::= 4432 [formal_parameter_NAME =>] MECHANISM_NAME 4433 4434MECHANISM_NAME ::= Value | Reference 4435@end example 4436 4437This pragma is identical to @code{Import_Function} except that it 4438applies to a procedure rather than a function and the parameters 4439@code{Result_Type} and @code{Result_Mechanism} are not permitted. 4440 4441@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas 4442@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7b} 4443@section Pragma Import_Valued_Procedure 4444 4445 4446Syntax: 4447 4448@example 4449pragma Import_Valued_Procedure ( 4450 [Internal =>] LOCAL_NAME 4451 [, [External =>] EXTERNAL_SYMBOL] 4452 [, [Parameter_Types =>] PARAMETER_TYPES] 4453 [, [Mechanism =>] MECHANISM]); 4454 4455EXTERNAL_SYMBOL ::= 4456 IDENTIFIER 4457| static_string_EXPRESSION 4458 4459PARAMETER_TYPES ::= 4460 null 4461| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4462 4463TYPE_DESIGNATOR ::= 4464 subtype_NAME 4465| subtype_Name ' Access 4466 4467MECHANISM ::= 4468 MECHANISM_NAME 4469| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4470 4471MECHANISM_ASSOCIATION ::= 4472 [formal_parameter_NAME =>] MECHANISM_NAME 4473 4474MECHANISM_NAME ::= Value | Reference 4475@end example 4476 4477This pragma is identical to @code{Import_Procedure} except that the 4478first parameter of @code{LOCAL_NAME}, which must be present, must be of 4479mode @code{out}, and externally the subprogram is treated as a function 4480with this parameter as the result of the function. The purpose of this 4481capability is to allow the use of @code{out} and @code{in out} 4482parameters in interfacing to external functions (which are not permitted 4483in Ada functions). You may optionally use the @code{Mechanism} 4484parameters to specify passing mechanisms for the parameters. 4485If you specify a single mechanism name, it applies to all parameters. 4486Otherwise you may specify a mechanism on a parameter by parameter 4487basis using either positional or named notation. If the mechanism is not 4488specified, the default mechanism is used. 4489 4490Note that it is important to use this pragma in conjunction with a separate 4491pragma Import that specifies the desired convention, since otherwise the 4492default convention is Ada, which is almost certainly not what is required. 4493 4494@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas 4495@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7c} 4496@section Pragma Independent 4497 4498 4499Syntax: 4500 4501@example 4502pragma Independent (Local_NAME); 4503@end example 4504 4505This pragma is standard in Ada 2012 mode (which also provides an aspect 4506of the same name). It is also available as an implementation-defined 4507pragma in all earlier versions. It specifies that the 4508designated object or all objects of the designated type must be 4509independently addressable. This means that separate tasks can safely 4510manipulate such objects. For example, if two components of a record are 4511independent, then two separate tasks may access these two components. 4512This may place 4513constraints on the representation of the object (for instance prohibiting 4514tight packing). 4515 4516@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas 4517@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7d} 4518@section Pragma Independent_Components 4519 4520 4521Syntax: 4522 4523@example 4524pragma Independent_Components (Local_NAME); 4525@end example 4526 4527This pragma is standard in Ada 2012 mode (which also provides an aspect 4528of the same name). It is also available as an implementation-defined 4529pragma in all earlier versions. It specifies that the components of the 4530designated object, or the components of each object of the designated 4531type, must be 4532independently addressable. This means that separate tasks can safely 4533manipulate separate components in the composite object. This may place 4534constraints on the representation of the object (for instance prohibiting 4535tight packing). 4536 4537@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas 4538@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7e}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7f} 4539@section Pragma Initial_Condition 4540 4541 4542Syntax: 4543 4544@example 4545pragma Initial_Condition (boolean_EXPRESSION); 4546@end example 4547 4548For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} 4549in the SPARK 2014 Reference Manual, section 7.1.6. 4550 4551@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas 4552@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{80} 4553@section Pragma Initialize_Scalars 4554 4555 4556@geindex debugging with Initialize_Scalars 4557 4558Syntax: 4559 4560@example 4561pragma Initialize_Scalars 4562 [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; 4563 4564TYPE_VALUE_PAIR ::= 4565 SCALAR_TYPE => static_EXPRESSION 4566 4567SCALAR_TYPE := 4568 Short_Float 4569| Float 4570| Long_Float 4571| Long_Long_Flat 4572| Signed_8 4573| Signed_16 4574| Signed_32 4575| Signed_64 4576| Unsigned_8 4577| Unsigned_16 4578| Unsigned_32 4579| Unsigned_64 4580@end example 4581 4582This pragma is similar to @code{Normalize_Scalars} conceptually but has two 4583important differences. 4584 4585First, there is no requirement for the pragma to be used uniformly in all units 4586of a partition. In particular, it is fine to use this just for some or all of 4587the application units of a partition, without needing to recompile the run-time 4588library. In the case where some units are compiled with the pragma, and some 4589without, then a declaration of a variable where the type is defined in package 4590Standard or is locally declared will always be subject to initialization, as 4591will any declaration of a scalar variable. For composite variables, whether the 4592variable is initialized may also depend on whether the package in which the 4593type of the variable is declared is compiled with the pragma. 4594 4595The other important difference is that the programmer can control the value 4596used for initializing scalar objects. This effect can be achieved in several 4597different ways: 4598 4599 4600@itemize * 4601 4602@item 4603At compile time, the programmer can specify the invalid value for a 4604particular family of scalar types using the optional arguments of the pragma. 4605 4606The compile-time approach is intended to optimize the generated code for the 4607pragma, by possibly using fast operations such as @code{memset}. Note that such 4608optimizations require using values where the bytes all have the same binary 4609representation. 4610 4611@item 4612At bind time, the programmer has several options: 4613 4614 4615@itemize * 4616 4617@item 4618Initialization with invalid values (similar to Normalize_Scalars, though 4619for Initialize_Scalars it is not always possible to determine the invalid 4620values in complex cases like signed component fields with nonstandard 4621sizes). 4622 4623@item 4624Initialization with high values. 4625 4626@item 4627Initialization with low values. 4628 4629@item 4630Initialization with a specific bit pattern. 4631@end itemize 4632 4633See the GNAT User’s Guide for binder options for specifying these cases. 4634 4635The bind-time approach is intended to provide fast turnaround for testing 4636with different values, without having to recompile the program. 4637 4638@item 4639At execution time, the programmer can specify the invalid values using an 4640environment variable. See the GNAT User’s Guide for details. 4641 4642The execution-time approach is intended to provide fast turnaround for 4643testing with different values, without having to recompile and rebind the 4644program. 4645@end itemize 4646 4647Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction 4648with the enhanced validity checking that is now provided in GNAT, which checks 4649for invalid values under more conditions. Using this feature (see description 4650of the @emph{-gnatV} flag in the GNAT User’s Guide) in conjunction with pragma 4651@code{Initialize_Scalars} provides a powerful new tool to assist in the detection 4652of problems caused by uninitialized variables. 4653 4654Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the 4655generated code. This may cause your code to be substantially larger. It may 4656also cause an increase in the amount of stack required, so it is probably a 4657good idea to turn on stack checking (see description of stack checking in the 4658GNAT User’s Guide) when using this pragma. 4659 4660@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas 4661@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{81}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{82} 4662@section Pragma Initializes 4663 4664 4665Syntax: 4666 4667@example 4668pragma Initializes (INITIALIZATION_LIST); 4669 4670INITIALIZATION_LIST ::= 4671 null 4672 | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) 4673 4674INITIALIZATION_ITEM ::= name [=> INPUT_LIST] 4675 4676INPUT_LIST ::= 4677 null 4678 | INPUT 4679 | (INPUT @{, INPUT@}) 4680 4681INPUT ::= name 4682@end example 4683 4684For the semantics of this pragma, see the entry for aspect @code{Initializes} in the 4685SPARK 2014 Reference Manual, section 7.1.5. 4686 4687@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas 4688@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{84} 4689@section Pragma Inline_Always 4690 4691 4692Syntax: 4693 4694@example 4695pragma Inline_Always (NAME [, NAME]); 4696@end example 4697 4698Similar to pragma @code{Inline} except that inlining is unconditional. 4699Inline_Always instructs the compiler to inline every direct call to the 4700subprogram or else to emit a compilation error, independently of any 4701option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level. 4702It is an error to take the address or access of @code{NAME}. It is also an error to 4703apply this pragma to a primitive operation of a tagged type. Thanks to such 4704restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. 4705 4706@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas 4707@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{85} 4708@section Pragma Inline_Generic 4709 4710 4711Syntax: 4712 4713@example 4714pragma Inline_Generic (GNAME @{, GNAME@}); 4715 4716GNAME ::= generic_unit_NAME | generic_instance_NAME 4717@end example 4718 4719This pragma is provided for compatibility with Dec Ada 83. It has 4720no effect in GNAT (which always inlines generics), other 4721than to check that the given names are all names of generic units or 4722generic instances. 4723 4724@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas 4725@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{86} 4726@section Pragma Interface 4727 4728 4729Syntax: 4730 4731@example 4732pragma Interface ( 4733 [Convention =>] convention_identifier, 4734 [Entity =>] local_NAME 4735 [, [External_Name =>] static_string_expression] 4736 [, [Link_Name =>] static_string_expression]); 4737@end example 4738 4739This pragma is identical in syntax and semantics to 4740the standard Ada pragma @code{Import}. It is provided for compatibility 4741with Ada 83. The definition is upwards compatible both with pragma 4742@code{Interface} as defined in the Ada 83 Reference Manual, and also 4743with some extended implementations of this pragma in certain Ada 83 4744implementations. The only difference between pragma @code{Interface} 4745and pragma @code{Import} is that there is special circuitry to allow 4746both pragmas to appear for the same subprogram entity (normally it 4747is illegal to have multiple @code{Import} pragmas. This is useful in 4748maintaining Ada 83/Ada 95 compatibility and is compatible with other 4749Ada 83 compilers. 4750 4751@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas 4752@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{87} 4753@section Pragma Interface_Name 4754 4755 4756Syntax: 4757 4758@example 4759pragma Interface_Name ( 4760 [Entity =>] LOCAL_NAME 4761 [, [External_Name =>] static_string_EXPRESSION] 4762 [, [Link_Name =>] static_string_EXPRESSION]); 4763@end example 4764 4765This pragma provides an alternative way of specifying the interface name 4766for an interfaced subprogram, and is provided for compatibility with Ada 476783 compilers that use the pragma for this purpose. You must provide at 4768least one of @code{External_Name} or @code{Link_Name}. 4769 4770@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas 4771@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{88} 4772@section Pragma Interrupt_Handler 4773 4774 4775Syntax: 4776 4777@example 4778pragma Interrupt_Handler (procedure_LOCAL_NAME); 4779@end example 4780 4781This program unit pragma is supported for parameterless protected procedures 4782as described in Annex C of the Ada Reference Manual. 4783 4784@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas 4785@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{89} 4786@section Pragma Interrupt_State 4787 4788 4789Syntax: 4790 4791@example 4792pragma Interrupt_State 4793 ([Name =>] value, 4794 [State =>] SYSTEM | RUNTIME | USER); 4795@end example 4796 4797Normally certain interrupts are reserved to the implementation. Any attempt 4798to attach an interrupt causes Program_Error to be raised, as described in 4799RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 4800many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is 4801reserved to the implementation, so that @code{Ctrl-C} can be used to 4802interrupt execution. Additionally, signals such as @code{SIGSEGV}, 4803@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 4804Ada exceptions, or used to implement run-time functions such as the 4805@code{abort} statement and stack overflow checking. 4806 4807Pragma @code{Interrupt_State} provides a general mechanism for overriding 4808such uses of interrupts. It subsumes the functionality of pragma 4809@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 4810available on Windows. On all other platforms than VxWorks, 4811it applies to signals; on VxWorks, it applies to vectored hardware interrupts 4812and may be used to mark interrupts required by the board support package 4813as reserved. 4814 4815Interrupts can be in one of three states: 4816 4817 4818@itemize * 4819 4820@item 4821System 4822 4823The interrupt is reserved (no Ada handler can be installed), and the 4824Ada run-time may not install a handler. As a result you are guaranteed 4825standard system default action if this interrupt is raised. This also allows 4826installing a low level handler via C APIs such as sigaction(), outside 4827of Ada control. 4828 4829@item 4830Runtime 4831 4832The interrupt is reserved (no Ada handler can be installed). The run time 4833is allowed to install a handler for internal control purposes, but is 4834not required to do so. 4835 4836@item 4837User 4838 4839The interrupt is unreserved. The user may install an Ada handler via 4840Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide 4841some other action. 4842@end itemize 4843 4844These states are the allowed values of the @code{State} parameter of the 4845pragma. The @code{Name} parameter is a value of the type 4846@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 4847@code{Ada.Interrupts.Names}. 4848 4849This is a configuration pragma, and the binder will check that there 4850are no inconsistencies between different units in a partition in how a 4851given interrupt is specified. It may appear anywhere a pragma is legal. 4852 4853The effect is to move the interrupt to the specified state. 4854 4855By declaring interrupts to be SYSTEM, you guarantee the standard system 4856action, such as a core dump. 4857 4858By declaring interrupts to be USER, you guarantee that you can install 4859a handler. 4860 4861Note that certain signals on many operating systems cannot be caught and 4862handled by applications. In such cases, the pragma is ignored. See the 4863operating system documentation, or the value of the array @code{Reserved} 4864declared in the spec of package @code{System.OS_Interface}. 4865 4866Overriding the default state of signals used by the Ada runtime may interfere 4867with an application’s runtime behavior in the cases of the synchronous signals, 4868and in the case of the signal used to implement the @code{abort} statement. 4869 4870@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas 4871@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{8a}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8b} 4872@section Pragma Invariant 4873 4874 4875Syntax: 4876 4877@example 4878pragma Invariant 4879 ([Entity =>] private_type_LOCAL_NAME, 4880 [Check =>] EXPRESSION 4881 [,[Message =>] String_Expression]); 4882@end example 4883 4884This pragma provides exactly the same capabilities as the Type_Invariant aspect 4885defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 4886Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 4887requires the use of the aspect syntax, which is not available except in 2012 4888mode, it is not possible to use the Type_Invariant aspect in earlier versions 4889of Ada. However the Invariant pragma may be used in any version of Ada. Also 4890note that the aspect Invariant is a synonym in GNAT for the aspect 4891Type_Invariant, but there is no pragma Type_Invariant. 4892 4893The pragma must appear within the visible part of the package specification, 4894after the type to which its Entity argument appears. As with the Invariant 4895aspect, the Check expression is not analyzed until the end of the visible 4896part of the package, so it may contain forward references. The Message 4897argument, if present, provides the exception message used if the invariant 4898is violated. If no Message parameter is provided, a default message that 4899identifies the line on which the pragma appears is used. 4900 4901It is permissible to have multiple Invariants for the same type entity, in 4902which case they are and’ed together. It is permissible to use this pragma 4903in Ada 2012 mode, but you cannot have both an invariant aspect and an 4904invariant pragma for the same entity. 4905 4906For further details on the use of this pragma, see the Ada 2012 documentation 4907of the Type_Invariant aspect. 4908 4909@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas 4910@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8c} 4911@section Pragma Keep_Names 4912 4913 4914Syntax: 4915 4916@example 4917pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 4918@end example 4919 4920The @code{LOCAL_NAME} argument 4921must refer to an enumeration first subtype 4922in the current declarative part. The effect is to retain the enumeration 4923literal names for use by @code{Image} and @code{Value} even if a global 4924@code{Discard_Names} pragma applies. This is useful when you want to 4925generally suppress enumeration literal names and for example you therefore 4926use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you 4927want to retain the names for specific enumeration types. 4928 4929@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas 4930@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8d} 4931@section Pragma License 4932 4933 4934@geindex License checking 4935 4936Syntax: 4937 4938@example 4939pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 4940@end example 4941 4942This pragma is provided to allow automated checking for appropriate license 4943conditions with respect to the standard and modified GPL. A pragma 4944@code{License}, which is a configuration pragma that typically appears at 4945the start of a source file or in a separate @code{gnat.adc} file, specifies 4946the licensing conditions of a unit as follows: 4947 4948 4949@itemize * 4950 4951@item 4952Unrestricted 4953This is used for a unit that can be freely used with no license restrictions. 4954Examples of such units are public domain units, and units from the Ada 4955Reference Manual. 4956 4957@item 4958GPL 4959This is used for a unit that is licensed under the unmodified GPL, and which 4960therefore cannot be @code{with}ed by a restricted unit. 4961 4962@item 4963Modified_GPL 4964This is used for a unit licensed under the GNAT modified GPL that includes 4965a special exception paragraph that specifically permits the inclusion of 4966the unit in programs without requiring the entire program to be released 4967under the GPL. 4968 4969@item 4970Restricted 4971This is used for a unit that is restricted in that it is not permitted to 4972depend on units that are licensed under the GPL. Typical examples are 4973proprietary code that is to be released under more restrictive license 4974conditions. Note that restricted units are permitted to @code{with} units 4975which are licensed under the modified GPL (this is the whole point of the 4976modified GPL). 4977@end itemize 4978 4979Normally a unit with no @code{License} pragma is considered to have an 4980unknown license, and no checking is done. However, standard GNAT headers 4981are recognized, and license information is derived from them as follows. 4982 4983A GNAT license header starts with a line containing 78 hyphens. The following 4984comment text is searched for the appearance of any of the following strings. 4985 4986If the string ‘GNU General Public License’ is found, then the unit is assumed 4987to have GPL license, unless the string ‘As a special exception’ follows, in 4988which case the license is assumed to be modified GPL. 4989 4990If one of the strings 4991‘This specification is adapted from the Ada Semantic Interface’ or 4992‘This specification is derived from the Ada Reference Manual’ is found 4993then the unit is assumed to be unrestricted. 4994 4995These default actions means that a program with a restricted license pragma 4996will automatically get warnings if a GPL unit is inappropriately 4997@code{with}ed. For example, the program: 4998 4999@example 5000with Sem_Ch3; 5001with GNAT.Sockets; 5002procedure Secret_Stuff is 5003 ... 5004end Secret_Stuff 5005@end example 5006 5007if compiled with pragma @code{License} (@code{Restricted}) in a 5008@code{gnat.adc} file will generate the warning: 5009 5010@example 50111. with Sem_Ch3; 5012 | 5013 >>> license of withed unit "Sem_Ch3" is incompatible 5014 50152. with GNAT.Sockets; 50163. procedure Secret_Stuff is 5017@end example 5018 5019Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 5020compiler and is licensed under the 5021GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 5022run time, and is therefore licensed under the modified GPL. 5023 5024@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas 5025@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8e} 5026@section Pragma Link_With 5027 5028 5029Syntax: 5030 5031@example 5032pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 5033@end example 5034 5035This pragma is provided for compatibility with certain Ada 83 compilers. 5036It has exactly the same effect as pragma @code{Linker_Options} except 5037that spaces occurring within one of the string expressions are treated 5038as separators. For example, in the following case: 5039 5040@example 5041pragma Link_With ("-labc -ldef"); 5042@end example 5043 5044results in passing the strings @code{-labc} and @code{-ldef} as two 5045separate arguments to the linker. In addition pragma Link_With allows 5046multiple arguments, with the same effect as successive pragmas. 5047 5048@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas 5049@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8f} 5050@section Pragma Linker_Alias 5051 5052 5053Syntax: 5054 5055@example 5056pragma Linker_Alias ( 5057 [Entity =>] LOCAL_NAME, 5058 [Target =>] static_string_EXPRESSION); 5059@end example 5060 5061@code{LOCAL_NAME} must refer to an object that is declared at the library 5062level. This pragma establishes the given entity as a linker alias for the 5063given target. It is equivalent to @code{__attribute__((alias))} in GNU C 5064and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol 5065@code{static_string_EXPRESSION} in the object file, that is to say no space 5066is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved 5067to the same address as @code{static_string_EXPRESSION} by the linker. 5068 5069The actual linker name for the target must be used (e.g., the fully 5070encoded name with qualification in Ada, or the mangled name in C++), 5071or it must be declared using the C convention with @code{pragma Import} 5072or @code{pragma Export}. 5073 5074Not all target machines support this pragma. On some of them it is accepted 5075only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. 5076 5077@example 5078-- Example of the use of pragma Linker_Alias 5079 5080package p is 5081 i : Integer := 1; 5082 pragma Export (C, i); 5083 5084 new_name_for_i : Integer; 5085 pragma Linker_Alias (new_name_for_i, "i"); 5086end p; 5087@end example 5088 5089@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas 5090@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{90} 5091@section Pragma Linker_Constructor 5092 5093 5094Syntax: 5095 5096@example 5097pragma Linker_Constructor (procedure_LOCAL_NAME); 5098@end example 5099 5100@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 5101is declared at the library level. A procedure to which this pragma is 5102applied will be treated as an initialization routine by the linker. 5103It is equivalent to @code{__attribute__((constructor))} in GNU C and 5104causes @code{procedure_LOCAL_NAME} to be invoked before the entry point 5105of the executable is called (or immediately after the shared library is 5106loaded if the procedure is linked in a shared library), in particular 5107before the Ada run-time environment is set up. 5108 5109Because of these specific contexts, the set of operations such a procedure 5110can perform is very limited and the type of objects it can manipulate is 5111essentially restricted to the elementary types. In particular, it must only 5112contain code to which pragma Restrictions (No_Elaboration_Code) applies. 5113 5114This pragma is used by GNAT to implement auto-initialization of shared Stand 5115Alone Libraries, which provides a related capability without the restrictions 5116listed above. Where possible, the use of Stand Alone Libraries is preferable 5117to the use of this pragma. 5118 5119@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas 5120@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{91} 5121@section Pragma Linker_Destructor 5122 5123 5124Syntax: 5125 5126@example 5127pragma Linker_Destructor (procedure_LOCAL_NAME); 5128@end example 5129 5130@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 5131is declared at the library level. A procedure to which this pragma is 5132applied will be treated as a finalization routine by the linker. 5133It is equivalent to @code{__attribute__((destructor))} in GNU C and 5134causes @code{procedure_LOCAL_NAME} to be invoked after the entry point 5135of the executable has exited (or immediately before the shared library 5136is unloaded if the procedure is linked in a shared library), in particular 5137after the Ada run-time environment is shut down. 5138 5139See @code{pragma Linker_Constructor} for the set of restrictions that apply 5140because of these specific contexts. 5141 5142@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas 5143@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{92}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{93} 5144@section Pragma Linker_Section 5145 5146 5147Syntax: 5148 5149@example 5150pragma Linker_Section ( 5151 [Entity =>] LOCAL_NAME, 5152 [Section =>] static_string_EXPRESSION); 5153@end example 5154 5155@code{LOCAL_NAME} must refer to an object, type, or subprogram that is 5156declared at the library level. This pragma specifies the name of the 5157linker section for the given entity. It is equivalent to 5158@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to 5159be placed in the @code{static_string_EXPRESSION} section of the 5160executable (assuming the linker doesn’t rename the section). 5161GNAT also provides an implementation defined aspect of the same name. 5162 5163In the case of specifying this aspect for a type, the effect is to 5164specify the corresponding section for all library-level objects of 5165the type that do not have an explicit linker section set. Note that 5166this only applies to whole objects, not to components of composite objects. 5167 5168In the case of a subprogram, the linker section applies to all previously 5169declared matching overloaded subprograms in the current declarative part 5170which do not already have a linker section assigned. The linker section 5171aspect is useful in this case for specifying different linker sections 5172for different elements of such an overloaded set. 5173 5174Note that an empty string specifies that no linker section is specified. 5175This is not quite the same as omitting the pragma or aspect, since it 5176can be used to specify that one element of an overloaded set of subprograms 5177has the default linker section, or that one object of a type for which a 5178linker section is specified should has the default linker section. 5179 5180The compiler normally places library-level entities in standard sections 5181depending on the class: procedures and functions generally go in the 5182@code{.text} section, initialized variables in the @code{.data} section 5183and uninitialized variables in the @code{.bss} section. 5184 5185Other, special sections may exist on given target machines to map special 5186hardware, for example I/O ports or flash memory. This pragma is a means to 5187defer the final layout of the executable to the linker, thus fully working 5188at the symbolic level with the compiler. 5189 5190Some file formats do not support arbitrary sections so not all target 5191machines support this pragma. The use of this pragma may cause a program 5192execution to be erroneous if it is used to place an entity into an 5193inappropriate section (e.g., a modified variable into the @code{.text} 5194section). See also @code{pragma Persistent_BSS}. 5195 5196@example 5197-- Example of the use of pragma Linker_Section 5198 5199package IO_Card is 5200 Port_A : Integer; 5201 pragma Volatile (Port_A); 5202 pragma Linker_Section (Port_A, ".bss.port_a"); 5203 5204 Port_B : Integer; 5205 pragma Volatile (Port_B); 5206 pragma Linker_Section (Port_B, ".bss.port_b"); 5207 5208 type Port_Type is new Integer with Linker_Section => ".bss"; 5209 PA : Port_Type with Linker_Section => ".bss.PA"; 5210 PB : Port_Type; -- ends up in linker section ".bss" 5211 5212 procedure Q with Linker_Section => "Qsection"; 5213end IO_Card; 5214@end example 5215 5216@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas 5217@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{95} 5218@section Pragma Lock_Free 5219 5220 5221Syntax: 5222This pragma may be specified for protected types or objects. It specifies that 5223the implementation of protected operations must be implemented without locks. 5224Compilation fails if the compiler cannot generate lock-free code for the 5225operations. 5226 5227The current conditions required to support this pragma are: 5228 5229 5230@itemize * 5231 5232@item 5233Protected type declarations may not contain entries 5234 5235@item 5236Protected subprogram declarations may not have nonelementary parameters 5237@end itemize 5238 5239In addition, each protected subprogram body must satisfy: 5240 5241 5242@itemize * 5243 5244@item 5245May reference only one protected component 5246 5247@item 5248May not reference nonconstant entities outside the protected subprogram 5249scope. 5250 5251@item 5252May not contain address representation items, allocators, or quantified 5253expressions. 5254 5255@item 5256May not contain delay, goto, loop, or procedure-call statements. 5257 5258@item 5259May not contain exported and imported entities 5260 5261@item 5262May not dereferenced access values 5263 5264@item 5265Function calls and attribute references must be static 5266@end itemize 5267 5268@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas 5269@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{96} 5270@section Pragma Loop_Invariant 5271 5272 5273Syntax: 5274 5275@example 5276pragma Loop_Invariant ( boolean_EXPRESSION ); 5277@end example 5278 5279The effect of this pragma is similar to that of pragma @code{Assert}, 5280except that in an @code{Assertion_Policy} pragma, the identifier 5281@code{Loop_Invariant} is used to control whether it is ignored or checked 5282(or disabled). 5283 5284@code{Loop_Invariant} can only appear as one of the items in the sequence 5285of statements of a loop body, or nested inside block statements that 5286appear in the sequence of statements of a loop body. 5287The intention is that it be used to 5288represent a “loop invariant” assertion, i.e. something that is true each 5289time through the loop, and which can be used to show that the loop is 5290achieving its purpose. 5291 5292Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5293apply to the same loop should be grouped in the same sequence of 5294statements. 5295 5296To aid in writing such invariants, the special attribute @code{Loop_Entry} 5297may be used to refer to the value of an expression on entry to the loop. This 5298attribute can only be used within the expression of a @code{Loop_Invariant} 5299pragma. For full details, see documentation of attribute @code{Loop_Entry}. 5300 5301@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas 5302@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{97} 5303@section Pragma Loop_Optimize 5304 5305 5306Syntax: 5307 5308@example 5309pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 5310 5311OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector 5312@end example 5313 5314This pragma must appear immediately within a loop statement. It allows the 5315programmer to specify optimization hints for the enclosing loop. The hints 5316are not mutually exclusive and can be freely mixed, but not all combinations 5317will yield a sensible outcome. 5318 5319There are five supported optimization hints for a loop: 5320 5321 5322@itemize * 5323 5324@item 5325Ivdep 5326 5327The programmer asserts that there are no loop-carried dependencies 5328which would prevent consecutive iterations of the loop from being 5329executed simultaneously. 5330 5331@item 5332No_Unroll 5333 5334The loop must not be unrolled. This is a strong hint: the compiler will not 5335unroll a loop marked with this hint. 5336 5337@item 5338Unroll 5339 5340The loop should be unrolled. This is a weak hint: the compiler will try to 5341apply unrolling to this loop preferably to other optimizations, notably 5342vectorization, but there is no guarantee that the loop will be unrolled. 5343 5344@item 5345No_Vector 5346 5347The loop must not be vectorized. This is a strong hint: the compiler will not 5348vectorize a loop marked with this hint. 5349 5350@item 5351Vector 5352 5353The loop should be vectorized. This is a weak hint: the compiler will try to 5354apply vectorization to this loop preferably to other optimizations, notably 5355unrolling, but there is no guarantee that the loop will be vectorized. 5356@end itemize 5357 5358These hints do not remove the need to pass the appropriate switches to the 5359compiler in order to enable the relevant optimizations, that is to say 5360@emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for 5361vectorization. 5362 5363@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas 5364@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{98} 5365@section Pragma Loop_Variant 5366 5367 5368Syntax: 5369 5370@example 5371pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); 5372LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 5373CHANGE_DIRECTION ::= Increases | Decreases 5374@end example 5375 5376@code{Loop_Variant} can only appear as one of the items in the sequence 5377of statements of a loop body, or nested inside block statements that 5378appear in the sequence of statements of a loop body. 5379It allows the specification of quantities which must always 5380decrease or increase in successive iterations of the loop. In its simplest 5381form, just one expression is specified, whose value must increase or decrease 5382on each iteration of the loop. 5383 5384In a more complex form, multiple arguments can be given which are intepreted 5385in a nesting lexicographic manner. For example: 5386 5387@example 5388pragma Loop_Variant (Increases => X, Decreases => Y); 5389@end example 5390 5391specifies that each time through the loop either X increases, or X stays 5392the same and Y decreases. A @code{Loop_Variant} pragma ensures that the 5393loop is making progress. It can be useful in helping to show informally 5394or prove formally that the loop always terminates. 5395 5396@code{Loop_Variant} is an assertion whose effect can be controlled using 5397an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The 5398policy can be @code{Check} to enable the loop variant check, @code{Ignore} 5399to ignore the check (in which case the pragma has no effect on the program), 5400or @code{Disable} in which case the pragma is not even checked for correct 5401syntax. 5402 5403Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5404apply to the same loop should be grouped in the same sequence of 5405statements. 5406 5407The @code{Loop_Entry} attribute may be used within the expressions of the 5408@code{Loop_Variant} pragma to refer to values on entry to the loop. 5409 5410@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas 5411@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{99} 5412@section Pragma Machine_Attribute 5413 5414 5415Syntax: 5416 5417@example 5418pragma Machine_Attribute ( 5419 [Entity =>] LOCAL_NAME, 5420 [Attribute_Name =>] static_string_EXPRESSION 5421 [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); 5422@end example 5423 5424Machine-dependent attributes can be specified for types and/or 5425declarations. This pragma is semantically equivalent to 5426@code{__attribute__((@emph{attribute_name}))} (if @code{info} is not 5427specified) or @code{__attribute__((@emph{attribute_name(info})))} 5428or @code{__attribute__((@emph{attribute_name(info,...})))} in GNU C, 5429where @emph{attribute_name} is recognized by the compiler middle-end 5430or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note 5431that a string literal for the optional parameter @code{info} or the 5432following ones is transformed by default into an identifier, 5433which may make this pragma unusable for some attributes. 5434For further information see @cite{GNU Compiler Collection (GCC) Internals}. 5435 5436@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas 5437@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9a} 5438@section Pragma Main 5439 5440 5441Syntax: 5442 5443@example 5444pragma Main 5445 (MAIN_OPTION [, MAIN_OPTION]); 5446 5447MAIN_OPTION ::= 5448 [Stack_Size =>] static_integer_EXPRESSION 5449| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 5450| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 5451@end example 5452 5453This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5454no effect in GNAT, other than being syntax checked. 5455 5456@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas 5457@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9b} 5458@section Pragma Main_Storage 5459 5460 5461Syntax: 5462 5463@example 5464pragma Main_Storage 5465 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 5466 5467MAIN_STORAGE_OPTION ::= 5468 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 5469| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 5470@end example 5471 5472This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5473no effect in GNAT, other than being syntax checked. 5474 5475@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas 5476@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9c}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9d} 5477@section Pragma Max_Queue_Length 5478 5479 5480Syntax: 5481 5482@example 5483pragma Max_Entry_Queue (static_integer_EXPRESSION); 5484@end example 5485 5486This pragma is used to specify the maximum callers per entry queue for 5487individual protected entries and entry families. It accepts a single 5488integer (-1 or more) as a parameter and must appear after the declaration of an 5489entry. 5490 5491A value of -1 represents no additional restriction on queue length. 5492 5493@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas 5494@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9e} 5495@section Pragma No_Body 5496 5497 5498Syntax: 5499 5500@example 5501pragma No_Body; 5502@end example 5503 5504There are a number of cases in which a package spec does not require a body, 5505and in fact a body is not permitted. GNAT will not permit the spec to be 5506compiled if there is a body around. The pragma No_Body allows you to provide 5507a body file, even in a case where no body is allowed. The body file must 5508contain only comments and a single No_Body pragma. This is recognized by 5509the compiler as indicating that no body is logically present. 5510 5511This is particularly useful during maintenance when a package is modified in 5512such a way that a body needed before is no longer needed. The provision of a 5513dummy body with a No_Body pragma ensures that there is no interference from 5514earlier versions of the package body. 5515 5516@node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas 5517@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9f}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a0} 5518@section Pragma No_Caching 5519 5520 5521Syntax: 5522 5523@example 5524pragma No_Caching [ (boolean_EXPRESSION) ]; 5525@end example 5526 5527For the semantics of this pragma, see the entry for aspect @code{No_Caching} in 5528the SPARK 2014 Reference Manual, section 7.1.2. 5529 5530@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas 5531@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a1} 5532@section Pragma No_Component_Reordering 5533 5534 5535Syntax: 5536 5537@example 5538pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; 5539@end example 5540 5541@code{type_LOCAL_NAME} must refer to a record type declaration in the current 5542declarative part. The effect is to preclude any reordering of components 5543for the layout of the record, i.e. the record is laid out by the compiler 5544in the order in which the components are declared textually. The form with 5545no argument is a configuration pragma which applies to all record types 5546declared in units to which the pragma applies and there is a requirement 5547that this pragma be used consistently within a partition. 5548 5549@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas 5550@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a2}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a3} 5551@section Pragma No_Elaboration_Code_All 5552 5553 5554Syntax: 5555 5556@example 5557pragma No_Elaboration_Code_All [(program_unit_NAME)]; 5558@end example 5559 5560This is a program unit pragma (there is also an equivalent aspect of the 5561same name) that establishes the restriction @code{No_Elaboration_Code} for 5562the current unit and any extended main source units (body and subunits). 5563It also has the effect of enforcing a transitive application of this 5564aspect, so that if any unit is implicitly or explicitly with’ed by the 5565current unit, it must also have the No_Elaboration_Code_All aspect set. 5566It may be applied to package or subprogram specs or their generic versions. 5567 5568@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas 5569@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a4} 5570@section Pragma No_Heap_Finalization 5571 5572 5573Syntax: 5574 5575@example 5576pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; 5577@end example 5578 5579Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a 5580type-specific pragma. 5581 5582In its configuration form, the pragma must appear within a configuration file 5583such as gnat.adc, without an argument. The pragma suppresses the call to 5584@code{Finalize} for heap-allocated objects created through library-level named 5585access-to-object types in cases where the designated type requires finalization 5586actions. 5587 5588In its type-specific form, the argument of the pragma must denote a 5589library-level named access-to-object type. The pragma suppresses the call to 5590@code{Finalize} for heap-allocated objects created through the specific access type 5591in cases where the designated type requires finalization actions. 5592 5593It is still possible to finalize such heap-allocated objects by explicitly 5594deallocating them. 5595 5596A library-level named access-to-object type declared within a generic unit will 5597lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not 5598appear at the library level. 5599 5600@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas 5601@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a5}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a6} 5602@section Pragma No_Inline 5603 5604 5605Syntax: 5606 5607@example 5608pragma No_Inline (NAME @{, NAME@}); 5609@end example 5610 5611This pragma suppresses inlining for the callable entity or the instances of 5612the generic subprogram designated by @code{NAME}, including inlining that 5613results from the use of pragma @code{Inline}. This pragma is always active, 5614in particular it is not subject to the use of option @emph{-gnatn} or 5615@emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and 5616pragma @code{Inline_Always} for the same @code{NAME}. 5617 5618@node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas 5619@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a7} 5620@section Pragma No_Return 5621 5622 5623Syntax: 5624 5625@example 5626pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 5627@end example 5628 5629Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure 5630declarations in the current declarative part. A procedure to which this 5631pragma is applied may not contain any explicit @code{return} statements. 5632In addition, if the procedure contains any implicit returns from falling 5633off the end of a statement sequence, then execution of that implicit 5634return will cause Program_Error to be raised. 5635 5636One use of this pragma is to identify procedures whose only purpose is to raise 5637an exception. Another use of this pragma is to suppress incorrect warnings 5638about missing returns in functions, where the last statement of a function 5639statement sequence is a call to such a procedure. 5640 5641Note that in Ada 2005 mode, this pragma is part of the language. It is 5642available in all earlier versions of Ada as an implementation-defined 5643pragma. 5644 5645@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas 5646@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a8} 5647@section Pragma No_Strict_Aliasing 5648 5649 5650Syntax: 5651 5652@example 5653pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 5654@end example 5655 5656@code{type_LOCAL_NAME} must refer to an access type 5657declaration in the current declarative part. The effect is to inhibit 5658strict aliasing optimization for the given type. The form with no 5659arguments is a configuration pragma which applies to all access types 5660declared in units to which the pragma applies. For a detailed 5661description of the strict aliasing optimization, and the situations 5662in which it must be suppressed, see the section on Optimization and Strict Aliasing 5663in the @cite{GNAT User’s Guide}. 5664 5665This pragma currently has no effects on access to unconstrained array types. 5666 5667@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas 5668@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a9}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{aa} 5669@section Pragma No_Tagged_Streams 5670 5671 5672Syntax: 5673 5674@example 5675pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; 5676@end example 5677 5678Normally when a tagged type is introduced using a full type declaration, 5679part of the processing includes generating stream access routines to be 5680used by stream attributes referencing the type (or one of its subtypes 5681or derived types). This can involve the generation of significant amounts 5682of code which is wasted space if stream routines are not needed for the 5683type in question. 5684 5685The @code{No_Tagged_Streams} pragma causes the generation of these stream 5686routines to be skipped, and any attempt to use stream operations on 5687types subject to this pragma will be statically rejected as illegal. 5688 5689There are two forms of the pragma. The form with no arguments must appear 5690in a declarative sequence or in the declarations of a package spec. This 5691pragma affects all subsequent root tagged types declared in the declaration 5692sequence, and specifies that no stream routines be generated. The form with 5693an argument (for which there is also a corresponding aspect) specifies a 5694single root tagged type for which stream routines are not to be generated. 5695 5696Once the pragma has been given for a particular root tagged type, all subtypes 5697and derived types of this type inherit the pragma automatically, so the effect 5698applies to a complete hierarchy (this is necessary to deal with the class-wide 5699dispatching versions of the stream routines). 5700 5701When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously 5702applied to a tagged type its Expanded_Name and External_Tag are initialized 5703with empty strings. This is useful to avoid exposing entity names at binary 5704level but has a negative impact on the debuggability of tagged types. 5705 5706@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas 5707@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ab} 5708@section Pragma Normalize_Scalars 5709 5710 5711Syntax: 5712 5713@example 5714pragma Normalize_Scalars; 5715@end example 5716 5717This is a language defined pragma which is fully implemented in GNAT. The 5718effect is to cause all scalar objects that are not otherwise initialized 5719to be initialized. The initial values are implementation dependent and 5720are as follows: 5721 5722 5723@table @asis 5724 5725@item @emph{Standard.Character} 5726 5727Objects whose root type is Standard.Character are initialized to 5728Character’Last unless the subtype range excludes NUL (in which case 5729NUL is used). This choice will always generate an invalid value if 5730one exists. 5731 5732@item @emph{Standard.Wide_Character} 5733 5734Objects whose root type is Standard.Wide_Character are initialized to 5735Wide_Character’Last unless the subtype range excludes NUL (in which case 5736NUL is used). This choice will always generate an invalid value if 5737one exists. 5738 5739@item @emph{Standard.Wide_Wide_Character} 5740 5741Objects whose root type is Standard.Wide_Wide_Character are initialized to 5742the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 5743which case NUL is used). This choice will always generate an invalid value if 5744one exists. 5745 5746@item @emph{Integer types} 5747 5748Objects of an integer type are treated differently depending on whether 5749negative values are present in the subtype. If no negative values are 5750present, then all one bits is used as the initial value except in the 5751special case where zero is excluded from the subtype, in which case 5752all zero bits are used. This choice will always generate an invalid 5753value if one exists. 5754 5755For subtypes with negative values present, the largest negative number 5756is used, except in the unusual case where this largest negative number 5757is in the subtype, and the largest positive number is not, in which case 5758the largest positive value is used. This choice will always generate 5759an invalid value if one exists. 5760 5761@item @emph{Floating-Point Types} 5762 5763Objects of all floating-point types are initialized to all 1-bits. For 5764standard IEEE format, this corresponds to a NaN (not a number) which is 5765indeed an invalid value. 5766 5767@item @emph{Fixed-Point Types} 5768 5769Objects of all fixed-point types are treated as described above for integers, 5770with the rules applying to the underlying integer value used to represent 5771the fixed-point value. 5772 5773@item @emph{Modular types} 5774 5775Objects of a modular type are initialized to all one bits, except in 5776the special case where zero is excluded from the subtype, in which 5777case all zero bits are used. This choice will always generate an 5778invalid value if one exists. 5779 5780@item @emph{Enumeration types} 5781 5782Objects of an enumeration type are initialized to all one-bits, i.e., to 5783the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal 5784whose Pos value is zero, in which case a code of zero is used. This choice 5785will always generate an invalid value if one exists. 5786@end table 5787 5788@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas 5789@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ac}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ad} 5790@section Pragma Obsolescent 5791 5792 5793Syntax: 5794 5795@example 5796pragma Obsolescent; 5797 5798pragma Obsolescent ( 5799 [Message =>] static_string_EXPRESSION 5800[,[Version =>] Ada_05]]); 5801 5802pragma Obsolescent ( 5803 [Entity =>] NAME 5804[,[Message =>] static_string_EXPRESSION 5805[,[Version =>] Ada_05]] ); 5806@end example 5807 5808This pragma can occur immediately following a declaration of an entity, 5809including the case of a record component. If no Entity argument is present, 5810then this declaration is the one to which the pragma applies. If an Entity 5811parameter is present, it must either match the name of the entity in this 5812declaration, or alternatively, the pragma can immediately follow an enumeration 5813type declaration, where the Entity argument names one of the enumeration 5814literals. 5815 5816This pragma is used to indicate that the named entity 5817is considered obsolescent and should not be used. Typically this is 5818used when an API must be modified by eventually removing or modifying 5819existing subprograms or other entities. The pragma can be used at an 5820intermediate stage when the entity is still present, but will be 5821removed later. 5822 5823The effect of this pragma is to output a warning message on a reference to 5824an entity thus marked that the subprogram is obsolescent if the appropriate 5825warning option in the compiler is activated. If the @code{Message} parameter is 5826present, then a second warning message is given containing this text. In 5827addition, a reference to the entity is considered to be a violation of pragma 5828@code{Restrictions (No_Obsolescent_Features)}. 5829 5830This pragma can also be used as a program unit pragma for a package, 5831in which case the entity name is the name of the package, and the 5832pragma indicates that the entire package is considered 5833obsolescent. In this case a client @code{with}ing such a package 5834violates the restriction, and the @code{with} clause is 5835flagged with warnings if the warning option is set. 5836 5837If the @code{Version} parameter is present (which must be exactly 5838the identifier @code{Ada_05}, no other argument is allowed), then the 5839indication of obsolescence applies only when compiling in Ada 2005 5840mode. This is primarily intended for dealing with the situations 5841in the predefined library where subprograms or packages 5842have become defined as obsolescent in Ada 2005 5843(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. 5844 5845The following examples show typical uses of this pragma: 5846 5847@example 5848package p is 5849 pragma Obsolescent (p, Message => "use pp instead of p"); 5850end p; 5851 5852package q is 5853 procedure q2; 5854 pragma Obsolescent ("use q2new instead"); 5855 5856 type R is new integer; 5857 pragma Obsolescent 5858 (Entity => R, 5859 Message => "use RR in Ada 2005", 5860 Version => Ada_05); 5861 5862 type M is record 5863 F1 : Integer; 5864 F2 : Integer; 5865 pragma Obsolescent; 5866 F3 : Integer; 5867 end record; 5868 5869 type E is (a, bc, 'd', quack); 5870 pragma Obsolescent (Entity => bc) 5871 pragma Obsolescent (Entity => 'd') 5872 5873 function "+" 5874 (a, b : character) return character; 5875 pragma Obsolescent (Entity => "+"); 5876end; 5877@end example 5878 5879Note that, as for all pragmas, if you use a pragma argument identifier, 5880then all subsequent parameters must also use a pragma argument identifier. 5881So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} 5882argument is present, it must be preceded by @code{Message =>}. 5883 5884@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas 5885@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ae} 5886@section Pragma Optimize_Alignment 5887 5888 5889@geindex Alignment 5890@geindex default settings 5891 5892Syntax: 5893 5894@example 5895pragma Optimize_Alignment (TIME | SPACE | OFF); 5896@end example 5897 5898This is a configuration pragma which affects the choice of default alignments 5899for types and objects where no alignment is explicitly specified. There is a 5900time/space trade-off in the selection of these values. Large alignments result 5901in more efficient code, at the expense of larger data space, since sizes have 5902to be increased to match these alignments. Smaller alignments save space, but 5903the access code is slower. The normal choice of default alignments for types 5904and individual alignment promotions for objects (which is what you get if you 5905do not use this pragma, or if you use an argument of OFF), tries to balance 5906these two requirements. 5907 5908Specifying SPACE causes smaller default alignments to be chosen in two cases. 5909First any packed record is given an alignment of 1. Second, if a size is given 5910for the type, then the alignment is chosen to avoid increasing this size. For 5911example, consider: 5912 5913@example 5914type R is record 5915 X : Integer; 5916 Y : Character; 5917end record; 5918 5919for R'Size use 5*8; 5920@end example 5921 5922In the default mode, this type gets an alignment of 4, so that access to the 5923Integer field X are efficient. But this means that objects of the type end up 5924with a size of 8 bytes. This is a valid choice, since sizes of objects are 5925allowed to be bigger than the size of the type, but it can waste space if for 5926example fields of type R appear in an enclosing record. If the above type is 5927compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. 5928 5929However, there is one case in which SPACE is ignored. If a variable length 5930record (that is a discriminated record with a component which is an array 5931whose length depends on a discriminant), has a pragma Pack, then it is not 5932in general possible to set the alignment of such a record to one, so the 5933pragma is ignored in this case (with a warning). 5934 5935Specifying SPACE also disables alignment promotions for standalone objects, 5936which occur when the compiler increases the alignment of a specific object 5937without changing the alignment of its type. 5938 5939Specifying SPACE also disables component reordering in unpacked record types, 5940which can result in larger sizes in order to meet alignment requirements. 5941 5942Specifying TIME causes larger default alignments to be chosen in the case of 5943small types with sizes that are not a power of 2. For example, consider: 5944 5945@example 5946type R is record 5947 A : Character; 5948 B : Character; 5949 C : Boolean; 5950end record; 5951 5952pragma Pack (R); 5953for R'Size use 17; 5954@end example 5955 5956The default alignment for this record is normally 1, but if this type is 5957compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set 5958to 4, which wastes space for objects of the type, since they are now 4 bytes 5959long, but results in more efficient access when the whole record is referenced. 5960 5961As noted above, this is a configuration pragma, and there is a requirement 5962that all units in a partition be compiled with a consistent setting of the 5963optimization setting. This would normally be achieved by use of a configuration 5964pragma file containing the appropriate setting. The exception to this rule is 5965that units with an explicit configuration pragma in the same file as the source 5966unit are excluded from the consistency check, as are all predefined units. The 5967latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 5968pragma appears at the start of the file. 5969 5970@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas 5971@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{af} 5972@section Pragma Ordered 5973 5974 5975Syntax: 5976 5977@example 5978pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 5979@end example 5980 5981Most enumeration types are from a conceptual point of view unordered. 5982For example, consider: 5983 5984@example 5985type Color is (Red, Blue, Green, Yellow); 5986@end example 5987 5988By Ada semantics @code{Blue > Red} and @code{Green > Blue}, 5989but really these relations make no sense; the enumeration type merely 5990specifies a set of possible colors, and the order is unimportant. 5991 5992For unordered enumeration types, it is generally a good idea if 5993clients avoid comparisons (other than equality or inequality) and 5994explicit ranges. (A @emph{client} is a unit where the type is referenced, 5995other than the unit where the type is declared, its body, and its subunits.) 5996For example, if code buried in some client says: 5997 5998@example 5999if Current_Color < Yellow then ... 6000if Current_Color in Blue .. Green then ... 6001@end example 6002 6003then the client code is relying on the order, which is undesirable. 6004It makes the code hard to read and creates maintenance difficulties if 6005entries have to be added to the enumeration type. Instead, 6006the code in the client should list the possibilities, or an 6007appropriate subtype should be declared in the unit that declares 6008the original enumeration type. E.g., the following subtype could 6009be declared along with the type @code{Color}: 6010 6011@example 6012subtype RBG is Color range Red .. Green; 6013@end example 6014 6015and then the client could write: 6016 6017@example 6018if Current_Color in RBG then ... 6019if Current_Color = Blue or Current_Color = Green then ... 6020@end example 6021 6022However, some enumeration types are legitimately ordered from a conceptual 6023point of view. For example, if you declare: 6024 6025@example 6026type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 6027@end example 6028 6029then the ordering imposed by the language is reasonable, and 6030clients can depend on it, writing for example: 6031 6032@example 6033if D in Mon .. Fri then ... 6034if D < Wed then ... 6035@end example 6036 6037The pragma @emph{Ordered} is provided to mark enumeration types that 6038are conceptually ordered, alerting the reader that clients may depend 6039on the ordering. GNAT provides a pragma to mark enumerations as ordered 6040rather than one to mark them as unordered, since in our experience, 6041the great majority of enumeration types are conceptually unordered. 6042 6043The types @code{Boolean}, @code{Character}, @code{Wide_Character}, 6044and @code{Wide_Wide_Character} 6045are considered to be ordered types, so each is declared with a 6046pragma @code{Ordered} in package @code{Standard}. 6047 6048Normally pragma @code{Ordered} serves only as documentation and a guide for 6049coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that 6050requests warnings for inappropriate uses (comparisons and explicit 6051subranges) for unordered types. If this switch is used, then any 6052enumeration type not marked with pragma @code{Ordered} will be considered 6053as unordered, and will generate warnings for inappropriate uses. 6054 6055Note that generic types are not considered ordered or unordered (since the 6056template can be instantiated for both cases), so we never generate warnings 6057for the case of generic enumerated types. 6058 6059For additional information please refer to the description of the 6060@emph{-gnatw.u} switch in the GNAT User’s Guide. 6061 6062@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas 6063@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b0} 6064@section Pragma Overflow_Mode 6065 6066 6067Syntax: 6068 6069@example 6070pragma Overflow_Mode 6071 ( [General =>] MODE 6072 [,[Assertions =>] MODE]); 6073 6074MODE ::= STRICT | MINIMIZED | ELIMINATED 6075@end example 6076 6077This pragma sets the current overflow mode to the given setting. For details 6078of the meaning of these modes, please refer to the 6079‘Overflow Check Handling in GNAT’ appendix in the 6080GNAT User’s Guide. If only the @code{General} parameter is present, 6081the given mode applies to all expressions. If both parameters are present, 6082the @code{General} mode applies to expressions outside assertions, and 6083the @code{Eliminated} mode applies to expressions within assertions. 6084 6085The case of the @code{MODE} parameter is ignored, 6086so @code{MINIMIZED}, @code{Minimized} and 6087@code{minimized} all have the same effect. 6088 6089The @code{Overflow_Mode} pragma has the same scoping and placement 6090rules as pragma @code{Suppress}, so it can occur either as a 6091configuration pragma, specifying a default for the whole 6092program, or in a declarative scope, where it applies to the 6093remaining declarations and statements in that scope. 6094 6095The pragma @code{Suppress (Overflow_Check)} suppresses 6096overflow checking, but does not affect the overflow mode. 6097 6098The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) 6099overflow checking, but does not affect the overflow mode. 6100 6101@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas 6102@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b1} 6103@section Pragma Overriding_Renamings 6104 6105 6106@geindex Rational profile 6107 6108@geindex Rational compatibility 6109 6110Syntax: 6111 6112@example 6113pragma Overriding_Renamings; 6114@end example 6115 6116This is a GNAT configuration pragma to simplify porting 6117legacy code accepted by the Rational 6118Ada compiler. In the presence of this pragma, a renaming declaration that 6119renames an inherited operation declared in the same scope is legal if selected 6120notation is used as in: 6121 6122@example 6123pragma Overriding_Renamings; 6124... 6125package R is 6126 function F (..); 6127 ... 6128 function F (..) renames R.F; 6129end R; 6130@end example 6131 6132even though 6133RM 8.3 (15) stipulates that an overridden operation is not visible within the 6134declaration of the overriding operation. 6135 6136@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas 6137@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b2} 6138@section Pragma Partition_Elaboration_Policy 6139 6140 6141Syntax: 6142 6143@example 6144pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 6145 6146POLICY_IDENTIFIER ::= Concurrent | Sequential 6147@end example 6148 6149This pragma is standard in Ada 2005, but is available in all earlier 6150versions of Ada as an implementation-defined pragma. 6151See Ada 2012 Reference Manual for details. 6152 6153@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas 6154@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b3}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b4} 6155@section Pragma Part_Of 6156 6157 6158Syntax: 6159 6160@example 6161pragma Part_Of (ABSTRACT_STATE); 6162 6163ABSTRACT_STATE ::= NAME 6164@end example 6165 6166For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the 6167SPARK 2014 Reference Manual, section 7.2.6. 6168 6169@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas 6170@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b5} 6171@section Pragma Passive 6172 6173 6174Syntax: 6175 6176@example 6177pragma Passive [(Semaphore | No)]; 6178@end example 6179 6180Syntax checked, but otherwise ignored by GNAT. This is recognized for 6181compatibility with DEC Ada 83 implementations, where it is used within a 6182task definition to request that a task be made passive. If the argument 6183@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 6184treats the pragma as an assertion that the containing task is passive 6185and that optimization of context switch with this task is permitted and 6186desired. If the argument @code{No} is present, the task must not be 6187optimized. GNAT does not attempt to optimize any tasks in this manner 6188(since protected objects are available in place of passive tasks). 6189 6190For more information on the subject of passive tasks, see the section 6191‘Passive Task Optimization’ in the GNAT Users Guide. 6192 6193@node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas 6194@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b6}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b7} 6195@section Pragma Persistent_BSS 6196 6197 6198Syntax: 6199 6200@example 6201pragma Persistent_BSS [(LOCAL_NAME)] 6202@end example 6203 6204This pragma allows selected objects to be placed in the @code{.persistent_bss} 6205section. On some targets the linker and loader provide for special 6206treatment of this section, allowing a program to be reloaded without 6207affecting the contents of this data (hence the name persistent). 6208 6209There are two forms of usage. If an argument is given, it must be the 6210local name of a library-level object, with no explicit initialization 6211and whose type is potentially persistent. If no argument is given, then 6212the pragma is a configuration pragma, and applies to all library-level 6213objects with no explicit initialization of potentially persistent types. 6214 6215A potentially persistent type is a scalar type, or an untagged, 6216non-discriminated record, all of whose components have no explicit 6217initialization and are themselves of a potentially persistent type, 6218or an array, all of whose constraints are static, and whose component 6219type is potentially persistent. 6220 6221If this pragma is used on a target where this feature is not supported, 6222then the pragma will be ignored. See also @code{pragma Linker_Section}. 6223 6224@node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas 6225@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b8} 6226@section Pragma Post 6227 6228 6229@geindex Post 6230 6231@geindex Checks 6232@geindex postconditions 6233 6234Syntax: 6235 6236@example 6237pragma Post (Boolean_Expression); 6238@end example 6239 6240The @code{Post} pragma is intended to be an exact replacement for 6241the language-defined 6242@code{Post} aspect, and shares its restrictions and semantics. 6243It must appear either immediately following the corresponding 6244subprogram declaration (only other pragmas may intervene), or 6245if there is no separate subprogram declaration, then it can 6246appear at the start of the declarations in a subprogram body 6247(preceded only by other pragmas). 6248 6249@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas 6250@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b9} 6251@section Pragma Postcondition 6252 6253 6254@geindex Postcondition 6255 6256@geindex Checks 6257@geindex postconditions 6258 6259Syntax: 6260 6261@example 6262pragma Postcondition ( 6263 [Check =>] Boolean_Expression 6264 [,[Message =>] String_Expression]); 6265@end example 6266 6267The @code{Postcondition} pragma allows specification of automatic 6268postcondition checks for subprograms. These checks are similar to 6269assertions, but are automatically inserted just prior to the return 6270statements of the subprogram with which they are associated (including 6271implicit returns at the end of procedure bodies and associated 6272exception handlers). 6273 6274In addition, the boolean expression which is the condition which 6275must be true may contain references to function’Result in the case 6276of a function to refer to the returned value. 6277 6278@code{Postcondition} pragmas may appear either immediately following the 6279(separate) declaration of a subprogram, or at the start of the 6280declarations of a subprogram body. Only other pragmas may intervene 6281(that is appear between the subprogram declaration and its 6282postconditions, or appear before the postcondition in the 6283declaration sequence in a subprogram body). In the case of a 6284postcondition appearing after a subprogram declaration, the 6285formal arguments of the subprogram are visible, and can be 6286referenced in the postcondition expressions. 6287 6288The postconditions are collected and automatically tested just 6289before any return (implicit or explicit) in the subprogram body. 6290A postcondition is only recognized if postconditions are active 6291at the time the pragma is encountered. The compiler switch @emph{gnata} 6292turns on all postconditions by default, and pragma @code{Check_Policy} 6293with an identifier of @code{Postcondition} can also be used to 6294control whether postconditions are active. 6295 6296The general approach is that postconditions are placed in the spec 6297if they represent functional aspects which make sense to the client. 6298For example we might have: 6299 6300@example 6301function Direction return Integer; 6302pragma Postcondition 6303 (Direction'Result = +1 6304 or else 6305 Direction'Result = -1); 6306@end example 6307 6308which serves to document that the result must be +1 or -1, and 6309will test that this is the case at run time if postcondition 6310checking is active. 6311 6312Postconditions within the subprogram body can be used to 6313check that some internal aspect of the implementation, 6314not visible to the client, is operating as expected. 6315For instance if a square root routine keeps an internal 6316counter of the number of times it is called, then we 6317might have the following postcondition: 6318 6319@example 6320Sqrt_Calls : Natural := 0; 6321 6322function Sqrt (Arg : Float) return Float is 6323 pragma Postcondition 6324 (Sqrt_Calls = Sqrt_Calls'Old + 1); 6325 ... 6326end Sqrt 6327@end example 6328 6329As this example, shows, the use of the @code{Old} attribute 6330is often useful in postconditions to refer to the state on 6331entry to the subprogram. 6332 6333Note that postconditions are only checked on normal returns 6334from the subprogram. If an abnormal return results from 6335raising an exception, then the postconditions are not checked. 6336 6337If a postcondition fails, then the exception 6338@code{System.Assertions.Assert_Failure} is raised. If 6339a message argument was supplied, then the given string 6340will be used as the exception message. If no message 6341argument was supplied, then the default message has 6342the form “Postcondition failed at file_name:line”. The 6343exception is raised in the context of the subprogram 6344body, so it is possible to catch postcondition failures 6345within the subprogram body itself. 6346 6347Within a package spec, normal visibility rules 6348in Ada would prevent forward references within a 6349postcondition pragma to functions defined later in 6350the same package. This would introduce undesirable 6351ordering constraints. To avoid this problem, all 6352postcondition pragmas are analyzed at the end of 6353the package spec, allowing forward references. 6354 6355The following example shows that this even allows 6356mutually recursive postconditions as in: 6357 6358@example 6359package Parity_Functions is 6360 function Odd (X : Natural) return Boolean; 6361 pragma Postcondition 6362 (Odd'Result = 6363 (x = 1 6364 or else 6365 (x /= 0 and then Even (X - 1)))); 6366 6367 function Even (X : Natural) return Boolean; 6368 pragma Postcondition 6369 (Even'Result = 6370 (x = 0 6371 or else 6372 (x /= 1 and then Odd (X - 1)))); 6373 6374end Parity_Functions; 6375@end example 6376 6377There are no restrictions on the complexity or form of 6378conditions used within @code{Postcondition} pragmas. 6379The following example shows that it is even possible 6380to verify performance behavior. 6381 6382@example 6383package Sort is 6384 6385 Performance : constant Float; 6386 -- Performance constant set by implementation 6387 -- to match target architecture behavior. 6388 6389 procedure Treesort (Arg : String); 6390 -- Sorts characters of argument using N*logN sort 6391 pragma Postcondition 6392 (Float (Clock - Clock'Old) <= 6393 Float (Arg'Length) * 6394 log (Float (Arg'Length)) * 6395 Performance); 6396end Sort; 6397@end example 6398 6399Note: postcondition pragmas associated with subprograms that are 6400marked as Inline_Always, or those marked as Inline with front-end 6401inlining (-gnatN option set) are accepted and legality-checked 6402by the compiler, but are ignored at run-time even if postcondition 6403checking is enabled. 6404 6405Note that pragma @code{Postcondition} differs from the language-defined 6406@code{Post} aspect (and corresponding @code{Post} pragma) in allowing 6407multiple occurrences, allowing occurences in the body even if there 6408is a separate spec, and allowing a second string parameter, and the 6409use of the pragma identifier @code{Check}. Historically, pragma 6410@code{Postcondition} was implemented prior to the development of 6411Ada 2012, and has been retained in its original form for 6412compatibility purposes. 6413 6414@node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas 6415@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{ba} 6416@section Pragma Post_Class 6417 6418 6419@geindex Post 6420 6421@geindex Checks 6422@geindex postconditions 6423 6424Syntax: 6425 6426@example 6427pragma Post_Class (Boolean_Expression); 6428@end example 6429 6430The @code{Post_Class} pragma is intended to be an exact replacement for 6431the language-defined 6432@code{Post'Class} aspect, and shares its restrictions and semantics. 6433It must appear either immediately following the corresponding 6434subprogram declaration (only other pragmas may intervene), or 6435if there is no separate subprogram declaration, then it can 6436appear at the start of the declarations in a subprogram body 6437(preceded only by other pragmas). 6438 6439Note: This pragma is called @code{Post_Class} rather than 6440@code{Post'Class} because the latter would not be strictly 6441conforming to the allowed syntax for pragmas. The motivation 6442for provinding pragmas equivalent to the aspects is to allow a program 6443to be written using the pragmas, and then compiled if necessary 6444using an Ada compiler that does not recognize the pragmas or 6445aspects, but is prepared to ignore the pragmas. The assertion 6446policy that controls this pragma is @code{Post'Class}, not 6447@code{Post_Class}. 6448 6449@node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas 6450@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{bb} 6451@section Pragma Pre 6452 6453 6454@geindex Pre 6455 6456@geindex Checks 6457@geindex preconditions 6458 6459Syntax: 6460 6461@example 6462pragma Pre (Boolean_Expression); 6463@end example 6464 6465The @code{Pre} pragma is intended to be an exact replacement for 6466the language-defined 6467@code{Pre} aspect, and shares its restrictions and semantics. 6468It must appear either immediately following the corresponding 6469subprogram declaration (only other pragmas may intervene), or 6470if there is no separate subprogram declaration, then it can 6471appear at the start of the declarations in a subprogram body 6472(preceded only by other pragmas). 6473 6474@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas 6475@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bc} 6476@section Pragma Precondition 6477 6478 6479@geindex Preconditions 6480 6481@geindex Checks 6482@geindex preconditions 6483 6484Syntax: 6485 6486@example 6487pragma Precondition ( 6488 [Check =>] Boolean_Expression 6489 [,[Message =>] String_Expression]); 6490@end example 6491 6492The @code{Precondition} pragma is similar to @code{Postcondition} 6493except that the corresponding checks take place immediately upon 6494entry to the subprogram, and if a precondition fails, the exception 6495is raised in the context of the caller, and the attribute ‘Result 6496cannot be used within the precondition expression. 6497 6498Otherwise, the placement and visibility rules are identical to those 6499described for postconditions. The following is an example of use 6500within a package spec: 6501 6502@example 6503package Math_Functions is 6504 ... 6505 function Sqrt (Arg : Float) return Float; 6506 pragma Precondition (Arg >= 0.0) 6507 ... 6508end Math_Functions; 6509@end example 6510 6511@code{Precondition} pragmas may appear either immediately following the 6512(separate) declaration of a subprogram, or at the start of the 6513declarations of a subprogram body. Only other pragmas may intervene 6514(that is appear between the subprogram declaration and its 6515postconditions, or appear before the postcondition in the 6516declaration sequence in a subprogram body). 6517 6518Note: precondition pragmas associated with subprograms that are 6519marked as Inline_Always, or those marked as Inline with front-end 6520inlining (-gnatN option set) are accepted and legality-checked 6521by the compiler, but are ignored at run-time even if precondition 6522checking is enabled. 6523 6524Note that pragma @code{Precondition} differs from the language-defined 6525@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing 6526multiple occurrences, allowing occurences in the body even if there 6527is a separate spec, and allowing a second string parameter, and the 6528use of the pragma identifier @code{Check}. Historically, pragma 6529@code{Precondition} was implemented prior to the development of 6530Ada 2012, and has been retained in its original form for 6531compatibility purposes. 6532 6533@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas 6534@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{bd}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{be} 6535@section Pragma Predicate 6536 6537 6538Syntax: 6539 6540@example 6541pragma Predicate 6542 ([Entity =>] type_LOCAL_NAME, 6543 [Check =>] EXPRESSION); 6544@end example 6545 6546This pragma (available in all versions of Ada in GNAT) encompasses both 6547the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in 6548Ada 2012. A predicate is regarded as static if it has an allowed form 6549for @code{Static_Predicate} and is otherwise treated as a 6550@code{Dynamic_Predicate}. Otherwise, predicates specified by this 6551pragma behave exactly as described in the Ada 2012 reference manual. 6552For example, if we have 6553 6554@example 6555type R is range 1 .. 10; 6556subtype S is R; 6557pragma Predicate (Entity => S, Check => S not in 4 .. 6); 6558subtype Q is R 6559pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 6560@end example 6561 6562the effect is identical to the following Ada 2012 code: 6563 6564@example 6565type R is range 1 .. 10; 6566subtype S is R with 6567 Static_Predicate => S not in 4 .. 6; 6568subtype Q is R with 6569 Dynamic_Predicate => F(Q) or G(Q); 6570@end example 6571 6572Note that there are no pragmas @code{Dynamic_Predicate} 6573or @code{Static_Predicate}. That is 6574because these pragmas would affect legality and semantics of 6575the program and thus do not have a neutral effect if ignored. 6576The motivation behind providing pragmas equivalent to 6577corresponding aspects is to allow a program to be written 6578using the pragmas, and then compiled with a compiler that 6579will ignore the pragmas. That doesn’t work in the case of 6580static and dynamic predicates, since if the corresponding 6581pragmas are ignored, then the behavior of the program is 6582fundamentally changed (for example a membership test 6583@code{A in B} would not take into account a predicate 6584defined for subtype B). When following this approach, the 6585use of predicates should be avoided. 6586 6587@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas 6588@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{bf} 6589@section Pragma Predicate_Failure 6590 6591 6592Syntax: 6593 6594@example 6595pragma Predicate_Failure 6596 ([Entity =>] type_LOCAL_NAME, 6597 [Message =>] String_Expression); 6598@end example 6599 6600The @code{Predicate_Failure} pragma is intended to be an exact replacement for 6601the language-defined 6602@code{Predicate_Failure} aspect, and shares its restrictions and semantics. 6603 6604@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas 6605@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c0} 6606@section Pragma Preelaborable_Initialization 6607 6608 6609Syntax: 6610 6611@example 6612pragma Preelaborable_Initialization (DIRECT_NAME); 6613@end example 6614 6615This pragma is standard in Ada 2005, but is available in all earlier 6616versions of Ada as an implementation-defined pragma. 6617See Ada 2012 Reference Manual for details. 6618 6619@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas 6620@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c1} 6621@section Pragma Prefix_Exception_Messages 6622 6623 6624@geindex Prefix_Exception_Messages 6625 6626@geindex exception 6627 6628@geindex Exception_Message 6629 6630Syntax: 6631 6632@example 6633pragma Prefix_Exception_Messages; 6634@end example 6635 6636This is an implementation-defined configuration pragma that affects the 6637behavior of raise statements with a message given as a static string 6638constant (typically a string literal). In such cases, the string will 6639be automatically prefixed by the name of the enclosing entity (giving 6640the package and subprogram containing the raise statement). This helps 6641to identify where messages are coming from, and this mode is automatic 6642for the run-time library. 6643 6644The pragma has no effect if the message is computed with an expression other 6645than a static string constant, since the assumption in this case is that 6646the program computes exactly the string it wants. If you still want the 6647prefixing in this case, you can always call 6648@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. 6649 6650@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas 6651@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c2} 6652@section Pragma Pre_Class 6653 6654 6655@geindex Pre_Class 6656 6657@geindex Checks 6658@geindex preconditions 6659 6660Syntax: 6661 6662@example 6663pragma Pre_Class (Boolean_Expression); 6664@end example 6665 6666The @code{Pre_Class} pragma is intended to be an exact replacement for 6667the language-defined 6668@code{Pre'Class} aspect, and shares its restrictions and semantics. 6669It must appear either immediately following the corresponding 6670subprogram declaration (only other pragmas may intervene), or 6671if there is no separate subprogram declaration, then it can 6672appear at the start of the declarations in a subprogram body 6673(preceded only by other pragmas). 6674 6675Note: This pragma is called @code{Pre_Class} rather than 6676@code{Pre'Class} because the latter would not be strictly 6677conforming to the allowed syntax for pragmas. The motivation 6678for providing pragmas equivalent to the aspects is to allow a program 6679to be written using the pragmas, and then compiled if necessary 6680using an Ada compiler that does not recognize the pragmas or 6681aspects, but is prepared to ignore the pragmas. The assertion 6682policy that controls this pragma is @code{Pre'Class}, not 6683@code{Pre_Class}. 6684 6685@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas 6686@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c3} 6687@section Pragma Priority_Specific_Dispatching 6688 6689 6690Syntax: 6691 6692@example 6693pragma Priority_Specific_Dispatching ( 6694 POLICY_IDENTIFIER, 6695 first_priority_EXPRESSION, 6696 last_priority_EXPRESSION) 6697 6698POLICY_IDENTIFIER ::= 6699 EDF_Across_Priorities | 6700 FIFO_Within_Priorities | 6701 Non_Preemptive_Within_Priorities | 6702 Round_Robin_Within_Priorities 6703@end example 6704 6705This pragma is standard in Ada 2005, but is available in all earlier 6706versions of Ada as an implementation-defined pragma. 6707See Ada 2012 Reference Manual for details. 6708 6709@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas 6710@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c4} 6711@section Pragma Profile 6712 6713 6714Syntax: 6715 6716@example 6717pragma Profile (Ravenscar | Restricted | Rational | Jorvik | 6718 GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); 6719@end example 6720 6721This pragma is standard in Ada 2005, but is available in all earlier 6722versions of Ada as an implementation-defined pragma. This is a 6723configuration pragma that establishes a set of configuration pragmas 6724that depend on the argument. @code{Ravenscar} is standard in Ada 2005. 6725@code{Jorvik} is standard in Ada 202x. 6726The other possibilities (@code{Restricted}, @code{Rational}, 6727@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) 6728are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. 6729 6730The set of configuration pragmas is defined in the following sections. 6731 6732 6733@itemize * 6734 6735@item 6736Pragma Profile (Ravenscar) 6737 6738The @code{Ravenscar} profile is standard in Ada 2005, 6739but is available in all earlier 6740versions of Ada as an implementation-defined pragma. This profile 6741establishes the following set of configuration pragmas: 6742 6743 6744@itemize * 6745 6746@item 6747@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} 6748 6749[RM D.2.2] Tasks are dispatched following a preemptive 6750priority-ordered scheduling policy. 6751 6752@item 6753@code{Locking_Policy (Ceiling_Locking)} 6754 6755[RM D.3] While tasks and interrupts execute a protected action, they inherit 6756the ceiling priority of the corresponding protected object. 6757 6758@item 6759@code{Detect_Blocking} 6760 6761This pragma forces the detection of potentially blocking operations within a 6762protected operation, and to raise Program_Error if that happens. 6763@end itemize 6764 6765plus the following set of restrictions: 6766 6767 6768@itemize * 6769 6770@item 6771@code{Max_Entry_Queue_Length => 1} 6772 6773No task can be queued on a protected entry. 6774 6775@item 6776@code{Max_Protected_Entries => 1} 6777 6778@item 6779@code{Max_Task_Entries => 0} 6780 6781No rendezvous statements are allowed. 6782 6783@item 6784@code{No_Abort_Statements} 6785 6786@item 6787@code{No_Dynamic_Attachment} 6788 6789@item 6790@code{No_Dynamic_Priorities} 6791 6792@item 6793@code{No_Implicit_Heap_Allocations} 6794 6795@item 6796@code{No_Local_Protected_Objects} 6797 6798@item 6799@code{No_Local_Timing_Events} 6800 6801@item 6802@code{No_Protected_Type_Allocators} 6803 6804@item 6805@code{No_Relative_Delay} 6806 6807@item 6808@code{No_Requeue_Statements} 6809 6810@item 6811@code{No_Select_Statements} 6812 6813@item 6814@code{No_Specific_Termination_Handlers} 6815 6816@item 6817@code{No_Task_Allocators} 6818 6819@item 6820@code{No_Task_Hierarchy} 6821 6822@item 6823@code{No_Task_Termination} 6824 6825@item 6826@code{Simple_Barriers} 6827@end itemize 6828 6829The Ravenscar profile also includes the following restrictions that specify 6830that there are no semantic dependencies on the corresponding predefined 6831packages: 6832 6833 6834@itemize * 6835 6836@item 6837@code{No_Dependence => Ada.Asynchronous_Task_Control} 6838 6839@item 6840@code{No_Dependence => Ada.Calendar} 6841 6842@item 6843@code{No_Dependence => Ada.Execution_Time.Group_Budget} 6844 6845@item 6846@code{No_Dependence => Ada.Execution_Time.Timers} 6847 6848@item 6849@code{No_Dependence => Ada.Task_Attributes} 6850 6851@item 6852@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} 6853@end itemize 6854 6855This set of configuration pragmas and restrictions correspond to the 6856definition of the ‘Ravenscar Profile’ for limited tasking, devised and 6857published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. 6858A description is also available at 6859@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 6860 6861The original definition of the profile was revised at subsequent IRTAW 6862meetings. It has been included in the ISO 6863@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, 6864and was made part of the Ada 2005 standard. 6865The formal definition given by 6866the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 6867AI-305) available at 6868@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 6869@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 6870 6871The above set is a superset of the restrictions provided by pragma 6872@code{Profile (Restricted)}, it includes six additional restrictions 6873(@code{Simple_Barriers}, @code{No_Select_Statements}, 6874@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 6875@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 6876that pragma @code{Profile (Ravenscar)}, like the pragma 6877@code{Profile (Restricted)}, 6878automatically causes the use of a simplified, 6879more efficient version of the tasking run-time library. 6880 6881@item 6882Pragma Profile (Jorvik) 6883 6884@code{Jorvik} is the new profile added to the Ada 202x draft standard, 6885previously implemented under the name @code{GNAT_Extended_Ravenscar}. 6886 6887The @code{No_Implicit_Heap_Allocations} restriction has been replaced 6888by @code{No_Implicit_Task_Allocations} and 6889@code{No_Implicit_Protected_Object_Allocations}. 6890 6891The @code{Simple_Barriers} restriction has been replaced by 6892@code{Pure_Barriers}. 6893 6894The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and 6895@code{No_Relative_Delay} restrictions have been removed. 6896 6897Details on the rationale for @code{Jorvik} and implications for use may be 6898found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, 6899T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, 6900Number 10300. 6901 6902@item 6903Pragma Profile (GNAT_Ravenscar_EDF) 6904 6905This profile corresponds to the Ravenscar profile but using 6906EDF_Across_Priority as the Task_Scheduling_Policy. 6907 6908@item 6909Pragma Profile (Restricted) 6910 6911This profile corresponds to the GNAT restricted run time. It 6912establishes the following set of restrictions: 6913 6914 6915@itemize * 6916 6917@item 6918@code{No_Abort_Statements} 6919 6920@item 6921@code{No_Entry_Queue} 6922 6923@item 6924@code{No_Task_Hierarchy} 6925 6926@item 6927@code{No_Task_Allocators} 6928 6929@item 6930@code{No_Dynamic_Priorities} 6931 6932@item 6933@code{No_Terminate_Alternatives} 6934 6935@item 6936@code{No_Dynamic_Attachment} 6937 6938@item 6939@code{No_Protected_Type_Allocators} 6940 6941@item 6942@code{No_Local_Protected_Objects} 6943 6944@item 6945@code{No_Requeue_Statements} 6946 6947@item 6948@code{No_Task_Attributes_Package} 6949 6950@item 6951@code{Max_Asynchronous_Select_Nesting = 0} 6952 6953@item 6954@code{Max_Task_Entries = 0} 6955 6956@item 6957@code{Max_Protected_Entries = 1} 6958 6959@item 6960@code{Max_Select_Alternatives = 0} 6961@end itemize 6962 6963This set of restrictions causes the automatic selection of a simplified 6964version of the run time that provides improved performance for the 6965limited set of tasking functionality permitted by this set of restrictions. 6966 6967@item 6968Pragma Profile (Rational) 6969 6970The Rational profile is intended to facilitate porting legacy code that 6971compiles with the Rational APEX compiler, even when the code includes non- 6972conforming Ada constructs. The profile enables the following three pragmas: 6973 6974 6975@itemize * 6976 6977@item 6978@code{pragma Implicit_Packing} 6979 6980@item 6981@code{pragma Overriding_Renamings} 6982 6983@item 6984@code{pragma Use_VADS_Size} 6985@end itemize 6986@end itemize 6987 6988@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas 6989@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c5} 6990@section Pragma Profile_Warnings 6991 6992 6993Syntax: 6994 6995@example 6996pragma Profile_Warnings (Ravenscar | Restricted | Rational); 6997@end example 6998 6999This is an implementation-defined pragma that is similar in 7000effect to @code{pragma Profile} except that instead of 7001generating @code{Restrictions} pragmas, it generates 7002@code{Restriction_Warnings} pragmas. The result is that 7003violations of the profile generate warning messages instead 7004of error messages. 7005 7006@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas 7007@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c6} 7008@section Pragma Propagate_Exceptions 7009 7010 7011@geindex Interfacing to C++ 7012 7013Syntax: 7014 7015@example 7016pragma Propagate_Exceptions; 7017@end example 7018 7019This pragma is now obsolete and, other than generating a warning if warnings 7020on obsolescent features are enabled, is ignored. 7021It is retained for compatibility 7022purposes. It used to be used in connection with optimization of 7023a now-obsolete mechanism for implementation of exceptions. 7024 7025@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas 7026@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c7} 7027@section Pragma Provide_Shift_Operators 7028 7029 7030@geindex Shift operators 7031 7032Syntax: 7033 7034@example 7035pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 7036@end example 7037 7038This pragma can be applied to a first subtype local name that specifies 7039either an unsigned or signed type. It has the effect of providing the 7040five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 7041Rotate_Left and Rotate_Right) for the given type. It is similar to 7042including the function declarations for these five operators, together 7043with the pragma Import (Intrinsic, …) statements. 7044 7045@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas 7046@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c8} 7047@section Pragma Psect_Object 7048 7049 7050Syntax: 7051 7052@example 7053pragma Psect_Object ( 7054 [Internal =>] LOCAL_NAME, 7055 [, [External =>] EXTERNAL_SYMBOL] 7056 [, [Size =>] EXTERNAL_SYMBOL]); 7057 7058EXTERNAL_SYMBOL ::= 7059 IDENTIFIER 7060| static_string_EXPRESSION 7061@end example 7062 7063This pragma is identical in effect to pragma @code{Common_Object}. 7064 7065@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas 7066@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{c9}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{ca} 7067@section Pragma Pure_Function 7068 7069 7070Syntax: 7071 7072@example 7073pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 7074@end example 7075 7076This pragma appears in the same declarative part as a function 7077declaration (or a set of function declarations if more than one 7078overloaded declaration exists, in which case the pragma applies 7079to all entities). It specifies that the function @code{Entity} is 7080to be considered pure for the purposes of code generation. This means 7081that the compiler can assume that there are no side effects, and 7082in particular that two calls with identical arguments produce the 7083same result. It also means that the function can be used in an 7084address clause. 7085 7086Note that, quite deliberately, there are no static checks to try 7087to ensure that this promise is met, so @code{Pure_Function} can be used 7088with functions that are conceptually pure, even if they do modify 7089global variables. For example, a square root function that is 7090instrumented to count the number of times it is called is still 7091conceptually pure, and can still be optimized, even though it 7092modifies a global variable (the count). Memo functions are another 7093example (where a table of previous calls is kept and consulted to 7094avoid re-computation). 7095 7096Note also that the normal rules excluding optimization of subprograms 7097in pure units (when parameter types are descended from System.Address, 7098or when the full view of a parameter type is limited), do not apply 7099for the Pure_Function case. If you explicitly specify Pure_Function, 7100the compiler may optimize away calls with identical arguments, and 7101if that results in unexpected behavior, the proper action is not to 7102use the pragma for subprograms that are not (conceptually) pure. 7103 7104Note: Most functions in a @code{Pure} package are automatically pure, and 7105there is no need to use pragma @code{Pure_Function} for such functions. One 7106exception is any function that has at least one formal of type 7107@code{System.Address} or a type derived from it. Such functions are not 7108considered pure by default, since the compiler assumes that the 7109@code{Address} parameter may be functioning as a pointer and that the 7110referenced data may change even if the address value does not. 7111Similarly, imported functions are not considered to be pure by default, 7112since there is no way of checking that they are in fact pure. The use 7113of pragma @code{Pure_Function} for such a function will override these default 7114assumption, and cause the compiler to treat a designated subprogram as pure 7115in these cases. 7116 7117Note: If pragma @code{Pure_Function} is applied to a renamed function, it 7118applies to the underlying renamed function. This can be used to 7119disambiguate cases of overloading where some but not all functions 7120in a set of overloaded functions are to be designated as pure. 7121 7122If pragma @code{Pure_Function} is applied to a library-level function, the 7123function is also considered pure from an optimization point of view, but the 7124unit is not a Pure unit in the categorization sense. So for example, a function 7125thus marked is free to @code{with} non-pure units. 7126 7127@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas 7128@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{cb} 7129@section Pragma Rational 7130 7131 7132Syntax: 7133 7134@example 7135pragma Rational; 7136@end example 7137 7138This pragma is considered obsolescent, but is retained for 7139compatibility purposes. It is equivalent to: 7140 7141@example 7142pragma Profile (Rational); 7143@end example 7144 7145@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas 7146@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cc} 7147@section Pragma Ravenscar 7148 7149 7150Syntax: 7151 7152@example 7153pragma Ravenscar; 7154@end example 7155 7156This pragma is considered obsolescent, but is retained for 7157compatibility purposes. It is equivalent to: 7158 7159@example 7160pragma Profile (Ravenscar); 7161@end example 7162 7163which is the preferred method of setting the @code{Ravenscar} profile. 7164 7165@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas 7166@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cd}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{ce} 7167@section Pragma Refined_Depends 7168 7169 7170Syntax: 7171 7172@example 7173pragma Refined_Depends (DEPENDENCY_RELATION); 7174 7175DEPENDENCY_RELATION ::= 7176 null 7177 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 7178 7179DEPENDENCY_CLAUSE ::= 7180 OUTPUT_LIST =>[+] INPUT_LIST 7181 | NULL_DEPENDENCY_CLAUSE 7182 7183NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 7184 7185OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 7186 7187INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 7188 7189OUTPUT ::= NAME | FUNCTION_RESULT 7190INPUT ::= NAME 7191 7192where FUNCTION_RESULT is a function Result attribute_reference 7193@end example 7194 7195For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in 7196the SPARK 2014 Reference Manual, section 6.1.5. 7197 7198@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas 7199@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d0} 7200@section Pragma Refined_Global 7201 7202 7203Syntax: 7204 7205@example 7206pragma Refined_Global (GLOBAL_SPECIFICATION); 7207 7208GLOBAL_SPECIFICATION ::= 7209 null 7210 | (GLOBAL_LIST) 7211 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 7212 7213MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 7214 7215MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 7216GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 7217GLOBAL_ITEM ::= NAME 7218@end example 7219 7220For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in 7221the SPARK 2014 Reference Manual, section 6.1.4. 7222 7223@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas 7224@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d1}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d2} 7225@section Pragma Refined_Post 7226 7227 7228Syntax: 7229 7230@example 7231pragma Refined_Post (boolean_EXPRESSION); 7232@end example 7233 7234For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in 7235the SPARK 2014 Reference Manual, section 7.2.7. 7236 7237@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas 7238@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d3}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d4} 7239@section Pragma Refined_State 7240 7241 7242Syntax: 7243 7244@example 7245pragma Refined_State (REFINEMENT_LIST); 7246 7247REFINEMENT_LIST ::= 7248 (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) 7249 7250REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST 7251 7252CONSTITUENT_LIST ::= 7253 null 7254 | CONSTITUENT 7255 | (CONSTITUENT @{, CONSTITUENT@}) 7256 7257CONSTITUENT ::= object_NAME | state_NAME 7258@end example 7259 7260For the semantics of this pragma, see the entry for aspect @code{Refined_State} in 7261the SPARK 2014 Reference Manual, section 7.2.2. 7262 7263@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas 7264@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d5} 7265@section Pragma Relative_Deadline 7266 7267 7268Syntax: 7269 7270@example 7271pragma Relative_Deadline (time_span_EXPRESSION); 7272@end example 7273 7274This pragma is standard in Ada 2005, but is available in all earlier 7275versions of Ada as an implementation-defined pragma. 7276See Ada 2012 Reference Manual for details. 7277 7278@node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas 7279@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d6}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d7} 7280@section Pragma Remote_Access_Type 7281 7282 7283Syntax: 7284 7285@example 7286pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 7287@end example 7288 7289This pragma appears in the formal part of a generic declaration. 7290It specifies an exception to the RM rule from E.2.2(17/2), which forbids 7291the use of a remote access to class-wide type as actual for a formal 7292access type. 7293 7294When this pragma applies to a formal access type @code{Entity}, that 7295type is treated as a remote access to class-wide type in the generic. 7296It must be a formal general access type, and its designated type must 7297be the class-wide type of a formal tagged limited private type from the 7298same generic declaration. 7299 7300In the generic unit, the formal type is subject to all restrictions 7301pertaining to remote access to class-wide types. At instantiation, the 7302actual type must be a remote access to class-wide type. 7303 7304@node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas 7305@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{d8} 7306@section Pragma Rename_Pragma 7307 7308 7309@geindex Pragmas 7310@geindex synonyms 7311 7312Syntax: 7313 7314@example 7315pragma Rename_Pragma ( 7316 [New_Name =>] IDENTIFIER, 7317 [Renamed =>] pragma_IDENTIFIER); 7318@end example 7319 7320This pragma provides a mechanism for supplying new names for existing 7321pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for 7322the Renamed pragma. For example, suppose you have code that was originally 7323developed on a compiler that supports Inline_Only as an implementation defined 7324pragma. And suppose the semantics of pragma Inline_Only are identical to (or at 7325least very similar to) the GNAT implementation defined pragma 7326Inline_Always. You could globally replace Inline_Only with Inline_Always. 7327 7328However, to avoid that source modification, you could instead add a 7329configuration pragma: 7330 7331@example 7332pragma Rename_Pragma ( 7333 New_Name => Inline_Only, 7334 Renamed => Inline_Always); 7335@end example 7336 7337Then GNAT will treat “pragma Inline_Only …” as if you had written 7338“pragma Inline_Always …”. 7339 7340Pragma Inline_Only will not necessarily mean the same thing as the other Ada 7341compiler; it’s up to you to make sure the semantics are close enough. 7342 7343@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas 7344@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d9} 7345@section Pragma Restricted_Run_Time 7346 7347 7348Syntax: 7349 7350@example 7351pragma Restricted_Run_Time; 7352@end example 7353 7354This pragma is considered obsolescent, but is retained for 7355compatibility purposes. It is equivalent to: 7356 7357@example 7358pragma Profile (Restricted); 7359@end example 7360 7361which is the preferred method of setting the restricted run time 7362profile. 7363 7364@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas 7365@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{da} 7366@section Pragma Restriction_Warnings 7367 7368 7369Syntax: 7370 7371@example 7372pragma Restriction_Warnings 7373 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 7374@end example 7375 7376This pragma allows a series of restriction identifiers to be 7377specified (the list of allowed identifiers is the same as for 7378pragma @code{Restrictions}). For each of these identifiers 7379the compiler checks for violations of the restriction, but 7380generates a warning message rather than an error message 7381if the restriction is violated. 7382 7383One use of this is in situations where you want to know 7384about violations of a restriction, but you want to ignore some of 7385these violations. Consider this example, where you want to set 7386Ada_95 mode and enable style checks, but you want to know about 7387any other use of implementation pragmas: 7388 7389@example 7390pragma Restriction_Warnings (No_Implementation_Pragmas); 7391pragma Warnings (Off, "violation of No_Implementation_Pragmas"); 7392pragma Ada_95; 7393pragma Style_Checks ("2bfhkM160"); 7394pragma Warnings (On, "violation of No_Implementation_Pragmas"); 7395@end example 7396 7397By including the above lines in a configuration pragmas file, 7398the Ada_95 and Style_Checks pragmas are accepted without 7399generating a warning, but any other use of implementation 7400defined pragmas will cause a warning to be generated. 7401 7402@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas 7403@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{db} 7404@section Pragma Reviewable 7405 7406 7407Syntax: 7408 7409@example 7410pragma Reviewable; 7411@end example 7412 7413This pragma is an RM-defined standard pragma, but has no effect on the 7414program being compiled, or on the code generated for the program. 7415 7416To obtain the required output specified in RM H.3.1, the compiler must be 7417run with various special switches as follows: 7418 7419 7420@itemize * 7421 7422@item 7423@emph{Where compiler-generated run-time checks remain} 7424 7425The switch @emph{-gnatGL} 7426may be used to list the expanded code in pseudo-Ada form. 7427Runtime checks show up in the listing either as explicit 7428checks or operators marked with @{@} to indicate a check is present. 7429 7430@item 7431@emph{An identification of known exceptions at compile time} 7432 7433If the program is compiled with @emph{-gnatwa}, 7434the compiler warning messages will indicate all cases where the compiler 7435detects that an exception is certain to occur at run time. 7436 7437@item 7438@emph{Possible reads of uninitialized variables} 7439 7440The compiler warns of many such cases, but its output is incomplete. 7441@end itemize 7442 7443 7444A supplemental static analysis tool 7445may be used to obtain a comprehensive list of all 7446possible points at which uninitialized data may be read. 7447 7448 7449@itemize * 7450 7451@item 7452@emph{Where run-time support routines are implicitly invoked} 7453 7454In the output from @emph{-gnatGL}, 7455run-time calls are explicitly listed as calls to the relevant 7456run-time routine. 7457 7458@item 7459@emph{Object code listing} 7460 7461This may be obtained either by using the @emph{-S} switch, 7462or the objdump utility. 7463 7464@item 7465@emph{Constructs known to be erroneous at compile time} 7466 7467These are identified by warnings issued by the compiler (use @emph{-gnatwa}). 7468 7469@item 7470@emph{Stack usage information} 7471 7472Static stack usage data (maximum per-subprogram) can be obtained via the 7473@emph{-fstack-usage} switch to the compiler. 7474Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch 7475to gnatbind 7476@end itemize 7477 7478 7479 7480@itemize * 7481 7482@item 7483@emph{Object code listing of entire partition} 7484 7485This can be obtained by compiling the partition with @emph{-S}, 7486or by applying objdump 7487to all the object files that are part of the partition. 7488 7489@item 7490@emph{A description of the run-time model} 7491 7492The full sources of the run-time are available, and the documentation of 7493these routines describes how these run-time routines interface to the 7494underlying operating system facilities. 7495 7496@item 7497@emph{Control and data-flow information} 7498@end itemize 7499 7500 7501A supplemental static analysis tool 7502may be used to obtain complete control and data-flow information, as well as 7503comprehensive messages identifying possible problems based on this 7504information. 7505 7506@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas 7507@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{dc}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dd} 7508@section Pragma Secondary_Stack_Size 7509 7510 7511Syntax: 7512 7513@example 7514pragma Secondary_Stack_Size (integer_EXPRESSION); 7515@end example 7516 7517This pragma appears within the task definition of a single task declaration 7518or a task type declaration (like pragma @code{Storage_Size}) and applies to all 7519task objects of that type. The argument specifies the size of the secondary 7520stack to be used by these task objects, and must be of an integer type. The 7521secondary stack is used to handle functions that return a variable-sized 7522result, for example a function returning an unconstrained String. 7523 7524Note this pragma only applies to targets using fixed secondary stacks, like 7525VxWorks 653 and bare board targets, where a fixed block for the 7526secondary stack is allocated from the primary stack of the task. By default, 7527these targets assign a percentage of the primary stack for the secondary stack, 7528as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, 7529an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. 7530 7531For most targets, the pragma does not apply as the secondary stack grows on 7532demand: allocated as a chain of blocks in the heap. The default size of these 7533blocks can be modified via the @code{-D} binder option as described in 7534@cite{GNAT User’s Guide}. 7535 7536Note that no check is made to see if the secondary stack can fit inside the 7537primary stack. 7538 7539Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} 7540is in effect. 7541 7542@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas 7543@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{de} 7544@section Pragma Share_Generic 7545 7546 7547Syntax: 7548 7549@example 7550pragma Share_Generic (GNAME @{, GNAME@}); 7551 7552GNAME ::= generic_unit_NAME | generic_instance_NAME 7553@end example 7554 7555This pragma is provided for compatibility with Dec Ada 83. It has 7556no effect in GNAT (which does not implement shared generics), other 7557than to check that the given names are all names of generic units or 7558generic instances. 7559 7560@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas 7561@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{df}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e0} 7562@section Pragma Shared 7563 7564 7565This pragma is provided for compatibility with Ada 83. The syntax and 7566semantics are identical to pragma Atomic. 7567 7568@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas 7569@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e1} 7570@section Pragma Short_Circuit_And_Or 7571 7572 7573Syntax: 7574 7575@example 7576pragma Short_Circuit_And_Or; 7577@end example 7578 7579This configuration pragma causes any occurrence of the AND operator applied to 7580operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 7581is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 7582may be useful in the context of certification protocols requiring the use of 7583short-circuited logical operators. If this configuration pragma occurs locally 7584within the file being compiled, it applies only to the file being compiled. 7585There is no requirement that all units in a partition use this option. 7586 7587@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas 7588@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e2} 7589@section Pragma Short_Descriptors 7590 7591 7592Syntax: 7593 7594@example 7595pragma Short_Descriptors 7596@end example 7597 7598This pragma is provided for compatibility with other Ada implementations. It 7599is recognized but ignored by all current versions of GNAT. 7600 7601@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas 7602@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e3}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e4} 7603@section Pragma Simple_Storage_Pool_Type 7604 7605 7606@geindex Storage pool 7607@geindex simple 7608 7609@geindex Simple storage pool 7610 7611Syntax: 7612 7613@example 7614pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 7615@end example 7616 7617A type can be established as a ‘simple storage pool type’ by applying 7618the representation pragma @code{Simple_Storage_Pool_Type} to the type. 7619A type named in the pragma must be a library-level immutably limited record 7620type or limited tagged type declared immediately within a package declaration. 7621The type can also be a limited private type whose full type is allowed as 7622a simple storage pool type. 7623 7624For a simple storage pool type @code{SSP}, nonabstract primitive subprograms 7625@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that 7626are subtype conformant with the following subprogram declarations: 7627 7628@example 7629procedure Allocate 7630 (Pool : in out SSP; 7631 Storage_Address : out System.Address; 7632 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7633 Alignment : System.Storage_Elements.Storage_Count); 7634 7635procedure Deallocate 7636 (Pool : in out SSP; 7637 Storage_Address : System.Address; 7638 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7639 Alignment : System.Storage_Elements.Storage_Count); 7640 7641function Storage_Size (Pool : SSP) 7642 return System.Storage_Elements.Storage_Count; 7643@end example 7644 7645Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and 7646@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then 7647applying an unchecked deallocation has no effect other than to set its actual 7648parameter to null. If @code{Storage_Size} is not declared, then the 7649@code{Storage_Size} attribute applied to an access type associated with 7650a pool object of type SSP returns zero. Additional operations can be declared 7651for a simple storage pool type (such as for supporting a mark/release 7652storage-management discipline). 7653 7654An object of a simple storage pool type can be associated with an access 7655type by specifying the attribute 7656@ref{e5,,Simple_Storage_Pool}. For example: 7657 7658@example 7659My_Pool : My_Simple_Storage_Pool_Type; 7660 7661type Acc is access My_Data_Type; 7662 7663for Acc'Simple_Storage_Pool use My_Pool; 7664@end example 7665 7666See attribute @ref{e5,,Simple_Storage_Pool} 7667for further details. 7668 7669@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas 7670@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e6}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e7} 7671@section Pragma Source_File_Name 7672 7673 7674Syntax: 7675 7676@example 7677pragma Source_File_Name ( 7678 [Unit_Name =>] unit_NAME, 7679 Spec_File_Name => STRING_LITERAL, 7680 [Index => INTEGER_LITERAL]); 7681 7682pragma Source_File_Name ( 7683 [Unit_Name =>] unit_NAME, 7684 Body_File_Name => STRING_LITERAL, 7685 [Index => INTEGER_LITERAL]); 7686@end example 7687 7688Use this to override the normal naming convention. It is a configuration 7689pragma, and so has the usual applicability of configuration pragmas 7690(i.e., it applies to either an entire partition, or to all units in a 7691compilation, or to a single unit, depending on how it is used. 7692@code{unit_name} is mapped to @code{file_name_literal}. The identifier for 7693the second argument is required, and indicates whether this is the file 7694name for the spec or for the body. 7695 7696The optional Index argument should be used when a file contains multiple 7697units, and when you do not want to use @code{gnatchop} to separate then 7698into multiple files (which is the recommended procedure to limit the 7699number of recompilations that are needed when some sources change). 7700For instance, if the source file @code{source.ada} contains 7701 7702@example 7703package B is 7704... 7705end B; 7706 7707with B; 7708procedure A is 7709begin 7710 .. 7711end A; 7712@end example 7713 7714you could use the following configuration pragmas: 7715 7716@example 7717pragma Source_File_Name 7718 (B, Spec_File_Name => "source.ada", Index => 1); 7719pragma Source_File_Name 7720 (A, Body_File_Name => "source.ada", Index => 2); 7721@end example 7722 7723Note that the @code{gnatname} utility can also be used to generate those 7724configuration pragmas. 7725 7726Another form of the @code{Source_File_Name} pragma allows 7727the specification of patterns defining alternative file naming schemes 7728to apply to all files. 7729 7730@example 7731pragma Source_File_Name 7732 ( [Spec_File_Name =>] STRING_LITERAL 7733 [,[Casing =>] CASING_SPEC] 7734 [,[Dot_Replacement =>] STRING_LITERAL]); 7735 7736pragma Source_File_Name 7737 ( [Body_File_Name =>] STRING_LITERAL 7738 [,[Casing =>] CASING_SPEC] 7739 [,[Dot_Replacement =>] STRING_LITERAL]); 7740 7741pragma Source_File_Name 7742 ( [Subunit_File_Name =>] STRING_LITERAL 7743 [,[Casing =>] CASING_SPEC] 7744 [,[Dot_Replacement =>] STRING_LITERAL]); 7745 7746CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 7747@end example 7748 7749The first argument is a pattern that contains a single asterisk indicating 7750the point at which the unit name is to be inserted in the pattern string 7751to form the file name. The second argument is optional. If present it 7752specifies the casing of the unit name in the resulting file name string. 7753The default is lower case. Finally the third argument allows for systematic 7754replacement of any dots in the unit name by the specified string literal. 7755 7756Note that Source_File_Name pragmas should not be used if you are using 7757project files. The reason for this rule is that the project manager is not 7758aware of these pragmas, and so other tools that use the projet file would not 7759be aware of the intended naming conventions. If you are using project files, 7760file naming is controlled by Source_File_Name_Project pragmas, which are 7761usually supplied automatically by the project manager. A pragma 7762Source_File_Name cannot appear after a @ref{e8,,Pragma Source_File_Name_Project}. 7763 7764For more details on the use of the @code{Source_File_Name} pragma, see the 7765sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} 7766in the @cite{GNAT User’s Guide}. 7767 7768@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas 7769@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e9}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e8} 7770@section Pragma Source_File_Name_Project 7771 7772 7773This pragma has the same syntax and semantics as pragma Source_File_Name. 7774It is only allowed as a stand-alone configuration pragma. 7775It cannot appear after a @ref{e7,,Pragma Source_File_Name}, and 7776most importantly, once pragma Source_File_Name_Project appears, 7777no further Source_File_Name pragmas are allowed. 7778 7779The intention is that Source_File_Name_Project pragmas are always 7780generated by the Project Manager in a manner consistent with the naming 7781specified in a project file, and when naming is controlled in this manner, 7782it is not permissible to attempt to modify this naming scheme using 7783Source_File_Name or Source_File_Name_Project pragmas (which would not be 7784known to the project manager). 7785 7786@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas 7787@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ea} 7788@section Pragma Source_Reference 7789 7790 7791Syntax: 7792 7793@example 7794pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 7795@end example 7796 7797This pragma must appear as the first line of a source file. 7798@code{integer_literal} is the logical line number of the line following 7799the pragma line (for use in error messages and debugging 7800information). @code{string_literal} is a static string constant that 7801specifies the file name to be used in error messages and debugging 7802information. This is most notably used for the output of @code{gnatchop} 7803with the @emph{-r} switch, to make sure that the original unchopped 7804source file is the one referred to. 7805 7806The second argument must be a string literal, it cannot be a static 7807string expression other than a string literal. This is because its value 7808is needed for error messages issued by all phases of the compiler. 7809 7810@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas 7811@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{eb}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{ec} 7812@section Pragma SPARK_Mode 7813 7814 7815Syntax: 7816 7817@example 7818pragma SPARK_Mode [(On | Off)] ; 7819@end example 7820 7821In general a program can have some parts that are in SPARK 2014 (and 7822follow all the rules in the SPARK Reference Manual), and some parts 7823that are full Ada 2012. 7824 7825The SPARK_Mode pragma is used to identify which parts are in SPARK 78262014 (by default programs are in full Ada). The SPARK_Mode pragma can 7827be used in the following places: 7828 7829 7830@itemize * 7831 7832@item 7833As a configuration pragma, in which case it sets the default mode for 7834all units compiled with this pragma. 7835 7836@item 7837Immediately following a library-level subprogram spec 7838 7839@item 7840Immediately within a library-level package body 7841 7842@item 7843Immediately following the @code{private} keyword of a library-level 7844package spec 7845 7846@item 7847Immediately following the @code{begin} keyword of a library-level 7848package body 7849 7850@item 7851Immediately within a library-level subprogram body 7852@end itemize 7853 7854Normally a subprogram or package spec/body inherits the current mode 7855that is active at the point it is declared. But this can be overridden 7856by pragma within the spec or body as above. 7857 7858The basic consistency rule is that you can’t turn SPARK_Mode back 7859@code{On}, once you have explicitly (with a pragma) turned if 7860@code{Off}. So the following rules apply: 7861 7862If a subprogram spec has SPARK_Mode @code{Off}, then the body must 7863also have SPARK_Mode @code{Off}. 7864 7865For a package, we have four parts: 7866 7867 7868@itemize * 7869 7870@item 7871the package public declarations 7872 7873@item 7874the package private part 7875 7876@item 7877the body of the package 7878 7879@item 7880the elaboration code after @code{begin} 7881@end itemize 7882 7883For a package, the rule is that if you explicitly turn SPARK_Mode 7884@code{Off} for any part, then all the following parts must have 7885SPARK_Mode @code{Off}. Note that this may require repeating a pragma 7886SPARK_Mode (@code{Off}) in the body. For example, if we have a 7887configuration pragma SPARK_Mode (@code{On}) that turns the mode on by 7888default everywhere, and one particular package spec has pragma 7889SPARK_Mode (@code{Off}), then that pragma will need to be repeated in 7890the package body. 7891 7892@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas 7893@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ed} 7894@section Pragma Static_Elaboration_Desired 7895 7896 7897Syntax: 7898 7899@example 7900pragma Static_Elaboration_Desired; 7901@end example 7902 7903This pragma is used to indicate that the compiler should attempt to initialize 7904statically the objects declared in the library unit to which the pragma applies, 7905when these objects are initialized (explicitly or implicitly) by an aggregate. 7906In the absence of this pragma, aggregates in object declarations are expanded 7907into assignments and loops, even when the aggregate components are static 7908constants. When the aggregate is present the compiler builds a static expression 7909that requires no run-time code, so that the initialized object can be placed in 7910read-only data space. If the components are not static, or the aggregate has 7911more that 100 components, the compiler emits a warning that the pragma cannot 7912be obeyed. (See also the restriction No_Implicit_Loops, which supports static 7913construction of larger aggregates with static components that include an others 7914choice.) 7915 7916@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas 7917@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ee} 7918@section Pragma Stream_Convert 7919 7920 7921Syntax: 7922 7923@example 7924pragma Stream_Convert ( 7925 [Entity =>] type_LOCAL_NAME, 7926 [Read =>] function_NAME, 7927 [Write =>] function_NAME); 7928@end example 7929 7930This pragma provides an efficient way of providing user-defined stream 7931attributes. Not only is it simpler to use than specifying the attributes 7932directly, but more importantly, it allows the specification to be made in such 7933a way that the predefined unit Ada.Streams is not loaded unless it is actually 7934needed (i.e. unless the stream attributes are actually used); the use of 7935the Stream_Convert pragma adds no overhead at all, unless the stream 7936attributes are actually used on the designated type. 7937 7938The first argument specifies the type for which stream functions are 7939provided. The second parameter provides a function used to read values 7940of this type. It must name a function whose argument type may be any 7941subtype, and whose returned type must be the type given as the first 7942argument to the pragma. 7943 7944The meaning of the @code{Read} parameter is that if a stream attribute directly 7945or indirectly specifies reading of the type given as the first parameter, 7946then a value of the type given as the argument to the Read function is 7947read from the stream, and then the Read function is used to convert this 7948to the required target type. 7949 7950Similarly the @code{Write} parameter specifies how to treat write attributes 7951that directly or indirectly apply to the type given as the first parameter. 7952It must have an input parameter of the type specified by the first parameter, 7953and the return type must be the same as the input type of the Read function. 7954The effect is to first call the Write function to convert to the given stream 7955type, and then write the result type to the stream. 7956 7957The Read and Write functions must not be overloaded subprograms. If necessary 7958renamings can be supplied to meet this requirement. 7959The usage of this attribute is best illustrated by a simple example, taken 7960from the GNAT implementation of package Ada.Strings.Unbounded: 7961 7962@example 7963function To_Unbounded (S : String) return Unbounded_String 7964 renames To_Unbounded_String; 7965 7966pragma Stream_Convert 7967 (Unbounded_String, To_Unbounded, To_String); 7968@end example 7969 7970The specifications of the referenced functions, as given in the Ada 7971Reference Manual are: 7972 7973@example 7974function To_Unbounded_String (Source : String) 7975 return Unbounded_String; 7976 7977function To_String (Source : Unbounded_String) 7978 return String; 7979@end example 7980 7981The effect is that if the value of an unbounded string is written to a stream, 7982then the representation of the item in the stream is in the same format that 7983would be used for @code{Standard.String'Output}, and this same representation 7984is expected when a value of this type is read from the stream. Note that the 7985value written always includes the bounds, even for Unbounded_String’Write, 7986since Unbounded_String is not an array type. 7987 7988Note that the @code{Stream_Convert} pragma is not effective in the case of 7989a derived type of a non-limited tagged type. If such a type is specified then 7990the pragma is silently ignored, and the default implementation of the stream 7991attributes is used instead. 7992 7993@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas 7994@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ef} 7995@section Pragma Style_Checks 7996 7997 7998Syntax: 7999 8000@example 8001pragma Style_Checks (string_LITERAL | ALL_CHECKS | 8002 On | Off [, LOCAL_NAME]); 8003@end example 8004 8005This pragma is used in conjunction with compiler switches to control the 8006built in style checking provided by GNAT. The compiler switches, if set, 8007provide an initial setting for the switches, and this pragma may be used 8008to modify these settings, or the settings may be provided entirely by 8009the use of the pragma. This pragma can be used anywhere that a pragma 8010is legal, including use as a configuration pragma (including use in 8011the @code{gnat.adc} file). 8012 8013The form with a string literal specifies which style options are to be 8014activated. These are additive, so they apply in addition to any previously 8015set style check options. The codes for the options are the same as those 8016used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. 8017For example the following two methods can be used to enable 8018layout checking: 8019 8020 8021@itemize * 8022 8023@item 8024@example 8025pragma Style_Checks ("l"); 8026@end example 8027 8028@item 8029@example 8030gcc -c -gnatyl ... 8031@end example 8032@end itemize 8033 8034The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent 8035to the use of the @code{gnaty} switch with no options. 8036See the @cite{GNAT User’s Guide} for details.) 8037 8038Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). 8039In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check 8040options (i.e. equivalent to @code{-gnatyg}). 8041 8042The forms with @code{Off} and @code{On} 8043can be used to temporarily disable style checks 8044as shown in the following example: 8045 8046@example 8047pragma Style_Checks ("k"); -- requires keywords in lower case 8048pragma Style_Checks (Off); -- turn off style checks 8049NULL; -- this will not generate an error message 8050pragma Style_Checks (On); -- turn style checks back on 8051NULL; -- this will generate an error message 8052@end example 8053 8054Finally the two argument form is allowed only if the first argument is 8055@code{On} or @code{Off}. The effect is to turn of semantic style checks 8056for the specified entity, as shown in the following example: 8057 8058@example 8059pragma Style_Checks ("r"); -- require consistency of identifier casing 8060Arg : Integer; 8061Rf1 : Integer := ARG; -- incorrect, wrong case 8062pragma Style_Checks (Off, Arg); 8063Rf2 : Integer := ARG; -- OK, no error 8064@end example 8065 8066@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas 8067@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f0} 8068@section Pragma Subtitle 8069 8070 8071Syntax: 8072 8073@example 8074pragma Subtitle ([Subtitle =>] STRING_LITERAL); 8075@end example 8076 8077This pragma is recognized for compatibility with other Ada compilers 8078but is ignored by GNAT. 8079 8080@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas 8081@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f1} 8082@section Pragma Suppress 8083 8084 8085Syntax: 8086 8087@example 8088pragma Suppress (Identifier [, [On =>] Name]); 8089@end example 8090 8091This is a standard pragma, and supports all the check names required in 8092the RM. It is included here because GNAT recognizes some additional check 8093names that are implementation defined (as permitted by the RM): 8094 8095 8096@itemize * 8097 8098@item 8099@code{Alignment_Check} can be used to suppress alignment checks 8100on addresses used in address clauses. Such checks can also be suppressed 8101by suppressing range checks, but the specific use of @code{Alignment_Check} 8102allows suppression of alignment checks without suppressing other range checks. 8103Note that @code{Alignment_Check} is suppressed by default on machines (such as 8104the x86) with non-strict alignment. 8105 8106@item 8107@code{Atomic_Synchronization} can be used to suppress the special memory 8108synchronization instructions that are normally generated for access to 8109@code{Atomic} variables to ensure correct synchronization between tasks 8110that use such variables for synchronization purposes. 8111 8112@item 8113@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated 8114for a duplicated tag value when a tagged type is declared. 8115 8116@item 8117@code{Container_Checks} Can be used to suppress all checks within Ada.Containers 8118and instances of its children, including Tampering_Check. 8119 8120@item 8121@code{Tampering_Check} Can be used to suppress tampering check in the containers. 8122 8123@item 8124@code{Predicate_Check} can be used to control whether predicate checks are 8125active. It is applicable only to predicates for which the policy is 8126@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given 8127predicate is ignored or checked for the whole program, the use of 8128@code{Suppress} and @code{Unsuppress} with this check name allows a given 8129predicate to be turned on and off at specific points in the program. 8130 8131@item 8132@code{Validity_Check} can be used specifically to control validity checks. 8133If @code{Suppress} is used to suppress validity checks, then no validity 8134checks are performed, including those specified by the appropriate compiler 8135switch or the @code{Validity_Checks} pragma. 8136 8137@item 8138Additional check names previously introduced by use of the @code{Check_Name} 8139pragma are also allowed. 8140@end itemize 8141 8142Note that pragma Suppress gives the compiler permission to omit 8143checks, but does not require the compiler to omit checks. The compiler 8144will generate checks if they are essentially free, even when they are 8145suppressed. In particular, if the compiler can prove that a certain 8146check will necessarily fail, it will generate code to do an 8147unconditional ‘raise’, even if checks are suppressed. The compiler 8148warns in this case. 8149 8150Of course, run-time checks are omitted whenever the compiler can prove 8151that they will not fail, whether or not checks are suppressed. 8152 8153@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas 8154@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f2} 8155@section Pragma Suppress_All 8156 8157 8158Syntax: 8159 8160@example 8161pragma Suppress_All; 8162@end example 8163 8164This pragma can appear anywhere within a unit. 8165The effect is to apply @code{Suppress (All_Checks)} to the unit 8166in which it appears. This pragma is implemented for compatibility with DEC 8167Ada 83 usage where it appears at the end of a unit, and for compatibility 8168with Rational Ada, where it appears as a program unit pragma. 8169The use of the standard Ada pragma @code{Suppress (All_Checks)} 8170as a normal configuration pragma is the preferred usage in GNAT. 8171 8172@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas 8173@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f3}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f4} 8174@section Pragma Suppress_Debug_Info 8175 8176 8177Syntax: 8178 8179@example 8180pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 8181@end example 8182 8183This pragma can be used to suppress generation of debug information 8184for the specified entity. It is intended primarily for use in debugging 8185the debugger, and navigating around debugger problems. 8186 8187@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas 8188@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f5} 8189@section Pragma Suppress_Exception_Locations 8190 8191 8192Syntax: 8193 8194@example 8195pragma Suppress_Exception_Locations; 8196@end example 8197 8198In normal mode, a raise statement for an exception by default generates 8199an exception message giving the file name and line number for the location 8200of the raise. This is useful for debugging and logging purposes, but this 8201entails extra space for the strings for the messages. The configuration 8202pragma @code{Suppress_Exception_Locations} can be used to suppress the 8203generation of these strings, with the result that space is saved, but the 8204exception message for such raises is null. This configuration pragma may 8205appear in a global configuration pragma file, or in a specific unit as 8206usual. It is not required that this pragma be used consistently within 8207a partition, so it is fine to have some units within a partition compiled 8208with this pragma and others compiled in normal mode without it. 8209 8210@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas 8211@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f6}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f7} 8212@section Pragma Suppress_Initialization 8213 8214 8215@geindex Suppressing initialization 8216 8217@geindex Initialization 8218@geindex suppression of 8219 8220Syntax: 8221 8222@example 8223pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); 8224@end example 8225 8226Here variable_or_subtype_Name is the name introduced by a type declaration 8227or subtype declaration or the name of a variable introduced by an 8228object declaration. 8229 8230In the case of a type or subtype 8231this pragma suppresses any implicit or explicit initialization 8232for all variables of the given type or subtype, 8233including initialization resulting from the use of pragmas 8234Normalize_Scalars or Initialize_Scalars. 8235 8236This is considered a representation item, so it cannot be given after 8237the type is frozen. It applies to all subsequent object declarations, 8238and also any allocator that creates objects of the type. 8239 8240If the pragma is given for the first subtype, then it is considered 8241to apply to the base type and all its subtypes. If the pragma is given 8242for other than a first subtype, then it applies only to the given subtype. 8243The pragma may not be given after the type is frozen. 8244 8245Note that this includes eliminating initialization of discriminants 8246for discriminated types, and tags for tagged types. In these cases, 8247you will have to use some non-portable mechanism (e.g. address 8248overlays or unchecked conversion) to achieve required initialization 8249of these fields before accessing any object of the corresponding type. 8250 8251For the variable case, implicit initialization for the named variable 8252is suppressed, just as though its subtype had been given in a pragma 8253Suppress_Initialization, as described above. 8254 8255@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas 8256@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f8} 8257@section Pragma Task_Name 8258 8259 8260Syntax 8261 8262@example 8263pragma Task_Name (string_EXPRESSION); 8264@end example 8265 8266This pragma appears within a task definition (like pragma 8267@code{Priority}) and applies to the task in which it appears. The 8268argument must be of type String, and provides a name to be used for 8269the task instance when the task is created. Note that this expression 8270is not required to be static, and in particular, it can contain 8271references to task discriminants. This facility can be used to 8272provide different names for different tasks as they are created, 8273as illustrated in the example below. 8274 8275The task name is recorded internally in the run-time structures 8276and is accessible to tools like the debugger. In addition the 8277routine @code{Ada.Task_Identification.Image} will return this 8278string, with a unique task address appended. 8279 8280@example 8281-- Example of the use of pragma Task_Name 8282 8283with Ada.Task_Identification; 8284use Ada.Task_Identification; 8285with Text_IO; use Text_IO; 8286procedure t3 is 8287 8288 type Astring is access String; 8289 8290 task type Task_Typ (Name : access String) is 8291 pragma Task_Name (Name.all); 8292 end Task_Typ; 8293 8294 task body Task_Typ is 8295 Nam : constant String := Image (Current_Task); 8296 begin 8297 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 8298 end Task_Typ; 8299 8300 type Ptr_Task is access Task_Typ; 8301 Task_Var : Ptr_Task; 8302 8303begin 8304 Task_Var := 8305 new Task_Typ (new String'("This is task 1")); 8306 Task_Var := 8307 new Task_Typ (new String'("This is task 2")); 8308end; 8309@end example 8310 8311@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas 8312@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f9} 8313@section Pragma Task_Storage 8314 8315 8316Syntax: 8317 8318@example 8319pragma Task_Storage ( 8320 [Task_Type =>] LOCAL_NAME, 8321 [Top_Guard =>] static_integer_EXPRESSION); 8322@end example 8323 8324This pragma specifies the length of the guard area for tasks. The guard 8325area is an additional storage area allocated to a task. A value of zero 8326means that either no guard area is created or a minimal guard area is 8327created, depending on the target. This pragma can appear anywhere a 8328@code{Storage_Size} attribute definition clause is allowed for a task 8329type. 8330 8331@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas 8332@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fb} 8333@section Pragma Test_Case 8334 8335 8336@geindex Test cases 8337 8338Syntax: 8339 8340@example 8341pragma Test_Case ( 8342 [Name =>] static_string_Expression 8343 ,[Mode =>] (Nominal | Robustness) 8344 [, Requires => Boolean_Expression] 8345 [, Ensures => Boolean_Expression]); 8346@end example 8347 8348The @code{Test_Case} pragma allows defining fine-grain specifications 8349for use by testing tools. 8350The compiler checks the validity of the @code{Test_Case} pragma, but its 8351presence does not lead to any modification of the code generated by the 8352compiler. 8353 8354@code{Test_Case} pragmas may only appear immediately following the 8355(separate) declaration of a subprogram in a package declaration, inside 8356a package spec unit. Only other pragmas may intervene (that is appear 8357between the subprogram declaration and a test case). 8358 8359The compiler checks that boolean expressions given in @code{Requires} and 8360@code{Ensures} are valid, where the rules for @code{Requires} are the 8361same as the rule for an expression in @code{Precondition} and the rules 8362for @code{Ensures} are the same as the rule for an expression in 8363@code{Postcondition}. In particular, attributes @code{'Old} and 8364@code{'Result} can only be used within the @code{Ensures} 8365expression. The following is an example of use within a package spec: 8366 8367@example 8368package Math_Functions is 8369 ... 8370 function Sqrt (Arg : Float) return Float; 8371 pragma Test_Case (Name => "Test 1", 8372 Mode => Nominal, 8373 Requires => Arg < 10000.0, 8374 Ensures => Sqrt'Result < 10.0); 8375 ... 8376end Math_Functions; 8377@end example 8378 8379The meaning of a test case is that there is at least one context where 8380@code{Requires} holds such that, if the associated subprogram is executed in 8381that context, then @code{Ensures} holds when the subprogram returns. 8382Mode @code{Nominal} indicates that the input context should also satisfy the 8383precondition of the subprogram, and the output context should also satisfy its 8384postcondition. Mode @code{Robustness} indicates that the precondition and 8385postcondition of the subprogram should be ignored for this test case. 8386 8387@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas 8388@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fc}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fd} 8389@section Pragma Thread_Local_Storage 8390 8391 8392@geindex Task specific storage 8393 8394@geindex TLS (Thread Local Storage) 8395 8396@geindex Task_Attributes 8397 8398Syntax: 8399 8400@example 8401pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 8402@end example 8403 8404This pragma specifies that the specified entity, which must be 8405a variable declared in a library-level package, is to be marked as 8406“Thread Local Storage” (@code{TLS}). On systems supporting this (which 8407include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each 8408thread (and hence each Ada task) to see a distinct copy of the variable. 8409 8410The variable must not have default initialization, and if there is 8411an explicit initialization, it must be either @code{null} for an 8412access variable, a static expression for a scalar variable, or a fully 8413static aggregate for a composite type, that is to say, an aggregate all 8414of whose components are static, and which does not include packed or 8415discriminated components. 8416 8417This provides a low-level mechanism similar to that provided by 8418the @code{Ada.Task_Attributes} package, but much more efficient 8419and is also useful in writing interface code that will interact 8420with foreign threads. 8421 8422If this pragma is used on a system where @code{TLS} is not supported, 8423then an error message will be generated and the program will be rejected. 8424 8425@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas 8426@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fe} 8427@section Pragma Time_Slice 8428 8429 8430Syntax: 8431 8432@example 8433pragma Time_Slice (static_duration_EXPRESSION); 8434@end example 8435 8436For implementations of GNAT on operating systems where it is possible 8437to supply a time slice value, this pragma may be used for this purpose. 8438It is ignored if it is used in a system that does not allow this control, 8439or if it appears in other than the main program unit. 8440 8441@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas 8442@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{ff} 8443@section Pragma Title 8444 8445 8446Syntax: 8447 8448@example 8449pragma Title (TITLING_OPTION [, TITLING OPTION]); 8450 8451TITLING_OPTION ::= 8452 [Title =>] STRING_LITERAL, 8453| [Subtitle =>] STRING_LITERAL 8454@end example 8455 8456Syntax checked but otherwise ignored by GNAT. This is a listing control 8457pragma used in DEC Ada 83 implementations to provide a title and/or 8458subtitle for the program listing. The program listing generated by GNAT 8459does not have titles or subtitles. 8460 8461Unlike other pragmas, the full flexibility of named notation is allowed 8462for this pragma, i.e., the parameters may be given in any order if named 8463notation is used, and named and positional notation can be mixed 8464following the normal rules for procedure calls in Ada. 8465 8466@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas 8467@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{100} 8468@section Pragma Type_Invariant 8469 8470 8471Syntax: 8472 8473@example 8474pragma Type_Invariant 8475 ([Entity =>] type_LOCAL_NAME, 8476 [Check =>] EXPRESSION); 8477@end example 8478 8479The @code{Type_Invariant} pragma is intended to be an exact 8480replacement for the language-defined @code{Type_Invariant} 8481aspect, and shares its restrictions and semantics. It differs 8482from the language defined @code{Invariant} pragma in that it 8483does not permit a string parameter, and it is 8484controlled by the assertion identifier @code{Type_Invariant} 8485rather than @code{Invariant}. 8486 8487@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas 8488@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{101}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{102} 8489@section Pragma Type_Invariant_Class 8490 8491 8492Syntax: 8493 8494@example 8495pragma Type_Invariant_Class 8496 ([Entity =>] type_LOCAL_NAME, 8497 [Check =>] EXPRESSION); 8498@end example 8499 8500The @code{Type_Invariant_Class} pragma is intended to be an exact 8501replacement for the language-defined @code{Type_Invariant'Class} 8502aspect, and shares its restrictions and semantics. 8503 8504Note: This pragma is called @code{Type_Invariant_Class} rather than 8505@code{Type_Invariant'Class} because the latter would not be strictly 8506conforming to the allowed syntax for pragmas. The motivation 8507for providing pragmas equivalent to the aspects is to allow a program 8508to be written using the pragmas, and then compiled if necessary 8509using an Ada compiler that does not recognize the pragmas or 8510aspects, but is prepared to ignore the pragmas. The assertion 8511policy that controls this pragma is @code{Type_Invariant'Class}, 8512not @code{Type_Invariant_Class}. 8513 8514@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas 8515@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{103} 8516@section Pragma Unchecked_Union 8517 8518 8519@geindex Unions in C 8520 8521Syntax: 8522 8523@example 8524pragma Unchecked_Union (first_subtype_LOCAL_NAME); 8525@end example 8526 8527This pragma is used to specify a representation of a record type that is 8528equivalent to a C union. It was introduced as a GNAT implementation defined 8529pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 8530pragma, making it language defined, and GNAT fully implements this extended 8531version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 8532details, consult the Ada 2012 Reference Manual, section B.3.3. 8533 8534@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas 8535@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{104} 8536@section Pragma Unevaluated_Use_Of_Old 8537 8538 8539@geindex Attribute Old 8540 8541@geindex Attribute Loop_Entry 8542 8543@geindex Unevaluated_Use_Of_Old 8544 8545Syntax: 8546 8547@example 8548pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); 8549@end example 8550 8551This pragma controls the processing of attributes Old and Loop_Entry. 8552If either of these attributes is used in a potentially unevaluated 8553expression (e.g. the then or else parts of an if expression), then 8554normally this usage is considered illegal if the prefix of the attribute 8555is other than an entity name. The language requires this 8556behavior for Old, and GNAT copies the same rule for Loop_Entry. 8557 8558The reason for this rule is that otherwise, we can have a situation 8559where we save the Old value, and this results in an exception, even 8560though we might not evaluate the attribute. Consider this example: 8561 8562@example 8563package UnevalOld is 8564 K : Character; 8565 procedure U (A : String; C : Boolean) -- ERROR 8566 with Post => (if C then A(1)'Old = K else True); 8567end; 8568@end example 8569 8570If procedure U is called with a string with a lower bound of 2, and 8571C false, then an exception would be raised trying to evaluate A(1) 8572on entry even though the value would not be actually used. 8573 8574Although the rule guarantees against this possibility, it is sometimes 8575too restrictive. For example if we know that the string has a lower 8576bound of 1, then we will never raise an exception. 8577The pragma @code{Unevaluated_Use_Of_Old} can be 8578used to modify this behavior. If the argument is @code{Error} then an 8579error is given (this is the default RM behavior). If the argument is 8580@code{Warn} then the usage is allowed as legal but with a warning 8581that an exception might be raised. If the argument is @code{Allow} 8582then the usage is allowed as legal without generating a warning. 8583 8584This pragma may appear as a configuration pragma, or in a declarative 8585part or package specification. In the latter case it applies to 8586uses up to the end of the corresponding statement sequence or 8587sequence of package declarations. 8588 8589@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas 8590@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{105} 8591@section Pragma Unimplemented_Unit 8592 8593 8594Syntax: 8595 8596@example 8597pragma Unimplemented_Unit; 8598@end example 8599 8600If this pragma occurs in a unit that is processed by the compiler, GNAT 8601aborts with the message @code{xxx not implemented}, where 8602@code{xxx} is the name of the current compilation unit. This pragma is 8603intended to allow the compiler to handle unimplemented library units in 8604a clean manner. 8605 8606The abort only happens if code is being generated. Thus you can use 8607specs of unimplemented packages in syntax or semantic checking mode. 8608 8609@node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas 8610@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{106}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{107} 8611@section Pragma Universal_Aliasing 8612 8613 8614Syntax: 8615 8616@example 8617pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 8618@end example 8619 8620@code{type_LOCAL_NAME} must refer to a type declaration in the current 8621declarative part. The effect is to inhibit strict type-based aliasing 8622optimization for the given type. In other words, the effect is as though 8623access types designating this type were subject to pragma No_Strict_Aliasing. 8624For a detailed description of the strict aliasing optimization, and the 8625situations in which it must be suppressed, see the section on 8626@code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}. 8627 8628@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas 8629@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{109} 8630@section Pragma Unmodified 8631 8632 8633@geindex Warnings 8634@geindex unmodified 8635 8636Syntax: 8637 8638@example 8639pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 8640@end example 8641 8642This pragma signals that the assignable entities (variables, 8643@code{out} parameters, @code{in out} parameters) whose names are listed are 8644deliberately not assigned in the current source unit. This 8645suppresses warnings about the 8646entities being referenced but not assigned, and in addition a warning will be 8647generated if one of these entities is in fact assigned in the 8648same unit as the pragma (or in the corresponding body, or one 8649of its subunits). 8650 8651This is particularly useful for clearly signaling that a particular 8652parameter is not modified, even though the spec suggests that it might 8653be. 8654 8655For the variable case, warnings are never given for unreferenced variables 8656whose name contains one of the substrings 8657@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8658are typically to be used in cases where such warnings are expected. 8659Thus it is never necessary to use @code{pragma Unmodified} for such 8660variables, though it is harmless to do so. 8661 8662@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas 8663@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10b} 8664@section Pragma Unreferenced 8665 8666 8667@geindex Warnings 8668@geindex unreferenced 8669 8670Syntax: 8671 8672@example 8673pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 8674pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 8675@end example 8676 8677This pragma signals that the entities whose names are listed are 8678deliberately not referenced in the current source unit after the 8679occurrence of the pragma. This 8680suppresses warnings about the 8681entities being unreferenced, and in addition a warning will be 8682generated if one of these entities is in fact subsequently referenced in the 8683same unit as the pragma (or in the corresponding body, or one 8684of its subunits). 8685 8686This is particularly useful for clearly signaling that a particular 8687parameter is not referenced in some particular subprogram implementation 8688and that this is deliberate. It can also be useful in the case of 8689objects declared only for their initialization or finalization side 8690effects. 8691 8692If @code{LOCAL_NAME} identifies more than one matching homonym in the 8693current scope, then the entity most recently declared is the one to which 8694the pragma applies. Note that in the case of accept formals, the pragma 8695Unreferenced may appear immediately after the keyword @code{do} which 8696allows the indication of whether or not accept formals are referenced 8697or not to be given individually for each accept statement. 8698 8699The left hand side of an assignment does not count as a reference for the 8700purpose of this pragma. Thus it is fine to assign to an entity for which 8701pragma Unreferenced is given. 8702 8703Note that if a warning is desired for all calls to a given subprogram, 8704regardless of whether they occur in the same unit as the subprogram 8705declaration, then this pragma should not be used (calls from another 8706unit would not be flagged); pragma Obsolescent can be used instead 8707for this purpose, see @ref{ad,,Pragma Obsolescent}. 8708 8709The second form of pragma @code{Unreferenced} is used within a context 8710clause. In this case the arguments must be unit names of units previously 8711mentioned in @code{with} clauses (similar to the usage of pragma 8712@code{Elaborate_All}. The effect is to suppress warnings about unreferenced 8713units and unreferenced entities within these units. 8714 8715For the variable case, warnings are never given for unreferenced variables 8716whose name contains one of the substrings 8717@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8718are typically to be used in cases where such warnings are expected. 8719Thus it is never necessary to use @code{pragma Unreferenced} for such 8720variables, though it is harmless to do so. 8721 8722@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas 8723@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10d} 8724@section Pragma Unreferenced_Objects 8725 8726 8727@geindex Warnings 8728@geindex unreferenced 8729 8730Syntax: 8731 8732@example 8733pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 8734@end example 8735 8736This pragma signals that for the types or subtypes whose names are 8737listed, objects which are declared with one of these types or subtypes may 8738not be referenced, and if no references appear, no warnings are given. 8739 8740This is particularly useful for objects which are declared solely for their 8741initialization and finalization effect. Such variables are sometimes referred 8742to as RAII variables (Resource Acquisition Is Initialization). Using this 8743pragma on the relevant type (most typically a limited controlled type), the 8744compiler will automatically suppress unwanted warnings about these variables 8745not being referenced. 8746 8747@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas 8748@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10e} 8749@section Pragma Unreserve_All_Interrupts 8750 8751 8752Syntax: 8753 8754@example 8755pragma Unreserve_All_Interrupts; 8756@end example 8757 8758Normally certain interrupts are reserved to the implementation. Any attempt 8759to attach an interrupt causes Program_Error to be raised, as described in 8760RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 8761many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is 8762reserved to the implementation, so that @code{Ctrl-C} can be used to 8763interrupt execution. 8764 8765If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 8766a program, then all such interrupts are unreserved. This allows the 8767program to handle these interrupts, but disables their standard 8768functions. For example, if this pragma is used, then pressing 8769@code{Ctrl-C} will not automatically interrupt execution. However, 8770a program can then handle the @code{SIGINT} interrupt as it chooses. 8771 8772For a full list of the interrupts handled in a specific implementation, 8773see the source code for the spec of @code{Ada.Interrupts.Names} in 8774file @code{a-intnam.ads}. This is a target dependent file that contains the 8775list of interrupts recognized for a given target. The documentation in 8776this file also specifies what interrupts are affected by the use of 8777the @code{Unreserve_All_Interrupts} pragma. 8778 8779For a more general facility for controlling what interrupts can be 8780handled, see pragma @code{Interrupt_State}, which subsumes the functionality 8781of the @code{Unreserve_All_Interrupts} pragma. 8782 8783@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas 8784@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10f} 8785@section Pragma Unsuppress 8786 8787 8788Syntax: 8789 8790@example 8791pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 8792@end example 8793 8794This pragma undoes the effect of a previous pragma @code{Suppress}. If 8795there is no corresponding pragma @code{Suppress} in effect, it has no 8796effect. The range of the effect is the same as for pragma 8797@code{Suppress}. The meaning of the arguments is identical to that used 8798in pragma @code{Suppress}. 8799 8800One important application is to ensure that checks are on in cases where 8801code depends on the checks for its correct functioning, so that the code 8802will compile correctly even if the compiler switches are set to suppress 8803checks. For example, in a program that depends on external names of tagged 8804types and wants to ensure that the duplicated tag check occurs even if all 8805run-time checks are suppressed by a compiler switch, the following 8806configuration pragma will ensure this test is not suppressed: 8807 8808@example 8809pragma Unsuppress (Duplicated_Tag_Check); 8810@end example 8811 8812This pragma is standard in Ada 2005. It is available in all earlier versions 8813of Ada as an implementation-defined pragma. 8814 8815Note that in addition to the checks defined in the Ada RM, GNAT recogizes a 8816number of implementation-defined check names. See the description of pragma 8817@code{Suppress} for full details. 8818 8819@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas 8820@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{110} 8821@section Pragma Use_VADS_Size 8822 8823 8824@geindex Size 8825@geindex VADS compatibility 8826 8827@geindex Rational profile 8828 8829Syntax: 8830 8831@example 8832pragma Use_VADS_Size; 8833@end example 8834 8835This is a configuration pragma. In a unit to which it applies, any use 8836of the ‘Size attribute is automatically interpreted as a use of the 8837‘VADS_Size attribute. Note that this may result in incorrect semantic 8838processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 8839the handling of existing code which depends on the interpretation of Size 8840as implemented in the VADS compiler. See description of the VADS_Size 8841attribute for further details. 8842 8843@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas 8844@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{111}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{112} 8845@section Pragma Unused 8846 8847 8848@geindex Warnings 8849@geindex unused 8850 8851Syntax: 8852 8853@example 8854pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); 8855@end example 8856 8857This pragma signals that the assignable entities (variables, 8858@code{out} parameters, and @code{in out} parameters) whose names are listed 8859deliberately do not get assigned or referenced in the current source unit 8860after the occurrence of the pragma in the current source unit. This 8861suppresses warnings about the entities that are unreferenced and/or not 8862assigned, and, in addition, a warning will be generated if one of these 8863entities gets assigned or subsequently referenced in the same unit as the 8864pragma (in the corresponding body or one of its subunits). 8865 8866This is particularly useful for clearly signaling that a particular 8867parameter is not modified or referenced, even though the spec suggests 8868that it might be. 8869 8870For the variable case, warnings are never given for unreferenced 8871variables whose name contains one of the substrings 8872@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8873are typically to be used in cases where such warnings are expected. 8874Thus it is never necessary to use @code{pragma Unmodified} for such 8875variables, though it is harmless to do so. 8876 8877@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas 8878@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{113} 8879@section Pragma Validity_Checks 8880 8881 8882Syntax: 8883 8884@example 8885pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 8886@end example 8887 8888This pragma is used in conjunction with compiler switches to control the 8889built-in validity checking provided by GNAT. The compiler switches, if set 8890provide an initial setting for the switches, and this pragma may be used 8891to modify these settings, or the settings may be provided entirely by 8892the use of the pragma. This pragma can be used anywhere that a pragma 8893is legal, including use as a configuration pragma (including use in 8894the @code{gnat.adc} file). 8895 8896The form with a string literal specifies which validity options are to be 8897activated. The validity checks are first set to include only the default 8898reference manual settings, and then a string of letters in the string 8899specifies the exact set of options required. The form of this string 8900is exactly as described for the @emph{-gnatVx} compiler switch (see the 8901GNAT User’s Guide for details). For example the following two 8902methods can be used to enable validity checking for mode @code{in} and 8903@code{in out} subprogram parameters: 8904 8905 8906@itemize * 8907 8908@item 8909@example 8910pragma Validity_Checks ("im"); 8911@end example 8912 8913@item 8914@example 8915$ gcc -c -gnatVim ... 8916@end example 8917@end itemize 8918 8919The form ALL_CHECKS activates all standard checks (its use is equivalent 8920to the use of the @code{gnatVa} switch). 8921 8922The forms with @code{Off} and @code{On} can be used to temporarily disable 8923validity checks as shown in the following example: 8924 8925@example 8926pragma Validity_Checks ("c"); -- validity checks for copies 8927pragma Validity_Checks (Off); -- turn off validity checks 8928A := B; -- B will not be validity checked 8929pragma Validity_Checks (On); -- turn validity checks back on 8930A := C; -- C will be validity checked 8931@end example 8932 8933@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas 8934@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{114}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{115} 8935@section Pragma Volatile 8936 8937 8938Syntax: 8939 8940@example 8941pragma Volatile (LOCAL_NAME); 8942@end example 8943 8944This pragma is defined by the Ada Reference Manual, and the GNAT 8945implementation is fully conformant with this definition. The reason it 8946is mentioned in this section is that a pragma of the same name was supplied 8947in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 8948implementation of pragma Volatile is upwards compatible with the 8949implementation in DEC Ada 83. 8950 8951@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas 8952@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{116}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{117} 8953@section Pragma Volatile_Full_Access 8954 8955 8956Syntax: 8957 8958@example 8959pragma Volatile_Full_Access (LOCAL_NAME); 8960@end example 8961 8962This is similar in effect to pragma Volatile, except that any reference to the 8963object is guaranteed to be done only with instructions that read or write all 8964the bits of the object. Furthermore, if the object is of a composite type, 8965then any reference to a subcomponent of the object is guaranteed to read 8966and/or write all the bits of the object. 8967 8968The intention is that this be suitable for use with memory-mapped I/O devices 8969on some machines. Note that there are two important respects in which this is 8970different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} 8971object is not a sequential action in the RM 9.10 sense and, therefore, does 8972not create a synchronization point. Second, in the case of @code{pragma Atomic}, 8973there is no guarantee that all the bits will be accessed if the reference 8974is not to the whole object; the compiler is allowed (and generally will) 8975access only part of the object in this case. 8976 8977@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas 8978@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{118}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{119} 8979@section Pragma Volatile_Function 8980 8981 8982Syntax: 8983 8984@example 8985pragma Volatile_Function [ (boolean_EXPRESSION) ]; 8986@end example 8987 8988For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} 8989in the SPARK 2014 Reference Manual, section 7.1.2. 8990 8991@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas 8992@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11a} 8993@section Pragma Warning_As_Error 8994 8995 8996Syntax: 8997 8998@example 8999pragma Warning_As_Error (static_string_EXPRESSION); 9000@end example 9001 9002This configuration pragma allows the programmer to specify a set 9003of warnings that will be treated as errors. Any warning that 9004matches the pattern given by the pragma argument will be treated 9005as an error. This gives more precise control than -gnatwe, 9006which treats warnings as errors. 9007 9008This pragma can apply to regular warnings (messages enabled by -gnatw) 9009and to style warnings (messages that start with “(style)”, 9010enabled by -gnaty). 9011 9012The pattern may contain asterisks, which match zero or more characters 9013in the message. For example, you can use @code{pragma Warning_As_Error 9014("bits of*unused")} to treat the warning message @code{warning: 960 bits of 9015"a" unused} as an error. All characters other than asterisk are treated 9016as literal characters in the match. The match is case insensitive; for 9017example XYZ matches xyz. 9018 9019Note that the pattern matches if it occurs anywhere within the warning 9020message string (it is not necessary to put an asterisk at the start and 9021the end of the message, since this is implied). 9022 9023Another possibility for the static_string_EXPRESSION which works whether 9024or not error tags are enabled (@emph{-gnatw.d}) is to use a single 9025@emph{-gnatw} tag string, enclosed in brackets, 9026as shown in the example below, to treat one category of warnings as errors. 9027Note that if you want to treat multiple categories of warnings as errors, 9028you can use multiple pragma Warning_As_Error. 9029 9030The above use of patterns to match the message applies only to warning 9031messages generated by the front end. This pragma can also be applied to 9032warnings provided by the back end and mentioned in @ref{11b,,Pragma Warnings}. 9033By using a single full @emph{-Wxxx} switch in the pragma, such warnings 9034can also be treated as errors. 9035 9036The pragma can appear either in a global configuration pragma file 9037(e.g. @code{gnat.adc}), or at the start of a file. Given a global 9038configuration pragma file containing: 9039 9040@example 9041pragma Warning_As_Error ("[-gnatwj]"); 9042@end example 9043 9044which will treat all obsolescent feature warnings as errors, the 9045following program compiles as shown (compile options here are 9046@emph{-gnatwa.d -gnatl -gnatj55}). 9047 9048@example 9049 1. pragma Warning_As_Error ("*never assigned*"); 9050 2. function Warnerr return String is 9051 3. X : Integer; 9052 | 9053 >>> error: variable "X" is never read and 9054 never assigned [-gnatwv] [warning-as-error] 9055 9056 4. Y : Integer; 9057 | 9058 >>> warning: variable "Y" is assigned but 9059 never read [-gnatwu] 9060 9061 5. begin 9062 6. Y := 0; 9063 7. return %ABC%; 9064 | 9065 >>> error: use of "%" is an obsolescent 9066 feature (RM J.2(4)), use """ instead 9067 [-gnatwj] [warning-as-error] 9068 9069 8. end; 9070 90718 lines: No errors, 3 warnings (2 treated as errors) 9072@end example 9073 9074Note that this pragma does not affect the set of warnings issued in 9075any way, it merely changes the effect of a matching warning if one 9076is produced as a result of other warnings options. As shown in this 9077example, if the pragma results in a warning being treated as an error, 9078the tag is changed from “warning:” to “error:” and the string 9079“[warning-as-error]” is appended to the end of the message. 9080 9081@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas 9082@anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11c}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11b} 9083@section Pragma Warnings 9084 9085 9086Syntax: 9087 9088@example 9089pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); 9090 9091DETAILS ::= On | Off 9092DETAILS ::= On | Off, local_NAME 9093DETAILS ::= static_string_EXPRESSION 9094DETAILS ::= On | Off, static_string_EXPRESSION 9095 9096TOOL_NAME ::= GNAT | GNATprove 9097 9098REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} 9099@end example 9100 9101Note: in Ada 83 mode, a string literal may be used in place of a static string 9102expression (which does not exist in Ada 83). 9103 9104Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the 9105second form is always understood. If the intention is to use 9106the fourth form, then you can write @code{NAME & ""} to force the 9107intepretation as a @emph{static_string_EXPRESSION}. 9108 9109Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted 9110that way. The use of the @code{TOOL_NAME} argument is relevant only to users 9111of SPARK and GNATprove, see last part of this section for details. 9112 9113Normally warnings are enabled, with the output being controlled by 9114the command line switch. Warnings (@code{Off}) turns off generation of 9115warnings until a Warnings (@code{On}) is encountered or the end of the 9116current unit. If generation of warnings is turned off using this 9117pragma, then some or all of the warning messages are suppressed, 9118regardless of the setting of the command line switches. 9119 9120The @code{Reason} parameter may optionally appear as the last argument 9121in any of the forms of this pragma. It is intended purely for the 9122purposes of documenting the reason for the @code{Warnings} pragma. 9123The compiler will check that the argument is a static string but 9124otherwise ignore this argument. Other tools may provide specialized 9125processing for this string. 9126 9127The form with a single argument (or two arguments if Reason present), 9128where the first argument is @code{ON} or @code{OFF} 9129may be used as a configuration pragma. 9130 9131If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for 9132the specified entity. This suppression is effective from the point where 9133it occurs till the end of the extended scope of the variable (similar to 9134the scope of @code{Suppress}). This form cannot be used as a configuration 9135pragma. 9136 9137In the case where the first argument is other than @code{ON} or 9138@code{OFF}, 9139the third form with a single static_string_EXPRESSION argument (and possible 9140reason) provides more precise 9141control over which warnings are active. The string is a list of letters 9142specifying which warnings are to be activated and which deactivated. The 9143code for these letters is the same as the string used in the command 9144line switch controlling warnings. For a brief summary, use the gnatmake 9145command with no arguments, which will generate usage information containing 9146the list of warnings switches supported. For 9147full details see the section on @code{Warning Message Control} in the 9148@cite{GNAT User’s Guide}. 9149This form can also be used as a configuration pragma. 9150 9151The warnings controlled by the @code{-gnatw} switch are generated by the 9152front end of the compiler. The GCC back end can provide additional warnings 9153and they are controlled by the @code{-W} switch. Such warnings can be 9154identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the 9155message which designates the @code{-W@emph{xxx}} switch that controls the message. 9156The form with a single @emph{static_string_EXPRESSION} argument also works for these 9157warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this 9158case. The above reference lists a few examples of these additional warnings. 9159 9160The specified warnings will be in effect until the end of the program 9161or another pragma @code{Warnings} is encountered. The effect of the pragma is 9162cumulative. Initially the set of warnings is the standard default set 9163as possibly modified by compiler switches. Then each pragma Warning 9164modifies this set of warnings as specified. This form of the pragma may 9165also be used as a configuration pragma. 9166 9167The fourth form, with an @code{On|Off} parameter and a string, is used to 9168control individual messages, based on their text. The string argument 9169is a pattern that is used to match against the text of individual 9170warning messages (not including the initial “warning: ” tag). 9171 9172The pattern may contain asterisks, which match zero or more characters in 9173the message. For example, you can use 9174@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning 9175message @code{warning: 960 bits of "a" unused}. No other regular 9176expression notations are permitted. All characters other than asterisk in 9177these three specific cases are treated as literal characters in the match. 9178The match is case insensitive, for example XYZ matches xyz. 9179 9180Note that the pattern matches if it occurs anywhere within the warning 9181message string (it is not necessary to put an asterisk at the start and 9182the end of the message, since this is implied). 9183 9184The above use of patterns to match the message applies only to warning 9185messages generated by the front end. This form of the pragma with a string 9186argument can also be used to control warnings provided by the back end and 9187mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma, 9188such warnings can be turned on and off. 9189 9190There are two ways to use the pragma in this form. The OFF form can be used 9191as a configuration pragma. The effect is to suppress all warnings (if any) 9192that match the pattern string throughout the compilation (or match the 9193-W switch in the back end case). 9194 9195The second usage is to suppress a warning locally, and in this case, two 9196pragmas must appear in sequence: 9197 9198@example 9199pragma Warnings (Off, Pattern); 9200... code where given warning is to be suppressed 9201pragma Warnings (On, Pattern); 9202@end example 9203 9204In this usage, the pattern string must match in the Off and On 9205pragmas, and (if @emph{-gnatw.w} is given) at least one matching 9206warning must be suppressed. 9207 9208Note: if the ON form is not found, then the effect of the OFF form extends 9209until the end of the file (pragma Warnings is purely textual, so its effect 9210does not stop at the end of the enclosing scope). 9211 9212Note: to write a string that will match any warning, use the string 9213@code{"***"}. It will not work to use a single asterisk or two 9214asterisks since this looks like an operator name. This form with three 9215asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching 9216@code{pragma Warnings (On, "***")} will be required. This can be 9217helpful in avoiding forgetting to turn warnings back on. 9218 9219Note: the debug flag @code{-gnatd.i} can be 9220used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 9221be useful in checking whether obsolete pragmas in existing programs are hiding 9222real problems. 9223 9224Note: pragma Warnings does not affect the processing of style messages. See 9225separate entry for pragma Style_Checks for control of style messages. 9226 9227Users of the formal verification tool GNATprove for the SPARK subset of Ada may 9228use the version of the pragma with a @code{TOOL_NAME} parameter. 9229 9230If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the 9231compiler or @code{GNATprove} for the formal verification tool. A given tool only 9232takes into account pragma Warnings that do not specify a tool name, or that 9233specify the matching tool name. This makes it possible to disable warnings 9234selectively for each tool, and as a consequence to detect useless pragma 9235Warnings with switch @code{-gnatw.w}. 9236 9237@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas 9238@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11d} 9239@section Pragma Weak_External 9240 9241 9242Syntax: 9243 9244@example 9245pragma Weak_External ([Entity =>] LOCAL_NAME); 9246@end example 9247 9248@code{LOCAL_NAME} must refer to an object that is declared at the library 9249level. This pragma specifies that the given entity should be marked as a 9250weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} 9251in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead 9252of a regular symbol, that is to say a symbol that does not have to be 9253resolved by the linker if used in conjunction with a pragma Import. 9254 9255When a weak symbol is not resolved by the linker, its address is set to 9256zero. This is useful in writing interfaces to external modules that may 9257or may not be linked in the final executable, for example depending on 9258configuration settings. 9259 9260If a program references at run time an entity to which this pragma has been 9261applied, and the corresponding symbol was not resolved at link time, then 9262the execution of the program is erroneous. It is not erroneous to take the 9263Address of such an entity, for example to guard potential references, 9264as shown in the example below. 9265 9266Some file formats do not support weak symbols so not all target machines 9267support this pragma. 9268 9269@example 9270-- Example of the use of pragma Weak_External 9271 9272package External_Module is 9273 key : Integer; 9274 pragma Import (C, key); 9275 pragma Weak_External (key); 9276 function Present return boolean; 9277end External_Module; 9278 9279with System; use System; 9280package body External_Module is 9281 function Present return boolean is 9282 begin 9283 return key'Address /= System.Null_Address; 9284 end Present; 9285end External_Module; 9286@end example 9287 9288@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas 9289@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11e} 9290@section Pragma Wide_Character_Encoding 9291 9292 9293Syntax: 9294 9295@example 9296pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 9297@end example 9298 9299This pragma specifies the wide character encoding to be used in program 9300source text appearing subsequently. It is a configuration pragma, but may 9301also be used at any point that a pragma is allowed, and it is permissible 9302to have more than one such pragma in a file, allowing multiple encodings 9303to appear within the same file. 9304 9305However, note that the pragma cannot immediately precede the relevant 9306wide character, because then the previous encoding will still be in 9307effect, causing “illegal character” errors. 9308 9309The argument can be an identifier or a character literal. In the identifier 9310case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, 9311@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal 9312case it is correspondingly one of the characters @code{h}, @code{u}, 9313@code{s}, @code{e}, @code{8}, or @code{b}. 9314 9315Note that when the pragma is used within a file, it affects only the 9316encoding within that file, and does not affect withed units, specs, 9317or subunits. 9318 9319@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top 9320@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} 9321@chapter Implementation Defined Aspects 9322 9323 9324Ada defines (throughout the Ada 2012 reference manual, summarized 9325in Annex K) a set of aspects that can be specified for certain entities. 9326These language defined aspects are implemented in GNAT in Ada 2012 mode 9327and work as described in the Ada 2012 Reference Manual. 9328 9329In addition, Ada 2012 allows implementations to define additional aspects 9330whose meaning is defined by the implementation. GNAT provides 9331a number of these implementation-defined aspects which can be used 9332to extend and enhance the functionality of the compiler. This section of 9333the GNAT reference manual describes these additional aspects. 9334 9335Note that any program using these aspects may not be portable to 9336other compilers (although GNAT implements this set of aspects on all 9337platforms). Therefore if portability to other compilers is an important 9338consideration, you should minimize the use of these aspects. 9339 9340Note that for many of these aspects, the effect is essentially similar 9341to the use of a pragma or attribute specification with the same name 9342applied to the entity. For example, if we write: 9343 9344@example 9345type R is range 1 .. 100 9346 with Value_Size => 10; 9347@end example 9348 9349then the effect is the same as: 9350 9351@example 9352type R is range 1 .. 100; 9353for R'Value_Size use 10; 9354@end example 9355 9356and if we write: 9357 9358@example 9359type R is new Integer 9360 with Shared => True; 9361@end example 9362 9363then the effect is the same as: 9364 9365@example 9366type R is new Integer; 9367pragma Shared (R); 9368@end example 9369 9370In the documentation below, such cases are simply marked 9371as being boolean aspects equivalent to the corresponding pragma 9372or attribute definition clause. 9373 9374@menu 9375* Aspect Abstract_State:: 9376* Aspect Annotate:: 9377* Aspect Async_Readers:: 9378* Aspect Async_Writers:: 9379* Aspect Constant_After_Elaboration:: 9380* Aspect Contract_Cases:: 9381* Aspect Depends:: 9382* Aspect Default_Initial_Condition:: 9383* Aspect Dimension:: 9384* Aspect Dimension_System:: 9385* Aspect Disable_Controlled:: 9386* Aspect Effective_Reads:: 9387* Aspect Effective_Writes:: 9388* Aspect Extensions_Visible:: 9389* Aspect Favor_Top_Level:: 9390* Aspect Ghost:: 9391* Aspect Global:: 9392* Aspect Initial_Condition:: 9393* Aspect Initializes:: 9394* Aspect Inline_Always:: 9395* Aspect Invariant:: 9396* Aspect Invariant’Class:: 9397* Aspect Iterable:: 9398* Aspect Linker_Section:: 9399* Aspect Lock_Free:: 9400* Aspect Max_Queue_Length:: 9401* Aspect No_Caching:: 9402* Aspect No_Elaboration_Code_All:: 9403* Aspect No_Inline:: 9404* Aspect No_Tagged_Streams:: 9405* Aspect No_Task_Parts:: 9406* Aspect Object_Size:: 9407* Aspect Obsolescent:: 9408* Aspect Part_Of:: 9409* Aspect Persistent_BSS:: 9410* Aspect Predicate:: 9411* Aspect Pure_Function:: 9412* Aspect Refined_Depends:: 9413* Aspect Refined_Global:: 9414* Aspect Refined_Post:: 9415* Aspect Refined_State:: 9416* Aspect Relaxed_Initialization:: 9417* Aspect Remote_Access_Type:: 9418* Aspect Secondary_Stack_Size:: 9419* Aspect Scalar_Storage_Order:: 9420* Aspect Shared:: 9421* Aspect Simple_Storage_Pool:: 9422* Aspect Simple_Storage_Pool_Type:: 9423* Aspect SPARK_Mode:: 9424* Aspect Suppress_Debug_Info:: 9425* Aspect Suppress_Initialization:: 9426* Aspect Test_Case:: 9427* Aspect Thread_Local_Storage:: 9428* Aspect Universal_Aliasing:: 9429* Aspect Unmodified:: 9430* Aspect Unreferenced:: 9431* Aspect Unreferenced_Objects:: 9432* Aspect Value_Size:: 9433* Aspect Volatile_Full_Access:: 9434* Aspect Volatile_Function:: 9435* Aspect Warnings:: 9436 9437@end menu 9438 9439@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects 9440@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{122} 9441@section Aspect Abstract_State 9442 9443 9444@geindex Abstract_State 9445 9446This aspect is equivalent to @ref{1e,,pragma Abstract_State}. 9447 9448@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects 9449@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{123} 9450@section Aspect Annotate 9451 9452 9453@geindex Annotate 9454 9455There are three forms of this aspect (where ID is an identifier, 9456and ARG is a general expression), 9457corresponding to @ref{28,,pragma Annotate}. 9458 9459 9460@table @asis 9461 9462@item @emph{Annotate => ID} 9463 9464Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9465 9466@item @emph{Annotate => (ID)} 9467 9468Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9469 9470@item @emph{Annotate => (ID ,ID @{, ARG@})} 9471 9472Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} 9473@end table 9474 9475@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects 9476@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{124} 9477@section Aspect Async_Readers 9478 9479 9480@geindex Async_Readers 9481 9482This boolean aspect is equivalent to @ref{2f,,pragma Async_Readers}. 9483 9484@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects 9485@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{125} 9486@section Aspect Async_Writers 9487 9488 9489@geindex Async_Writers 9490 9491This boolean aspect is equivalent to @ref{31,,pragma Async_Writers}. 9492 9493@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects 9494@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{126} 9495@section Aspect Constant_After_Elaboration 9496 9497 9498@geindex Constant_After_Elaboration 9499 9500This aspect is equivalent to @ref{43,,pragma Constant_After_Elaboration}. 9501 9502@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects 9503@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{127} 9504@section Aspect Contract_Cases 9505 9506 9507@geindex Contract_Cases 9508 9509This aspect is equivalent to @ref{45,,pragma Contract_Cases}, the sequence 9510of clauses being enclosed in parentheses so that syntactically it is an 9511aggregate. 9512 9513@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects 9514@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{128} 9515@section Aspect Depends 9516 9517 9518@geindex Depends 9519 9520This aspect is equivalent to @ref{55,,pragma Depends}. 9521 9522@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects 9523@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{129} 9524@section Aspect Default_Initial_Condition 9525 9526 9527@geindex Default_Initial_Condition 9528 9529This aspect is equivalent to @ref{4f,,pragma Default_Initial_Condition}. 9530 9531@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects 9532@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12a} 9533@section Aspect Dimension 9534 9535 9536@geindex Dimension 9537 9538The @code{Dimension} aspect is used to specify the dimensions of a given 9539subtype of a dimensioned numeric type. The aspect also specifies a symbol 9540used when doing formatted output of dimensioned quantities. The syntax is: 9541 9542@example 9543with Dimension => 9544 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) 9545 9546SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL 9547 9548DIMENSION_VALUE ::= 9549 RATIONAL 9550| others => RATIONAL 9551| DISCRETE_CHOICE_LIST => RATIONAL 9552 9553RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] 9554@end example 9555 9556This aspect can only be applied to a subtype whose parent type has 9557a @code{Dimension_System} aspect. The aspect must specify values for 9558all dimensions of the system. The rational values are the powers of the 9559corresponding dimensions that are used by the compiler to verify that 9560physical (numeric) computations are dimensionally consistent. For example, 9561the computation of a force must result in dimensions (L => 1, M => 1, T => -2). 9562For further examples of the usage 9563of this aspect, see package @code{System.Dim.Mks}. 9564Note that when the dimensioned type is an integer type, then any 9565dimension value must be an integer literal. 9566 9567@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects 9568@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12b} 9569@section Aspect Dimension_System 9570 9571 9572@geindex Dimension_System 9573 9574The @code{Dimension_System} aspect is used to define a system of 9575dimensions that will be used in subsequent subtype declarations with 9576@code{Dimension} aspects that reference this system. The syntax is: 9577 9578@example 9579with Dimension_System => (DIMENSION @{, DIMENSION@}); 9580 9581DIMENSION ::= ([Unit_Name =>] IDENTIFIER, 9582 [Unit_Symbol =>] SYMBOL, 9583 [Dim_Symbol =>] SYMBOL) 9584 9585SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL 9586@end example 9587 9588This aspect is applied to a type, which must be a numeric derived type 9589(typically a floating-point type), that 9590will represent values within the dimension system. Each @code{DIMENSION} 9591corresponds to one particular dimension. A maximum of 7 dimensions may 9592be specified. @code{Unit_Name} is the name of the dimension (for example 9593@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities 9594of this dimension (for example @code{m} for @code{Meter}). 9595@code{Dim_Symbol} gives 9596the identification within the dimension system (typically this is a 9597single letter, e.g. @code{L} standing for length for unit name @code{Meter}). 9598The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. 9599The @code{Dim_Symbol} is used in error messages when numeric operations have 9600inconsistent dimensions. 9601 9602GNAT provides the standard definition of the International MKS system in 9603the run-time package @code{System.Dim.Mks}. You can easily define 9604similar packages for cgs units or British units, and define conversion factors 9605between values in different systems. The MKS system is characterized by the 9606following aspect: 9607 9608@example 9609type Mks_Type is new Long_Long_Float with 9610 Dimension_System => ( 9611 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 9612 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 9613 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 9614 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 9615 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), 9616 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 9617 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 9618@end example 9619 9620Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to 9621represent a theta character (avoiding the use of extended Latin-1 9622characters in this context). 9623 9624See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users 9625Guide for detailed examples of use of the dimension system. 9626 9627@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects 9628@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12c} 9629@section Aspect Disable_Controlled 9630 9631 9632@geindex Disable_Controlled 9633 9634The aspect @code{Disable_Controlled} is defined for controlled record types. If 9635active, this aspect causes suppression of all related calls to @code{Initialize}, 9636@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, 9637where for example you might want a record to be controlled or not depending on 9638whether some run-time check is enabled or suppressed. 9639 9640@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects 9641@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12d} 9642@section Aspect Effective_Reads 9643 9644 9645@geindex Effective_Reads 9646 9647This aspect is equivalent to @ref{5a,,pragma Effective_Reads}. 9648 9649@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects 9650@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12e} 9651@section Aspect Effective_Writes 9652 9653 9654@geindex Effective_Writes 9655 9656This aspect is equivalent to @ref{5c,,pragma Effective_Writes}. 9657 9658@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects 9659@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12f} 9660@section Aspect Extensions_Visible 9661 9662 9663@geindex Extensions_Visible 9664 9665This aspect is equivalent to @ref{67,,pragma Extensions_Visible}. 9666 9667@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects 9668@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{130} 9669@section Aspect Favor_Top_Level 9670 9671 9672@geindex Favor_Top_Level 9673 9674This boolean aspect is equivalent to @ref{6c,,pragma Favor_Top_Level}. 9675 9676@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects 9677@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{131} 9678@section Aspect Ghost 9679 9680 9681@geindex Ghost 9682 9683This aspect is equivalent to @ref{70,,pragma Ghost}. 9684 9685@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects 9686@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{132} 9687@section Aspect Global 9688 9689 9690@geindex Global 9691 9692This aspect is equivalent to @ref{72,,pragma Global}. 9693 9694@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects 9695@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{133} 9696@section Aspect Initial_Condition 9697 9698 9699@geindex Initial_Condition 9700 9701This aspect is equivalent to @ref{7f,,pragma Initial_Condition}. 9702 9703@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects 9704@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{134} 9705@section Aspect Initializes 9706 9707 9708@geindex Initializes 9709 9710This aspect is equivalent to @ref{82,,pragma Initializes}. 9711 9712@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects 9713@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{135} 9714@section Aspect Inline_Always 9715 9716 9717@geindex Inline_Always 9718 9719This boolean aspect is equivalent to @ref{84,,pragma Inline_Always}. 9720 9721@node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects 9722@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{136} 9723@section Aspect Invariant 9724 9725 9726@geindex Invariant 9727 9728This aspect is equivalent to @ref{8b,,pragma Invariant}. It is a 9729synonym for the language defined aspect @code{Type_Invariant} except 9730that it is separately controllable using pragma @code{Assertion_Policy}. 9731 9732@node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects 9733@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{137} 9734@section Aspect Invariant’Class 9735 9736 9737@geindex Invariant'Class 9738 9739This aspect is equivalent to @ref{102,,pragma Type_Invariant_Class}. It is a 9740synonym for the language defined aspect @code{Type_Invariant'Class} except 9741that it is separately controllable using pragma @code{Assertion_Policy}. 9742 9743@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects 9744@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{138} 9745@section Aspect Iterable 9746 9747 9748@geindex Iterable 9749 9750This aspect provides a light-weight mechanism for loops and quantified 9751expressions over container types, without the overhead imposed by the tampering 9752checks of standard Ada 2012 iterators. The value of the aspect is an aggregate 9753with six named components, of which the last three are optional: @code{First}, 9754@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. 9755When only the first three components are specified, only the 9756@code{for .. in} form of iteration over cursors is available. When @code{Element} 9757is specified, both this form and the @code{for .. of} form of iteration over 9758elements are available. If the last two components are specified, reverse 9759iterations over the container can be specified (analogous to what can be done 9760over predefined containers that support the @code{Reverse_Iterator} interface). 9761The following is a typical example of use: 9762 9763@example 9764type List is private with 9765 Iterable => (First => First_Cursor, 9766 Next => Advance, 9767 Has_Element => Cursor_Has_Element, 9768 [Element => Get_Element]); 9769@end example 9770 9771 9772@itemize * 9773 9774@item 9775The value denoted by @code{First} must denote a primitive operation of the 9776container type that returns a @code{Cursor}, which must a be a type declared in 9777the container package or visible from it. For example: 9778@end itemize 9779 9780@example 9781function First_Cursor (Cont : Container) return Cursor; 9782@end example 9783 9784 9785@itemize * 9786 9787@item 9788The value of @code{Next} is a primitive operation of the container type that takes 9789both a container and a cursor and yields a cursor. For example: 9790@end itemize 9791 9792@example 9793function Advance (Cont : Container; Position : Cursor) return Cursor; 9794@end example 9795 9796 9797@itemize * 9798 9799@item 9800The value of @code{Has_Element} is a primitive operation of the container type 9801that takes both a container and a cursor and yields a boolean. For example: 9802@end itemize 9803 9804@example 9805function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; 9806@end example 9807 9808 9809@itemize * 9810 9811@item 9812The value of @code{Element} is a primitive operation of the container type that 9813takes both a container and a cursor and yields an @code{Element_Type}, which must 9814be a type declared in the container package or visible from it. For example: 9815@end itemize 9816 9817@example 9818function Get_Element (Cont : Container; Position : Cursor) return Element_Type; 9819@end example 9820 9821This aspect is used in the GNAT-defined formal container packages. 9822 9823@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects 9824@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{139} 9825@section Aspect Linker_Section 9826 9827 9828@geindex Linker_Section 9829 9830This aspect is equivalent to @ref{93,,pragma Linker_Section}. 9831 9832@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects 9833@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{13a} 9834@section Aspect Lock_Free 9835 9836 9837@geindex Lock_Free 9838 9839This boolean aspect is equivalent to @ref{95,,pragma Lock_Free}. 9840 9841@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects 9842@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13b} 9843@section Aspect Max_Queue_Length 9844 9845 9846@geindex Max_Queue_Length 9847 9848This aspect is equivalent to @ref{9d,,pragma Max_Queue_Length}. 9849 9850@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects 9851@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13c} 9852@section Aspect No_Caching 9853 9854 9855@geindex No_Caching 9856 9857This boolean aspect is equivalent to @ref{a0,,pragma No_Caching}. 9858 9859@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects 9860@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13d} 9861@section Aspect No_Elaboration_Code_All 9862 9863 9864@geindex No_Elaboration_Code_All 9865 9866This aspect is equivalent to @ref{a3,,pragma No_Elaboration_Code_All} 9867for a program unit. 9868 9869@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects 9870@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13e} 9871@section Aspect No_Inline 9872 9873 9874@geindex No_Inline 9875 9876This boolean aspect is equivalent to @ref{a6,,pragma No_Inline}. 9877 9878@node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects 9879@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13f} 9880@section Aspect No_Tagged_Streams 9881 9882 9883@geindex No_Tagged_Streams 9884 9885This aspect is equivalent to @ref{aa,,pragma No_Tagged_Streams} with an 9886argument specifying a root tagged type (thus this aspect can only be 9887applied to such a type). 9888 9889@node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects 9890@anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{140} 9891@section Aspect No_Task_Parts 9892 9893 9894@geindex No_Task_Parts 9895 9896Applies to a type. If True, requires that the type and any descendants 9897do not have any task parts. The rules for this aspect are the same as 9898for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), 9899replacing “controlled” with “task”. 9900 9901If No_Task_Parts is True for a type T, then the compiler can optimize 9902away certain tasking-related code that would otherwise be needed 9903for T’Class, because descendants of T might contain tasks. 9904 9905@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects 9906@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{141} 9907@section Aspect Object_Size 9908 9909 9910@geindex Object_Size 9911 9912This aspect is equivalent to @ref{142,,attribute Object_Size}. 9913 9914@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects 9915@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{143} 9916@section Aspect Obsolescent 9917 9918 9919@geindex Obsolsecent 9920 9921This aspect is equivalent to @ref{ad,,pragma Obsolescent}. Note that the 9922evaluation of this aspect happens at the point of occurrence, it is not 9923delayed until the freeze point. 9924 9925@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects 9926@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{144} 9927@section Aspect Part_Of 9928 9929 9930@geindex Part_Of 9931 9932This aspect is equivalent to @ref{b4,,pragma Part_Of}. 9933 9934@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects 9935@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{145} 9936@section Aspect Persistent_BSS 9937 9938 9939@geindex Persistent_BSS 9940 9941This boolean aspect is equivalent to @ref{b7,,pragma Persistent_BSS}. 9942 9943@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects 9944@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{146} 9945@section Aspect Predicate 9946 9947 9948@geindex Predicate 9949 9950This aspect is equivalent to @ref{be,,pragma Predicate}. It is thus 9951similar to the language defined aspects @code{Dynamic_Predicate} 9952and @code{Static_Predicate} except that whether the resulting 9953predicate is static or dynamic is controlled by the form of the 9954expression. It is also separately controllable using pragma 9955@code{Assertion_Policy}. 9956 9957@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects 9958@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{147} 9959@section Aspect Pure_Function 9960 9961 9962@geindex Pure_Function 9963 9964This boolean aspect is equivalent to @ref{ca,,pragma Pure_Function}. 9965 9966@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects 9967@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{148} 9968@section Aspect Refined_Depends 9969 9970 9971@geindex Refined_Depends 9972 9973This aspect is equivalent to @ref{ce,,pragma Refined_Depends}. 9974 9975@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects 9976@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{149} 9977@section Aspect Refined_Global 9978 9979 9980@geindex Refined_Global 9981 9982This aspect is equivalent to @ref{d0,,pragma Refined_Global}. 9983 9984@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects 9985@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14a} 9986@section Aspect Refined_Post 9987 9988 9989@geindex Refined_Post 9990 9991This aspect is equivalent to @ref{d2,,pragma Refined_Post}. 9992 9993@node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects 9994@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14b} 9995@section Aspect Refined_State 9996 9997 9998@geindex Refined_State 9999 10000This aspect is equivalent to @ref{d4,,pragma Refined_State}. 10001 10002@node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects 10003@anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14c} 10004@section Aspect Relaxed_Initialization 10005 10006 10007@geindex Refined_Initialization 10008 10009For the syntax and semantics of this aspect, see the SPARK 2014 Reference 10010Manual, section 6.10. 10011 10012@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects 10013@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14d} 10014@section Aspect Remote_Access_Type 10015 10016 10017@geindex Remote_Access_Type 10018 10019This aspect is equivalent to @ref{d7,,pragma Remote_Access_Type}. 10020 10021@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects 10022@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14e} 10023@section Aspect Secondary_Stack_Size 10024 10025 10026@geindex Secondary_Stack_Size 10027 10028This aspect is equivalent to @ref{dd,,pragma Secondary_Stack_Size}. 10029 10030@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects 10031@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14f} 10032@section Aspect Scalar_Storage_Order 10033 10034 10035@geindex Scalar_Storage_Order 10036 10037This aspect is equivalent to a @ref{150,,attribute Scalar_Storage_Order}. 10038 10039@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects 10040@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{151} 10041@section Aspect Shared 10042 10043 10044@geindex Shared 10045 10046This boolean aspect is equivalent to @ref{e0,,pragma Shared} 10047and is thus a synonym for aspect @code{Atomic}. 10048 10049@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects 10050@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{152} 10051@section Aspect Simple_Storage_Pool 10052 10053 10054@geindex Simple_Storage_Pool 10055 10056This aspect is equivalent to @ref{e5,,attribute Simple_Storage_Pool}. 10057 10058@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects 10059@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{153} 10060@section Aspect Simple_Storage_Pool_Type 10061 10062 10063@geindex Simple_Storage_Pool_Type 10064 10065This boolean aspect is equivalent to @ref{e4,,pragma Simple_Storage_Pool_Type}. 10066 10067@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects 10068@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{154} 10069@section Aspect SPARK_Mode 10070 10071 10072@geindex SPARK_Mode 10073 10074This aspect is equivalent to @ref{ec,,pragma SPARK_Mode} and 10075may be specified for either or both of the specification and body 10076of a subprogram or package. 10077 10078@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects 10079@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{155} 10080@section Aspect Suppress_Debug_Info 10081 10082 10083@geindex Suppress_Debug_Info 10084 10085This boolean aspect is equivalent to @ref{f4,,pragma Suppress_Debug_Info}. 10086 10087@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects 10088@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{156} 10089@section Aspect Suppress_Initialization 10090 10091 10092@geindex Suppress_Initialization 10093 10094This boolean aspect is equivalent to @ref{f7,,pragma Suppress_Initialization}. 10095 10096@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects 10097@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{157} 10098@section Aspect Test_Case 10099 10100 10101@geindex Test_Case 10102 10103This aspect is equivalent to @ref{fb,,pragma Test_Case}. 10104 10105@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects 10106@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{158} 10107@section Aspect Thread_Local_Storage 10108 10109 10110@geindex Thread_Local_Storage 10111 10112This boolean aspect is equivalent to @ref{fd,,pragma Thread_Local_Storage}. 10113 10114@node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects 10115@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{159} 10116@section Aspect Universal_Aliasing 10117 10118 10119@geindex Universal_Aliasing 10120 10121This boolean aspect is equivalent to @ref{107,,pragma Universal_Aliasing}. 10122 10123@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects 10124@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{15a} 10125@section Aspect Unmodified 10126 10127 10128@geindex Unmodified 10129 10130This boolean aspect is equivalent to @ref{109,,pragma Unmodified}. 10131 10132@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects 10133@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15b} 10134@section Aspect Unreferenced 10135 10136 10137@geindex Unreferenced 10138 10139This boolean aspect is equivalent to @ref{10b,,pragma Unreferenced}. 10140 10141When using the @code{-gnat2022} switch, this aspect is also supported on formal 10142parameters, which is in particular the only form possible for expression 10143functions. 10144 10145@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects 10146@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15c} 10147@section Aspect Unreferenced_Objects 10148 10149 10150@geindex Unreferenced_Objects 10151 10152This boolean aspect is equivalent to @ref{10d,,pragma Unreferenced_Objects}. 10153 10154@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects 10155@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15d} 10156@section Aspect Value_Size 10157 10158 10159@geindex Value_Size 10160 10161This aspect is equivalent to @ref{15e,,attribute Value_Size}. 10162 10163@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects 10164@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15f} 10165@section Aspect Volatile_Full_Access 10166 10167 10168@geindex Volatile_Full_Access 10169 10170This boolean aspect is equivalent to @ref{117,,pragma Volatile_Full_Access}. 10171 10172@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects 10173@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{160} 10174@section Aspect Volatile_Function 10175 10176 10177@geindex Volatile_Function 10178 10179This boolean aspect is equivalent to @ref{119,,pragma Volatile_Function}. 10180 10181@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects 10182@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{161} 10183@section Aspect Warnings 10184 10185 10186@geindex Warnings 10187 10188This aspect is equivalent to the two argument form of @ref{11b,,pragma Warnings}, 10189where the first argument is @code{ON} or @code{OFF} and the second argument 10190is the entity. 10191 10192@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top 10193@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} 10194@chapter Implementation Defined Attributes 10195 10196 10197Ada defines (throughout the Ada reference manual, 10198summarized in Annex K), 10199a set of attributes that provide useful additional functionality in all 10200areas of the language. These language defined attributes are implemented 10201in GNAT and work as described in the Ada Reference Manual. 10202 10203In addition, Ada allows implementations to define additional 10204attributes whose meaning is defined by the implementation. GNAT provides 10205a number of these implementation-dependent attributes which can be used 10206to extend and enhance the functionality of the compiler. This section of 10207the GNAT reference manual describes these additional attributes. It also 10208describes additional implementation-dependent features of standard 10209language-defined attributes. 10210 10211Note that any program using these attributes may not be portable to 10212other compilers (although GNAT implements this set of attributes on all 10213platforms). Therefore if portability to other compilers is an important 10214consideration, you should minimize the use of these attributes. 10215 10216@menu 10217* Attribute Abort_Signal:: 10218* Attribute Address_Size:: 10219* Attribute Asm_Input:: 10220* Attribute Asm_Output:: 10221* Attribute Atomic_Always_Lock_Free:: 10222* Attribute Bit:: 10223* Attribute Bit_Position:: 10224* Attribute Code_Address:: 10225* Attribute Compiler_Version:: 10226* Attribute Constrained:: 10227* Attribute Default_Bit_Order:: 10228* Attribute Default_Scalar_Storage_Order:: 10229* Attribute Deref:: 10230* Attribute Descriptor_Size:: 10231* Attribute Elaborated:: 10232* Attribute Elab_Body:: 10233* Attribute Elab_Spec:: 10234* Attribute Elab_Subp_Body:: 10235* Attribute Emax:: 10236* Attribute Enabled:: 10237* Attribute Enum_Rep:: 10238* Attribute Enum_Val:: 10239* Attribute Epsilon:: 10240* Attribute Fast_Math:: 10241* Attribute Finalization_Size:: 10242* Attribute Fixed_Value:: 10243* Attribute From_Any:: 10244* Attribute Has_Access_Values:: 10245* Attribute Has_Discriminants:: 10246* Attribute Has_Tagged_Values:: 10247* Attribute Img:: 10248* Attribute Initialized:: 10249* Attribute Integer_Value:: 10250* Attribute Invalid_Value:: 10251* Attribute Iterable:: 10252* Attribute Large:: 10253* Attribute Library_Level:: 10254* Attribute Lock_Free:: 10255* Attribute Loop_Entry:: 10256* Attribute Machine_Size:: 10257* Attribute Mantissa:: 10258* Attribute Maximum_Alignment:: 10259* Attribute Max_Integer_Size:: 10260* Attribute Mechanism_Code:: 10261* Attribute Null_Parameter:: 10262* Attribute Object_Size:: 10263* Attribute Old:: 10264* Attribute Passed_By_Reference:: 10265* Attribute Pool_Address:: 10266* Attribute Range_Length:: 10267* Attribute Restriction_Set:: 10268* Attribute Result:: 10269* Attribute Safe_Emax:: 10270* Attribute Safe_Large:: 10271* Attribute Safe_Small:: 10272* Attribute Scalar_Storage_Order:: 10273* Attribute Simple_Storage_Pool:: 10274* Attribute Small:: 10275* Attribute Small_Denominator:: 10276* Attribute Small_Numerator:: 10277* Attribute Storage_Unit:: 10278* Attribute Stub_Type:: 10279* Attribute System_Allocator_Alignment:: 10280* Attribute Target_Name:: 10281* Attribute To_Address:: 10282* Attribute To_Any:: 10283* Attribute Type_Class:: 10284* Attribute Type_Key:: 10285* Attribute TypeCode:: 10286* Attribute Unconstrained_Array:: 10287* Attribute Universal_Literal_String:: 10288* Attribute Unrestricted_Access:: 10289* Attribute Update:: 10290* Attribute Valid_Image:: 10291* Attribute Valid_Scalars:: 10292* Attribute VADS_Size:: 10293* Attribute Value_Size:: 10294* Attribute Wchar_T_Size:: 10295* Attribute Word_Size:: 10296 10297@end menu 10298 10299@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes 10300@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{164} 10301@section Attribute Abort_Signal 10302 10303 10304@geindex Abort_Signal 10305 10306@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 10307prefix) provides the entity for the special exception used to signal 10308task abort or asynchronous transfer of control. Normally this attribute 10309should only be used in the tasking runtime (it is highly peculiar, and 10310completely outside the normal semantics of Ada, for a user program to 10311intercept the abort exception). 10312 10313@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes 10314@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{165} 10315@section Attribute Address_Size 10316 10317 10318@geindex Size of `@w{`}Address`@w{`} 10319 10320@geindex Address_Size 10321 10322@code{Standard'Address_Size} (@code{Standard} is the only allowed 10323prefix) is a static constant giving the number of bits in an 10324@code{Address}. It is the same value as System.Address’Size, 10325but has the advantage of being static, while a direct 10326reference to System.Address’Size is nonstatic because Address 10327is a private type. 10328 10329@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes 10330@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{166} 10331@section Attribute Asm_Input 10332 10333 10334@geindex Asm_Input 10335 10336The @code{Asm_Input} attribute denotes a function that takes two 10337parameters. The first is a string, the second is an expression of the 10338type designated by the prefix. The first (string) argument is required 10339to be a static expression, and is the constraint for the parameter, 10340(e.g., what kind of register is required). The second argument is the 10341value to be used as the input argument. The possible values for the 10342constant are the same as those used in the RTL, and are dependent on 10343the configuration file used to built the GCC back end. 10344@ref{167,,Machine Code Insertions} 10345 10346@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes 10347@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{168} 10348@section Attribute Asm_Output 10349 10350 10351@geindex Asm_Output 10352 10353The @code{Asm_Output} attribute denotes a function that takes two 10354parameters. The first is a string, the second is the name of a variable 10355of the type designated by the attribute prefix. The first (string) 10356argument is required to be a static expression and designates the 10357constraint for the parameter (e.g., what kind of register is 10358required). The second argument is the variable to be updated with the 10359result. The possible values for constraint are the same as those used in 10360the RTL, and are dependent on the configuration file used to build the 10361GCC back end. If there are no output operands, then this argument may 10362either be omitted, or explicitly given as @code{No_Output_Operands}. 10363@ref{167,,Machine Code Insertions} 10364 10365@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes 10366@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{169} 10367@section Attribute Atomic_Always_Lock_Free 10368 10369 10370@geindex Atomic_Always_Lock_Free 10371 10372The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. 10373The result is a Boolean value which is True if the type has discriminants, 10374and False otherwise. The result indicate whether atomic operations are 10375supported by the target for the given type. 10376 10377@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes 10378@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{16a} 10379@section Attribute Bit 10380 10381 10382@geindex Bit 10383 10384@code{obj'Bit}, where @code{obj} is any object, yields the bit 10385offset within the storage unit (byte) that contains the first bit of 10386storage allocated for the object. The value of this attribute is of the 10387type @emph{universal_integer} and is always a nonnegative number smaller 10388than @code{System.Storage_Unit}. 10389 10390For an object that is a variable or a constant allocated in a register, 10391the value is zero. (The use of this attribute does not force the 10392allocation of a variable to memory). 10393 10394For an object that is a formal parameter, this attribute applies 10395to either the matching actual parameter or to a copy of the 10396matching actual parameter. 10397 10398For an access object the value is zero. Note that 10399@code{obj.all'Bit} is subject to an @code{Access_Check} for the 10400designated object. Similarly for a record component 10401@code{X.C'Bit} is subject to a discriminant check and 10402@code{X(I).Bit} and @code{X(I1..I2)'Bit} 10403are subject to index checks. 10404 10405This attribute is designed to be compatible with the DEC Ada 83 definition 10406and implementation of the @code{Bit} attribute. 10407 10408@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes 10409@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16b} 10410@section Attribute Bit_Position 10411 10412 10413@geindex Bit_Position 10414 10415@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one 10416of the fields of the record type, yields the bit 10417offset within the record contains the first bit of 10418storage allocated for the object. The value of this attribute is of the 10419type @emph{universal_integer}. The value depends only on the field 10420@code{C} and is independent of the alignment of 10421the containing record @code{R}. 10422 10423@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes 10424@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16c} 10425@section Attribute Code_Address 10426 10427 10428@geindex Code_Address 10429 10430@geindex Subprogram address 10431 10432@geindex Address of subprogram code 10433 10434The @code{'Address} 10435attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 10436intended effect seems to be to provide 10437an address value which can be used to call the subprogram by means of 10438an address clause as in the following example: 10439 10440@example 10441procedure K is ... 10442 10443procedure L; 10444for L'Address use K'Address; 10445pragma Import (Ada, L); 10446@end example 10447 10448A call to @code{L} is then expected to result in a call to @code{K}. 10449In Ada 83, where there were no access-to-subprogram values, this was 10450a common work-around for getting the effect of an indirect call. 10451GNAT implements the above use of @code{Address} and the technique 10452illustrated by the example code works correctly. 10453 10454However, for some purposes, it is useful to have the address of the start 10455of the generated code for the subprogram. On some architectures, this is 10456not necessarily the same as the @code{Address} value described above. 10457For example, the @code{Address} value may reference a subprogram 10458descriptor rather than the subprogram itself. 10459 10460The @code{'Code_Address} attribute, which can only be applied to 10461subprogram entities, always returns the address of the start of the 10462generated code of the specified subprogram, which may or may not be 10463the same value as is returned by the corresponding @code{'Address} 10464attribute. 10465 10466@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes 10467@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16d} 10468@section Attribute Compiler_Version 10469 10470 10471@geindex Compiler_Version 10472 10473@code{Standard'Compiler_Version} (@code{Standard} is the only allowed 10474prefix) yields a static string identifying the version of the compiler 10475being used to compile the unit containing the attribute reference. 10476 10477@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes 10478@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16e} 10479@section Attribute Constrained 10480 10481 10482@geindex Constrained 10483 10484In addition to the usage of this attribute in the Ada RM, GNAT 10485also permits the use of the @code{'Constrained} attribute 10486in a generic template 10487for any type, including types without discriminants. The value of this 10488attribute in the generic instance when applied to a scalar type or a 10489record type without discriminants is always @code{True}. This usage is 10490compatible with older Ada compilers, including notably DEC Ada. 10491 10492@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes 10493@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16f} 10494@section Attribute Default_Bit_Order 10495 10496 10497@geindex Big endian 10498 10499@geindex Little endian 10500 10501@geindex Default_Bit_Order 10502 10503@code{Standard'Default_Bit_Order} (@code{Standard} is the only 10504allowed prefix), provides the value @code{System.Default_Bit_Order} 10505as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 10506@code{Low_Order_First}). This is used to construct the definition of 10507@code{Default_Bit_Order} in package @code{System}. 10508 10509@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes 10510@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{170} 10511@section Attribute Default_Scalar_Storage_Order 10512 10513 10514@geindex Big endian 10515 10516@geindex Little endian 10517 10518@geindex Default_Scalar_Storage_Order 10519 10520@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only 10521allowed prefix), provides the current value of the default scalar storage 10522order (as specified using pragma @code{Default_Scalar_Storage_Order}, or 10523equal to @code{Default_Bit_Order} if unspecified) as a 10524@code{System.Bit_Order} value. This is a static attribute. 10525 10526@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes 10527@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{171} 10528@section Attribute Deref 10529 10530 10531@geindex Deref 10532 10533The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields 10534the variable of type @code{typ} that is located at the given address. It is similar 10535to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to 10536a named access-to-@cite{typ} type, except that it yields a variable, so it can be 10537used on the left side of an assignment. 10538 10539@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes 10540@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{172} 10541@section Attribute Descriptor_Size 10542 10543 10544@geindex Descriptor 10545 10546@geindex Dope vector 10547 10548@geindex Descriptor_Size 10549 10550Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the 10551descriptor allocated for a type. The result is non-zero only for unconstrained 10552array types and the returned value is of type universal integer. In GNAT, an 10553array descriptor contains bounds information and is located immediately before 10554the first element of the array. 10555 10556@example 10557type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; 10558Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 10559@end example 10560 10561The attribute takes into account any padding due to the alignment of the 10562component type. In the example above, the descriptor contains two values 10563of type @code{Short_Short_Integer} representing the low and high bound. But, 10564since @code{Positive} has an alignment of 4, the size of the descriptor is 10565@code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, 10566which yields a size of 32 bits, i.e. including 16 bits of padding. 10567 10568@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes 10569@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{173} 10570@section Attribute Elaborated 10571 10572 10573@geindex Elaborated 10574 10575The prefix of the @code{'Elaborated} attribute must be a unit name. The 10576value is a Boolean which indicates whether or not the given unit has been 10577elaborated. This attribute is primarily intended for internal use by the 10578generated code for dynamic elaboration checking, but it can also be used 10579in user programs. The value will always be True once elaboration of all 10580units has been completed. An exception is for units which need no 10581elaboration, the value is always False for such units. 10582 10583@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes 10584@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{174} 10585@section Attribute Elab_Body 10586 10587 10588@geindex Elab_Body 10589 10590This attribute can only be applied to a program unit name. It returns 10591the entity for the corresponding elaboration procedure for elaborating 10592the body of the referenced unit. This is used in the main generated 10593elaboration procedure by the binder and is not normally used in any 10594other context. However, there may be specialized situations in which it 10595is useful to be able to call this elaboration procedure from Ada code, 10596e.g., if it is necessary to do selective re-elaboration to fix some 10597error. 10598 10599@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes 10600@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{175} 10601@section Attribute Elab_Spec 10602 10603 10604@geindex Elab_Spec 10605 10606This attribute can only be applied to a program unit name. It returns 10607the entity for the corresponding elaboration procedure for elaborating 10608the spec of the referenced unit. This is used in the main 10609generated elaboration procedure by the binder and is not normally used 10610in any other context. However, there may be specialized situations in 10611which it is useful to be able to call this elaboration procedure from 10612Ada code, e.g., if it is necessary to do selective re-elaboration to fix 10613some error. 10614 10615@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes 10616@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{176} 10617@section Attribute Elab_Subp_Body 10618 10619 10620@geindex Elab_Subp_Body 10621 10622This attribute can only be applied to a library level subprogram 10623name and is only allowed in CodePeer mode. It returns the entity 10624for the corresponding elaboration procedure for elaborating the body 10625of the referenced subprogram unit. This is used in the main generated 10626elaboration procedure by the binder in CodePeer mode only and is unrecognized 10627otherwise. 10628 10629@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes 10630@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{177} 10631@section Attribute Emax 10632 10633 10634@geindex Ada 83 attributes 10635 10636@geindex Emax 10637 10638The @code{Emax} attribute is provided for compatibility with Ada 83. See 10639the Ada 83 reference manual for an exact description of the semantics of 10640this attribute. 10641 10642@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes 10643@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{178} 10644@section Attribute Enabled 10645 10646 10647@geindex Enabled 10648 10649The @code{Enabled} attribute allows an application program to check at compile 10650time to see if the designated check is currently enabled. The prefix is a 10651simple identifier, referencing any predefined check name (other than 10652@code{All_Checks}) or a check name introduced by pragma Check_Name. If 10653no argument is given for the attribute, the check is for the general state 10654of the check, if an argument is given, then it is an entity name, and the 10655check indicates whether an @code{Suppress} or @code{Unsuppress} has been 10656given naming the entity (if not, then the argument is ignored). 10657 10658Note that instantiations inherit the check status at the point of the 10659instantiation, so a useful idiom is to have a library package that 10660introduces a check name with @code{pragma Check_Name}, and then contains 10661generic packages or subprograms which use the @code{Enabled} attribute 10662to see if the check is enabled. A user of this package can then issue 10663a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating 10664the package or subprogram, controlling whether the check will be present. 10665 10666@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes 10667@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{179} 10668@section Attribute Enum_Rep 10669 10670 10671@geindex Representation of enums 10672 10673@geindex Enum_Rep 10674 10675Note that this attribute is now standard in Ada 202x and is available 10676as an implementation defined attribute for earlier Ada versions. 10677 10678For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a 10679function with the following spec: 10680 10681@example 10682function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; 10683@end example 10684 10685It is also allowable to apply @code{Enum_Rep} directly to an object of an 10686enumeration type or to a non-overloaded enumeration 10687literal. In this case @code{S'Enum_Rep} is equivalent to 10688@code{typ'Enum_Rep(S)} where @code{typ} is the type of the 10689enumeration literal or object. 10690 10691The function returns the representation value for the given enumeration 10692value. This will be equal to value of the @code{Pos} attribute in the 10693absence of an enumeration representation clause. This is a static 10694attribute (i.e., the result is static if the argument is static). 10695 10696@code{S'Enum_Rep} can also be used with integer types and objects, 10697in which case it simply returns the integer value. The reason for this 10698is to allow it to be used for @code{(<>)} discrete formal arguments in 10699a generic unit that can be instantiated with either enumeration types 10700or integer types. Note that if @code{Enum_Rep} is used on a modular 10701type whose upper bound exceeds the upper bound of the largest signed 10702integer type, and the argument is a variable, so that the universal 10703integer calculation is done at run time, then the call to @code{Enum_Rep} 10704may raise @code{Constraint_Error}. 10705 10706@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes 10707@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{17a} 10708@section Attribute Enum_Val 10709 10710 10711@geindex Representation of enums 10712 10713@geindex Enum_Val 10714 10715Note that this attribute is now standard in Ada 202x and is available 10716as an implementation defined attribute for earlier Ada versions. 10717 10718For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a 10719function with the following spec: 10720 10721@example 10722function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; 10723@end example 10724 10725The function returns the enumeration value whose representation matches the 10726argument, or raises Constraint_Error if no enumeration literal of the type 10727has the matching value. 10728This will be equal to value of the @code{Val} attribute in the 10729absence of an enumeration representation clause. This is a static 10730attribute (i.e., the result is static if the argument is static). 10731 10732@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes 10733@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17b} 10734@section Attribute Epsilon 10735 10736 10737@geindex Ada 83 attributes 10738 10739@geindex Epsilon 10740 10741The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 10742the Ada 83 reference manual for an exact description of the semantics of 10743this attribute. 10744 10745@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes 10746@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17c} 10747@section Attribute Fast_Math 10748 10749 10750@geindex Fast_Math 10751 10752@code{Standard'Fast_Math} (@code{Standard} is the only allowed 10753prefix) yields a static Boolean value that is True if pragma 10754@code{Fast_Math} is active, and False otherwise. 10755 10756@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes 10757@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17d} 10758@section Attribute Finalization_Size 10759 10760 10761@geindex Finalization_Size 10762 10763The prefix of attribute @code{Finalization_Size} must be an object or 10764a non-class-wide type. This attribute returns the size of any hidden data 10765reserved by the compiler to handle finalization-related actions. The type of 10766the attribute is @emph{universal_integer}. 10767 10768@code{Finalization_Size} yields a value of zero for a type with no controlled 10769parts, an object whose type has no controlled parts, or an object of a 10770class-wide type whose tag denotes a type with no controlled parts. 10771 10772Note that only heap-allocated objects contain finalization data. 10773 10774@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes 10775@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17e} 10776@section Attribute Fixed_Value 10777 10778 10779@geindex Fixed_Value 10780 10781For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a 10782function with the following specification: 10783 10784@example 10785function S'Fixed_Value (Arg : <Universal_Integer>) return S; 10786@end example 10787 10788The value returned is the fixed-point value @code{V} such that: 10789 10790@example 10791V = Arg * S'Small 10792@end example 10793 10794The effect is thus similar to first converting the argument to the 10795integer type used to represent @code{S}, and then doing an unchecked 10796conversion to the fixed-point type. The difference is 10797that there are full range checks, to ensure that the result is in range. 10798This attribute is primarily intended for use in implementation of the 10799input-output functions for fixed-point values. 10800 10801@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes 10802@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17f} 10803@section Attribute From_Any 10804 10805 10806@geindex From_Any 10807 10808This internal attribute is used for the generation of remote subprogram 10809stubs in the context of the Distributed Systems Annex. 10810 10811@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes 10812@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{180} 10813@section Attribute Has_Access_Values 10814 10815 10816@geindex Access values 10817@geindex testing for 10818 10819@geindex Has_Access_Values 10820 10821The prefix of the @code{Has_Access_Values} attribute is a type. The result 10822is a Boolean value which is True if the is an access type, or is a composite 10823type with a component (at any nesting depth) that is an access type, and is 10824False otherwise. 10825The intended use of this attribute is in conjunction with generic 10826definitions. If the attribute is applied to a generic private type, it 10827indicates whether or not the corresponding actual type has access values. 10828 10829@node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes 10830@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{181} 10831@section Attribute Has_Discriminants 10832 10833 10834@geindex Discriminants 10835@geindex testing for 10836 10837@geindex Has_Discriminants 10838 10839The prefix of the @code{Has_Discriminants} attribute is a type. The result 10840is a Boolean value which is True if the type has discriminants, and False 10841otherwise. The intended use of this attribute is in conjunction with generic 10842definitions. If the attribute is applied to a generic private type, it 10843indicates whether or not the corresponding actual type has discriminants. 10844 10845@node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes 10846@anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{182} 10847@section Attribute Has_Tagged_Values 10848 10849 10850@geindex Tagged values 10851@geindex testing for 10852 10853@geindex Has_Tagged_Values 10854 10855The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a 10856Boolean value which is True if the type is a composite type (array or record) 10857that is either a tagged type or has a subcomponent that is tagged, and is False 10858otherwise. The intended use of this attribute is in conjunction with generic 10859definitions. If the attribute is applied to a generic private type, it 10860indicates whether or not the corresponding actual type has access values. 10861 10862@node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes 10863@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{183} 10864@section Attribute Img 10865 10866 10867@geindex Img 10868 10869The @code{Img} attribute differs from @code{Image} in that, while both can be 10870applied directly to an object, @code{Img} cannot be applied to types. 10871 10872Example usage of the attribute: 10873 10874@example 10875Put_Line ("X = " & X'Img); 10876@end example 10877 10878which has the same meaning as the more verbose: 10879 10880@example 10881Put_Line ("X = " & T'Image (X)); 10882@end example 10883 10884where @code{T} is the (sub)type of the object @code{X}. 10885 10886Note that technically, in analogy to @code{Image}, 10887@code{X'Img} returns a parameterless function 10888that returns the appropriate string when called. This means that 10889@code{X'Img} can be renamed as a function-returning-string, or used 10890in an instantiation as a function parameter. 10891 10892@node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes 10893@anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{184} 10894@section Attribute Initialized 10895 10896 10897@geindex Initialized 10898 10899For the syntax and semantics of this attribute, see the SPARK 2014 Reference 10900Manual, section 6.10. 10901 10902@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes 10903@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{185} 10904@section Attribute Integer_Value 10905 10906 10907@geindex Integer_Value 10908 10909For every integer type @code{S}, @code{S'Integer_Value} denotes a 10910function with the following spec: 10911 10912@example 10913function S'Integer_Value (Arg : <Universal_Fixed>) return S; 10914@end example 10915 10916The value returned is the integer value @code{V}, such that: 10917 10918@example 10919Arg = V * T'Small 10920@end example 10921 10922where @code{T} is the type of @code{Arg}. 10923The effect is thus similar to first doing an unchecked conversion from 10924the fixed-point type to its corresponding implementation type, and then 10925converting the result to the target integer type. The difference is 10926that there are full range checks, to ensure that the result is in range. 10927This attribute is primarily intended for use in implementation of the 10928standard input-output functions for fixed-point values. 10929 10930@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes 10931@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{186} 10932@section Attribute Invalid_Value 10933 10934 10935@geindex Invalid_Value 10936 10937For every scalar type S, S’Invalid_Value returns an undefined value of the 10938type. If possible this value is an invalid representation for the type. The 10939value returned is identical to the value used to initialize an otherwise 10940uninitialized value of the type if pragma Initialize_Scalars is used, 10941including the ability to modify the value with the binder -Sxx flag and 10942relevant environment variables at run time. 10943 10944@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes 10945@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{187} 10946@section Attribute Iterable 10947 10948 10949@geindex Iterable 10950 10951Equivalent to Aspect Iterable. 10952 10953@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes 10954@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{188} 10955@section Attribute Large 10956 10957 10958@geindex Ada 83 attributes 10959 10960@geindex Large 10961 10962The @code{Large} attribute is provided for compatibility with Ada 83. See 10963the Ada 83 reference manual for an exact description of the semantics of 10964this attribute. 10965 10966@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes 10967@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{189} 10968@section Attribute Library_Level 10969 10970 10971@geindex Library_Level 10972 10973@code{P'Library_Level}, where P is an entity name, 10974returns a Boolean value which is True if the entity is declared 10975at the library level, and False otherwise. Note that within a 10976generic instantition, the name of the generic unit denotes the 10977instance, which means that this attribute can be used to test 10978if a generic is instantiated at the library level, as shown 10979in this example: 10980 10981@example 10982generic 10983 ... 10984package Gen is 10985 pragma Compile_Time_Error 10986 (not Gen'Library_Level, 10987 "Gen can only be instantiated at library level"); 10988 ... 10989end Gen; 10990@end example 10991 10992@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes 10993@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{18a} 10994@section Attribute Lock_Free 10995 10996 10997@geindex Lock_Free 10998 10999@code{P'Lock_Free}, where P is a protected object, returns True if a 11000pragma @code{Lock_Free} applies to P. 11001 11002@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes 11003@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18b} 11004@section Attribute Loop_Entry 11005 11006 11007@geindex Loop_Entry 11008 11009Syntax: 11010 11011@example 11012X'Loop_Entry [(loop_name)] 11013@end example 11014 11015The @code{Loop_Entry} attribute is used to refer to the value that an 11016expression had upon entry to a given loop in much the same way that the 11017@code{Old} attribute in a subprogram postcondition can be used to refer 11018to the value an expression had upon entry to the subprogram. The 11019relevant loop is either identified by the given loop name, or it is the 11020innermost enclosing loop when no loop name is given. 11021 11022A @code{Loop_Entry} attribute can only occur within a 11023@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of 11024@code{Loop_Entry} is to compare the current value of objects with their 11025initial value at loop entry, in a @code{Loop_Invariant} pragma. 11026 11027The effect of using @code{X'Loop_Entry} is the same as declaring 11028a constant initialized with the initial value of @code{X} at loop 11029entry. This copy is not performed if the loop is not entered, or if the 11030corresponding pragmas are ignored or disabled. 11031 11032@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes 11033@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18c} 11034@section Attribute Machine_Size 11035 11036 11037@geindex Machine_Size 11038 11039This attribute is identical to the @code{Object_Size} attribute. It is 11040provided for compatibility with the DEC Ada 83 attribute of this name. 11041 11042@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes 11043@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18d} 11044@section Attribute Mantissa 11045 11046 11047@geindex Ada 83 attributes 11048 11049@geindex Mantissa 11050 11051The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 11052the Ada 83 reference manual for an exact description of the semantics of 11053this attribute. 11054 11055@node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes 11056@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18e}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18f} 11057@section Attribute Maximum_Alignment 11058 11059 11060@geindex Alignment 11061@geindex maximum 11062 11063@geindex Maximum_Alignment 11064 11065@code{Standard'Maximum_Alignment} (@code{Standard} is the only 11066allowed prefix) provides the maximum useful alignment value for the 11067target. This is a static value that can be used to specify the alignment 11068for an object, guaranteeing that it is properly aligned in all 11069cases. 11070 11071@node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes 11072@anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{190} 11073@section Attribute Max_Integer_Size 11074 11075 11076@geindex Max_Integer_Size 11077 11078@code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed 11079prefix) provides the size of the largest supported integer type for 11080the target. The result is a static constant. 11081 11082@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes 11083@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{191} 11084@section Attribute Mechanism_Code 11085 11086 11087@geindex Return values 11088@geindex passing mechanism 11089 11090@geindex Parameters 11091@geindex passing mechanism 11092 11093@geindex Mechanism_Code 11094 11095@code{func'Mechanism_Code} yields an integer code for the 11096mechanism used for the result of function @code{func}, and 11097@code{subprog'Mechanism_Code (n)} yields the mechanism 11098used for formal parameter number @emph{n} (a static integer value, with 1 11099meaning the first parameter) of subprogram @code{subprog}. The code returned is: 11100 11101 11102@table @asis 11103 11104@item @emph{1} 11105 11106by copy (value) 11107 11108@item @emph{2} 11109 11110by reference 11111@end table 11112 11113@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes 11114@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{192} 11115@section Attribute Null_Parameter 11116 11117 11118@geindex Zero address 11119@geindex passing 11120 11121@geindex Null_Parameter 11122 11123A reference @code{T'Null_Parameter} denotes an imaginary object of 11124type or subtype @code{T} allocated at machine address zero. The attribute 11125is allowed only as the default expression of a formal parameter, or as 11126an actual expression of a subprogram call. In either case, the 11127subprogram must be imported. 11128 11129The identity of the object is represented by the address zero in the 11130argument list, independent of the passing mechanism (explicit or 11131default). 11132 11133This capability is needed to specify that a zero address should be 11134passed for a record or other composite object passed by reference. 11135There is no way of indicating this without the @code{Null_Parameter} 11136attribute. 11137 11138@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes 11139@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{142}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{193} 11140@section Attribute Object_Size 11141 11142 11143@geindex Size 11144@geindex used for objects 11145 11146@geindex Object_Size 11147 11148The size of an object is not necessarily the same as the size of the type 11149of an object. This is because by default object sizes are increased to be 11150a multiple of the alignment of the object. For example, 11151@code{Natural'Size} is 1115231, but by default objects of type @code{Natural} will have a size of 32 bits. 11153Similarly, a record containing an integer and a character: 11154 11155@example 11156type Rec is record 11157 I : Integer; 11158 C : Character; 11159end record; 11160@end example 11161 11162will have a size of 40 (that is @code{Rec'Size} will be 40). The 11163alignment will be 4, because of the 11164integer field, and so the default size of record objects for this type 11165will be 64 (8 bytes). 11166 11167If the alignment of the above record is specified to be 1, then the 11168object size will be 40 (5 bytes). This is true by default, and also 11169an object size of 40 can be explicitly specified in this case. 11170 11171A consequence of this capability is that different object sizes can be 11172given to subtypes that would otherwise be considered in Ada to be 11173statically matching. But it makes no sense to consider such subtypes 11174as statically matching. Consequently, GNAT adds a rule 11175to the static matching rules that requires object sizes to match. 11176Consider this example: 11177 11178@example 11179 1. procedure BadAVConvert is 11180 2. type R is new Integer; 11181 3. subtype R1 is R range 1 .. 10; 11182 4. subtype R2 is R range 1 .. 10; 11183 5. for R1'Object_Size use 8; 11184 6. for R2'Object_Size use 16; 11185 7. type R1P is access all R1; 11186 8. type R2P is access all R2; 11187 9. R1PV : R1P := new R1'(4); 1118810. R2PV : R2P; 1118911. begin 1119012. R2PV := R2P (R1PV); 11191 | 11192 >>> target designated subtype not compatible with 11193 type "R1" defined at line 3 11194 1119513. end; 11196@end example 11197 11198In the absence of lines 5 and 6, 11199types @code{R1} and @code{R2} statically match and 11200hence the conversion on line 12 is legal. But since lines 5 and 6 11201cause the object sizes to differ, GNAT considers that types 11202@code{R1} and @code{R2} are not statically matching, and line 12 11203generates the diagnostic shown above. 11204 11205Similar additional checks are performed in other contexts requiring 11206statically matching subtypes. 11207 11208@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes 11209@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{194} 11210@section Attribute Old 11211 11212 11213@geindex Old 11214 11215In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage 11216within @code{Post} aspect), GNAT also permits the use of this attribute 11217in implementation defined pragmas @code{Postcondition}, 11218@code{Contract_Cases} and @code{Test_Case}. Also usages of 11219@code{Old} which would be illegal according to the Ada 2012 RM 11220definition are allowed under control of 11221implementation defined pragma @code{Unevaluated_Use_Of_Old}. 11222 11223@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes 11224@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{195} 11225@section Attribute Passed_By_Reference 11226 11227 11228@geindex Parameters 11229@geindex when passed by reference 11230 11231@geindex Passed_By_Reference 11232 11233@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns 11234a value of type @code{Boolean} value that is @code{True} if the type is 11235normally passed by reference and @code{False} if the type is normally 11236passed by copy in calls. For scalar types, the result is always @code{False} 11237and is static. For non-scalar types, the result is nonstatic. 11238 11239@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes 11240@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{196} 11241@section Attribute Pool_Address 11242 11243 11244@geindex Pool_Address 11245 11246@code{X'Pool_Address} for any object @code{X} returns the address 11247of X within its storage pool. This is the same as 11248@code{X'Address}, except that for an unconstrained array whose 11249bounds are allocated just before the first component, 11250@code{X'Pool_Address} returns the address of those bounds, 11251whereas @code{X'Address} returns the address of the first 11252component. 11253 11254Here, we are interpreting ‘storage pool’ broadly to mean 11255@code{wherever the object is allocated}, which could be a 11256user-defined storage pool, 11257the global heap, on the stack, or in a static memory area. 11258For an object created by @code{new}, @code{Ptr.all'Pool_Address} is 11259what is passed to @code{Allocate} and returned from @code{Deallocate}. 11260 11261@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes 11262@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{197} 11263@section Attribute Range_Length 11264 11265 11266@geindex Range_Length 11267 11268@code{typ'Range_Length} for any discrete type @cite{typ} yields 11269the number of values represented by the subtype (zero for a null 11270range). The result is static for static subtypes. @code{Range_Length} 11271applied to the index subtype of a one dimensional array always gives the 11272same result as @code{Length} applied to the array itself. 11273 11274@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes 11275@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{198} 11276@section Attribute Restriction_Set 11277 11278 11279@geindex Restriction_Set 11280 11281@geindex Restrictions 11282 11283This attribute allows compile time testing of restrictions that 11284are currently in effect. It is primarily intended for specializing 11285code in the run-time based on restrictions that are active (e.g. 11286don’t need to save fpt registers if restriction No_Floating_Point 11287is known to be in effect), but can be used anywhere. 11288 11289There are two forms: 11290 11291@example 11292System'Restriction_Set (partition_boolean_restriction_NAME) 11293System'Restriction_Set (No_Dependence => library_unit_NAME); 11294@end example 11295 11296In the case of the first form, the only restriction names 11297allowed are parameterless restrictions that are checked 11298for consistency at bind time. For a complete list see the 11299subtype @code{System.Rident.Partition_Boolean_Restrictions}. 11300 11301The result returned is True if the restriction is known to 11302be in effect, and False if the restriction is known not to 11303be in effect. An important guarantee is that the value of 11304a Restriction_Set attribute is known to be consistent throughout 11305all the code of a partition. 11306 11307This is trivially achieved if the entire partition is compiled 11308with a consistent set of restriction pragmas. However, the 11309compilation model does not require this. It is possible to 11310compile one set of units with one set of pragmas, and another 11311set of units with another set of pragmas. It is even possible 11312to compile a spec with one set of pragmas, and then WITH the 11313same spec with a different set of pragmas. Inconsistencies 11314in the actual use of the restriction are checked at bind time. 11315 11316In order to achieve the guarantee of consistency for the 11317Restriction_Set pragma, we consider that a use of the pragma 11318that yields False is equivalent to a violation of the 11319restriction. 11320 11321So for example if you write 11322 11323@example 11324if System'Restriction_Set (No_Floating_Point) then 11325 ... 11326else 11327 ... 11328end if; 11329@end example 11330 11331And the result is False, so that the else branch is executed, 11332you can assume that this restriction is not set for any unit 11333in the partition. This is checked by considering this use of 11334the restriction pragma to be a violation of the restriction 11335No_Floating_Point. This means that no other unit can attempt 11336to set this restriction (if some unit does attempt to set it, 11337the binder will refuse to bind the partition). 11338 11339Technical note: The restriction name and the unit name are 11340intepreted entirely syntactically, as in the corresponding 11341Restrictions pragma, they are not analyzed semantically, 11342so they do not have a type. 11343 11344@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes 11345@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{199} 11346@section Attribute Result 11347 11348 11349@geindex Result 11350 11351@code{function'Result} can only be used with in a Postcondition pragma 11352for a function. The prefix must be the name of the corresponding function. This 11353is used to refer to the result of the function in the postcondition expression. 11354For a further discussion of the use of this attribute and examples of its use, 11355see the description of pragma Postcondition. 11356 11357@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes 11358@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19a} 11359@section Attribute Safe_Emax 11360 11361 11362@geindex Ada 83 attributes 11363 11364@geindex Safe_Emax 11365 11366The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 11367the Ada 83 reference manual for an exact description of the semantics of 11368this attribute. 11369 11370@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes 11371@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{19b} 11372@section Attribute Safe_Large 11373 11374 11375@geindex Ada 83 attributes 11376 11377@geindex Safe_Large 11378 11379The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See 11380the Ada 83 reference manual for an exact description of the semantics of 11381this attribute. 11382 11383@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes 11384@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19c} 11385@section Attribute Safe_Small 11386 11387 11388@geindex Ada 83 attributes 11389 11390@geindex Safe_Small 11391 11392The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See 11393the Ada 83 reference manual for an exact description of the semantics of 11394this attribute. 11395 11396@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes 11397@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{150}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19d} 11398@section Attribute Scalar_Storage_Order 11399 11400 11401@geindex Endianness 11402 11403@geindex Scalar storage order 11404 11405@geindex Scalar_Storage_Order 11406 11407For every array or record type @code{S}, the representation attribute 11408@code{Scalar_Storage_Order} denotes the order in which storage elements 11409that make up scalar components are ordered within S. The value given must 11410be a static expression of type System.Bit_Order. The following is an example 11411of the use of this feature: 11412 11413@example 11414-- Component type definitions 11415 11416subtype Yr_Type is Natural range 0 .. 127; 11417subtype Mo_Type is Natural range 1 .. 12; 11418subtype Da_Type is Natural range 1 .. 31; 11419 11420-- Record declaration 11421 11422type Date is record 11423 Years_Since_1980 : Yr_Type; 11424 Month : Mo_Type; 11425 Day_Of_Month : Da_Type; 11426end record; 11427 11428-- Record representation clause 11429 11430for Date use record 11431 Years_Since_1980 at 0 range 0 .. 6; 11432 Month at 0 range 7 .. 10; 11433 Day_Of_Month at 0 range 11 .. 15; 11434end record; 11435 11436-- Attribute definition clauses 11437 11438for Date'Bit_Order use System.High_Order_First; 11439for Date'Scalar_Storage_Order use System.High_Order_First; 11440-- If Scalar_Storage_Order is specified, it must be consistent with 11441-- Bit_Order, so it's best to always define the latter explicitly if 11442-- the former is used. 11443@end example 11444 11445Other properties are as for the standard representation attribute @code{Bit_Order} 11446defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. 11447 11448For a record type @code{T}, if @code{T'Scalar_Storage_Order} is 11449specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: 11450this means that if a @code{Scalar_Storage_Order} attribute definition 11451clause is not confirming, then the type’s @code{Bit_Order} shall be 11452specified explicitly and set to the same value. 11453 11454Derived types inherit an explicitly set scalar storage order from their parent 11455types. This may be overridden for the derived type by giving an explicit scalar 11456storage order for it. However, for a record extension, the derived type must 11457have the same scalar storage order as the parent type. 11458 11459A component of a record type that is itself a record or an array and that does 11460not start and end on a byte boundary must have have the same scalar storage 11461order as the record type. A component of a bit-packed array type that is itself 11462a record or an array must have the same scalar storage order as the array type. 11463 11464No component of a type that has an explicit @code{Scalar_Storage_Order} 11465attribute definition may be aliased. 11466 11467A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. 11468with a value equal to @code{System.Default_Bit_Order}) has no effect. 11469 11470If the opposite storage order is specified, then whenever the value of 11471a scalar component of an object of type @code{S} is read, the storage 11472elements of the enclosing machine scalar are first reversed (before 11473retrieving the component value, possibly applying some shift and mask 11474operatings on the enclosing machine scalar), and the opposite operation 11475is done for writes. 11476 11477In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 11478are relaxed. Instead, the following rules apply: 11479 11480 11481@itemize * 11482 11483@item 11484the underlying storage elements are those at positions 11485@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} 11486 11487@item 11488the sequence of underlying storage elements shall have 11489a size no greater than the largest machine scalar 11490 11491@item 11492the enclosing machine scalar is defined as the smallest machine 11493scalar starting at a position no greater than 11494@code{position + first_bit / storage_element_size} and covering 11495storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`} 11496 11497@item 11498the position of the component is interpreted relative to that machine 11499scalar. 11500@end itemize 11501 11502If no scalar storage order is specified for a type (either directly, or by 11503inheritance in the case of a derived type), then the default is normally 11504the native ordering of the target, but this default can be overridden using 11505pragma @code{Default_Scalar_Storage_Order}. 11506 11507If a component of @code{T} is itself of a record or array type, the specfied 11508@code{Scalar_Storage_Order} does @emph{not} apply to that nested type: an explicit 11509attribute definition clause must be provided for the component type as well 11510if desired. 11511 11512Representation changes that explicitly or implicitly toggle the scalar storage 11513order are not supported and may result in erroneous execution of the program, 11514except when performed by means of an instance of @code{Ada.Unchecked_Conversion}. 11515 11516In particular, overlays are not supported and a warning is given for them: 11517 11518@example 11519type Rec_LE is record 11520 I : Integer; 11521end record; 11522 11523for Rec_LE use record 11524 I at 0 range 0 .. 31; 11525end record; 11526 11527for Rec_LE'Bit_Order use System.Low_Order_First; 11528for Rec_LE'Scalar_Storage_Order use System.Low_Order_First; 11529 11530type Rec_BE is record 11531 I : Integer; 11532end record; 11533 11534for Rec_BE use record 11535 I at 0 range 0 .. 31; 11536end record; 11537 11538for Rec_BE'Bit_Order use System.High_Order_First; 11539for Rec_BE'Scalar_Storage_Order use System.High_Order_First; 11540 11541R_LE : Rec_LE; 11542 11543R_BE : Rec_BE; 11544for R_BE'Address use R_LE'Address; 11545@end example 11546 11547@code{warning: overlay changes scalar storage order [enabled by default]} 11548 11549In most cases, such representation changes ought to be replaced by an 11550instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}. 11551 11552Note that the scalar storage order only affects the in-memory data 11553representation. It has no effect on the representation used by stream 11554attributes. 11555 11556Note that debuggers may be unable to display the correct value of scalar 11557components of a type for which the opposite storage order is specified. 11558 11559@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes 11560@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e5}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{19e} 11561@section Attribute Simple_Storage_Pool 11562 11563 11564@geindex Storage pool 11565@geindex simple 11566 11567@geindex Simple storage pool 11568 11569@geindex Simple_Storage_Pool 11570 11571For every nonformal, nonderived access-to-object type @code{Acc}, the 11572representation attribute @code{Simple_Storage_Pool} may be specified 11573via an attribute_definition_clause (or by specifying the equivalent aspect): 11574 11575@example 11576My_Pool : My_Simple_Storage_Pool_Type; 11577 11578type Acc is access My_Data_Type; 11579 11580for Acc'Simple_Storage_Pool use My_Pool; 11581@end example 11582 11583The name given in an attribute_definition_clause for the 11584@code{Simple_Storage_Pool} attribute shall denote a variable of 11585a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}). 11586 11587The use of this attribute is only allowed for a prefix denoting a type 11588for which it has been specified. The type of the attribute is the type 11589of the variable specified as the simple storage pool of the access type, 11590and the attribute denotes that variable. 11591 11592It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} 11593for the same access type. 11594 11595If the @code{Simple_Storage_Pool} attribute has been specified for an access 11596type, then applying the @code{Storage_Pool} attribute to the type is flagged 11597with a warning and its evaluation raises the exception @code{Program_Error}. 11598 11599If the Simple_Storage_Pool attribute has been specified for an access 11600type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} 11601returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, 11602which is intended to indicate the number of storage elements reserved for 11603the simple storage pool. If the Storage_Size function has not been defined 11604for the simple storage pool type, then this attribute returns zero. 11605 11606If an access type @code{S} has a specified simple storage pool of type 11607@code{SSP}, then the evaluation of an allocator for that access type calls 11608the primitive @code{Allocate} procedure for type @code{SSP}, passing 11609@code{S'Simple_Storage_Pool} as the pool parameter. The detailed 11610semantics of such allocators is the same as those defined for allocators 11611in section 13.11 of the @cite{Ada Reference Manual}, with the term 11612@emph{simple storage pool} substituted for @emph{storage pool}. 11613 11614If an access type @code{S} has a specified simple storage pool of type 11615@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} 11616for that access type invokes the primitive @code{Deallocate} procedure 11617for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool 11618parameter. The detailed semantics of such unchecked deallocations is the same 11619as defined in section 13.11.2 of the Ada Reference Manual, except that the 11620term @emph{simple storage pool} is substituted for @emph{storage pool}. 11621 11622@node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes 11623@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{19f} 11624@section Attribute Small 11625 11626 11627@geindex Ada 83 attributes 11628 11629@geindex Small 11630 11631The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for 11632fixed-point types. 11633GNAT also allows this attribute to be applied to floating-point types 11634for compatibility with Ada 83. See 11635the Ada 83 reference manual for an exact description of the semantics of 11636this attribute when applied to floating-point types. 11637 11638@node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes 11639@anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{1a0} 11640@section Attribute Small_Denominator 11641 11642 11643@geindex Small 11644 11645@geindex Small_Denominator 11646 11647@code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the 11648denominator in the representation of @code{typ'Small} as a rational number 11649with coprime factors (i.e. as an irreducible fraction). 11650 11651@node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes 11652@anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{1a1} 11653@section Attribute Small_Numerator 11654 11655 11656@geindex Small 11657 11658@geindex Small_Numerator 11659 11660@code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the 11661numerator in the representation of @code{typ'Small} as a rational number 11662with coprime factors (i.e. as an irreducible fraction). 11663 11664@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes 11665@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a2} 11666@section Attribute Storage_Unit 11667 11668 11669@geindex Storage_Unit 11670 11671@code{Standard'Storage_Unit} (@code{Standard} is the only allowed 11672prefix) provides the same value as @code{System.Storage_Unit}. 11673 11674@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes 11675@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a3} 11676@section Attribute Stub_Type 11677 11678 11679@geindex Stub_Type 11680 11681The GNAT implementation of remote access-to-classwide types is 11682organized as described in AARM section E.4 (20.t): a value of an RACW type 11683(designating a remote object) is represented as a normal access 11684value, pointing to a “stub” object which in turn contains the 11685necessary information to contact the designated remote object. A 11686call on any dispatching operation of such a stub object does the 11687remote call, if necessary, using the information in the stub object 11688to locate the target partition, etc. 11689 11690For a prefix @code{T} that denotes a remote access-to-classwide type, 11691@code{T'Stub_Type} denotes the type of the corresponding stub objects. 11692 11693By construction, the layout of @code{T'Stub_Type} is identical to that of 11694type @code{RACW_Stub_Type} declared in the internal implementation-defined 11695unit @code{System.Partition_Interface}. Use of this attribute will create 11696an implicit dependency on this unit. 11697 11698@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes 11699@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a4} 11700@section Attribute System_Allocator_Alignment 11701 11702 11703@geindex Alignment 11704@geindex allocator 11705 11706@geindex System_Allocator_Alignment 11707 11708@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only 11709allowed prefix) provides the observable guaranted to be honored by 11710the system allocator (malloc). This is a static value that can be used 11711in user storage pools based on malloc either to reject allocation 11712with alignment too large or to enable a realignment circuitry if the 11713alignment request is larger than this value. 11714 11715@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes 11716@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a5} 11717@section Attribute Target_Name 11718 11719 11720@geindex Target_Name 11721 11722@code{Standard'Target_Name} (@code{Standard} is the only allowed 11723prefix) provides a static string value that identifies the target 11724for the current compilation. For GCC implementations, this is the 11725standard gcc target name without the terminating slash (for 11726example, GNAT 5.0 on windows yields “i586-pc-mingw32msv”). 11727 11728@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes 11729@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a6} 11730@section Attribute To_Address 11731 11732 11733@geindex To_Address 11734 11735The @code{System'To_Address} 11736(@code{System} is the only allowed prefix) 11737denotes a function identical to 11738@code{System.Storage_Elements.To_Address} except that 11739it is a static attribute. This means that if its argument is 11740a static expression, then the result of the attribute is a 11741static expression. This means that such an expression can be 11742used in contexts (e.g., preelaborable packages) which require a 11743static expression and where the function call could not be used 11744(since the function call is always nonstatic, even if its 11745argument is static). The argument must be in the range 11746-(2**(m-1)) .. 2**m-1, where m is the memory size 11747(typically 32 or 64). Negative values are intepreted in a 11748modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on 11749a 32 bits machine). 11750 11751@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes 11752@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a7} 11753@section Attribute To_Any 11754 11755 11756@geindex To_Any 11757 11758This internal attribute is used for the generation of remote subprogram 11759stubs in the context of the Distributed Systems Annex. 11760 11761@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes 11762@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a8} 11763@section Attribute Type_Class 11764 11765 11766@geindex Type_Class 11767 11768@code{typ'Type_Class} for any type or subtype @cite{typ} yields 11769the value of the type class for the full type of @cite{typ}. If 11770@cite{typ} is a generic formal type, the value is the value for the 11771corresponding actual subtype. The value of this attribute is of type 11772@code{System.Aux_DEC.Type_Class}, which has the following definition: 11773 11774@example 11775type Type_Class is 11776 (Type_Class_Enumeration, 11777 Type_Class_Integer, 11778 Type_Class_Fixed_Point, 11779 Type_Class_Floating_Point, 11780 Type_Class_Array, 11781 Type_Class_Record, 11782 Type_Class_Access, 11783 Type_Class_Task, 11784 Type_Class_Address); 11785@end example 11786 11787Protected types yield the value @code{Type_Class_Task}, which thus 11788applies to all concurrent types. This attribute is designed to 11789be compatible with the DEC Ada 83 attribute of the same name. 11790 11791@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes 11792@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a9} 11793@section Attribute Type_Key 11794 11795 11796@geindex Type_Key 11797 11798The @code{Type_Key} attribute is applicable to a type or subtype and 11799yields a value of type Standard.String containing encoded information 11800about the type or subtype. This provides improved compatibility with 11801other implementations that support this attribute. 11802 11803@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes 11804@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1aa} 11805@section Attribute TypeCode 11806 11807 11808@geindex TypeCode 11809 11810This internal attribute is used for the generation of remote subprogram 11811stubs in the context of the Distributed Systems Annex. 11812 11813@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes 11814@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1ab} 11815@section Attribute Unconstrained_Array 11816 11817 11818@geindex Unconstrained_Array 11819 11820The @code{Unconstrained_Array} attribute can be used with a prefix that 11821denotes any type or subtype. It is a static attribute that yields 11822@code{True} if the prefix designates an unconstrained array, 11823and @code{False} otherwise. In a generic instance, the result is 11824still static, and yields the result of applying this test to the 11825generic actual. 11826 11827@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes 11828@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1ac} 11829@section Attribute Universal_Literal_String 11830 11831 11832@geindex Named numbers 11833@geindex representation of 11834 11835@geindex Universal_Literal_String 11836 11837The prefix of @code{Universal_Literal_String} must be a named 11838number. The static result is the string consisting of the characters of 11839the number as defined in the original source. This allows the user 11840program to access the actual text of named numbers without intermediate 11841conversions and without the need to enclose the strings in quotes (which 11842would preclude their use as numbers). 11843 11844For example, the following program prints the first 50 digits of pi: 11845 11846@example 11847with Text_IO; use Text_IO; 11848with Ada.Numerics; 11849procedure Pi is 11850begin 11851 Put (Ada.Numerics.Pi'Universal_Literal_String); 11852end; 11853@end example 11854 11855@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes 11856@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1ad} 11857@section Attribute Unrestricted_Access 11858 11859 11860@geindex Access 11861@geindex unrestricted 11862 11863@geindex Unrestricted_Access 11864 11865The @code{Unrestricted_Access} attribute is similar to @code{Access} 11866except that all accessibility and aliased view checks are omitted. This 11867is a user-beware attribute. 11868 11869For objects, it is similar to @code{Address}, for which it is a 11870desirable replacement where the value desired is an access type. 11871In other words, its effect is similar to first applying the 11872@code{Address} attribute and then doing an unchecked conversion to a 11873desired access type. 11874 11875For subprograms, @code{P'Unrestricted_Access} may be used where 11876@code{P'Access} would be illegal, to construct a value of a 11877less-nested named access type that designates a more-nested 11878subprogram. This value may be used in indirect calls, so long as the 11879more-nested subprogram still exists; once the subprogram containing it 11880has returned, such calls are erroneous. For example: 11881 11882@example 11883package body P is 11884 11885 type Less_Nested is not null access procedure; 11886 Global : Less_Nested; 11887 11888 procedure P1 is 11889 begin 11890 Global.all; 11891 end P1; 11892 11893 procedure P2 is 11894 Local_Var : Integer; 11895 11896 procedure More_Nested is 11897 begin 11898 ... Local_Var ... 11899 end More_Nested; 11900 begin 11901 Global := More_Nested'Unrestricted_Access; 11902 P1; 11903 end P2; 11904 11905end P; 11906@end example 11907 11908When P1 is called from P2, the call via Global is OK, but if P1 were 11909called after P2 returns, it would be an erroneous use of a dangling 11910pointer. 11911 11912For objects, it is possible to use @code{Unrestricted_Access} for any 11913type. However, if the result is of an access-to-unconstrained array 11914subtype, then the resulting pointer has the same scope as the context 11915of the attribute, and must not be returned to some enclosing scope. 11916For instance, if a function uses @code{Unrestricted_Access} to create 11917an access-to-unconstrained-array and returns that value to the caller, 11918the result will involve dangling pointers. In addition, it is only 11919valid to create pointers to unconstrained arrays using this attribute 11920if the pointer has the normal default ‘fat’ representation where a 11921pointer has two components, one points to the array and one points to 11922the bounds. If a size clause is used to force ‘thin’ representation 11923for a pointer to unconstrained where there is only space for a single 11924pointer, then the resulting pointer is not usable. 11925 11926In the simple case where a direct use of Unrestricted_Access attempts 11927to make a thin pointer for a non-aliased object, the compiler will 11928reject the use as illegal, as shown in the following example: 11929 11930@example 11931with System; use System; 11932procedure SliceUA2 is 11933 type A is access all String; 11934 for A'Size use Standard'Address_Size; 11935 11936 procedure P (Arg : A) is 11937 begin 11938 null; 11939 end P; 11940 11941 X : String := "hello world!"; 11942 X2 : aliased String := "hello world!"; 11943 11944 AV : A := X'Unrestricted_Access; -- ERROR 11945 | 11946>>> illegal use of Unrestricted_Access attribute 11947>>> attempt to generate thin pointer to unaliased object 11948 11949begin 11950 P (X'Unrestricted_Access); -- ERROR 11951 | 11952>>> illegal use of Unrestricted_Access attribute 11953>>> attempt to generate thin pointer to unaliased object 11954 11955 P (X(7 .. 12)'Unrestricted_Access); -- ERROR 11956 | 11957>>> illegal use of Unrestricted_Access attribute 11958>>> attempt to generate thin pointer to unaliased object 11959 11960 P (X2'Unrestricted_Access); -- OK 11961end; 11962@end example 11963 11964but other cases cannot be detected by the compiler, and are 11965considered to be erroneous. Consider the following example: 11966 11967@example 11968with System; use System; 11969with System; use System; 11970procedure SliceUA is 11971 type AF is access all String; 11972 11973 type A is access all String; 11974 for A'Size use Standard'Address_Size; 11975 11976 procedure P (Arg : A) is 11977 begin 11978 if Arg'Length /= 6 then 11979 raise Program_Error; 11980 end if; 11981 end P; 11982 11983 X : String := "hello world!"; 11984 Y : AF := X (7 .. 12)'Unrestricted_Access; 11985 11986begin 11987 P (A (Y)); 11988end; 11989@end example 11990 11991A normal unconstrained array value 11992or a constrained array object marked as aliased has the bounds in memory 11993just before the array, so a thin pointer can retrieve both the data and 11994the bounds. But in this case, the non-aliased object @code{X} does not have the 11995bounds before the string. If the size clause for type @code{A} 11996were not present, then the pointer 11997would be a fat pointer, where one component is a pointer to the bounds, 11998and all would be well. But with the size clause present, the conversion from 11999fat pointer to thin pointer in the call loses the bounds, and so this 12000is erroneous, and the program likely raises a @code{Program_Error} exception. 12001 12002In general, it is advisable to completely 12003avoid mixing the use of thin pointers and the use of 12004@code{Unrestricted_Access} where the designated type is an 12005unconstrained array. The use of thin pointers should be restricted to 12006cases of porting legacy code that implicitly assumes the size of pointers, 12007and such code should not in any case be using this attribute. 12008 12009Another erroneous situation arises if the attribute is 12010applied to a constant. The resulting pointer can be used to access the 12011constant, but the effect of trying to modify a constant in this manner 12012is not well-defined. Consider this example: 12013 12014@example 12015P : constant Integer := 4; 12016type R is access all Integer; 12017RV : R := P'Unrestricted_Access; 12018.. 12019RV.all := 3; 12020@end example 12021 12022Here we attempt to modify the constant P from 4 to 3, but the compiler may 12023or may not notice this attempt, and subsequent references to P may yield 12024either the value 3 or the value 4 or the assignment may blow up if the 12025compiler decides to put P in read-only memory. One particular case where 12026@code{Unrestricted_Access} can be used in this way is to modify the 12027value of an @code{in} parameter: 12028 12029@example 12030procedure K (S : in String) is 12031 type R is access all Character; 12032 RV : R := S (3)'Unrestricted_Access; 12033begin 12034 RV.all := 'a'; 12035end; 12036@end example 12037 12038In general this is a risky approach. It may appear to “work” but such uses of 12039@code{Unrestricted_Access} are potentially non-portable, even from one version 12040of GNAT to another, so are best avoided if possible. 12041 12042@node Attribute Update,Attribute Valid_Image,Attribute Unrestricted_Access,Implementation Defined Attributes 12043@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1ae} 12044@section Attribute Update 12045 12046 12047@geindex Update 12048 12049The @code{Update} attribute creates a copy of an array or record value 12050with one or more modified components. The syntax is: 12051 12052@example 12053PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 12054PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) 12055PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 12056 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) 12057 12058MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 12059INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} 12060INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) 12061@end example 12062 12063where @code{PREFIX} is the name of an array or record object, the 12064association list in parentheses does not contain an @code{others} 12065choice and the box symbol @code{<>} may not appear in any 12066expression. The effect is to yield a copy of the array or record value 12067which is unchanged apart from the components mentioned in the 12068association list, which are changed to the indicated value. The 12069original value of the array or record value is not affected. For 12070example: 12071 12072@example 12073type Arr is Array (1 .. 5) of Integer; 12074... 12075Avar1 : Arr := (1,2,3,4,5); 12076Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 12077@end example 12078 12079yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} 12080begin unmodified. Similarly: 12081 12082@example 12083type Rec is A, B, C : Integer; 12084... 12085Rvar1 : Rec := (A => 1, B => 2, C => 3); 12086Rvar2 : Rec := Rvar1'Update (B => 20); 12087@end example 12088 12089yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), 12090with @code{Rvar1} being unmodifed. 12091Note that the value of the attribute reference is computed 12092completely before it is used. This means that if you write: 12093 12094@example 12095Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 12096@end example 12097 12098then the value of @code{Avar1} is not modified if @code{Function_Call} 12099raises an exception, unlike the effect of a series of direct assignments 12100to elements of @code{Avar1}. In general this requires that 12101two extra complete copies of the object are required, which should be 12102kept in mind when considering efficiency. 12103 12104The @code{Update} attribute cannot be applied to prefixes of a limited 12105type, and cannot reference discriminants in the case of a record type. 12106The accessibility level of an Update attribute result object is defined 12107as for an aggregate. 12108 12109In the record case, no component can be mentioned more than once. In 12110the array case, two overlapping ranges can appear in the association list, 12111in which case the modifications are processed left to right. 12112 12113Multi-dimensional arrays can be modified, as shown by this example: 12114 12115@example 12116A : array (1 .. 10, 1 .. 10) of Integer; 12117.. 12118A := A'Update ((1, 2) => 20, (3, 4) => 30); 12119@end example 12120 12121which changes element (1,2) to 20 and (3,4) to 30. 12122 12123@node Attribute Valid_Image,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes 12124@anchor{gnat_rm/implementation_defined_attributes attribute-valid-image}@anchor{1af} 12125@section Attribute Valid_Image 12126 12127 12128@geindex Valid_Image 12129 12130The @code{'Valid_Image} attribute is defined for enumeration types other than 12131those in package Standard. This attribute is a function that takes 12132a String, and returns Boolean. @code{T'Valid_Image (S)} returns True 12133if and only if @code{T'Value (S)} would not raise Constraint_Error. 12134 12135@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Image,Implementation Defined Attributes 12136@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b0} 12137@section Attribute Valid_Scalars 12138 12139 12140@geindex Valid_Scalars 12141 12142The @code{'Valid_Scalars} attribute is intended to make it easier to check the 12143validity of scalar subcomponents of composite objects. The attribute is defined 12144for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type 12145except for tagged private or @code{Unchecked_Union} types. The value of the 12146attribute is of type @code{Boolean}. 12147 12148@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of 12149@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if 12150@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent 12151to attribute @code{'Valid} for scalar types. 12152 12153It is not specified in what order the subcomponents are checked, nor whether 12154any more are checked after any one of them is determined to be invalid. If the 12155prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated 12156specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then 12157only the subcomponents of @code{T} are checked; in other words, components of 12158extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. 12159 12160The compiler will issue a warning if it can be determined at compile time that 12161the prefix of the attribute has no scalar subcomponents. 12162 12163Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of 12164a large variant record. If the attribute is called in many places in the same 12165program applied to objects of the same type, it can reduce program size to 12166write a function with a single use of the attribute, and then call that 12167function from multiple places. 12168 12169@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes 12170@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b1} 12171@section Attribute VADS_Size 12172 12173 12174@geindex Size 12175@geindex VADS compatibility 12176 12177@geindex VADS_Size 12178 12179The @code{'VADS_Size} attribute is intended to make it easier to port 12180legacy code which relies on the semantics of @code{'Size} as implemented 12181by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 12182same semantic interpretation. In particular, @code{'VADS_Size} applied 12183to a predefined or other primitive type with no Size clause yields the 12184Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 12185typical machines). In addition @code{'VADS_Size} applied to an object 12186gives the result that would be obtained by applying the attribute to 12187the corresponding type. 12188 12189@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes 12190@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15e}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b2} 12191@section Attribute Value_Size 12192 12193 12194@geindex Size 12195@geindex setting for not-first subtype 12196 12197@geindex Value_Size 12198 12199@code{type'Value_Size} is the number of bits required to represent 12200a value of the given subtype. It is the same as @code{type'Size}, 12201but, unlike @code{Size}, may be set for non-first subtypes. 12202 12203@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes 12204@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b3} 12205@section Attribute Wchar_T_Size 12206 12207 12208@geindex Wchar_T_Size 12209 12210@code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed 12211prefix) provides the size in bits of the C @code{wchar_t} type 12212primarily for constructing the definition of this type in 12213package @code{Interfaces.C}. The result is a static constant. 12214 12215@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes 12216@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b4} 12217@section Attribute Word_Size 12218 12219 12220@geindex Word_Size 12221 12222@code{Standard'Word_Size} (@code{Standard} is the only allowed 12223prefix) provides the value @code{System.Word_Size}. The result is 12224a static constant. 12225 12226@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top 12227@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} 12228@chapter Standard and Implementation Defined Restrictions 12229 12230 12231All Ada Reference Manual-defined Restriction identifiers are implemented: 12232 12233 12234@itemize * 12235 12236@item 12237language-defined restrictions (see 13.12.1) 12238 12239@item 12240tasking restrictions (see D.7) 12241 12242@item 12243high integrity restrictions (see H.4) 12244@end itemize 12245 12246GNAT implements additional restriction identifiers. All restrictions, whether 12247language defined or GNAT-specific, are listed in the following. 12248 12249@menu 12250* Partition-Wide Restrictions:: 12251* Program Unit Level Restrictions:: 12252 12253@end menu 12254 12255@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions 12256@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b7}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b8} 12257@section Partition-Wide Restrictions 12258 12259 12260There are two separate lists of restriction identifiers. The first 12261set requires consistency throughout a partition (in other words, if the 12262restriction identifier is used for any compilation unit in the partition, 12263then all compilation units in the partition must obey the restriction). 12264 12265@menu 12266* Immediate_Reclamation:: 12267* Max_Asynchronous_Select_Nesting:: 12268* Max_Entry_Queue_Length:: 12269* Max_Protected_Entries:: 12270* Max_Select_Alternatives:: 12271* Max_Storage_At_Blocking:: 12272* Max_Task_Entries:: 12273* Max_Tasks:: 12274* No_Abort_Statements:: 12275* No_Access_Parameter_Allocators:: 12276* No_Access_Subprograms:: 12277* No_Allocators:: 12278* No_Anonymous_Allocators:: 12279* No_Asynchronous_Control:: 12280* No_Calendar:: 12281* No_Coextensions:: 12282* No_Default_Initialization:: 12283* No_Delay:: 12284* No_Dependence:: 12285* No_Direct_Boolean_Operators:: 12286* No_Dispatch:: 12287* No_Dispatching_Calls:: 12288* No_Dynamic_Attachment:: 12289* No_Dynamic_Priorities:: 12290* No_Entry_Calls_In_Elaboration_Code:: 12291* No_Enumeration_Maps:: 12292* No_Exception_Handlers:: 12293* No_Exception_Propagation:: 12294* No_Exception_Registration:: 12295* No_Exceptions:: 12296* No_Finalization:: 12297* No_Fixed_Point:: 12298* No_Floating_Point:: 12299* No_Implicit_Conditionals:: 12300* No_Implicit_Dynamic_Code:: 12301* No_Implicit_Heap_Allocations:: 12302* No_Implicit_Protected_Object_Allocations:: 12303* No_Implicit_Task_Allocations:: 12304* No_Initialize_Scalars:: 12305* No_IO:: 12306* No_Local_Allocators:: 12307* No_Local_Protected_Objects:: 12308* No_Local_Timing_Events:: 12309* No_Long_Long_Integers:: 12310* No_Multiple_Elaboration:: 12311* No_Nested_Finalization:: 12312* No_Protected_Type_Allocators:: 12313* No_Protected_Types:: 12314* No_Recursion:: 12315* No_Reentrancy:: 12316* No_Relative_Delay:: 12317* No_Requeue_Statements:: 12318* No_Secondary_Stack:: 12319* No_Select_Statements:: 12320* No_Specific_Termination_Handlers:: 12321* No_Specification_of_Aspect:: 12322* No_Standard_Allocators_After_Elaboration:: 12323* No_Standard_Storage_Pools:: 12324* No_Stream_Optimizations:: 12325* No_Streams:: 12326* No_Task_Allocators:: 12327* No_Task_At_Interrupt_Priority:: 12328* No_Task_Attributes_Package:: 12329* No_Task_Hierarchy:: 12330* No_Task_Termination:: 12331* No_Tasking:: 12332* No_Terminate_Alternatives:: 12333* No_Unchecked_Access:: 12334* No_Unchecked_Conversion:: 12335* No_Unchecked_Deallocation:: 12336* No_Use_Of_Entity:: 12337* Pure_Barriers:: 12338* Simple_Barriers:: 12339* Static_Priorities:: 12340* Static_Storage_Size:: 12341 12342@end menu 12343 12344@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions 12345@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b9} 12346@subsection Immediate_Reclamation 12347 12348 12349@geindex Immediate_Reclamation 12350 12351[RM H.4] This restriction ensures that, except for storage occupied by 12352objects created by allocators and not deallocated via unchecked 12353deallocation, any storage reserved at run time for an object is 12354immediately reclaimed when the object no longer exists. 12355 12356@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions 12357@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1ba} 12358@subsection Max_Asynchronous_Select_Nesting 12359 12360 12361@geindex Max_Asynchronous_Select_Nesting 12362 12363[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 12364selects. Violations of this restriction with a value of zero are 12365detected at compile time. Violations of this restriction with values 12366other than zero cause Storage_Error to be raised. 12367 12368@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions 12369@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1bb} 12370@subsection Max_Entry_Queue_Length 12371 12372 12373@geindex Max_Entry_Queue_Length 12374 12375[RM D.7] This restriction is a declaration that any protected entry compiled in 12376the scope of the restriction has at most the specified number of 12377tasks waiting on the entry at any one time, and so no queue is required. 12378Note that this restriction is checked at run time. Violation of this 12379restriction results in the raising of Program_Error exception at the point of 12380the call. 12381 12382@geindex Max_Entry_Queue_Depth 12383 12384The restriction @code{Max_Entry_Queue_Depth} is recognized as a 12385synonym for @code{Max_Entry_Queue_Length}. This is retained for historical 12386compatibility purposes (and a warning will be generated for its use if 12387warnings on obsolescent features are activated). 12388 12389@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions 12390@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1bc} 12391@subsection Max_Protected_Entries 12392 12393 12394@geindex Max_Protected_Entries 12395 12396[RM D.7] Specifies the maximum number of entries per protected type. The 12397bounds of every entry family of a protected unit shall be static, or shall be 12398defined by a discriminant of a subtype whose corresponding bound is static. 12399 12400@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions 12401@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bd} 12402@subsection Max_Select_Alternatives 12403 12404 12405@geindex Max_Select_Alternatives 12406 12407[RM D.7] Specifies the maximum number of alternatives in a selective accept. 12408 12409@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions 12410@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1be} 12411@subsection Max_Storage_At_Blocking 12412 12413 12414@geindex Max_Storage_At_Blocking 12415 12416[RM D.7] Specifies the maximum portion (in storage elements) of a task’s 12417Storage_Size that can be retained by a blocked task. A violation of this 12418restriction causes Storage_Error to be raised. 12419 12420@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions 12421@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1bf} 12422@subsection Max_Task_Entries 12423 12424 12425@geindex Max_Task_Entries 12426 12427[RM D.7] Specifies the maximum number of entries 12428per task. The bounds of every entry family 12429of a task unit shall be static, or shall be 12430defined by a discriminant of a subtype whose 12431corresponding bound is static. 12432 12433@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions 12434@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c0} 12435@subsection Max_Tasks 12436 12437 12438@geindex Max_Tasks 12439 12440[RM D.7] Specifies the maximum number of task that may be created, not 12441counting the creation of the environment task. Violations of this 12442restriction with a value of zero are detected at compile 12443time. Violations of this restriction with values other than zero cause 12444Storage_Error to be raised. 12445 12446@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions 12447@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c1} 12448@subsection No_Abort_Statements 12449 12450 12451@geindex No_Abort_Statements 12452 12453[RM D.7] There are no abort_statements, and there are 12454no calls to Task_Identification.Abort_Task. 12455 12456@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions 12457@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c2} 12458@subsection No_Access_Parameter_Allocators 12459 12460 12461@geindex No_Access_Parameter_Allocators 12462 12463[RM H.4] This restriction ensures at compile time that there are no 12464occurrences of an allocator as the actual parameter to an access 12465parameter. 12466 12467@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions 12468@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c3} 12469@subsection No_Access_Subprograms 12470 12471 12472@geindex No_Access_Subprograms 12473 12474[RM H.4] This restriction ensures at compile time that there are no 12475declarations of access-to-subprogram types. 12476 12477@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions 12478@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c4} 12479@subsection No_Allocators 12480 12481 12482@geindex No_Allocators 12483 12484[RM H.4] This restriction ensures at compile time that there are no 12485occurrences of an allocator. 12486 12487@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions 12488@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c5} 12489@subsection No_Anonymous_Allocators 12490 12491 12492@geindex No_Anonymous_Allocators 12493 12494[RM H.4] This restriction ensures at compile time that there are no 12495occurrences of an allocator of anonymous access type. 12496 12497@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions 12498@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c6} 12499@subsection No_Asynchronous_Control 12500 12501 12502@geindex No_Asynchronous_Control 12503 12504[RM J.13] This restriction ensures at compile time that there are no semantic 12505dependences on the predefined package Asynchronous_Task_Control. 12506 12507@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions 12508@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c7} 12509@subsection No_Calendar 12510 12511 12512@geindex No_Calendar 12513 12514[GNAT] This restriction ensures at compile time that there are no semantic 12515dependences on package Calendar. 12516 12517@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions 12518@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c8} 12519@subsection No_Coextensions 12520 12521 12522@geindex No_Coextensions 12523 12524[RM H.4] This restriction ensures at compile time that there are no 12525coextensions. See 3.10.2. 12526 12527@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions 12528@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c9} 12529@subsection No_Default_Initialization 12530 12531 12532@geindex No_Default_Initialization 12533 12534[GNAT] This restriction prohibits any instance of default initialization 12535of variables. The binder implements a consistency rule which prevents 12536any unit compiled without the restriction from with’ing a unit with the 12537restriction (this allows the generation of initialization procedures to 12538be skipped, since you can be sure that no call is ever generated to an 12539initialization procedure in a unit with the restriction active). If used 12540in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 12541is to prohibit all cases of variables declared without a specific 12542initializer (including the case of OUT scalar parameters). 12543 12544@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions 12545@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1ca} 12546@subsection No_Delay 12547 12548 12549@geindex No_Delay 12550 12551[RM H.4] This restriction ensures at compile time that there are no 12552delay statements and no semantic dependences on package Calendar. 12553 12554@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions 12555@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1cb} 12556@subsection No_Dependence 12557 12558 12559@geindex No_Dependence 12560 12561[RM 13.12.1] This restriction ensures at compile time that there are no 12562dependences on a library unit. 12563 12564@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions 12565@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1cc} 12566@subsection No_Direct_Boolean_Operators 12567 12568 12569@geindex No_Direct_Boolean_Operators 12570 12571[GNAT] This restriction ensures that no logical operators (and/or/xor) 12572are used on operands of type Boolean (or any type derived from Boolean). 12573This is intended for use in safety critical programs where the certification 12574protocol requires the use of short-circuit (and then, or else) forms for all 12575composite boolean operations. 12576 12577@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions 12578@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cd} 12579@subsection No_Dispatch 12580 12581 12582@geindex No_Dispatch 12583 12584[RM H.4] This restriction ensures at compile time that there are no 12585occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. 12586 12587@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions 12588@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1ce} 12589@subsection No_Dispatching_Calls 12590 12591 12592@geindex No_Dispatching_Calls 12593 12594[GNAT] This restriction ensures at compile time that the code generated by the 12595compiler involves no dispatching calls. The use of this restriction allows the 12596safe use of record extensions, classwide membership tests and other classwide 12597features not involving implicit dispatching. This restriction ensures that 12598the code contains no indirect calls through a dispatching mechanism. Note that 12599this includes internally-generated calls created by the compiler, for example 12600in the implementation of class-wide objects assignments. The 12601membership test is allowed in the presence of this restriction, because its 12602implementation requires no dispatching. 12603This restriction is comparable to the official Ada restriction 12604@code{No_Dispatch} except that it is a bit less restrictive in that it allows 12605all classwide constructs that do not imply dispatching. 12606The following example indicates constructs that violate this restriction. 12607 12608@example 12609package Pkg is 12610 type T is tagged record 12611 Data : Natural; 12612 end record; 12613 procedure P (X : T); 12614 12615 type DT is new T with record 12616 More_Data : Natural; 12617 end record; 12618 procedure Q (X : DT); 12619end Pkg; 12620 12621with Pkg; use Pkg; 12622procedure Example is 12623 procedure Test (O : T'Class) is 12624 N : Natural := O'Size; -- Error: Dispatching call 12625 C : T'Class := O; -- Error: implicit Dispatching Call 12626 begin 12627 if O in DT'Class then -- OK : Membership test 12628 Q (DT (O)); -- OK : Type conversion plus direct call 12629 else 12630 P (O); -- Error: Dispatching call 12631 end if; 12632 end Test; 12633 12634 Obj : DT; 12635begin 12636 P (Obj); -- OK : Direct call 12637 P (T (Obj)); -- OK : Type conversion plus direct call 12638 P (T'Class (Obj)); -- Error: Dispatching call 12639 12640 Test (Obj); -- OK : Type conversion 12641 12642 if Obj in T'Class then -- OK : Membership test 12643 null; 12644 end if; 12645end Example; 12646@end example 12647 12648@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions 12649@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1cf} 12650@subsection No_Dynamic_Attachment 12651 12652 12653@geindex No_Dynamic_Attachment 12654 12655[RM D.7] This restriction ensures that there is no call to any of the 12656operations defined in package Ada.Interrupts 12657(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 12658Detach_Handler, and Reference). 12659 12660@geindex No_Dynamic_Interrupts 12661 12662The restriction @code{No_Dynamic_Interrupts} is recognized as a 12663synonym for @code{No_Dynamic_Attachment}. This is retained for historical 12664compatibility purposes (and a warning will be generated for its use if 12665warnings on obsolescent features are activated). 12666 12667@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions 12668@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d0} 12669@subsection No_Dynamic_Priorities 12670 12671 12672@geindex No_Dynamic_Priorities 12673 12674[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 12675 12676@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions 12677@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d1} 12678@subsection No_Entry_Calls_In_Elaboration_Code 12679 12680 12681@geindex No_Entry_Calls_In_Elaboration_Code 12682 12683[GNAT] This restriction ensures at compile time that no task or protected entry 12684calls are made during elaboration code. As a result of the use of this 12685restriction, the compiler can assume that no code past an accept statement 12686in a task can be executed at elaboration time. 12687 12688@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions 12689@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d2} 12690@subsection No_Enumeration_Maps 12691 12692 12693@geindex No_Enumeration_Maps 12694 12695[GNAT] This restriction ensures at compile time that no operations requiring 12696enumeration maps are used (that is Image and Value attributes applied 12697to enumeration types). 12698 12699@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions 12700@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d3} 12701@subsection No_Exception_Handlers 12702 12703 12704@geindex No_Exception_Handlers 12705 12706[GNAT] This restriction ensures at compile time that there are no explicit 12707exception handlers. It also indicates that no exception propagation will 12708be provided. In this mode, exceptions may be raised but will result in 12709an immediate call to the last chance handler, a routine that the user 12710must define with the following profile: 12711 12712@example 12713procedure Last_Chance_Handler 12714 (Source_Location : System.Address; Line : Integer); 12715pragma Export (C, Last_Chance_Handler, 12716 "__gnat_last_chance_handler"); 12717@end example 12718 12719The parameter is a C null-terminated string representing a message to be 12720associated with the exception (typically the source location of the raise 12721statement generated by the compiler). The Line parameter when nonzero 12722represents the line number in the source program where the raise occurs. 12723 12724@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions 12725@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d4} 12726@subsection No_Exception_Propagation 12727 12728 12729@geindex No_Exception_Propagation 12730 12731[GNAT] This restriction guarantees that exceptions are never propagated 12732to an outer subprogram scope. The only case in which an exception may 12733be raised is when the handler is statically in the same subprogram, so 12734that the effect of a raise is essentially like a goto statement. Any 12735other raise statement (implicit or explicit) will be considered 12736unhandled. Exception handlers are allowed, but may not contain an 12737exception occurrence identifier (exception choice). In addition, use of 12738the package GNAT.Current_Exception is not permitted, and reraise 12739statements (raise with no operand) are not permitted. 12740 12741@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions 12742@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d5} 12743@subsection No_Exception_Registration 12744 12745 12746@geindex No_Exception_Registration 12747 12748[GNAT] This restriction ensures at compile time that no stream operations for 12749types Exception_Id or Exception_Occurrence are used. This also makes it 12750impossible to pass exceptions to or from a partition with this restriction 12751in a distributed environment. If this restriction is active, the generated 12752code is simplified by omitting the otherwise-required global registration 12753of exceptions when they are declared. 12754 12755@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions 12756@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d6} 12757@subsection No_Exceptions 12758 12759 12760@geindex No_Exceptions 12761 12762[RM H.4] This restriction ensures at compile time that there are no 12763raise statements and no exception handlers and also suppresses the 12764generation of language-defined run-time checks. 12765 12766@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions 12767@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d7} 12768@subsection No_Finalization 12769 12770 12771@geindex No_Finalization 12772 12773[GNAT] This restriction disables the language features described in 12774chapter 7.6 of the Ada 2005 RM as well as all form of code generation 12775performed by the compiler to support these features. The following types 12776are no longer considered controlled when this restriction is in effect: 12777 12778 12779@itemize * 12780 12781@item 12782@code{Ada.Finalization.Controlled} 12783 12784@item 12785@code{Ada.Finalization.Limited_Controlled} 12786 12787@item 12788Derivations from @code{Controlled} or @code{Limited_Controlled} 12789 12790@item 12791Class-wide types 12792 12793@item 12794Protected types 12795 12796@item 12797Task types 12798 12799@item 12800Array and record types with controlled components 12801@end itemize 12802 12803The compiler no longer generates code to initialize, finalize or adjust an 12804object or a nested component, either declared on the stack or on the heap. The 12805deallocation of a controlled object no longer finalizes its contents. 12806 12807@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions 12808@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d8} 12809@subsection No_Fixed_Point 12810 12811 12812@geindex No_Fixed_Point 12813 12814[RM H.4] This restriction ensures at compile time that there are no 12815occurrences of fixed point types and operations. 12816 12817@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions 12818@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d9} 12819@subsection No_Floating_Point 12820 12821 12822@geindex No_Floating_Point 12823 12824[RM H.4] This restriction ensures at compile time that there are no 12825occurrences of floating point types and operations. 12826 12827@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions 12828@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1da} 12829@subsection No_Implicit_Conditionals 12830 12831 12832@geindex No_Implicit_Conditionals 12833 12834[GNAT] This restriction ensures that the generated code does not contain any 12835implicit conditionals, either by modifying the generated code where possible, 12836or by rejecting any construct that would otherwise generate an implicit 12837conditional. Note that this check does not include run time constraint 12838checks, which on some targets may generate implicit conditionals as 12839well. To control the latter, constraint checks can be suppressed in the 12840normal manner. Constructs generating implicit conditionals include comparisons 12841of composite objects and the Max/Min attributes. 12842 12843@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions 12844@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1db} 12845@subsection No_Implicit_Dynamic_Code 12846 12847 12848@geindex No_Implicit_Dynamic_Code 12849 12850@geindex trampoline 12851 12852[GNAT] This restriction prevents the compiler from building ‘trampolines’. 12853This is a structure that is built on the stack and contains dynamic 12854code to be executed at run time. On some targets, a trampoline is 12855built for the following features: @code{Access}, 12856@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; 12857nested task bodies; primitive operations of nested tagged types. 12858Trampolines do not work on machines that prevent execution of stack 12859data. For example, on windows systems, enabling DEP (data execution 12860protection) will cause trampolines to raise an exception. 12861Trampolines are also quite slow at run time. 12862 12863On many targets, trampolines have been largely eliminated. Look at the 12864version of system.ads for your target — if it has 12865Always_Compatible_Rep equal to False, then trampolines are largely 12866eliminated. In particular, a trampoline is built for the following 12867features: @code{Address} of a nested subprogram; 12868@code{Access} or @code{Unrestricted_Access} of a nested subprogram, 12869but only if pragma Favor_Top_Level applies, or the access type has a 12870foreign-language convention; primitive operations of nested tagged 12871types. 12872 12873@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions 12874@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1dc} 12875@subsection No_Implicit_Heap_Allocations 12876 12877 12878@geindex No_Implicit_Heap_Allocations 12879 12880[RM D.7] No constructs are allowed to cause implicit heap allocation. 12881 12882@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions 12883@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1dd} 12884@subsection No_Implicit_Protected_Object_Allocations 12885 12886 12887@geindex No_Implicit_Protected_Object_Allocations 12888 12889[GNAT] No constructs are allowed to cause implicit heap allocation of a 12890protected object. 12891 12892@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions 12893@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1de} 12894@subsection No_Implicit_Task_Allocations 12895 12896 12897@geindex No_Implicit_Task_Allocations 12898 12899[GNAT] No constructs are allowed to cause implicit heap allocation of a task. 12900 12901@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions 12902@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1df} 12903@subsection No_Initialize_Scalars 12904 12905 12906@geindex No_Initialize_Scalars 12907 12908[GNAT] This restriction ensures that no unit in the partition is compiled with 12909pragma Initialize_Scalars. This allows the generation of more efficient 12910code, and in particular eliminates dummy null initialization routines that 12911are otherwise generated for some record and array types. 12912 12913@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions 12914@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e0} 12915@subsection No_IO 12916 12917 12918@geindex No_IO 12919 12920[RM H.4] This restriction ensures at compile time that there are no 12921dependences on any of the library units Sequential_IO, Direct_IO, 12922Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 12923 12924@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions 12925@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e1} 12926@subsection No_Local_Allocators 12927 12928 12929@geindex No_Local_Allocators 12930 12931[RM H.4] This restriction ensures at compile time that there are no 12932occurrences of an allocator in subprograms, generic subprograms, tasks, 12933and entry bodies. 12934 12935@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions 12936@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e2} 12937@subsection No_Local_Protected_Objects 12938 12939 12940@geindex No_Local_Protected_Objects 12941 12942[RM D.7] This restriction ensures at compile time that protected objects are 12943only declared at the library level. 12944 12945@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions 12946@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e3} 12947@subsection No_Local_Timing_Events 12948 12949 12950@geindex No_Local_Timing_Events 12951 12952[RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are 12953declared at the library level. 12954 12955@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions 12956@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e4} 12957@subsection No_Long_Long_Integers 12958 12959 12960@geindex No_Long_Long_Integers 12961 12962[GNAT] This partition-wide restriction forbids any explicit reference to 12963type Standard.Long_Long_Integer, and also forbids declaring range types whose 12964implicit base type is Long_Long_Integer, and modular types whose size exceeds 12965Long_Integer’Size. 12966 12967@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions 12968@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e5} 12969@subsection No_Multiple_Elaboration 12970 12971 12972@geindex No_Multiple_Elaboration 12973 12974[GNAT] When this restriction is active and the static elaboration model is 12975used, and -fpreserve-control-flow is not used, the compiler is allowed to 12976suppress the elaboration counter normally associated with the unit, even if 12977the unit has elaboration code. This counter is typically used to check for 12978access before elaboration and to control multiple elaboration attempts. If the 12979restriction is used, then the situations in which multiple elaboration is 12980possible, including non-Ada main programs and Stand Alone libraries, are not 12981permitted and will be diagnosed by the binder. 12982 12983@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions 12984@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e6} 12985@subsection No_Nested_Finalization 12986 12987 12988@geindex No_Nested_Finalization 12989 12990[RM D.7] All objects requiring finalization are declared at the library level. 12991 12992@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions 12993@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e7} 12994@subsection No_Protected_Type_Allocators 12995 12996 12997@geindex No_Protected_Type_Allocators 12998 12999[RM D.7] This restriction ensures at compile time that there are no allocator 13000expressions that attempt to allocate protected objects. 13001 13002@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions 13003@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e8} 13004@subsection No_Protected_Types 13005 13006 13007@geindex No_Protected_Types 13008 13009[RM H.4] This restriction ensures at compile time that there are no 13010declarations of protected types or protected objects. 13011 13012@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions 13013@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e9} 13014@subsection No_Recursion 13015 13016 13017@geindex No_Recursion 13018 13019[RM H.4] A program execution is erroneous if a subprogram is invoked as 13020part of its execution. 13021 13022@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions 13023@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1ea} 13024@subsection No_Reentrancy 13025 13026 13027@geindex No_Reentrancy 13028 13029[RM H.4] A program execution is erroneous if a subprogram is executed by 13030two tasks at the same time. 13031 13032@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions 13033@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1eb} 13034@subsection No_Relative_Delay 13035 13036 13037@geindex No_Relative_Delay 13038 13039[RM D.7] This restriction ensures at compile time that there are no delay 13040relative statements and prevents expressions such as @code{delay 1.23;} from 13041appearing in source code. 13042 13043@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions 13044@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1ec} 13045@subsection No_Requeue_Statements 13046 13047 13048@geindex No_Requeue_Statements 13049 13050[RM D.7] This restriction ensures at compile time that no requeue statements 13051are permitted and prevents keyword @code{requeue} from being used in source 13052code. 13053 13054@geindex No_Requeue 13055 13056The restriction @code{No_Requeue} is recognized as a 13057synonym for @code{No_Requeue_Statements}. This is retained for historical 13058compatibility purposes (and a warning will be generated for its use if 13059warnings on oNobsolescent features are activated). 13060 13061@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions 13062@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ed} 13063@subsection No_Secondary_Stack 13064 13065 13066@geindex No_Secondary_Stack 13067 13068[GNAT] This restriction ensures at compile time that the generated code 13069does not contain any reference to the secondary stack. The secondary 13070stack is used to implement functions returning unconstrained objects 13071(arrays or records) on some targets. Suppresses the allocation of 13072secondary stacks for tasks (excluding the environment task) at run time. 13073 13074@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions 13075@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ee} 13076@subsection No_Select_Statements 13077 13078 13079@geindex No_Select_Statements 13080 13081[RM D.7] This restriction ensures at compile time no select statements of any 13082kind are permitted, that is the keyword @code{select} may not appear. 13083 13084@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions 13085@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ef} 13086@subsection No_Specific_Termination_Handlers 13087 13088 13089@geindex No_Specific_Termination_Handlers 13090 13091[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 13092or to Ada.Task_Termination.Specific_Handler. 13093 13094@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions 13095@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f0} 13096@subsection No_Specification_of_Aspect 13097 13098 13099@geindex No_Specification_of_Aspect 13100 13101[RM 13.12.1] This restriction checks at compile time that no aspect 13102specification, attribute definition clause, or pragma is given for a 13103given aspect. 13104 13105@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions 13106@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f1} 13107@subsection No_Standard_Allocators_After_Elaboration 13108 13109 13110@geindex No_Standard_Allocators_After_Elaboration 13111 13112[RM D.7] Specifies that an allocator using a standard storage pool 13113should never be evaluated at run time after the elaboration of the 13114library items of the partition has completed. Otherwise, Storage_Error 13115is raised. 13116 13117@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions 13118@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f2} 13119@subsection No_Standard_Storage_Pools 13120 13121 13122@geindex No_Standard_Storage_Pools 13123 13124[GNAT] This restriction ensures at compile time that no access types 13125use the standard default storage pool. Any access type declared must 13126have an explicit Storage_Pool attribute defined specifying a 13127user-defined storage pool. 13128 13129@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions 13130@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f3} 13131@subsection No_Stream_Optimizations 13132 13133 13134@geindex No_Stream_Optimizations 13135 13136[GNAT] This restriction affects the performance of stream operations on types 13137@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the 13138compiler uses block reads and writes when manipulating @code{String} objects 13139due to their superior performance. When this restriction is in effect, the 13140compiler performs all IO operations on a per-character basis. 13141 13142@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions 13143@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f4} 13144@subsection No_Streams 13145 13146 13147@geindex No_Streams 13148 13149[GNAT] This restriction ensures at compile/bind time that there are no 13150stream objects created and no use of stream attributes. 13151This restriction does not forbid dependences on the package 13152@code{Ada.Streams}. So it is permissible to with 13153@code{Ada.Streams} (or another package that does so itself) 13154as long as no actual stream objects are created and no 13155stream attributes are used. 13156 13157Note that the use of restriction allows optimization of tagged types, 13158since they do not need to worry about dispatching stream operations. 13159To take maximum advantage of this space-saving optimization, any 13160unit declaring a tagged type should be compiled with the restriction, 13161though this is not required. 13162 13163@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions 13164@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f5} 13165@subsection No_Task_Allocators 13166 13167 13168@geindex No_Task_Allocators 13169 13170[RM D.7] There are no allocators for task types 13171or types containing task subcomponents. 13172 13173@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions 13174@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f6} 13175@subsection No_Task_At_Interrupt_Priority 13176 13177 13178@geindex No_Task_At_Interrupt_Priority 13179 13180[GNAT] This restriction ensures at compile time that there is no 13181Interrupt_Priority aspect or pragma for a task or a task type. As 13182a consequence, the tasks are always created with a priority below 13183that an interrupt priority. 13184 13185@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions 13186@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f7} 13187@subsection No_Task_Attributes_Package 13188 13189 13190@geindex No_Task_Attributes_Package 13191 13192[GNAT] This restriction ensures at compile time that there are no implicit or 13193explicit dependencies on the package @code{Ada.Task_Attributes}. 13194 13195@geindex No_Task_Attributes 13196 13197The restriction @code{No_Task_Attributes} is recognized as a synonym 13198for @code{No_Task_Attributes_Package}. This is retained for historical 13199compatibility purposes (and a warning will be generated for its use if 13200warnings on obsolescent features are activated). 13201 13202@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions 13203@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f8} 13204@subsection No_Task_Hierarchy 13205 13206 13207@geindex No_Task_Hierarchy 13208 13209[RM D.7] All (non-environment) tasks depend 13210directly on the environment task of the partition. 13211 13212@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions 13213@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f9} 13214@subsection No_Task_Termination 13215 13216 13217@geindex No_Task_Termination 13218 13219[RM D.7] Tasks that terminate are erroneous. 13220 13221@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions 13222@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fa} 13223@subsection No_Tasking 13224 13225 13226@geindex No_Tasking 13227 13228[GNAT] This restriction prevents the declaration of tasks or task types 13229throughout the partition. It is similar in effect to the use of 13230@code{Max_Tasks => 0} except that violations are caught at compile time 13231and cause an error message to be output either by the compiler or 13232binder. 13233 13234@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions 13235@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fb} 13236@subsection No_Terminate_Alternatives 13237 13238 13239@geindex No_Terminate_Alternatives 13240 13241[RM D.7] There are no selective accepts with terminate alternatives. 13242 13243@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions 13244@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fc} 13245@subsection No_Unchecked_Access 13246 13247 13248@geindex No_Unchecked_Access 13249 13250[RM H.4] This restriction ensures at compile time that there are no 13251occurrences of the Unchecked_Access attribute. 13252 13253@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions 13254@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fd} 13255@subsection No_Unchecked_Conversion 13256 13257 13258@geindex No_Unchecked_Conversion 13259 13260[RM J.13] This restriction ensures at compile time that there are no semantic 13261dependences on the predefined generic function Unchecked_Conversion. 13262 13263@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions 13264@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1fe} 13265@subsection No_Unchecked_Deallocation 13266 13267 13268@geindex No_Unchecked_Deallocation 13269 13270[RM J.13] This restriction ensures at compile time that there are no semantic 13271dependences on the predefined generic procedure Unchecked_Deallocation. 13272 13273@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions 13274@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1ff} 13275@subsection No_Use_Of_Entity 13276 13277 13278@geindex No_Use_Of_Entity 13279 13280[GNAT] This restriction ensures at compile time that there are no references 13281to the entity given in the form 13282 13283@example 13284No_Use_Of_Entity => Name 13285@end example 13286 13287where @code{Name} is the fully qualified entity, for example 13288 13289@example 13290No_Use_Of_Entity => Ada.Text_IO.Put_Line 13291@end example 13292 13293@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions 13294@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{200} 13295@subsection Pure_Barriers 13296 13297 13298@geindex Pure_Barriers 13299 13300[GNAT] This restriction ensures at compile time that protected entry 13301barriers are restricted to: 13302 13303 13304@itemize * 13305 13306@item 13307components of the protected object (excluding selection from dereferences), 13308 13309@item 13310constant declarations, 13311 13312@item 13313named numbers, 13314 13315@item 13316enumeration literals, 13317 13318@item 13319integer literals, 13320 13321@item 13322real literals, 13323 13324@item 13325character literals, 13326 13327@item 13328implicitly defined comparison operators, 13329 13330@item 13331uses of the Standard.”not” operator, 13332 13333@item 13334short-circuit operator, 13335 13336@item 13337the Count attribute 13338@end itemize 13339 13340This restriction is a relaxation of the Simple_Barriers restriction, 13341but still ensures absence of side effects, exceptions, and recursion 13342during the evaluation of the barriers. 13343 13344@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions 13345@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{201} 13346@subsection Simple_Barriers 13347 13348 13349@geindex Simple_Barriers 13350 13351[RM D.7] This restriction ensures at compile time that barriers in entry 13352declarations for protected types are restricted to either static boolean 13353expressions or references to simple boolean variables defined in the private 13354part of the protected type. No other form of entry barriers is permitted. 13355 13356@geindex Boolean_Entry_Barriers 13357 13358The restriction @code{Boolean_Entry_Barriers} is recognized as a 13359synonym for @code{Simple_Barriers}. This is retained for historical 13360compatibility purposes (and a warning will be generated for its use if 13361warnings on obsolescent features are activated). 13362 13363@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions 13364@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{202} 13365@subsection Static_Priorities 13366 13367 13368@geindex Static_Priorities 13369 13370[GNAT] This restriction ensures at compile time that all priority expressions 13371are static, and that there are no dependences on the package 13372@code{Ada.Dynamic_Priorities}. 13373 13374@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions 13375@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{203} 13376@subsection Static_Storage_Size 13377 13378 13379@geindex Static_Storage_Size 13380 13381[GNAT] This restriction ensures at compile time that any expression appearing 13382in a Storage_Size pragma or attribute definition clause is static. 13383 13384@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions 13385@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} 13386@section Program Unit Level Restrictions 13387 13388 13389The second set of restriction identifiers 13390does not require partition-wide consistency. 13391The restriction may be enforced for a single 13392compilation unit without any effect on any of the 13393other compilation units in the partition. 13394 13395@menu 13396* No_Elaboration_Code:: 13397* No_Dynamic_Accessibility_Checks:: 13398* No_Dynamic_Sized_Objects:: 13399* No_Entry_Queue:: 13400* No_Implementation_Aspect_Specifications:: 13401* No_Implementation_Attributes:: 13402* No_Implementation_Identifiers:: 13403* No_Implementation_Pragmas:: 13404* No_Implementation_Restrictions:: 13405* No_Implementation_Units:: 13406* No_Implicit_Aliasing:: 13407* No_Implicit_Loops:: 13408* No_Obsolescent_Features:: 13409* No_Wide_Characters:: 13410* Static_Dispatch_Tables:: 13411* SPARK_05:: 13412 13413@end menu 13414 13415@node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions 13416@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{206} 13417@subsection No_Elaboration_Code 13418 13419 13420@geindex No_Elaboration_Code 13421 13422[GNAT] This restriction ensures at compile time that no elaboration code is 13423generated. Note that this is not the same condition as is enforced 13424by pragma @code{Preelaborate}. There are cases in which pragma 13425@code{Preelaborate} still permits code to be generated (e.g., code 13426to initialize a large array to all zeroes), and there are cases of units 13427which do not meet the requirements for pragma @code{Preelaborate}, 13428but for which no elaboration code is generated. Generally, it is 13429the case that preelaborable units will meet the restrictions, with 13430the exception of large aggregates initialized with an others_clause, 13431and exception declarations (which generate calls to a run-time 13432registry procedure). This restriction is enforced on 13433a unit by unit basis, it need not be obeyed consistently 13434throughout a partition. 13435 13436In the case of aggregates with others, if the aggregate has a dynamic 13437size, there is no way to eliminate the elaboration code (such dynamic 13438bounds would be incompatible with @code{Preelaborate} in any case). If 13439the bounds are static, then use of this restriction actually modifies 13440the code choice of the compiler to avoid generating a loop, and instead 13441generate the aggregate statically if possible, no matter how many times 13442the data for the others clause must be repeatedly generated. 13443 13444It is not possible to precisely document 13445the constructs which are compatible with this restriction, since, 13446unlike most other restrictions, this is not a restriction on the 13447source code, but a restriction on the generated object code. For 13448example, if the source contains a declaration: 13449 13450@example 13451Val : constant Integer := X; 13452@end example 13453 13454where X is not a static constant, it may be possible, depending 13455on complex optimization circuitry, for the compiler to figure 13456out the value of X at compile time, in which case this initialization 13457can be done by the loader, and requires no initialization code. It 13458is not possible to document the precise conditions under which the 13459optimizer can figure this out. 13460 13461Note that this the implementation of this restriction requires full 13462code generation. If it is used in conjunction with “semantics only” 13463checking, then some cases of violations may be missed. 13464 13465When this restriction is active, we are not requesting control-flow 13466preservation with -fpreserve-control-flow, and the static elaboration model is 13467used, the compiler is allowed to suppress the elaboration counter normally 13468associated with the unit. This counter is typically used to check for access 13469before elaboration and to control multiple elaboration attempts. 13470 13471@node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions 13472@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{207} 13473@subsection No_Dynamic_Accessibility_Checks 13474 13475 13476@geindex No_Dynamic_Accessibility_Checks 13477 13478[GNAT] No dynamic accessibility checks are generated when this restriction is 13479in effect. Instead, dangling references are prevented via more conservative 13480compile-time checking. More specifically, existing compile-time checks are 13481enforced but with more conservative assumptions about the accessibility levels 13482of the relevant entities. These conservative assumptions eliminate the need for 13483dynamic accessibility checks. 13484 13485These new rules for computing (at compile-time) the accessibility level of an 13486anonymous access type T are as follows: 13487 13488 13489@itemize * 13490 13491@item 13492If T is a function result type then, from the caller’s perspective, its level 13493is that of the innermost master enclosing the function call. From the callee’s 13494perspective, the level of parameters and local variables of the callee is 13495statically deeper than the level of T. 13496 13497For any other accessibility level L such that the level of parameters and local 13498variables of the callee is statically deeper than L, the level of T (from the 13499callee’s perspective) is also statically deeper than L. 13500 13501@item 13502If T is the type of a formal parameter then, from the caller’s perspective, 13503its level is at least as deep as that of the type of the corresponding actual 13504parameter (whatever that actual parameter might be). From the callee’s 13505perspective, the level of parameters and local variables of the callee is 13506statically deeper than the level of T. 13507 13508@item 13509If T is the type of a discriminant then its level is that of the discriminated 13510type. 13511 13512@item 13513If T is the type of a stand-alone object then its level is the level of the 13514object. 13515 13516@item 13517In all other cases, the level of T is as defined by the existing rules of Ada. 13518@end itemize 13519 13520@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions 13521@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{208} 13522@subsection No_Dynamic_Sized_Objects 13523 13524 13525@geindex No_Dynamic_Sized_Objects 13526 13527[GNAT] This restriction disallows certain constructs that might lead to the 13528creation of dynamic-sized composite objects (or array or discriminated type). 13529An array subtype indication is illegal if the bounds are not static 13530or references to discriminants of an enclosing type. 13531A discriminated subtype indication is illegal if the type has 13532discriminant-dependent array components or a variant part, and the 13533discriminants are not static. In addition, array and record aggregates are 13534illegal in corresponding cases. Note that this restriction does not forbid 13535access discriminants. It is often a good idea to combine this restriction 13536with No_Secondary_Stack. 13537 13538@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions 13539@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{209} 13540@subsection No_Entry_Queue 13541 13542 13543@geindex No_Entry_Queue 13544 13545[GNAT] This restriction is a declaration that any protected entry compiled in 13546the scope of the restriction has at most one task waiting on the entry 13547at any one time, and so no queue is required. This restriction is not 13548checked at compile time. A program execution is erroneous if an attempt 13549is made to queue a second task on such an entry. 13550 13551@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions 13552@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{20a} 13553@subsection No_Implementation_Aspect_Specifications 13554 13555 13556@geindex No_Implementation_Aspect_Specifications 13557 13558[RM 13.12.1] This restriction checks at compile time that no 13559GNAT-defined aspects are present. With this restriction, the only 13560aspects that can be used are those defined in the Ada Reference Manual. 13561 13562@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions 13563@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{20b} 13564@subsection No_Implementation_Attributes 13565 13566 13567@geindex No_Implementation_Attributes 13568 13569[RM 13.12.1] This restriction checks at compile time that no 13570GNAT-defined attributes are present. With this restriction, the only 13571attributes that can be used are those defined in the Ada Reference 13572Manual. 13573 13574@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions 13575@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20c} 13576@subsection No_Implementation_Identifiers 13577 13578 13579@geindex No_Implementation_Identifiers 13580 13581[RM 13.12.1] This restriction checks at compile time that no 13582implementation-defined identifiers (marked with pragma Implementation_Defined) 13583occur within language-defined packages. 13584 13585@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions 13586@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20d} 13587@subsection No_Implementation_Pragmas 13588 13589 13590@geindex No_Implementation_Pragmas 13591 13592[RM 13.12.1] This restriction checks at compile time that no 13593GNAT-defined pragmas are present. With this restriction, the only 13594pragmas that can be used are those defined in the Ada Reference Manual. 13595 13596@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions 13597@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20e} 13598@subsection No_Implementation_Restrictions 13599 13600 13601@geindex No_Implementation_Restrictions 13602 13603[GNAT] This restriction checks at compile time that no GNAT-defined restriction 13604identifiers (other than @code{No_Implementation_Restrictions} itself) 13605are present. With this restriction, the only other restriction identifiers 13606that can be used are those defined in the Ada Reference Manual. 13607 13608@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions 13609@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20f} 13610@subsection No_Implementation_Units 13611 13612 13613@geindex No_Implementation_Units 13614 13615[RM 13.12.1] This restriction checks at compile time that there is no 13616mention in the context clause of any implementation-defined descendants 13617of packages Ada, Interfaces, or System. 13618 13619@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions 13620@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{210} 13621@subsection No_Implicit_Aliasing 13622 13623 13624@geindex No_Implicit_Aliasing 13625 13626[GNAT] This restriction, which is not required to be partition-wide consistent, 13627requires an explicit aliased keyword for an object to which ‘Access, 13628‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of 13629the ‘Unrestricted_Access attribute for objects. Note: the reason that 13630Unrestricted_Access is forbidden is that it would require the prefix 13631to be aliased, and in such cases, it can always be replaced by 13632the standard attribute Unchecked_Access which is preferable. 13633 13634@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions 13635@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{211} 13636@subsection No_Implicit_Loops 13637 13638 13639@geindex No_Implicit_Loops 13640 13641[GNAT] This restriction ensures that the generated code of the unit marked 13642with this restriction does not contain any implicit @code{for} loops, either by 13643modifying the generated code where possible, or by rejecting any construct 13644that would otherwise generate an implicit @code{for} loop. If this restriction is 13645active, it is possible to build large array aggregates with all static 13646components without generating an intermediate temporary, and without generating 13647a loop to initialize individual components. Otherwise, a loop is created for 13648arrays larger than about 5000 scalar components. Note that if this restriction 13649is set in the spec of a package, it will not apply to its body. 13650 13651@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions 13652@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{212} 13653@subsection No_Obsolescent_Features 13654 13655 13656@geindex No_Obsolescent_Features 13657 13658[RM 13.12.1] This restriction checks at compile time that no obsolescent 13659features are used, as defined in Annex J of the Ada Reference Manual. 13660 13661@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions 13662@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{213} 13663@subsection No_Wide_Characters 13664 13665 13666@geindex No_Wide_Characters 13667 13668[GNAT] This restriction ensures at compile time that no uses of the types 13669@code{Wide_Character} or @code{Wide_String} or corresponding wide 13670wide types 13671appear, and that no wide or wide wide string or character literals 13672appear in the program (that is literals representing characters not in 13673type @code{Character}). 13674 13675@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions 13676@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{214} 13677@subsection Static_Dispatch_Tables 13678 13679 13680@geindex Static_Dispatch_Tables 13681 13682[GNAT] This restriction checks at compile time that all the artifacts 13683associated with dispatch tables can be placed in read-only memory. 13684 13685@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions 13686@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{215} 13687@subsection SPARK_05 13688 13689 13690@geindex SPARK_05 13691 13692[GNAT] This restriction no longer has any effect and is superseded by 13693SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that 13694a codebase respects SPARK 2014 restrictions, mark the code with pragma or 13695aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as 13696follows: 13697 13698@example 13699gnatprove -P project.gpr --mode=stone 13700@end example 13701 13702or equivalently: 13703 13704@example 13705gnatprove -P project.gpr --mode=check_all 13706@end example 13707 13708@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top 13709@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} 13710@chapter Implementation Advice 13711 13712 13713The main text of the Ada Reference Manual describes the required 13714behavior of all Ada compilers, and the GNAT compiler conforms to 13715these requirements. 13716 13717In addition, there are sections throughout the Ada Reference Manual headed 13718by the phrase ‘Implementation advice’. These sections are not normative, 13719i.e., they do not specify requirements that all compilers must 13720follow. Rather they provide advice on generally desirable behavior. 13721They are not requirements, because they describe behavior that cannot 13722be provided on all systems, or may be undesirable on some systems. 13723 13724As far as practical, GNAT follows the implementation advice in 13725the Ada Reference Manual. Each such RM section corresponds to a section 13726in this chapter whose title specifies the 13727RM section number and paragraph number and the subject of 13728the advice. The contents of each section consists of the RM text within 13729quotation marks, 13730followed by the GNAT interpretation of the advice. Most often, this simply says 13731‘followed’, which means that GNAT follows the advice. However, in a 13732number of cases, GNAT deliberately deviates from this advice, in which 13733case the text describes what GNAT does and why. 13734 13735@geindex Error detection 13736 13737@menu 13738* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 13739* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 13740* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 13741* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 13742* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 13743* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 13744* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 13745* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 13746* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 13747* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 13748* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 13749* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. 13750* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 13751* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 13752* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 13753* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 13754* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 13755* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 13756* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 13757* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 13758* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 13759* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 13760* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 13761* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 13762* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 13763* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 13764* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 13765* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 13766* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 13767* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 13768* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 13769* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 13770* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 13771* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 13772* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 13773* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 13774* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 13775* RM A.18; Containers: RM A 18 Containers. 13776* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 13777* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 13778* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 13779* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 13780* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 13781* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 13782* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 13783* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 13784* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 13785* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 13786* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 13787* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 13788* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 13789* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 13790* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 13791* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 13792* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 13793* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 13794* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 13795* RM F(7); COBOL Support: RM F 7 COBOL Support. 13796* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 13797* RM G; Numerics: RM G Numerics. 13798* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 13799* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 13800* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 13801* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 13802* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 13803 13804@end menu 13805 13806@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice 13807@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{218} 13808@section RM 1.1.3(20): Error Detection 13809 13810 13811@quotation 13812 13813“If an implementation detects the use of an unsupported Specialized Needs 13814Annex feature at run time, it should raise @code{Program_Error} if 13815feasible.” 13816@end quotation 13817 13818Not relevant. All specialized needs annex features are either supported, 13819or diagnosed at compile time. 13820 13821@geindex Child Units 13822 13823@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice 13824@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{219} 13825@section RM 1.1.3(31): Child Units 13826 13827 13828@quotation 13829 13830“If an implementation wishes to provide implementation-defined 13831extensions to the functionality of a language-defined library unit, it 13832should normally do so by adding children to the library unit.” 13833@end quotation 13834 13835Followed. 13836 13837@geindex Bounded errors 13838 13839@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice 13840@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{21a} 13841@section RM 1.1.5(12): Bounded Errors 13842 13843 13844@quotation 13845 13846“If an implementation detects a bounded error or erroneous 13847execution, it should raise @code{Program_Error}.” 13848@end quotation 13849 13850Followed in all cases in which the implementation detects a bounded 13851error or erroneous execution. Not all such situations are detected at 13852runtime. 13853 13854@geindex Pragmas 13855 13856@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice 13857@anchor{gnat_rm/implementation_advice id2}@anchor{21b}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21c} 13858@section RM 2.8(16): Pragmas 13859 13860 13861@quotation 13862 13863“Normally, implementation-defined pragmas should have no semantic effect 13864for error-free programs; that is, if the implementation-defined pragmas 13865are removed from a working program, the program should still be legal, 13866and should still have the same semantics.” 13867@end quotation 13868 13869The following implementation defined pragmas are exceptions to this 13870rule: 13871 13872 13873@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 13874@headitem 13875 13876Pragma 13877 13878@tab 13879 13880Explanation 13881 13882@item 13883 13884@emph{Abort_Defer} 13885 13886@tab 13887 13888Affects semantics 13889 13890@item 13891 13892@emph{Ada_83} 13893 13894@tab 13895 13896Affects legality 13897 13898@item 13899 13900@emph{Assert} 13901 13902@tab 13903 13904Affects semantics 13905 13906@item 13907 13908@emph{CPP_Class} 13909 13910@tab 13911 13912Affects semantics 13913 13914@item 13915 13916@emph{CPP_Constructor} 13917 13918@tab 13919 13920Affects semantics 13921 13922@item 13923 13924@emph{Debug} 13925 13926@tab 13927 13928Affects semantics 13929 13930@item 13931 13932@emph{Interface_Name} 13933 13934@tab 13935 13936Affects semantics 13937 13938@item 13939 13940@emph{Machine_Attribute} 13941 13942@tab 13943 13944Affects semantics 13945 13946@item 13947 13948@emph{Unimplemented_Unit} 13949 13950@tab 13951 13952Affects legality 13953 13954@item 13955 13956@emph{Unchecked_Union} 13957 13958@tab 13959 13960Affects semantics 13961 13962@end multitable 13963 13964 13965In each of the above cases, it is essential to the purpose of the pragma 13966that this advice not be followed. For details see 13967@ref{7,,Implementation Defined Pragmas}. 13968 13969@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice 13970@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21d} 13971@section RM 2.8(17-19): Pragmas 13972 13973 13974@quotation 13975 13976“Normally, an implementation should not define pragmas that can 13977make an illegal program legal, except as follows: 13978 13979 13980@itemize * 13981 13982@item 13983A pragma used to complete a declaration, such as a pragma @code{Import}; 13984 13985@item 13986A pragma used to configure the environment by adding, removing, or 13987replacing @code{library_items}.” 13988@end itemize 13989@end quotation 13990 13991See @ref{21c,,RM 2.8(16); Pragmas}. 13992 13993@geindex Character Sets 13994 13995@geindex Alternative Character Sets 13996 13997@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice 13998@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21e} 13999@section RM 3.5.2(5): Alternative Character Sets 14000 14001 14002@quotation 14003 14004“If an implementation supports a mode with alternative interpretations 14005for @code{Character} and @code{Wide_Character}, the set of graphic 14006characters of @code{Character} should nevertheless remain a proper 14007subset of the set of graphic characters of @code{Wide_Character}. Any 14008character set ‘localizations’ should be reflected in the results of 14009the subprograms defined in the language-defined package 14010@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 14011an alternative interpretation of @code{Character}, the implementation should 14012also support a corresponding change in what is a legal 14013@code{identifier_letter}.” 14014@end quotation 14015 14016Not all wide character modes follow this advice, in particular the JIS 14017and IEC modes reflect standard usage in Japan, and in these encoding, 14018the upper half of the Latin-1 set is not part of the wide-character 14019subset, since the most significant bit is used for wide character 14020encoding. However, this only applies to the external forms. Internally 14021there is no such restriction. 14022 14023@geindex Integer types 14024 14025@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 14026@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21f} 14027@section RM 3.5.4(28): Integer Types 14028 14029 14030@quotation 14031 14032“An implementation should support @code{Long_Integer} in addition to 14033@code{Integer} if the target machine supports 32-bit (or longer) 14034arithmetic. No other named integer subtypes are recommended for package 14035@code{Standard}. Instead, appropriate named integer subtypes should be 14036provided in the library package @code{Interfaces} (see B.2).” 14037@end quotation 14038 14039@code{Long_Integer} is supported. Other standard integer types are supported 14040so this advice is not fully followed. These types 14041are supported for convenient interface to C, and so that all hardware 14042types of the machine are easily available. 14043 14044@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice 14045@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{220} 14046@section RM 3.5.4(29): Integer Types 14047 14048 14049@quotation 14050 14051“An implementation for a two’s complement machine should support 14052modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 14053implementation should support a non-binary modules up to @code{Integer'Last}.” 14054@end quotation 14055 14056Followed. 14057 14058@geindex Enumeration values 14059 14060@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice 14061@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{221} 14062@section RM 3.5.5(8): Enumeration Values 14063 14064 14065@quotation 14066 14067“For the evaluation of a call on @code{S'Pos} for an enumeration 14068subtype, if the value of the operand does not correspond to the internal 14069code for any enumeration literal of its type (perhaps due to an 14070un-initialized variable), then the implementation should raise 14071@code{Program_Error}. This is particularly important for enumeration 14072types with noncontiguous internal codes specified by an 14073enumeration_representation_clause.” 14074@end quotation 14075 14076Followed. 14077 14078@geindex Float types 14079 14080@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice 14081@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{222} 14082@section RM 3.5.7(17): Float Types 14083 14084 14085@quotation 14086 14087“An implementation should support @code{Long_Float} in addition to 14088@code{Float} if the target machine supports 11 or more digits of 14089precision. No other named floating point subtypes are recommended for 14090package @code{Standard}. Instead, appropriate named floating point subtypes 14091should be provided in the library package @code{Interfaces} (see B.2).” 14092@end quotation 14093 14094@code{Short_Float} and @code{Long_Long_Float} are also provided. The 14095former provides improved compatibility with other implementations 14096supporting this type. The latter corresponds to the highest precision 14097floating-point type supported by the hardware. On most machines, this 14098will be the same as @code{Long_Float}, but on some machines, it will 14099correspond to the IEEE extended form. The notable case is all x86 14100implementations, where @code{Long_Long_Float} corresponds to the 80-bit 14101extended precision format supported in hardware on this processor. 14102Note that the 128-bit format on SPARC is not supported, since this 14103is a software rather than a hardware format. 14104 14105@geindex Multidimensional arrays 14106 14107@geindex Arrays 14108@geindex multidimensional 14109 14110@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice 14111@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{223} 14112@section RM 3.6.2(11): Multidimensional Arrays 14113 14114 14115@quotation 14116 14117“An implementation should normally represent multidimensional arrays in 14118row-major order, consistent with the notation used for multidimensional 14119array aggregates (see 4.3.3). However, if a pragma @code{Convention} 14120(@code{Fortran}, …) applies to a multidimensional array type, then 14121column-major order should be used instead (see B.5, @emph{Interfacing with Fortran}).” 14122@end quotation 14123 14124Followed. 14125 14126@geindex Duration'Small 14127 14128@node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice 14129@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{224} 14130@section RM 9.6(30-31): Duration’Small 14131 14132 14133@quotation 14134 14135“Whenever possible in an implementation, the value of @code{Duration'Small} 14136should be no greater than 100 microseconds.” 14137@end quotation 14138 14139Followed. (@code{Duration'Small} = 10**(-9)). 14140 14141@quotation 14142 14143“The time base for @code{delay_relative_statements} should be monotonic; 14144it need not be the same time base as used for @code{Calendar.Clock}.” 14145@end quotation 14146 14147Followed. 14148 14149@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice 14150@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{225} 14151@section RM 10.2.1(12): Consistent Representation 14152 14153 14154@quotation 14155 14156“In an implementation, a type declared in a pre-elaborated package should 14157have the same representation in every elaboration of a given version of 14158the package, whether the elaborations occur in distinct executions of 14159the same program, or in executions of distinct programs or partitions 14160that include the given version.” 14161@end quotation 14162 14163Followed, except in the case of tagged types. Tagged types involve 14164implicit pointers to a local copy of a dispatch table, and these pointers 14165have representations which thus depend on a particular elaboration of the 14166package. It is not easy to see how it would be possible to follow this 14167advice without severely impacting efficiency of execution. 14168 14169@geindex Exception information 14170 14171@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice 14172@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{226} 14173@section RM 11.4.1(19): Exception Information 14174 14175 14176@quotation 14177 14178“@code{Exception_Message} by default and @code{Exception_Information} 14179should produce information useful for 14180debugging. @code{Exception_Message} should be short, about one 14181line. @code{Exception_Information} can be long. @code{Exception_Message} 14182should not include the 14183@code{Exception_Name}. @code{Exception_Information} should include both 14184the @code{Exception_Name} and the @code{Exception_Message}.” 14185@end quotation 14186 14187Followed. For each exception that doesn’t have a specified 14188@code{Exception_Message}, the compiler generates one containing the location 14189of the raise statement. This location has the form ‘file_name:line’, where 14190file_name is the short file name (without path information) and line is the line 14191number in the file. Note that in the case of the Zero Cost Exception 14192mechanism, these messages become redundant with the Exception_Information that 14193contains a full backtrace of the calling sequence, so they are disabled. 14194To disable explicitly the generation of the source location message, use the 14195Pragma @code{Discard_Names}. 14196 14197@geindex Suppression of checks 14198 14199@geindex Checks 14200@geindex suppression of 14201 14202@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice 14203@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{227} 14204@section RM 11.5(28): Suppression of Checks 14205 14206 14207@quotation 14208 14209“The implementation should minimize the code executed for checks that 14210have been suppressed.” 14211@end quotation 14212 14213Followed. 14214 14215@geindex Representation clauses 14216 14217@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice 14218@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{228} 14219@section RM 13.1 (21-24): Representation Clauses 14220 14221 14222@quotation 14223 14224“The recommended level of support for all representation items is 14225qualified as follows: 14226 14227An implementation need not support representation items containing 14228nonstatic expressions, except that an implementation should support a 14229representation item for a given entity if each nonstatic expression in 14230the representation item is a name that statically denotes a constant 14231declared before the entity.” 14232@end quotation 14233 14234Followed. In fact, GNAT goes beyond the recommended level of support 14235by allowing nonstatic expressions in some representation clauses even 14236without the need to declare constants initialized with the values of 14237such expressions. 14238For example: 14239 14240@example 14241 X : Integer; 14242 Y : Float; 14243 for Y'Address use X'Address;>> 14244 14245 14246"An implementation need not support a specification for the `@w{`}Size`@w{`} 14247for a given composite subtype, nor the size or storage place for an 14248object (including a component) of a given composite subtype, unless the 14249constraints on the subtype and its composite subcomponents (if any) are 14250all static constraints." 14251@end example 14252 14253Followed. Size Clauses are not permitted on nonstatic components, as 14254described above. 14255 14256@quotation 14257 14258“An aliased component, or a component whose type is by-reference, should 14259always be allocated at an addressable location.” 14260@end quotation 14261 14262Followed. 14263 14264@geindex Packed types 14265 14266@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice 14267@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{229} 14268@section RM 13.2(6-8): Packed Types 14269 14270 14271@quotation 14272 14273“If a type is packed, then the implementation should try to minimize 14274storage allocated to objects of the type, possibly at the expense of 14275speed of accessing components, subject to reasonable complexity in 14276addressing calculations. 14277 14278The recommended level of support pragma @code{Pack} is: 14279 14280For a packed record type, the components should be packed as tightly as 14281possible subject to the Sizes of the component subtypes, and subject to 14282any @emph{record_representation_clause} that applies to the type; the 14283implementation may, but need not, reorder components or cross aligned 14284word boundaries to improve the packing. A component whose @code{Size} is 14285greater than the word size may be allocated an integral number of words.” 14286@end quotation 14287 14288Followed. Tight packing of arrays is supported for all component sizes 14289up to 64-bits. If the array component size is 1 (that is to say, if 14290the component is a boolean type or an enumeration type with two values) 14291then values of the type are implicitly initialized to zero. This 14292happens both for objects of the packed type, and for objects that have a 14293subcomponent of the packed type. 14294 14295@quotation 14296 14297“An implementation should support Address clauses for imported 14298subprograms.” 14299@end quotation 14300 14301Followed. 14302 14303@geindex Address clauses 14304 14305@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice 14306@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{22a} 14307@section RM 13.3(14-19): Address Clauses 14308 14309 14310@quotation 14311 14312“For an array @code{X}, @code{X'Address} should point at the first 14313component of the array, and not at the array bounds.” 14314@end quotation 14315 14316Followed. 14317 14318@quotation 14319 14320“The recommended level of support for the @code{Address} attribute is: 14321 14322@code{X'Address} should produce a useful result if @code{X} is an 14323object that is aliased or of a by-reference type, or is an entity whose 14324@code{Address} has been specified.” 14325@end quotation 14326 14327Followed. A valid address will be produced even if none of those 14328conditions have been met. If necessary, the object is forced into 14329memory to ensure the address is valid. 14330 14331@quotation 14332 14333“An implementation should support @code{Address} clauses for imported 14334subprograms.” 14335@end quotation 14336 14337Followed. 14338 14339@quotation 14340 14341“Objects (including subcomponents) that are aliased or of a by-reference 14342type should be allocated on storage element boundaries.” 14343@end quotation 14344 14345Followed. 14346 14347@quotation 14348 14349“If the @code{Address} of an object is specified, or it is imported or exported, 14350then the implementation should not perform optimizations based on 14351assumptions of no aliases.” 14352@end quotation 14353 14354Followed. 14355 14356@geindex Alignment clauses 14357 14358@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice 14359@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{22b} 14360@section RM 13.3(29-35): Alignment Clauses 14361 14362 14363@quotation 14364 14365“The recommended level of support for the @code{Alignment} attribute for 14366subtypes is: 14367 14368An implementation should support specified Alignments that are factors 14369and multiples of the number of storage elements per word, subject to the 14370following:” 14371@end quotation 14372 14373Followed. 14374 14375@quotation 14376 14377“An implementation need not support specified Alignments for 14378combinations of Sizes and Alignments that cannot be easily 14379loaded and stored by available machine instructions.” 14380@end quotation 14381 14382Followed. 14383 14384@quotation 14385 14386“An implementation need not support specified Alignments that are 14387greater than the maximum @code{Alignment} the implementation ever returns by 14388default.” 14389@end quotation 14390 14391Followed. 14392 14393@quotation 14394 14395“The recommended level of support for the @code{Alignment} attribute for 14396objects is: 14397 14398Same as above, for subtypes, but in addition:” 14399@end quotation 14400 14401Followed. 14402 14403@quotation 14404 14405“For stand-alone library-level objects of statically constrained 14406subtypes, the implementation should support all alignments 14407supported by the target linker. For example, page alignment is likely to 14408be supported for such objects, but not for subtypes.” 14409@end quotation 14410 14411Followed. 14412 14413@geindex Size clauses 14414 14415@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice 14416@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22c} 14417@section RM 13.3(42-43): Size Clauses 14418 14419 14420@quotation 14421 14422“The recommended level of support for the @code{Size} attribute of 14423objects is: 14424 14425A @code{Size} clause should be supported for an object if the specified 14426@code{Size} is at least as large as its subtype’s @code{Size}, and 14427corresponds to a size in storage elements that is a multiple of the 14428object’s @code{Alignment} (if the @code{Alignment} is nonzero).” 14429@end quotation 14430 14431Followed. 14432 14433@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 14434@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22d} 14435@section RM 13.3(50-56): Size Clauses 14436 14437 14438@quotation 14439 14440“If the @code{Size} of a subtype is specified, and allows for efficient 14441independent addressability (see 9.10) on the target architecture, then 14442the @code{Size} of the following objects of the subtype should equal the 14443@code{Size} of the subtype: 14444 14445Aliased objects (including components).” 14446@end quotation 14447 14448Followed. 14449 14450@quotation 14451 14452“@cite{Size} clause on a composite subtype should not affect the 14453internal layout of components.” 14454@end quotation 14455 14456Followed. But note that this can be overridden by use of the implementation 14457pragma Implicit_Packing in the case of packed arrays. 14458 14459@quotation 14460 14461“The recommended level of support for the @code{Size} attribute of subtypes is: 14462 14463The @code{Size} (if not specified) of a static discrete or fixed point 14464subtype should be the number of bits needed to represent each value 14465belonging to the subtype using an unbiased representation, leaving space 14466for a sign bit only if the subtype contains negative values. If such a 14467subtype is a first subtype, then an implementation should support a 14468specified @code{Size} for it that reflects this representation.” 14469@end quotation 14470 14471Followed. 14472 14473@quotation 14474 14475“For a subtype implemented with levels of indirection, the @code{Size} 14476should include the size of the pointers, but not the size of what they 14477point at.” 14478@end quotation 14479 14480Followed. 14481 14482@geindex Component_Size clauses 14483 14484@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 14485@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22e} 14486@section RM 13.3(71-73): Component Size Clauses 14487 14488 14489@quotation 14490 14491“The recommended level of support for the @code{Component_Size} 14492attribute is: 14493 14494An implementation need not support specified @code{Component_Sizes} that are 14495less than the @code{Size} of the component subtype.” 14496@end quotation 14497 14498Followed. 14499 14500@quotation 14501 14502“An implementation should support specified Component_Sizes that 14503are factors and multiples of the word size. For such 14504Component_Sizes, the array should contain no gaps between 14505components. For other Component_Sizes (if supported), the array 14506should contain no gaps between components when packing is also 14507specified; the implementation should forbid this combination in cases 14508where it cannot support a no-gaps representation.” 14509@end quotation 14510 14511Followed. 14512 14513@geindex Enumeration representation clauses 14514 14515@geindex Representation clauses 14516@geindex enumeration 14517 14518@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 14519@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22f} 14520@section RM 13.4(9-10): Enumeration Representation Clauses 14521 14522 14523@quotation 14524 14525“The recommended level of support for enumeration representation clauses 14526is: 14527 14528An implementation need not support enumeration representation clauses 14529for boolean types, but should at minimum support the internal codes in 14530the range @code{System.Min_Int .. System.Max_Int}.” 14531@end quotation 14532 14533Followed. 14534 14535@geindex Record representation clauses 14536 14537@geindex Representation clauses 14538@geindex records 14539 14540@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 14541@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{230} 14542@section RM 13.5.1(17-22): Record Representation Clauses 14543 14544 14545@quotation 14546 14547“The recommended level of support for 14548@emph{record_representation_clause}s is: 14549 14550An implementation should support storage places that can be extracted 14551with a load, mask, shift sequence of machine code, and set with a load, 14552shift, mask, store sequence, given the available machine instructions 14553and run-time model.” 14554@end quotation 14555 14556Followed. 14557 14558@quotation 14559 14560“A storage place should be supported if its size is equal to the 14561@code{Size} of the component subtype, and it starts and ends on a 14562boundary that obeys the @code{Alignment} of the component subtype.” 14563@end quotation 14564 14565Followed. 14566 14567@quotation 14568 14569“If the default bit ordering applies to the declaration of a given type, 14570then for a component whose subtype’s @code{Size} is less than the word 14571size, any storage place that does not cross an aligned word boundary 14572should be supported.” 14573@end quotation 14574 14575Followed. 14576 14577@quotation 14578 14579“An implementation may reserve a storage place for the tag field of a 14580tagged type, and disallow other components from overlapping that place.” 14581@end quotation 14582 14583Followed. The storage place for the tag field is the beginning of the tagged 14584record, and its size is Address’Size. GNAT will reject an explicit component 14585clause for the tag field. 14586 14587@quotation 14588 14589“An implementation need not support a @emph{component_clause} for a 14590component of an extension part if the storage place is not after the 14591storage places of all components of the parent type, whether or not 14592those storage places had been specified.” 14593@end quotation 14594 14595Followed. The above advice on record representation clauses is followed, 14596and all mentioned features are implemented. 14597 14598@geindex Storage place attributes 14599 14600@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 14601@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{231} 14602@section RM 13.5.2(5): Storage Place Attributes 14603 14604 14605@quotation 14606 14607“If a component is represented using some form of pointer (such as an 14608offset) to the actual data of the component, and this data is contiguous 14609with the rest of the object, then the storage place attributes should 14610reflect the place of the actual data, not the pointer. If a component is 14611allocated discontinuously from the rest of the object, then a warning 14612should be generated upon reference to one of its storage place 14613attributes.” 14614@end quotation 14615 14616Followed. There are no such components in GNAT. 14617 14618@geindex Bit ordering 14619 14620@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 14621@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{232} 14622@section RM 13.5.3(7-8): Bit Ordering 14623 14624 14625@quotation 14626 14627“The recommended level of support for the non-default bit ordering is: 14628 14629If @code{Word_Size} = @code{Storage_Unit}, then the implementation 14630should support the non-default bit ordering in addition to the default 14631bit ordering.” 14632@end quotation 14633 14634Followed. Word size does not equal storage size in this implementation. 14635Thus non-default bit ordering is not supported. 14636 14637@geindex Address 14638@geindex as private type 14639 14640@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 14641@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{233} 14642@section RM 13.7(37): Address as Private 14643 14644 14645@quotation 14646 14647“@cite{Address} should be of a private type.” 14648@end quotation 14649 14650Followed. 14651 14652@geindex Operations 14653@geindex on `@w{`}Address`@w{`} 14654 14655@geindex Address 14656@geindex operations of 14657 14658@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice 14659@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{234} 14660@section RM 13.7.1(16): Address Operations 14661 14662 14663@quotation 14664 14665“Operations in @code{System} and its children should reflect the target 14666environment semantics as closely as is reasonable. For example, on most 14667machines, it makes sense for address arithmetic to ‘wrap around’. 14668Operations that do not make sense should raise @code{Program_Error}.” 14669@end quotation 14670 14671Followed. Address arithmetic is modular arithmetic that wraps around. No 14672operation raises @code{Program_Error}, since all operations make sense. 14673 14674@geindex Unchecked conversion 14675 14676@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 14677@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{235} 14678@section RM 13.9(14-17): Unchecked Conversion 14679 14680 14681@quotation 14682 14683“The @code{Size} of an array object should not include its bounds; hence, 14684the bounds should not be part of the converted data.” 14685@end quotation 14686 14687Followed. 14688 14689@quotation 14690 14691“The implementation should not generate unnecessary run-time checks to 14692ensure that the representation of @code{S} is a representation of the 14693target type. It should take advantage of the permission to return by 14694reference when possible. Restrictions on unchecked conversions should be 14695avoided unless required by the target environment.” 14696@end quotation 14697 14698Followed. There are no restrictions on unchecked conversion. A warning is 14699generated if the source and target types do not have the same size since 14700the semantics in this case may be target dependent. 14701 14702@quotation 14703 14704“The recommended level of support for unchecked conversions is: 14705 14706Unchecked conversions should be supported and should be reversible in 14707the cases where this clause defines the result. To enable meaningful use 14708of unchecked conversion, a contiguous representation should be used for 14709elementary subtypes, for statically constrained array subtypes whose 14710component subtype is one of the subtypes described in this paragraph, 14711and for record subtypes without discriminants whose component subtypes 14712are described in this paragraph.” 14713@end quotation 14714 14715Followed. 14716 14717@geindex Heap usage 14718@geindex implicit 14719 14720@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 14721@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{236} 14722@section RM 13.11(23-25): Implicit Heap Usage 14723 14724 14725@quotation 14726 14727“An implementation should document any cases in which it dynamically 14728allocates heap storage for a purpose other than the evaluation of an 14729allocator.” 14730@end quotation 14731 14732Followed, the only other points at which heap storage is dynamically 14733allocated are as follows: 14734 14735 14736@itemize * 14737 14738@item 14739At initial elaboration time, to allocate dynamically sized global 14740objects. 14741 14742@item 14743To allocate space for a task when a task is created. 14744 14745@item 14746To extend the secondary stack dynamically when needed. The secondary 14747stack is used for returning variable length results. 14748@end itemize 14749 14750 14751@quotation 14752 14753“A default (implementation-provided) storage pool for an 14754access-to-constant type should not have overhead to support deallocation of 14755individual objects.” 14756@end quotation 14757 14758Followed. 14759 14760@quotation 14761 14762“A storage pool for an anonymous access type should be created at the 14763point of an allocator for the type, and be reclaimed when the designated 14764object becomes inaccessible.” 14765@end quotation 14766 14767Followed. 14768 14769@geindex Unchecked deallocation 14770 14771@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 14772@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{237} 14773@section RM 13.11.2(17): Unchecked Deallocation 14774 14775 14776@quotation 14777 14778“For a standard storage pool, @code{Free} should actually reclaim the 14779storage.” 14780@end quotation 14781 14782Followed. 14783 14784@geindex Stream oriented attributes 14785 14786@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 14787@anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{238} 14788@section RM 13.13.2(1.6): Stream Oriented Attributes 14789 14790 14791@quotation 14792 14793“If not specified, the value of Stream_Size for an elementary type 14794should be the number of bits that corresponds to the minimum number of 14795stream elements required by the first subtype of the type, rounded up 14796to the nearest factor or multiple of the word size that is also a 14797multiple of the stream element size.” 14798@end quotation 14799 14800Followed, except that the number of stream elements is 1, 2, 3, 4 or 8. 14801The Stream_Size may be used to override the default choice. 14802 14803The default implementation is based on direct binary representations and is 14804therefore target- and endianness-dependent. To address this issue, GNAT also 14805supplies an alternate implementation of the stream attributes @code{Read} and 14806@code{Write}, which uses the target-independent XDR standard representation for 14807scalar types. This XDR alternative can be enabled via the binder switch -xdr. 14808 14809@geindex XDR representation 14810 14811@geindex Read attribute 14812 14813@geindex Write attribute 14814 14815@geindex Stream oriented attributes 14816 14817@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 14818@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{239} 14819@section RM A.1(52): Names of Predefined Numeric Types 14820 14821 14822@quotation 14823 14824“If an implementation provides additional named predefined integer types, 14825then the names should end with @code{Integer} as in 14826@code{Long_Integer}. If an implementation provides additional named 14827predefined floating point types, then the names should end with 14828@code{Float} as in @code{Long_Float}.” 14829@end quotation 14830 14831Followed. 14832 14833@geindex Ada.Characters.Handling 14834 14835@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 14836@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{23a} 14837@section RM A.3.2(49): @code{Ada.Characters.Handling} 14838 14839 14840@quotation 14841 14842“If an implementation provides a localized definition of @code{Character} 14843or @code{Wide_Character}, then the effects of the subprograms in 14844@code{Characters.Handling} should reflect the localizations. 14845See also 3.5.2.” 14846@end quotation 14847 14848Followed. GNAT provides no such localized definitions. 14849 14850@geindex Bounded-length strings 14851 14852@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 14853@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{23b} 14854@section RM A.4.4(106): Bounded-Length String Handling 14855 14856 14857@quotation 14858 14859“Bounded string objects should not be implemented by implicit pointers 14860and dynamic allocation.” 14861@end quotation 14862 14863Followed. No implicit pointers or dynamic allocation are used. 14864 14865@geindex Random number generation 14866 14867@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 14868@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23c} 14869@section RM A.5.2(46-47): Random Number Generation 14870 14871 14872@quotation 14873 14874“Any storage associated with an object of type @code{Generator} should be 14875reclaimed on exit from the scope of the object.” 14876@end quotation 14877 14878Followed. 14879 14880@quotation 14881 14882“If the generator period is sufficiently long in relation to the number 14883of distinct initiator values, then each possible value of 14884@code{Initiator} passed to @code{Reset} should initiate a sequence of 14885random numbers that does not, in a practical sense, overlap the sequence 14886initiated by any other value. If this is not possible, then the mapping 14887between initiator values and generator states should be a rapidly 14888varying function of the initiator value.” 14889@end quotation 14890 14891Followed. The generator period is sufficiently long for the first 14892condition here to hold true. 14893 14894@geindex Get_Immediate 14895 14896@node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice 14897@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23d} 14898@section RM A.10.7(23): @code{Get_Immediate} 14899 14900 14901@quotation 14902 14903“The @code{Get_Immediate} procedures should be implemented with 14904unbuffered input. For a device such as a keyboard, input should be 14905available if a key has already been typed, whereas for a disk 14906file, input should always be available except at end of file. For a file 14907associated with a keyboard-like device, any line-editing features of the 14908underlying operating system should be disabled during the execution of 14909@code{Get_Immediate}.” 14910@end quotation 14911 14912Followed on all targets except VxWorks. For VxWorks, there is no way to 14913provide this functionality that does not result in the input buffer being 14914flushed before the @code{Get_Immediate} call. A special unit 14915@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 14916this functionality. 14917 14918@geindex Containers 14919 14920@node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice 14921@anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{23e} 14922@section RM A.18: @code{Containers} 14923 14924 14925All implementation advice pertaining to Ada.Containers and its 14926child units (that is, all implementation advice occurring within 14927section A.18 and its subsections) is followed except for A.18.24(17): 14928 14929@quotation 14930 14931“Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “ 14932@end quotation 14933 14934The implementations of the two Reference_Preserving_Key functions of 14935the generic package Ada.Containers.Bounded_Ordered_Sets each currently make 14936use of dynamic allocation; other operations on bounded ordered set objects 14937follow the implementation advice. 14938 14939@geindex Export 14940 14941@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice 14942@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23f} 14943@section RM B.1(39-41): Pragma @code{Export} 14944 14945 14946@quotation 14947 14948“If an implementation supports pragma @code{Export} to a given language, 14949then it should also allow the main subprogram to be written in that 14950language. It should support some mechanism for invoking the elaboration 14951of the Ada library units included in the system, and for invoking the 14952finalization of the environment task. On typical systems, the 14953recommended mechanism is to provide two subprograms whose link names are 14954@code{adainit} and @code{adafinal}. @code{adainit} should contain the 14955elaboration code for library units. @code{adafinal} should contain the 14956finalization code. These subprograms should have no effect the second 14957and subsequent time they are called.” 14958@end quotation 14959 14960Followed. 14961 14962@quotation 14963 14964“Automatic elaboration of pre-elaborated packages should be 14965provided when pragma @code{Export} is supported.” 14966@end quotation 14967 14968Followed when the main program is in Ada. If the main program is in a 14969foreign language, then 14970@code{adainit} must be called to elaborate pre-elaborated 14971packages. 14972 14973@quotation 14974 14975“For each supported convention @emph{L} other than @code{Intrinsic}, an 14976implementation should support @code{Import} and @code{Export} pragmas 14977for objects of @emph{L}-compatible types and for subprograms, and pragma 14978@cite{Convention} for @emph{L}-eligible types and for subprograms, 14979presuming the other language has corresponding features. Pragma 14980@code{Convention} need not be supported for scalar types.” 14981@end quotation 14982 14983Followed. 14984 14985@geindex Package Interfaces 14986 14987@geindex Interfaces 14988 14989@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 14990@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{240} 14991@section RM B.2(12-13): Package @code{Interfaces} 14992 14993 14994@quotation 14995 14996“For each implementation-defined convention identifier, there should be a 14997child package of package Interfaces with the corresponding name. This 14998package should contain any declarations that would be useful for 14999interfacing to the language (implementation) represented by the 15000convention. Any declarations useful for interfacing to any language on 15001the given hardware architecture should be provided directly in 15002@code{Interfaces}.” 15003@end quotation 15004 15005Followed. 15006 15007@quotation 15008 15009“An implementation supporting an interface to C, COBOL, or Fortran should 15010provide the corresponding package or packages described in the following 15011clauses.” 15012@end quotation 15013 15014Followed. GNAT provides all the packages described in this section. 15015 15016@geindex C 15017@geindex interfacing with 15018 15019@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 15020@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{241} 15021@section RM B.3(63-71): Interfacing with C 15022 15023 15024@quotation 15025 15026“An implementation should support the following interface correspondences 15027between Ada and C.” 15028@end quotation 15029 15030Followed. 15031 15032@quotation 15033 15034“An Ada procedure corresponds to a void-returning C function.” 15035@end quotation 15036 15037Followed. 15038 15039@quotation 15040 15041“An Ada function corresponds to a non-void C function.” 15042@end quotation 15043 15044Followed. 15045 15046@quotation 15047 15048“An Ada @code{in} scalar parameter is passed as a scalar argument to a C 15049function.” 15050@end quotation 15051 15052Followed. 15053 15054@quotation 15055 15056“An Ada @code{in} parameter of an access-to-object type with designated 15057type @code{T} is passed as a @code{t*} argument to a C function, 15058where @code{t} is the C type corresponding to the Ada type @code{T}.” 15059@end quotation 15060 15061Followed. 15062 15063@quotation 15064 15065“An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} 15066parameter of an elementary type @code{T}, is passed as a @code{t*} 15067argument to a C function, where @code{t} is the C type corresponding to 15068the Ada type @code{T}. In the case of an elementary @code{out} or 15069@code{in out} parameter, a pointer to a temporary copy is used to 15070preserve by-copy semantics.” 15071@end quotation 15072 15073Followed. 15074 15075@quotation 15076 15077“An Ada parameter of a record type @code{T}, of any mode, is passed as a 15078@code{t*} argument to a C function, where @code{t} is the C 15079structure corresponding to the Ada type @code{T}.” 15080@end quotation 15081 15082Followed. This convention may be overridden by the use of the C_Pass_By_Copy 15083pragma, or Convention, or by explicitly specifying the mechanism for a given 15084call using an extended import or export pragma. 15085 15086@quotation 15087 15088“An Ada parameter of an array type with component type @code{T}, of any 15089mode, is passed as a @code{t*} argument to a C function, where 15090@code{t} is the C type corresponding to the Ada type @code{T}.” 15091@end quotation 15092 15093Followed. 15094 15095@quotation 15096 15097“An Ada parameter of an access-to-subprogram type is passed as a pointer 15098to a C function whose prototype corresponds to the designated 15099subprogram’s specification.” 15100@end quotation 15101 15102Followed. 15103 15104@geindex COBOL 15105@geindex interfacing with 15106 15107@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 15108@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{242} 15109@section RM B.4(95-98): Interfacing with COBOL 15110 15111 15112@quotation 15113 15114“An Ada implementation should support the following interface 15115correspondences between Ada and COBOL.” 15116@end quotation 15117 15118Followed. 15119 15120@quotation 15121 15122“An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of 15123the COBOL type corresponding to @code{T}.” 15124@end quotation 15125 15126Followed. 15127 15128@quotation 15129 15130“An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of 15131the corresponding COBOL type.” 15132@end quotation 15133 15134Followed. 15135 15136@quotation 15137 15138“Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the 15139COBOL type corresponding to the Ada parameter type; for scalars, a local 15140copy is used if necessary to ensure by-copy semantics.” 15141@end quotation 15142 15143Followed. 15144 15145@geindex Fortran 15146@geindex interfacing with 15147 15148@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 15149@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{243} 15150@section RM B.5(22-26): Interfacing with Fortran 15151 15152 15153@quotation 15154 15155“An Ada implementation should support the following interface 15156correspondences between Ada and Fortran:” 15157@end quotation 15158 15159Followed. 15160 15161@quotation 15162 15163“An Ada procedure corresponds to a Fortran subroutine.” 15164@end quotation 15165 15166Followed. 15167 15168@quotation 15169 15170“An Ada function corresponds to a Fortran function.” 15171@end quotation 15172 15173Followed. 15174 15175@quotation 15176 15177“An Ada parameter of an elementary, array, or record type @code{T} is 15178passed as a @code{T} argument to a Fortran procedure, where @code{T} is 15179the Fortran type corresponding to the Ada type @code{T}, and where the 15180INTENT attribute of the corresponding dummy argument matches the Ada 15181formal parameter mode; the Fortran implementation’s parameter passing 15182conventions are used. For elementary types, a local copy is used if 15183necessary to ensure by-copy semantics.” 15184@end quotation 15185 15186Followed. 15187 15188@quotation 15189 15190“An Ada parameter of an access-to-subprogram type is passed as a 15191reference to a Fortran procedure whose interface corresponds to the 15192designated subprogram’s specification.” 15193@end quotation 15194 15195Followed. 15196 15197@geindex Machine operations 15198 15199@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 15200@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{244} 15201@section RM C.1(3-5): Access to Machine Operations 15202 15203 15204@quotation 15205 15206“The machine code or intrinsic support should allow access to all 15207operations normally available to assembly language programmers for the 15208target environment, including privileged instructions, if any.” 15209@end quotation 15210 15211Followed. 15212 15213@quotation 15214 15215“The interfacing pragmas (see Annex B) should support interface to 15216assembler; the default assembler should be associated with the 15217convention identifier @code{Assembler}.” 15218@end quotation 15219 15220Followed. 15221 15222@quotation 15223 15224“If an entity is exported to assembly language, then the implementation 15225should allocate it at an addressable location, and should ensure that it 15226is retained by the linking process, even if not otherwise referenced 15227from the Ada code. The implementation should assume that any call to a 15228machine code or assembler subprogram is allowed to read or update every 15229object that is specified as exported.” 15230@end quotation 15231 15232Followed. 15233 15234@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 15235@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{245} 15236@section RM C.1(10-16): Access to Machine Operations 15237 15238 15239@quotation 15240 15241“The implementation should ensure that little or no overhead is 15242associated with calling intrinsic and machine-code subprograms.” 15243@end quotation 15244 15245Followed for both intrinsics and machine-code subprograms. 15246 15247@quotation 15248 15249“It is recommended that intrinsic subprograms be provided for convenient 15250access to any machine operations that provide special capabilities or 15251efficiency and that are not otherwise available through the language 15252constructs.” 15253@end quotation 15254 15255Followed. A full set of machine operation intrinsic subprograms is provided. 15256 15257@quotation 15258 15259“Atomic read-modify-write operations—e.g., test and set, compare and 15260swap, decrement and test, enqueue/dequeue.” 15261@end quotation 15262 15263Followed on any target supporting such operations. 15264 15265@quotation 15266 15267“Standard numeric functions—e.g.:, sin, log.” 15268@end quotation 15269 15270Followed on any target supporting such operations. 15271 15272@quotation 15273 15274“String manipulation operations—e.g.:, translate and test.” 15275@end quotation 15276 15277Followed on any target supporting such operations. 15278 15279@quotation 15280 15281“Vector operations—e.g.:, compare vector against thresholds.” 15282@end quotation 15283 15284Followed on any target supporting such operations. 15285 15286@quotation 15287 15288“Direct operations on I/O ports.” 15289@end quotation 15290 15291Followed on any target supporting such operations. 15292 15293@geindex Interrupt support 15294 15295@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 15296@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{246} 15297@section RM C.3(28): Interrupt Support 15298 15299 15300@quotation 15301 15302“If the @code{Ceiling_Locking} policy is not in effect, the 15303implementation should provide means for the application to specify which 15304interrupts are to be blocked during protected actions, if the underlying 15305system allows for a finer-grain control of interrupt blocking.” 15306@end quotation 15307 15308Followed. The underlying system does not allow for finer-grain control 15309of interrupt blocking. 15310 15311@geindex Protected procedure handlers 15312 15313@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 15314@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{247} 15315@section RM C.3.1(20-21): Protected Procedure Handlers 15316 15317 15318@quotation 15319 15320“Whenever possible, the implementation should allow interrupt handlers to 15321be called directly by the hardware.” 15322@end quotation 15323 15324Followed on any target where the underlying operating system permits 15325such direct calls. 15326 15327@quotation 15328 15329“Whenever practical, violations of any 15330implementation-defined restrictions should be detected before run time.” 15331@end quotation 15332 15333Followed. Compile time warnings are given when possible. 15334 15335@geindex Package `@w{`}Interrupts`@w{`} 15336 15337@geindex Interrupts 15338 15339@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 15340@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{248} 15341@section RM C.3.2(25): Package @code{Interrupts} 15342 15343 15344@quotation 15345 15346“If implementation-defined forms of interrupt handler procedures are 15347supported, such as protected procedures with parameters, then for each 15348such form of a handler, a type analogous to @code{Parameterless_Handler} 15349should be specified in a child package of @code{Interrupts}, with the 15350same operations as in the predefined package Interrupts.” 15351@end quotation 15352 15353Followed. 15354 15355@geindex Pre-elaboration requirements 15356 15357@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice 15358@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{249} 15359@section RM C.4(14): Pre-elaboration Requirements 15360 15361 15362@quotation 15363 15364“It is recommended that pre-elaborated packages be implemented in such a 15365way that there should be little or no code executed at run time for the 15366elaboration of entities not already covered by the Implementation 15367Requirements.” 15368@end quotation 15369 15370Followed. Executable code is generated in some cases, e.g., loops 15371to initialize large arrays. 15372 15373@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 15374@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{24a} 15375@section RM C.5(8): Pragma @code{Discard_Names} 15376 15377 15378@quotation 15379 15380“If the pragma applies to an entity, then the implementation should 15381reduce the amount of storage used for storing names associated with that 15382entity.” 15383@end quotation 15384 15385Followed. 15386 15387@geindex Package Task_Attributes 15388 15389@geindex Task_Attributes 15390 15391@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 15392@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{24b} 15393@section RM C.7.2(30): The Package Task_Attributes 15394 15395 15396@quotation 15397 15398“Some implementations are targeted to domains in which memory use at run 15399time must be completely deterministic. For such implementations, it is 15400recommended that the storage for task attributes will be pre-allocated 15401statically and not from the heap. This can be accomplished by either 15402placing restrictions on the number and the size of the task’s 15403attributes, or by using the pre-allocated storage for the first @code{N} 15404attribute objects, and the heap for the others. In the latter case, 15405@code{N} should be documented.” 15406@end quotation 15407 15408Not followed. This implementation is not targeted to such a domain. 15409 15410@geindex Locking Policies 15411 15412@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 15413@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{24c} 15414@section RM D.3(17): Locking Policies 15415 15416 15417@quotation 15418 15419“The implementation should use names that end with @code{_Locking} for 15420locking policies defined by the implementation.” 15421@end quotation 15422 15423Followed. Two implementation-defined locking policies are defined, 15424whose names (@code{Inheritance_Locking} and 15425@code{Concurrent_Readers_Locking}) follow this suggestion. 15426 15427@geindex Entry queuing policies 15428 15429@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice 15430@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24d} 15431@section RM D.4(16): Entry Queuing Policies 15432 15433 15434@quotation 15435 15436“Names that end with @code{_Queuing} should be used 15437for all implementation-defined queuing policies.” 15438@end quotation 15439 15440Followed. No such implementation-defined queuing policies exist. 15441 15442@geindex Preemptive abort 15443 15444@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice 15445@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24e} 15446@section RM D.6(9-10): Preemptive Abort 15447 15448 15449@quotation 15450 15451“Even though the @emph{abort_statement} is included in the list of 15452potentially blocking operations (see 9.5.1), it is recommended that this 15453statement be implemented in a way that never requires the task executing 15454the @emph{abort_statement} to block.” 15455@end quotation 15456 15457Followed. 15458 15459@quotation 15460 15461“On a multi-processor, the delay associated with aborting a task on 15462another processor should be bounded; the implementation should use 15463periodic polling, if necessary, to achieve this.” 15464@end quotation 15465 15466Followed. 15467 15468@geindex Tasking restrictions 15469 15470@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice 15471@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24f} 15472@section RM D.7(21): Tasking Restrictions 15473 15474 15475@quotation 15476 15477“When feasible, the implementation should take advantage of the specified 15478restrictions to produce a more efficient implementation.” 15479@end quotation 15480 15481GNAT currently takes advantage of these restrictions by providing an optimized 15482run time when the Ravenscar profile and the GNAT restricted run time set 15483of restrictions are specified. See pragma @code{Profile (Ravenscar)} and 15484pragma @code{Profile (Restricted)} for more details. 15485 15486@geindex Time 15487@geindex monotonic 15488 15489@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice 15490@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{250} 15491@section RM D.8(47-49): Monotonic Time 15492 15493 15494@quotation 15495 15496“When appropriate, implementations should provide configuration 15497mechanisms to change the value of @code{Tick}.” 15498@end quotation 15499 15500Such configuration mechanisms are not appropriate to this implementation 15501and are thus not supported. 15502 15503@quotation 15504 15505“It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 15506be implemented as transformations of the same time base.” 15507@end quotation 15508 15509Followed. 15510 15511@quotation 15512 15513“It is recommended that the best time base which exists in 15514the underlying system be available to the application through 15515@code{Clock}. @cite{Best} may mean highest accuracy or largest range.” 15516@end quotation 15517 15518Followed. 15519 15520@geindex Partition communication subsystem 15521 15522@geindex PCS 15523 15524@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice 15525@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{251} 15526@section RM E.5(28-29): Partition Communication Subsystem 15527 15528 15529@quotation 15530 15531“Whenever possible, the PCS on the called partition should allow for 15532multiple tasks to call the RPC-receiver with different messages and 15533should allow them to block until the corresponding subprogram body 15534returns.” 15535@end quotation 15536 15537Followed by GLADE, a separately supplied PCS that can be used with 15538GNAT. 15539 15540@quotation 15541 15542“The @code{Write} operation on a stream of type @code{Params_Stream_Type} 15543should raise @code{Storage_Error} if it runs out of space trying to 15544write the @code{Item} into the stream.” 15545@end quotation 15546 15547Followed by GLADE, a separately supplied PCS that can be used with 15548GNAT. 15549 15550@geindex COBOL support 15551 15552@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice 15553@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{252} 15554@section RM F(7): COBOL Support 15555 15556 15557@quotation 15558 15559“If COBOL (respectively, C) is widely supported in the target 15560environment, implementations supporting the Information Systems Annex 15561should provide the child package @code{Interfaces.COBOL} (respectively, 15562@code{Interfaces.C}) specified in Annex B and should support a 15563@code{convention_identifier} of COBOL (respectively, C) in the interfacing 15564pragmas (see Annex B), thus allowing Ada programs to interface with 15565programs written in that language.” 15566@end quotation 15567 15568Followed. 15569 15570@geindex Decimal radix support 15571 15572@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice 15573@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{253} 15574@section RM F.1(2): Decimal Radix Support 15575 15576 15577@quotation 15578 15579“Packed decimal should be used as the internal representation for objects 15580of subtype @code{S} when @code{S}’Machine_Radix = 10.” 15581@end quotation 15582 15583Not followed. GNAT ignores @code{S}’Machine_Radix and always uses binary 15584representations. 15585 15586@geindex Numerics 15587 15588@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice 15589@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{254} 15590@section RM G: Numerics 15591 15592 15593@quotation 15594 15595“If Fortran (respectively, C) is widely supported in the target 15596environment, implementations supporting the Numerics Annex 15597should provide the child package @code{Interfaces.Fortran} (respectively, 15598@code{Interfaces.C}) specified in Annex B and should support a 15599@code{convention_identifier} of Fortran (respectively, C) in the interfacing 15600pragmas (see Annex B), thus allowing Ada programs to interface with 15601programs written in that language.” 15602@end quotation 15603 15604Followed. 15605 15606@geindex Complex types 15607 15608@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice 15609@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{255} 15610@section RM G.1.1(56-58): Complex Types 15611 15612 15613@quotation 15614 15615“Because the usual mathematical meaning of multiplication of a complex 15616operand and a real operand is that of the scaling of both components of 15617the former by the latter, an implementation should not perform this 15618operation by first promoting the real operand to complex type and then 15619performing a full complex multiplication. In systems that, in the 15620future, support an Ada binding to IEC 559:1989, the latter technique 15621will not generate the required result when one of the components of the 15622complex operand is infinite. (Explicit multiplication of the infinite 15623component by the zero component obtained during promotion yields a NaN 15624that propagates into the final result.) Analogous advice applies in the 15625case of multiplication of a complex operand and a pure-imaginary 15626operand, and in the case of division of a complex operand by a real or 15627pure-imaginary operand.” 15628@end quotation 15629 15630Not followed. 15631 15632@quotation 15633 15634“Similarly, because the usual mathematical meaning of addition of a 15635complex operand and a real operand is that the imaginary operand remains 15636unchanged, an implementation should not perform this operation by first 15637promoting the real operand to complex type and then performing a full 15638complex addition. In implementations in which the @code{Signed_Zeros} 15639attribute of the component type is @code{True} (and which therefore 15640conform to IEC 559:1989 in regard to the handling of the sign of zero in 15641predefined arithmetic operations), the latter technique will not 15642generate the required result when the imaginary component of the complex 15643operand is a negatively signed zero. (Explicit addition of the negative 15644zero to the zero obtained during promotion yields a positive zero.) 15645Analogous advice applies in the case of addition of a complex operand 15646and a pure-imaginary operand, and in the case of subtraction of a 15647complex operand and a real or pure-imaginary operand.” 15648@end quotation 15649 15650Not followed. 15651 15652@quotation 15653 15654“Implementations in which @code{Real'Signed_Zeros} is @code{True} should 15655attempt to provide a rational treatment of the signs of zero results and 15656result components. As one example, the result of the @code{Argument} 15657function should have the sign of the imaginary component of the 15658parameter @code{X} when the point represented by that parameter lies on 15659the positive real axis; as another, the sign of the imaginary component 15660of the @code{Compose_From_Polar} function should be the same as 15661(respectively, the opposite of) that of the @code{Argument} parameter when that 15662parameter has a value of zero and the @code{Modulus} parameter has a 15663nonnegative (respectively, negative) value.” 15664@end quotation 15665 15666Followed. 15667 15668@geindex Complex elementary functions 15669 15670@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 15671@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{256} 15672@section RM G.1.2(49): Complex Elementary Functions 15673 15674 15675@quotation 15676 15677“Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 15678@code{True} should attempt to provide a rational treatment of the signs 15679of zero results and result components. For example, many of the complex 15680elementary functions have components that are odd functions of one of 15681the parameter components; in these cases, the result component should 15682have the sign of the parameter component at the origin. Other complex 15683elementary functions have zero components whose sign is opposite that of 15684a parameter component at the origin, or is always positive or always 15685negative.” 15686@end quotation 15687 15688Followed. 15689 15690@geindex Accuracy requirements 15691 15692@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 15693@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{257} 15694@section RM G.2.4(19): Accuracy Requirements 15695 15696 15697@quotation 15698 15699“The versions of the forward trigonometric functions without a 15700@code{Cycle} parameter should not be implemented by calling the 15701corresponding version with a @code{Cycle} parameter of 15702@code{2.0*Numerics.Pi}, since this will not provide the required 15703accuracy in some portions of the domain. For the same reason, the 15704version of @code{Log} without a @code{Base} parameter should not be 15705implemented by calling the corresponding version with a @code{Base} 15706parameter of @code{Numerics.e}.” 15707@end quotation 15708 15709Followed. 15710 15711@geindex Complex arithmetic accuracy 15712 15713@geindex Accuracy 15714@geindex complex arithmetic 15715 15716@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 15717@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{258} 15718@section RM G.2.6(15): Complex Arithmetic Accuracy 15719 15720 15721@quotation 15722 15723“The version of the @code{Compose_From_Polar} function without a 15724@code{Cycle} parameter should not be implemented by calling the 15725corresponding version with a @code{Cycle} parameter of 15726@code{2.0*Numerics.Pi}, since this will not provide the required 15727accuracy in some portions of the domain.” 15728@end quotation 15729 15730Followed. 15731 15732@geindex Sequential elaboration policy 15733 15734@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice 15735@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{259} 15736@section RM H.6(15/2): Pragma Partition_Elaboration_Policy 15737 15738 15739@quotation 15740 15741“If the partition elaboration policy is @code{Sequential} and the 15742Environment task becomes permanently blocked during elaboration then the 15743partition is deadlocked and it is recommended that the partition be 15744immediately terminated.” 15745@end quotation 15746 15747Not followed. 15748 15749@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top 15750@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} 15751@chapter Implementation Defined Characteristics 15752 15753 15754In addition to the implementation dependent pragmas and attributes, and the 15755implementation advice, there are a number of other Ada features that are 15756potentially implementation dependent and are designated as 15757implementation-defined. These are mentioned throughout the Ada Reference 15758Manual, and are summarized in Annex M. 15759 15760A requirement for conforming Ada compilers is that they provide 15761documentation describing how the implementation deals with each of these 15762issues. In this chapter you will find each point in Annex M listed, 15763followed by a description of how GNAT handles the implementation dependence. 15764 15765You can use this chapter as a guide to minimizing implementation 15766dependent features in your programs if portability to other compilers 15767and other operating systems is an important consideration. The numbers 15768in each entry below correspond to the paragraph numbers in the Ada 15769Reference Manual. 15770 15771 15772@itemize * 15773 15774@item 15775“Whether or not each recommendation given in Implementation 15776Advice is followed. See 1.1.2(37).” 15777@end itemize 15778 15779See @ref{a,,Implementation Advice}. 15780 15781 15782@itemize * 15783 15784@item 15785“Capacity limitations of the implementation. See 1.1.3(3).” 15786@end itemize 15787 15788The complexity of programs that can be processed is limited only by the 15789total amount of available virtual memory, and disk space for the 15790generated object files. 15791 15792 15793@itemize * 15794 15795@item 15796“Variations from the standard that are impractical to avoid 15797given the implementation’s execution environment. See 1.1.3(6).” 15798@end itemize 15799 15800There are no variations from the standard. 15801 15802 15803@itemize * 15804 15805@item 15806“Which code_statements cause external 15807interactions. See 1.1.3(10).” 15808@end itemize 15809 15810Any @emph{code_statement} can potentially cause external interactions. 15811 15812 15813@itemize * 15814 15815@item 15816“The coded representation for the text of an Ada 15817program. See 2.1(4).” 15818@end itemize 15819 15820See separate section on source representation. 15821 15822 15823@itemize * 15824 15825@item 15826 15827@table @asis 15828 15829@item “The semantics of an Ada program whose text is not in 15830 15831Normalization Form C. See 2.1(4).” 15832@end table 15833@end itemize 15834 15835See separate section on source representation. 15836 15837 15838@itemize * 15839 15840@item 15841“The representation for an end of line. See 2.2(2).” 15842@end itemize 15843 15844See separate section on source representation. 15845 15846 15847@itemize * 15848 15849@item 15850“Maximum supported line length and lexical element 15851length. See 2.2(15).” 15852@end itemize 15853 15854The maximum line length is 255 characters and the maximum length of 15855a lexical element is also 255 characters. This is the default setting 15856if not overridden by the use of compiler switch @emph{-gnaty} (which 15857sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum 15858line length to be specified to be any value up to 32767. The maximum 15859length of a lexical element is the same as the maximum line length. 15860 15861 15862@itemize * 15863 15864@item 15865“Implementation defined pragmas. See 2.8(14).” 15866@end itemize 15867 15868See @ref{7,,Implementation Defined Pragmas}. 15869 15870 15871@itemize * 15872 15873@item 15874“Effect of pragma @code{Optimize}. See 2.8(27).” 15875@end itemize 15876 15877Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 15878parameter, checks that the optimization flag is set, and aborts if it is 15879not. 15880 15881 15882@itemize * 15883 15884@item 15885“The message string associated with the Assertion_Error exception raised 15886by the failure of a predicate check if there is no applicable 15887Predicate_Failure aspect. See 3.2.4(31).” 15888@end itemize 15889 15890In the case of a Dynamic_Predicate aspect, the string is 15891“Dynamic_Predicate failed at <source position>”, where 15892“<source position>” might be something like “foo.adb:123”. 15893The Static_Predicate case is handled analogously. 15894 15895 15896@itemize * 15897 15898@item 15899“The predefined integer types declared in 15900@code{Standard}. See 3.5.4(25).” 15901@end itemize 15902 15903 15904@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15905@headitem 15906 15907Type 15908 15909@tab 15910 15911Representation 15912 15913@item 15914 15915@emph{Short_Short_Integer} 15916 15917@tab 15918 159198-bit signed 15920 15921@item 15922 15923@emph{Short_Integer} 15924 15925@tab 15926 1592716-bit signed 15928 15929@item 15930 15931@emph{Integer} 15932 15933@tab 15934 1593532-bit signed 15936 15937@item 15938 15939@emph{Long_Integer} 15940 15941@tab 15942 1594364-bit signed (on most 64-bit targets, 15944depending on the C definition of long) 1594532-bit signed (on all other targets) 15946 15947@item 15948 15949@emph{Long_Long_Integer} 15950 15951@tab 15952 1595364-bit signed 15954 15955@item 15956 15957@emph{Long_Long_Long_Integer} 15958 15959@tab 15960 15961128-bit signed (on 64-bit targets) 1596264-bit signed (on 32-bit targets) 15963 15964@end multitable 15965 15966 15967 15968@itemize * 15969 15970@item 15971“Any nonstandard integer types and the operators defined 15972for them. See 3.5.4(26).” 15973@end itemize 15974 15975There are no nonstandard integer types. 15976 15977 15978@itemize * 15979 15980@item 15981“Any nonstandard real types and the operators defined for 15982them. See 3.5.6(8).” 15983@end itemize 15984 15985There are no nonstandard real types. 15986 15987 15988@itemize * 15989 15990@item 15991“What combinations of requested decimal precision and range 15992are supported for floating point types. See 3.5.7(7).” 15993@end itemize 15994 15995The precision and range are defined by the IEEE Standard for Floating-Point 15996Arithmetic (IEEE 754-2019). 15997 15998 15999@itemize * 16000 16001@item 16002“The predefined floating point types declared in 16003@code{Standard}. See 3.5.7(16).” 16004@end itemize 16005 16006 16007@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16008@headitem 16009 16010Type 16011 16012@tab 16013 16014Representation 16015 16016@item 16017 16018@emph{Short_Float} 16019 16020@tab 16021 16022IEEE Binary32 (Single) 16023 16024@item 16025 16026@emph{Float} 16027 16028@tab 16029 16030IEEE Binary32 (Single) 16031 16032@item 16033 16034@emph{Long_Float} 16035 16036@tab 16037 16038IEEE Binary64 (Double) 16039 16040@item 16041 16042@emph{Long_Long_Float} 16043 16044@tab 16045 16046IEEE Binary64 (Double) on non-x86 architectures 16047IEEE 80-bit Extended on x86 architecture 16048 16049@end multitable 16050 16051 16052The default rounding mode specified by the IEEE 754 Standard is assumed both 16053for static and dynamic computations (that is, round to nearest, ties to even). 16054The input routines yield correctly rounded values for Short_Float, Float, and 16055Long_Float at least. The output routines can compute up to twice as many exact 16056digits as the value of @code{T'Digits} for any type, for example 30 digits for 16057Long_Float; if more digits are requested, zeros are printed. 16058 16059 16060@itemize * 16061 16062@item 16063“The small of an ordinary fixed point type. See 3.5.9(8).” 16064@end itemize 16065 16066The small is the largest power of two that does not exceed the delta. 16067 16068 16069@itemize * 16070 16071@item 16072“What combinations of small, range, and digits are 16073supported for fixed point types. See 3.5.9(10).” 16074@end itemize 16075 16076For an ordinary fixed point type, on 32-bit platforms, the small must lie in 160772.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination 16078is permitted that does not result in a mantissa larger than 63 bits. 16079 16080On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the 16081range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not 16082result in a mantissa larger than 63 bits, and any combination is permitted 16083that results in a mantissa between 64 and 127 bits if the small is the 16084ratio of two integers that lie in 1 .. 2.0**127. 16085 16086If the small is the ratio of two integers with 64-bit magnitude on 32-bit 16087platforms and 128-bit magnitude on 64-bit platforms, which is the case if 16088no @code{small} clause is provided, then the operations of the fixed point 16089type are entirely implemented by means of integer instructions. In the 16090other cases, some operations, in particular input and output, may be 16091implemented by means of floating-point instructions and may be affected 16092by accuracy issues on architectures other than x86. 16093 16094For a decimal fixed point type, on 32-bit platforms, the small must lie in 160951.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the 16096small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38. 16097 16098 16099@itemize * 16100 16101@item 16102“The result of @code{Tags.Expanded_Name} for types declared 16103within an unnamed @emph{block_statement}. See 3.9(10).” 16104@end itemize 16105 16106Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a 16107decimal integer are allocated. 16108 16109 16110@itemize * 16111 16112@item 16113“The sequence of characters of the value returned by Tags.Expanded_Name 16114(respectively, Tags.Wide_Expanded_Name) when some of the graphic 16115characters of Tags.Wide_Wide_Expanded_Name are not defined in Character 16116(respectively, Wide_Character). See 3.9(10.1).” 16117@end itemize 16118 16119This is handled in the same way as the implementation-defined behavior 16120referenced in A.4.12(34). 16121 16122 16123@itemize * 16124 16125@item 16126“Implementation-defined attributes. See 4.1.4(12).” 16127@end itemize 16128 16129See @ref{8,,Implementation Defined Attributes}. 16130 16131 16132@itemize * 16133 16134@item 16135“The value of the parameter to Empty for some container aggregates. 16136See 4.3.5(40).” 16137@end itemize 16138 16139As per the suggestion given in the Annotated Ada RM, the default value 16140of the formal parameter is used if one exists and zero is used otherwise. 16141 16142 16143@itemize * 16144 16145@item 16146“The maximum number of chunks for a parallel reduction expression without 16147a chunk_specification. See 4.5.10(21).” 16148@end itemize 16149 16150Feature unimplemented. 16151 16152 16153@itemize * 16154 16155@item 16156“Rounding of real static expressions which are exactly half-way between 16157two machine numbers. See 4.9(38).” 16158@end itemize 16159 16160Round to even is used in all such cases. 16161 16162 16163@itemize * 16164 16165@item 16166 16167@table @asis 16168 16169@item “The maximum number of chunks for a parallel generalized iterator without 16170 16171a chunk_specification. See 5.5.2(10).” 16172@end table 16173@end itemize 16174 16175Feature unimplemented. 16176 16177 16178@itemize * 16179 16180@item 16181“The number of chunks for an array component iterator. See 5.5.2(11).” 16182@end itemize 16183 16184Feature unimplemented. 16185 16186 16187@itemize * 16188 16189@item 16190“Any extensions of the Global aspect. See 6.1.2(43).” 16191@end itemize 16192 16193Feature unimplemented. 16194 16195 16196@itemize * 16197 16198@item 16199“The circumstances the implementation passes in the null value for a view 16200conversion of an access type used as an out parameter. See 6.4.1(19).” 16201@end itemize 16202 16203Difficult to characterize. 16204 16205 16206@itemize * 16207 16208@item 16209“Any extensions of the Default_Initial_Condition aspect. See 7.3.3(11).” 16210@end itemize 16211 16212SPARK allows specifying @emph{null} as the Default_Initial_Condition 16213aspect of a type. See the SPARK reference manual for further details. 16214 16215 16216@itemize * 16217 16218@item 16219“Any implementation-defined time types. See 9.6(6).” 16220@end itemize 16221 16222There are no implementation-defined time types. 16223 16224 16225@itemize * 16226 16227@item 16228“The time base associated with relative delays. See 9.6(20).” 16229@end itemize 16230 16231See 9.6(20). The time base used is that provided by the C library 16232function @code{gettimeofday}. 16233 16234 16235@itemize * 16236 16237@item 16238“The time base of the type @code{Calendar.Time}. See 9.6(23).” 16239@end itemize 16240 16241The time base used is that provided by the C library function 16242@code{gettimeofday}. 16243 16244 16245@itemize * 16246 16247@item 16248“The time zone used for package @code{Calendar} 16249operations. See 9.6(24).” 16250@end itemize 16251 16252The time zone used by package @code{Calendar} is the current system time zone 16253setting for local time, as accessed by the C library function 16254@code{localtime}. 16255 16256 16257@itemize * 16258 16259@item 16260“Any limit on @emph{delay_until_statements} of 16261@emph{select_statements}. See 9.6(29).” 16262@end itemize 16263 16264There are no such limits. 16265 16266 16267@itemize * 16268 16269@item 16270 16271@table @asis 16272 16273@item “The result of Calendar.Formatting.Image if its argument represents more 16274 16275than 100 hours. See 9.6.1(86).” 16276@end table 16277@end itemize 16278 16279Calendar.Time_Error is raised. 16280 16281 16282@itemize * 16283 16284@item 16285“Implementation-defined conflict check policies. See 9.10.1(5).” 16286@end itemize 16287 16288There are no implementation-defined conflict check policies. 16289 16290 16291@itemize * 16292 16293@item 16294“The representation for a compilation. See 10.1(2).” 16295@end itemize 16296 16297A compilation is represented by a sequence of files presented to the 16298compiler in a single invocation of the @emph{gcc} command. 16299 16300 16301@itemize * 16302 16303@item 16304“Any restrictions on compilations that contain multiple 16305compilation_units. See 10.1(4).” 16306@end itemize 16307 16308No single file can contain more than one compilation unit, but any 16309sequence of files can be presented to the compiler as a single 16310compilation. 16311 16312 16313@itemize * 16314 16315@item 16316“The mechanisms for creating an environment and for adding 16317and replacing compilation units. See 10.1.4(3).” 16318@end itemize 16319 16320See separate section on compilation model. 16321 16322 16323@itemize * 16324 16325@item 16326“The manner of explicitly assigning library units to a 16327partition. See 10.2(2).” 16328@end itemize 16329 16330If a unit contains an Ada main program, then the Ada units for the partition 16331are determined by recursive application of the rules in the Ada Reference 16332Manual section 10.2(2-6). In other words, the Ada units will be those that 16333are needed by the main program, and then this definition of need is applied 16334recursively to those units, and the partition contains the transitive 16335closure determined by this relationship. In short, all the necessary units 16336are included, with no need to explicitly specify the list. If additional 16337units are required, e.g., by foreign language units, then all units must be 16338mentioned in the context clause of one of the needed Ada units. 16339 16340If the partition contains no main program, or if the main program is in 16341a language other than Ada, then GNAT 16342provides the binder options @emph{-z} and @emph{-n} respectively, and in 16343this case a list of units can be explicitly supplied to the binder for 16344inclusion in the partition (all units needed by these units will also 16345be included automatically). For full details on the use of these 16346options, refer to @emph{GNAT Make Program gnatmake} in the 16347@cite{GNAT User’s Guide}. 16348 16349 16350@itemize * 16351 16352@item 16353“The implementation-defined means, if any, of specifying which compilation 16354units are needed by a given compilation unit. See 10.2(2).” 16355@end itemize 16356 16357The units needed by a given compilation unit are as defined in 16358the Ada Reference Manual section 10.2(2-6). There are no 16359implementation-defined pragmas or other implementation-defined 16360means for specifying needed units. 16361 16362 16363@itemize * 16364 16365@item 16366“The manner of designating the main subprogram of a 16367partition. See 10.2(7).” 16368@end itemize 16369 16370The main program is designated by providing the name of the 16371corresponding @code{ALI} file as the input parameter to the binder. 16372 16373 16374@itemize * 16375 16376@item 16377“The order of elaboration of @emph{library_items}. See 10.2(18).” 16378@end itemize 16379 16380The first constraint on ordering is that it meets the requirements of 16381Chapter 10 of the Ada Reference Manual. This still leaves some 16382implementation-dependent choices, which are resolved by analyzing 16383the elaboration code of each unit and identifying implicit 16384elaboration-order dependencies. 16385 16386 16387@itemize * 16388 16389@item 16390“Parameter passing and function return for the main 16391subprogram. See 10.2(21).” 16392@end itemize 16393 16394The main program has no parameters. It may be a procedure, or a function 16395returning an integer type. In the latter case, the returned integer 16396value is the return code of the program (overriding any value that 16397may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 16398 16399 16400@itemize * 16401 16402@item 16403“The mechanisms for building and running partitions. See 10.2(24).” 16404@end itemize 16405 16406GNAT itself supports programs with only a single partition. The GNATDIST 16407tool provided with the GLADE package (which also includes an implementation 16408of the PCS) provides a completely flexible method for building and running 16409programs consisting of multiple partitions. See the separate GLADE manual 16410for details. 16411 16412 16413@itemize * 16414 16415@item 16416“The details of program execution, including program 16417termination. See 10.2(25).” 16418@end itemize 16419 16420See separate section on compilation model. 16421 16422 16423@itemize * 16424 16425@item 16426“The semantics of any non-active partitions supported by the 16427implementation. See 10.2(28).” 16428@end itemize 16429 16430Passive partitions are supported on targets where shared memory is 16431provided by the operating system. See the GLADE reference manual for 16432further details. 16433 16434 16435@itemize * 16436 16437@item 16438“The information returned by @code{Exception_Message}. See 11.4.1(10).” 16439@end itemize 16440 16441Exception message returns the null string unless a specific message has 16442been passed by the program. 16443 16444 16445@itemize * 16446 16447@item 16448“The result of @code{Exceptions.Exception_Name} for types 16449declared within an unnamed @emph{block_statement}. See 11.4.1(12).” 16450@end itemize 16451 16452Blocks have implementation defined names of the form @code{B@emph{nnn}} 16453where @emph{nnn} is an integer. 16454 16455 16456@itemize * 16457 16458@item 16459“The information returned by 16460@code{Exception_Information}. See 11.4.1(13).” 16461@end itemize 16462 16463@code{Exception_Information} returns a string in the following format: 16464 16465@example 16466*Exception_Name:* nnnnn 16467*Message:* mmmmm 16468*PID:* ppp 16469*Load address:* 0xhhhh 16470*Call stack traceback locations:* 164710xhhhh 0xhhhh 0xhhhh ... 0xhhh 16472@end example 16473 16474where 16475 16476@quotation 16477 16478 16479@itemize * 16480 16481@item 16482@code{nnnn} is the fully qualified name of the exception in all upper 16483case letters. This line is always present. 16484 16485@item 16486@code{mmmm} is the message (this line present only if message is non-null) 16487 16488@item 16489@code{ppp} is the Process Id value as a decimal integer (this line is 16490present only if the Process Id is nonzero). Currently we are 16491not making use of this field. 16492 16493@item 16494The Load address line, the Call stack traceback locations line and the 16495following values are present only if at least one traceback location was 16496recorded. The Load address indicates the address at which the main executable 16497was loaded; this line may not be present if operating system hasn’t relocated 16498the main executable. The values are given in C style format, with lower case 16499letters for a-f, and only as many digits present as are necessary. 16500The line terminator sequence at the end of each line, including 16501the last line is a single @code{LF} character (@code{16#0A#}). 16502@end itemize 16503@end quotation 16504 16505 16506@itemize * 16507 16508@item 16509“The sequence of characters of the value returned by 16510Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name) 16511when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name 16512are not defined in Character (respectively, Wide_Character). 16513See 11.4.1(12.1).” 16514@end itemize 16515 16516This is handled in the same way as the implementation-defined behavior 16517referenced in A.4.12(34). 16518 16519 16520@itemize * 16521 16522@item 16523“The information returned by Exception_Information. See 11.4.1(13).” 16524@end itemize 16525 16526The exception name and the source location at which the exception was 16527raised are included. 16528 16529 16530@itemize * 16531 16532@item 16533“Implementation-defined policy_identifiers and assertion_aspect_marks 16534allowed in a pragma Assertion_Policy. See 11.4.2(9).” 16535@end itemize 16536 16537Implementation-defined assertion_aspect_marks include Assert_And_Cut, 16538Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant, 16539Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post, 16540Statement_Assertions, and Subprogram_Variant. Implementation-defined 16541policy_identifiers include Ignore and Suppressible. 16542 16543 16544@itemize * 16545 16546@item 16547“The default assertion policy. See 11.4.2(10).” 16548@end itemize 16549 16550The default assertion policy is Ignore, although this can be overridden 16551via compiler switches such as “-gnata”. 16552 16553 16554@itemize * 16555 16556@item 16557“Implementation-defined check names. See 11.5(27).” 16558@end itemize 16559 16560The implementation defined check names include Alignment_Check, 16561Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, 16562Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user 16563program can add implementation-defined check names by means of the pragma 16564Check_Name. See the description of pragma @code{Suppress} for full details. 16565 16566 16567@itemize * 16568 16569@item 16570“Existence and meaning of second parameter of pragma Unsuppress. 16571See 11.5(27.1).” 16572@end itemize 16573 16574The legality rules for and semantics of the second parameter of pragma 16575Unsuppress match those for the second argument of pragma Suppress. 16576 16577 16578@itemize * 16579 16580@item 16581 16582@table @asis 16583 16584@item “The cases that cause conflicts between the representation of the 16585 16586ancestors of a type_declaration. See 13.1(13.1).” 16587@end table 16588@end itemize 16589 16590No such cases exist. 16591 16592 16593@itemize * 16594 16595@item 16596“The interpretation of each representation aspect. See 13.1(20).” 16597@end itemize 16598 16599See separate section on data representations. 16600 16601 16602@itemize * 16603 16604@item 16605“Any restrictions placed upon the specification of representation aspects. 16606See 13.1(20).” 16607@end itemize 16608 16609See separate section on data representations. 16610 16611 16612@itemize * 16613 16614@item 16615“Implementation-defined aspects, including the syntax for specifying 16616such aspects and the legality rules for such aspects. See 13.1.1(38).” 16617@end itemize 16618 16619See @ref{121,,Implementation Defined Aspects}. 16620 16621 16622@itemize * 16623 16624@item 16625“The set of machine scalars. See 13.3(8.1).” 16626@end itemize 16627 16628See separate section on data representations. 16629 16630 16631@itemize * 16632 16633@item 16634“The meaning of @code{Size} for indefinite subtypes. See 13.3(48).” 16635@end itemize 16636 16637The Size attribute of an indefinite subtype is not less than the Size 16638attribute of any object of that type. 16639 16640 16641@itemize * 16642 16643@item 16644“The meaning of Object_Size for indefinite subtypes. See 13.3(58).” 16645@end itemize 16646 16647The Object_Size attribute of an indefinite subtype is not less than the 16648Object_Size attribute of any object of that type. 16649 16650 16651@itemize * 16652 16653@item 16654“The default external representation for a type tag. See 13.3(75).” 16655@end itemize 16656 16657The default external representation for a type tag is the fully expanded 16658name of the type in upper case letters. 16659 16660 16661@itemize * 16662 16663@item 16664“What determines whether a compilation unit is the same in 16665two different partitions. See 13.3(76).” 16666@end itemize 16667 16668A compilation unit is the same in two different partitions if and only 16669if it derives from the same source file. 16670 16671 16672@itemize * 16673 16674@item 16675“Implementation-defined components. See 13.5.1(15).” 16676@end itemize 16677 16678The only implementation defined component is the tag for a tagged type, 16679which contains a pointer to the dispatching table. 16680 16681 16682@itemize * 16683 16684@item 16685“If @code{Word_Size} = @code{Storage_Unit}, the default bit 16686ordering. See 13.5.3(5).” 16687@end itemize 16688 16689@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 16690implementation, so no non-default bit ordering is supported. The default 16691bit ordering corresponds to the natural endianness of the target architecture. 16692 16693 16694@itemize * 16695 16696@item 16697“The contents of the visible part of package @code{System}. See 13.7(2).” 16698@end itemize 16699 16700See the definition of package System in @code{system.ads}. 16701Note that two declarations are added to package System. 16702 16703@example 16704Max_Priority : constant Positive := Priority'Last; 16705Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; 16706@end example 16707 16708 16709@itemize * 16710 16711@item 16712“The range of Storage_Elements.Storage_Offset, the modulus of 16713Storage_Elements.Storage_Element, and the declaration of 16714Storage_Elements.Integer_Address. See 13.7.1(11).” 16715@end itemize 16716 16717See the definition of package System.Storage_Elements in @code{s-stoele.ads}. 16718 16719 16720@itemize * 16721 16722@item 16723“The contents of the visible part of package @code{System.Machine_Code}, 16724and the meaning of @emph{code_statements}. See 13.8(7).” 16725@end itemize 16726 16727See the definition and documentation in file @code{s-maccod.ads}. 16728 16729 16730@itemize * 16731 16732@item 16733“The result of unchecked conversion for instances with scalar result 16734types whose result is not defined by the language. See 13.9(11).” 16735@end itemize 16736 16737Unchecked conversion between types of the same size 16738results in an uninterpreted transmission of the bits from one type 16739to the other. If the types are of unequal sizes, then in the case of 16740discrete types, a shorter source is first zero or sign extended as 16741necessary, and a shorter target is simply truncated on the left. 16742For all non-discrete types, the source is first copied if necessary 16743to ensure that the alignment requirements of the target are met, then 16744a pointer is constructed to the source value, and the result is obtained 16745by dereferencing this pointer after converting it to be a pointer to the 16746target type. Unchecked conversions where the target subtype is an 16747unconstrained array are not permitted. If the target alignment is 16748greater than the source alignment, then a copy of the result is 16749made with appropriate alignment 16750 16751 16752@itemize * 16753 16754@item 16755“The result of unchecked conversion for instances with nonscalar result 16756types whose result is not defined by the language. See 13.9(11).” 16757@end itemize 16758 16759See preceding definition for the scalar result case. 16760 16761 16762@itemize * 16763 16764@item 16765“Whether or not the implementation provides user-accessible 16766names for the standard pool type(s). See 13.11(17).” 16767@end itemize 16768 16769There are 3 different standard pools used by the compiler when 16770@code{Storage_Pool} is not specified depending whether the type is local 16771to a subprogram or defined at the library level and whether 16772@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime 16773library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and 16774@code{System.Pool_Local} in files @code{s-poosiz.ads}, 16775@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the 16776default pools used. All these pools are accessible by means of @cite{with}ing 16777these units. 16778 16779 16780@itemize * 16781 16782@item 16783“The meaning of @code{Storage_Size} when neither the Storage_Size nor the 16784Storage_Pool is specified for an access type. See 13.11(18).” 16785@end itemize 16786 16787@code{Storage_Size} is measured in storage units, and refers to the 16788total space available for an access type collection, or to the primary 16789stack space for a task. 16790 16791 16792@itemize * 16793 16794@item 16795“The effect of specifying aspect Default_Storage_Pool on an instance 16796of a language-defined generic unit. See 13.11.3(5).” 16797@end itemize 16798 16799Instances of language-defined generic units are treated the same as other 16800instances with respect to the Default_Storage_Pool aspect. 16801 16802 16803@itemize * 16804 16805@item 16806“Implementation-defined restrictions allowed in a pragma 16807@code{Restrictions}. See 13.12(8.7).” 16808@end itemize 16809 16810See @ref{9,,Standard and Implementation Defined Restrictions}. 16811 16812 16813@itemize * 16814 16815@item 16816“The consequences of violating limitations on 16817@code{Restrictions} pragmas. See 13.12(9).” 16818@end itemize 16819 16820Restrictions that can be checked at compile time are enforced at 16821compile time; violations are illegal. For other restrictions, any 16822violation during program execution results in erroneous execution. 16823 16824 16825@itemize * 16826 16827@item 16828“Implementation-defined usage profiles allowed in a pragma Profile. 16829See 13.12(15).” 16830@end itemize 16831 16832See @ref{7,,Implementation Defined Pragmas}. 16833 16834 16835@itemize * 16836 16837@item 16838“The contents of the stream elements read and written by the Read and 16839Write attributes of elementary types. See 13.13.2(9).” 16840@end itemize 16841 16842The representation is the in-memory representation of the base type of 16843the type, using the number of bits corresponding to the 16844@code{type'Size} value, and the natural ordering of the machine. 16845 16846 16847@itemize * 16848 16849@item 16850“The names and characteristics of the numeric subtypes 16851declared in the visible part of package @code{Standard}. See A.1(3).” 16852@end itemize 16853 16854See items describing the integer and floating-point types supported. 16855 16856 16857@itemize * 16858 16859@item 16860“The values returned by Strings.Hash. See A.4.9(3).” 16861@end itemize 16862 16863This hash function has predictable collisions and is subject to 16864equivalent substring attacks. It is not suitable for construction of a 16865hash table keyed on possibly malicious user input. 16866 16867 16868@itemize * 16869 16870@item 16871“The value returned by a call to a Text_Buffer Get procedure if any 16872character in the returned sequence is not defined in Character. 16873See A.4.12(34).” 16874@end itemize 16875 16876The contents of a buffer is represented internally as a UTF_8 string. 16877The value return by Text_Buffer.Get is the result of passing that 16878UTF_8 string to UTF_Encoding.Strings.Decode. 16879 16880 16881@itemize * 16882 16883@item 16884“The value returned by a call to a Text_Buffer Wide_Get procedure if 16885any character in the returned sequence is not defined in Wide_Character. 16886See A.4.12(34).” 16887@end itemize 16888 16889The contents of a buffer is represented internally as a UTF_8 string. 16890The value return by Text_Buffer.Wide_Get is the result of passing that 16891UTF_8 string to UTF_Encoding.Wide_Strings.Decode. 16892 16893 16894@itemize * 16895 16896@item 16897“The accuracy actually achieved by the elementary 16898functions. See A.5.1(1).” 16899@end itemize 16900 16901The elementary functions correspond to the functions available in the C 16902library. Only fast math mode is implemented. 16903 16904 16905@itemize * 16906 16907@item 16908“The sign of a zero result from some of the operators or 16909functions in @code{Numerics.Generic_Elementary_Functions}, when 16910@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).” 16911@end itemize 16912 16913The sign of zeroes follows the requirements of the IEEE 754 standard on 16914floating-point. 16915 16916 16917@itemize * 16918 16919@item 16920“The value of 16921@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).” 16922@end itemize 16923 16924Maximum image width is 6864, see library file @code{s-rannum.ads}. 16925 16926 16927@itemize * 16928 16929@item 16930“The value of 16931@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).” 16932@end itemize 16933 16934Maximum image width is 6864, see library file @code{s-rannum.ads}. 16935 16936 16937@itemize * 16938 16939@item 16940“The string representation of a random number generator’s 16941state. See A.5.2(38).” 16942@end itemize 16943 16944The value returned by the Image function is the concatenation of 16945the fixed-width decimal representations of the 624 32-bit integers 16946of the state vector. 16947 16948 16949@itemize * 16950 16951@item 16952“The values of the @code{Model_Mantissa}, 16953@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 16954@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 16955Annex is not supported. See A.5.3(72).” 16956@end itemize 16957 16958Running the compiler with @emph{-gnatS} to produce a listing of package 16959@code{Standard} displays the values of these attributes. 16960 16961 16962@itemize * 16963 16964@item 16965“The value of @code{Buffer_Size} in @code{Storage_IO}. See A.9(10).” 16966@end itemize 16967 16968All type representations are contiguous, and the @code{Buffer_Size} is 16969the value of @code{type'Size} rounded up to the next storage unit 16970boundary. 16971 16972 16973@itemize * 16974 16975@item 16976“External files for standard input, standard output, and 16977standard error See A.10(5).” 16978@end itemize 16979 16980These files are mapped onto the files provided by the C streams 16981libraries. See source file @code{i-cstrea.ads} for further details. 16982 16983 16984@itemize * 16985 16986@item 16987“The accuracy of the value produced by @code{Put}. See A.10.9(36).” 16988@end itemize 16989 16990If more digits are requested in the output than are represented by the 16991precision of the value, zeroes are output in the corresponding least 16992significant digit positions. 16993 16994 16995@itemize * 16996 16997@item 16998“Current size for a stream file for which positioning is not supported. 16999See A.12.1(1.1).” 17000@end itemize 17001 17002Positioning is supported. 17003 17004 17005@itemize * 17006 17007@item 17008“The meaning of @code{Argument_Count}, @code{Argument}, and 17009@code{Command_Name}. See A.15(1).” 17010@end itemize 17011 17012These are mapped onto the @code{argv} and @code{argc} parameters of the 17013main program in the natural manner. 17014 17015 17016@itemize * 17017 17018@item 17019“The interpretation of file names and directory names. See A.16(46).” 17020@end itemize 17021 17022These names are interpreted consistently with the underlying file system. 17023 17024 17025@itemize * 17026 17027@item 17028“The maxium value for a file size in Directories. See A.16(87).” 17029@end itemize 17030 17031Directories.File_Size’Last is equal to Long_Long_Integer’Last . 17032 17033 17034@itemize * 17035 17036@item 17037 17038@table @asis 17039 17040@item “The result for Directories.Size for a directory or special file. 17041 17042See A.16(93).” 17043@end table 17044@end itemize 17045 17046Name_Error is raised. 17047 17048 17049@itemize * 17050 17051@item 17052 17053@table @asis 17054 17055@item “The result for Directories.Modification_Time for a directory or special file. 17056 17057See A.16(93).” 17058@end table 17059@end itemize 17060 17061Name_Error is raised. 17062 17063 17064@itemize * 17065 17066@item 17067 17068@table @asis 17069 17070@item “The interpretation of a nonnull search pattern in Directories. 17071 17072See A.16(104).” 17073@end table 17074@end itemize 17075 17076When the @code{Pattern} parameter is not the null string, it is interpreted 17077according to the syntax of regular expressions as defined in the 17078@code{GNAT.Regexp} package. 17079 17080See @ref{25c,,GNAT.Regexp (g-regexp.ads)}. 17081 17082 17083@itemize * 17084 17085@item 17086 17087@table @asis 17088 17089@item “The results of a Directories search if the contents of the directory are 17090 17091altered while a search is in progress. See A.16(110).” 17092@end table 17093@end itemize 17094 17095The effect of a call to Get_Next_Entry is determined by the current 17096state of the directory. 17097 17098 17099@itemize * 17100 17101@item 17102“The definition and meaning of an environment variable. See A.17(1).” 17103@end itemize 17104 17105This definition is determined by the underlying operating system. 17106 17107 17108@itemize * 17109 17110@item 17111“The circumstances where an environment variable cannot be defined. 17112See A.17(16).” 17113 17114There are no such implementation-defined circumstances. 17115 17116@item 17117“Environment names for which Set has the effect of Clear. See A.17(17).” 17118@end itemize 17119 17120There are no such names. 17121 17122 17123@itemize * 17124 17125@item 17126“The value of Containers.Hash_Type’Modulus. The value of 17127Containers.Count_Type’Last. See A.18.1(7).” 17128@end itemize 17129 17130Containers.Hash_Type’Modulus is 2**32. 17131Containers.Count_Type’Last is 2**31 - 1. 17132 17133 17134@itemize * 17135 17136@item 17137“Implementation-defined convention names. See B.1(11).” 17138@end itemize 17139 17140The following convention names are supported 17141 17142 17143@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 17144@headitem 17145 17146Convention Name 17147 17148@tab 17149 17150Interpretation 17151 17152@item 17153 17154@emph{Ada} 17155 17156@tab 17157 17158Ada 17159 17160@item 17161 17162@emph{Ada_Pass_By_Copy} 17163 17164@tab 17165 17166Allowed for any types except by-reference types such as limited 17167records. Compatible with convention Ada, but causes any parameters 17168with this convention to be passed by copy. 17169 17170@item 17171 17172@emph{Ada_Pass_By_Reference} 17173 17174@tab 17175 17176Allowed for any types except by-copy types such as scalars. 17177Compatible with convention Ada, but causes any parameters 17178with this convention to be passed by reference. 17179 17180@item 17181 17182@emph{Assembler} 17183 17184@tab 17185 17186Assembly language 17187 17188@item 17189 17190@emph{Asm} 17191 17192@tab 17193 17194Synonym for Assembler 17195 17196@item 17197 17198@emph{Assembly} 17199 17200@tab 17201 17202Synonym for Assembler 17203 17204@item 17205 17206@emph{C} 17207 17208@tab 17209 17210C 17211 17212@item 17213 17214@emph{C_Pass_By_Copy} 17215 17216@tab 17217 17218Allowed only for record types, like C, but also notes that record 17219is to be passed by copy rather than reference. 17220 17221@item 17222 17223@emph{COBOL} 17224 17225@tab 17226 17227COBOL 17228 17229@item 17230 17231@emph{C_Plus_Plus (or CPP)} 17232 17233@tab 17234 17235C++ 17236 17237@item 17238 17239@emph{Default} 17240 17241@tab 17242 17243Treated the same as C 17244 17245@item 17246 17247@emph{External} 17248 17249@tab 17250 17251Treated the same as C 17252 17253@item 17254 17255@emph{Fortran} 17256 17257@tab 17258 17259Fortran 17260 17261@item 17262 17263@emph{Intrinsic} 17264 17265@tab 17266 17267For support of pragma @code{Import} with convention Intrinsic, see 17268separate section on Intrinsic Subprograms. 17269 17270@item 17271 17272@emph{Stdcall} 17273 17274@tab 17275 17276Stdcall (used for Windows implementations only). This convention correspond 17277to the WINAPI (previously called Pascal convention) C/C++ convention under 17278Windows. A routine with this convention cleans the stack before 17279exit. This pragma cannot be applied to a dispatching call. 17280 17281@item 17282 17283@emph{DLL} 17284 17285@tab 17286 17287Synonym for Stdcall 17288 17289@item 17290 17291@emph{Win32} 17292 17293@tab 17294 17295Synonym for Stdcall 17296 17297@item 17298 17299@emph{Stubbed} 17300 17301@tab 17302 17303Stubbed is a special convention used to indicate that the body of the 17304subprogram will be entirely ignored. Any call to the subprogram 17305is converted into a raise of the @code{Program_Error} exception. If a 17306pragma @code{Import} specifies convention @code{stubbed} then no body need 17307be present at all. This convention is useful during development for the 17308inclusion of subprograms whose body has not yet been written. 17309In addition, all otherwise unrecognized convention names are also 17310treated as being synonymous with convention C. In all implementations, 17311use of such other names results in a warning. 17312 17313@end multitable 17314 17315 17316 17317@itemize * 17318 17319@item 17320“The meaning of link names. See B.1(36).” 17321@end itemize 17322 17323Link names are the actual names used by the linker. 17324 17325 17326@itemize * 17327 17328@item 17329“The manner of choosing link names when neither the link name nor the 17330address of an imported or exported entity is specified. See B.1(36).” 17331@end itemize 17332 17333The default linker name is that which would be assigned by the relevant 17334external language, interpreting the Ada name as being in all lower case 17335letters. 17336 17337 17338@itemize * 17339 17340@item 17341“The effect of pragma @code{Linker_Options}. See B.1(37).” 17342@end itemize 17343 17344The string passed to @code{Linker_Options} is presented uninterpreted as 17345an argument to the link command, unless it contains ASCII.NUL characters. 17346NUL characters if they appear act as argument separators, so for example 17347 17348@example 17349pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 17350@end example 17351 17352causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 17353linker. The order of linker options is preserved for a given unit. The final 17354list of options passed to the linker is in reverse order of the elaboration 17355order. For example, linker options for a body always appear before the options 17356from the corresponding package spec. 17357 17358 17359@itemize * 17360 17361@item 17362“The contents of the visible part of package 17363@code{Interfaces} and its language-defined descendants. See B.2(1).” 17364@end itemize 17365 17366See files with prefix @code{i-} in the distributed library. 17367 17368 17369@itemize * 17370 17371@item 17372“Implementation-defined children of package 17373@code{Interfaces}. The contents of the visible part of package 17374@code{Interfaces}. See B.2(11).” 17375@end itemize 17376 17377See files with prefix @code{i-} in the distributed library. 17378 17379 17380@itemize * 17381 17382@item 17383“The definitions of certain types and constants in Interfaces.C. 17384See B.3(41).” 17385@end itemize 17386 17387See source file @code{i-c.ads}. 17388 17389 17390@itemize * 17391 17392@item 17393“The types @code{Floating}, @code{Long_Floating}, 17394@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 17395@code{COBOL_Character}; and the initialization of the variables 17396@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 17397@code{Interfaces.COBOL}. See B.4(50).” 17398@end itemize 17399 17400 17401@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 17402@headitem 17403 17404COBOL 17405 17406@tab 17407 17408Ada 17409 17410@item 17411 17412@emph{Floating} 17413 17414@tab 17415 17416Float 17417 17418@item 17419 17420@emph{Long_Floating} 17421 17422@tab 17423 17424(Floating) Long_Float 17425 17426@item 17427 17428@emph{Binary} 17429 17430@tab 17431 17432Integer 17433 17434@item 17435 17436@emph{Long_Binary} 17437 17438@tab 17439 17440Long_Long_Integer 17441 17442@item 17443 17444@emph{Decimal_Element} 17445 17446@tab 17447 17448Character 17449 17450@item 17451 17452@emph{COBOL_Character} 17453 17454@tab 17455 17456Character 17457 17458@end multitable 17459 17460 17461For initialization, see the file @code{i-cobol.ads} in the distributed library. 17462 17463 17464@itemize * 17465 17466@item 17467“The types Fortran_Integer, Real, Double_Precision, and Character_Set 17468in Interfaces.Fortran. See B.5(17).” 17469@end itemize 17470 17471See source file @code{i-fortra.ads}. These types are derived, respectively, 17472from Integer, Float, Long_Float, and Character. 17473 17474 17475@itemize * 17476 17477@item 17478“Implementation-defined intrinsic subprograms. See C.1(1).” 17479@end itemize 17480 17481See separate section on Intrinsic Subprograms. 17482 17483 17484@itemize * 17485 17486@item 17487“Any restrictions on a protected procedure or its containing type when an 17488aspect Attach_handler or Interrupt_Handler is specified. See C.3.1(17).” 17489@end itemize 17490 17491There are no such restrictions. 17492 17493 17494@itemize * 17495 17496@item 17497“Any other forms of interrupt handler supported by the Attach_Handler and 17498Interrupt_Handler aspects. See C.3.1(19).” 17499@end itemize 17500 17501There are no such forms. 17502 17503 17504@itemize * 17505 17506@item 17507 17508@table @asis 17509 17510@item “The semantics of some attributes and functions of an entity for which 17511 17512aspect Discard_Names is True. See C.5(7).” 17513@end table 17514@end itemize 17515 17516If Discard_Names is True for an enumeration type, the Image attribute 17517provides the image of the Pos of the literal, and Value accepts 17518Pos values. 17519 17520If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true 17521for a tagged type, its Expanded_Name and External_Tag values are 17522empty strings. This is useful to avoid exposing entity names at binary 17523level. 17524 17525 17526@itemize * 17527 17528@item 17529“The modulus and size of Test_and_Set_Flag. See C.6.3(8).” 17530@end itemize 17531 17532The modulus is 2**8. The size is 8. 17533 17534 17535@itemize * 17536 17537@item 17538“The value used to represent the set value for Atomic_Test_and_Set. 17539See C.6.3(10).” 17540@end itemize 17541 17542The value is 1. 17543 17544 17545@itemize * 17546 17547@item 17548“The result of the @code{Task_Identification.Image} 17549attribute. See C.7.1(7).” 17550@end itemize 17551 17552The result of this attribute is a string that identifies 17553the object or component that denotes a given task. If a variable @code{Var} 17554has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}}, 17555where the suffix @emph{XXXXXXXX} 17556is the hexadecimal representation of the virtual address of the corresponding 17557task control block. If the variable is an array of tasks, the image of each 17558task will have the form of an indexed component indicating the position of a 17559given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a 17560component of a record, the image of the task will have the form of a selected 17561component. These rules are fully recursive, so that the image of a task that 17562is a subcomponent of a composite object corresponds to the expression that 17563designates this task. 17564 17565If a task is created by an allocator, its image depends on the context. If the 17566allocator is part of an object declaration, the rules described above are used 17567to construct its image, and this image is not affected by subsequent 17568assignments. If the allocator appears within an expression, the image 17569includes only the name of the task type. 17570 17571If the configuration pragma Discard_Names is present, or if the restriction 17572No_Implicit_Heap_Allocation is in effect, the image reduces to 17573the numeric suffix, that is to say the hexadecimal representation of the 17574virtual address of the control block of the task. 17575 17576 17577@itemize * 17578 17579@item 17580“The value of @code{Current_Task} when in a protected entry 17581or interrupt handler. See C.7.1(17).” 17582@end itemize 17583 17584Protected entries or interrupt handlers can be executed by any 17585convenient thread, so the value of @code{Current_Task} is undefined. 17586 17587 17588@itemize * 17589 17590@item 17591“Granularity of locking for Task_Attributes. See C.7.2(16).” 17592@end itemize 17593 17594No locking is needed if the formal type Attribute has the size and 17595alignment of either Integer or System.Address and the bit representation 17596of Initial_Value is all zeroes. Otherwise, locking is performed. 17597 17598 17599@itemize * 17600 17601@item 17602“The declarations of @code{Any_Priority} and 17603@code{Priority}. See D.1(11).” 17604@end itemize 17605 17606See declarations in file @code{system.ads}. 17607 17608 17609@itemize * 17610 17611@item 17612“Implementation-defined execution resources. See D.1(15).” 17613@end itemize 17614 17615There are no implementation-defined execution resources. 17616 17617 17618@itemize * 17619 17620@item 17621“Whether, on a multiprocessor, a task that is waiting for 17622access to a protected object keeps its processor busy. See D.2.1(3).” 17623@end itemize 17624 17625On a multi-processor, a task that is waiting for access to a protected 17626object does not keep its processor busy. 17627 17628 17629@itemize * 17630 17631@item 17632“The affect of implementation defined execution resources 17633on task dispatching. See D.2.1(9).” 17634@end itemize 17635 17636Tasks map to threads in the threads package used by GNAT. Where possible 17637and appropriate, these threads correspond to native threads of the 17638underlying operating system. 17639 17640 17641@itemize * 17642 17643@item 17644“Implementation-defined task dispatching policies. See D.2.2(3).” 17645@end itemize 17646 17647There are no implementation-defined task dispatching policies. 17648 17649 17650@itemize * 17651 17652@item 17653“The value of Default_Quantum in Dispatching.Round_Robin. See D.2.5(4).” 17654@end itemize 17655 17656The value is 10 milliseconds. 17657 17658 17659@itemize * 17660 17661@item 17662“Implementation-defined @emph{policy_identifiers} allowed 17663in a pragma @code{Locking_Policy}. See D.3(4).” 17664@end itemize 17665 17666The two implementation defined policies permitted in GNAT are 17667@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On 17668targets that support the @code{Inheritance_Locking} policy, locking is 17669implemented by inheritance, i.e., the task owning the lock operates 17670at a priority equal to the highest priority of any task currently 17671requesting the lock. On targets that support the 17672@code{Concurrent_Readers_Locking} policy, locking is implemented with a 17673read/write lock allowing multiple protected object functions to enter 17674concurrently. 17675 17676 17677@itemize * 17678 17679@item 17680“Default ceiling priorities. See D.3(10).” 17681@end itemize 17682 17683The ceiling priority of protected objects of the type 17684@code{System.Interrupt_Priority'Last} as described in the Ada 17685Reference Manual D.3(10), 17686 17687 17688@itemize * 17689 17690@item 17691“The ceiling of any protected object used internally by 17692the implementation. See D.3(16).” 17693@end itemize 17694 17695The ceiling priority of internal protected objects is 17696@code{System.Priority'Last}. 17697 17698 17699@itemize * 17700 17701@item 17702“Implementation-defined queuing policies. See D.4(1).” 17703@end itemize 17704 17705There are no implementation-defined queuing policies. 17706 17707 17708@itemize * 17709 17710@item 17711“Implementation-defined admission policies. See D.4.1(1).” 17712@end itemize 17713 17714There are no implementation-defined admission policies. 17715 17716 17717@itemize * 17718 17719@item 17720“Any operations that implicitly require heap storage 17721allocation. See D.7(8).” 17722@end itemize 17723 17724The only operation that implicitly requires heap storage allocation is 17725task creation. 17726 17727 17728@itemize * 17729 17730@item 17731“When restriction No_Dynamic_CPU_Assignment applies to a partition, the 17732processor on which a task with a CPU value of a Not_A_Specific_CPU will 17733execute. See D.7(10).” 17734@end itemize 17735 17736Unknown. 17737 17738 17739@itemize * 17740 17741@item 17742 17743@table @asis 17744 17745@item “When restriction No_Task_Termination applies to a partition, what happens 17746 17747when a task terminates. See D.7(15.1).” 17748@end table 17749@end itemize 17750 17751Execution is erroneous in that case. 17752 17753 17754@itemize * 17755 17756@item 17757 17758@table @asis 17759 17760@item “The behavior when restriction Max_Storage_At_Blocking is violated. 17761 17762See D.7(17).” 17763@end table 17764@end itemize 17765 17766Execution is erroneous in that case. 17767 17768 17769@itemize * 17770 17771@item 17772“The behavior when restriction Max_Asynchronous_Select_Nesting is violated. 17773See D.7(18).” 17774@end itemize 17775 17776Execution is erroneous in that case. 17777 17778 17779@itemize * 17780 17781@item 17782“The behavior when restriction Max_Tasks is violated. See D.7(19).” 17783@end itemize 17784 17785Execution is erroneous in that case. 17786 17787 17788@itemize * 17789 17790@item 17791 17792@table @asis 17793 17794@item “Whether the use of pragma Restrictions results in a reduction in program 17795 17796code or data size or execution time. See D.7(20).” 17797 17798Yes it can, but the precise circumstances and properties of such reductions 17799are difficult to characterize. 17800@end table 17801 17802@item 17803“The value of Barrier_Limit’Last in Synchronous_Barriers. See D.10.1(4).” 17804@end itemize 17805 17806Synchronous_Barriers.Barrier_Limit’Last is Integer’Last . 17807 17808 17809@itemize * 17810 17811@item 17812“When an aborted task that is waiting on a Synchronous_Barrier is aborted. 17813See D.10.1(13).” 17814@end itemize 17815 17816Difficult to characterize. 17817 17818 17819@itemize * 17820 17821@item 17822 17823@table @asis 17824 17825@item “The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets. 17826 17827See D.14.2(7).” 17828@end table 17829@end itemize 17830 17831See source file @code{a-etgrbu.ads}. 17832 17833 17834@itemize * 17835 17836@item 17837“The value of CPU_Range’Last in System.Multiprocessors. See D.16(4).” 17838@end itemize 17839 17840See source file @code{s-multip.ads}. 17841 17842 17843@itemize * 17844 17845@item 17846“The processor on which the environment task executes in the absence 17847of a value for the aspect CPU. See D.16(13).” 17848@end itemize 17849 17850Unknown. 17851 17852 17853@itemize * 17854 17855@item 17856“The means for creating and executing distributed 17857programs. See E(5).” 17858@end itemize 17859 17860The GLADE package provides a utility GNATDIST for creating and executing 17861distributed programs. See the GLADE reference manual for further details. 17862 17863 17864@itemize * 17865 17866@item 17867“Any events that can result in a partition becoming 17868inaccessible. See E.1(7).” 17869@end itemize 17870 17871See the GLADE reference manual for full details on such events. 17872 17873 17874@itemize * 17875 17876@item 17877“The scheduling policies, treatment of priorities, and management of 17878shared resources between partitions in certain cases. See E.1(11).” 17879@end itemize 17880 17881See the GLADE reference manual for full details on these aspects of 17882multi-partition execution. 17883 17884 17885@itemize * 17886 17887@item 17888“Whether the execution of the remote subprogram is 17889immediately aborted as a result of cancellation. See E.4(13).” 17890@end itemize 17891 17892See the GLADE reference manual for details on the effect of abort in 17893a distributed application. 17894 17895 17896@itemize * 17897 17898@item 17899“The range of type System.RPC.Partition_Id. See E.5(14).” 17900@end itemize 17901 17902System.RPC.Partion_ID’Last is Integer’Last. See source file @code{s-rpc.ads}. 17903 17904 17905@itemize * 17906 17907@item 17908“Implementation-defined interfaces in the PCS. See E.5(26).” 17909@end itemize 17910 17911See the GLADE reference manual for a full description of all 17912implementation defined interfaces. 17913 17914 17915@itemize * 17916 17917@item 17918“The values of named numbers in the package 17919@code{Decimal}. See F.2(7).” 17920@end itemize 17921 17922 17923@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 17924@headitem 17925 17926Named Number 17927 17928@tab 17929 17930Value 17931 17932@item 17933 17934@emph{Max_Scale} 17935 17936@tab 17937 17938+18 17939 17940@item 17941 17942@emph{Min_Scale} 17943 17944@tab 17945 17946-18 17947 17948@item 17949 17950@emph{Min_Delta} 17951 17952@tab 17953 179541.0E-18 17955 17956@item 17957 17958@emph{Max_Delta} 17959 17960@tab 17961 179621.0E+18 17963 17964@item 17965 17966@emph{Max_Decimal_Digits} 17967 17968@tab 17969 1797018 17971 17972@end multitable 17973 17974 17975 17976@itemize * 17977 17978@item 17979“The value of @code{Max_Picture_Length} in the package 17980@code{Text_IO.Editing}. See F.3.3(16).” 17981@end itemize 17982 1798364 17984 17985 17986@itemize * 17987 17988@item 17989“The value of @code{Max_Picture_Length} in the package 17990@code{Wide_Text_IO.Editing}. See F.3.4(5).” 17991@end itemize 17992 1799364 17994 17995 17996@itemize * 17997 17998@item 17999“The accuracy actually achieved by the complex elementary 18000functions and by other complex arithmetic operations. See G.1(1).” 18001@end itemize 18002 18003Standard library functions are used for the complex arithmetic 18004operations. Only fast math mode is currently supported. 18005 18006 18007@itemize * 18008 18009@item 18010“The sign of a zero result (or a component thereof) from 18011any operator or function in @code{Numerics.Generic_Complex_Types}, when 18012@code{Real'Signed_Zeros} is True. See G.1.1(53).” 18013@end itemize 18014 18015The signs of zero values are as recommended by the relevant 18016implementation advice. 18017 18018 18019@itemize * 18020 18021@item 18022“The sign of a zero result (or a component thereof) from 18023any operator or function in 18024@code{Numerics.Generic_Complex_Elementary_Functions}, when 18025@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).” 18026@end itemize 18027 18028The signs of zero values are as recommended by the relevant 18029implementation advice. 18030 18031 18032@itemize * 18033 18034@item 18035“Whether the strict mode or the relaxed mode is the 18036default. See G.2(2).” 18037@end itemize 18038 18039The strict mode is the default. There is no separate relaxed mode. GNAT 18040provides a highly efficient implementation of strict mode. 18041 18042 18043@itemize * 18044 18045@item 18046“The result interval in certain cases of fixed-to-float 18047conversion. See G.2.1(10).” 18048@end itemize 18049 18050For cases where the result interval is implementation dependent, the 18051accuracy is that provided by performing all operations in 64-bit IEEE 18052floating-point format. 18053 18054 18055@itemize * 18056 18057@item 18058“The result of a floating point arithmetic operation in 18059overflow situations, when the @code{Machine_Overflows} attribute of the 18060result type is @code{False}. See G.2.1(13).” 18061@end itemize 18062 18063Infinite and NaN values are produced as dictated by the IEEE 18064floating-point standard. 18065Note that on machines that are not fully compliant with the IEEE 18066floating-point standard, such as Alpha, the @emph{-mieee} compiler flag 18067must be used for achieving IEEE conforming behavior (although at the cost 18068of a significant performance penalty), so infinite and NaN values are 18069properly generated. 18070 18071 18072@itemize * 18073 18074@item 18075“The result interval for division (or exponentiation by a 18076negative exponent), when the floating point hardware implements division 18077as multiplication by a reciprocal. See G.2.1(16).” 18078@end itemize 18079 18080Not relevant, division is IEEE exact. 18081 18082 18083@itemize * 18084 18085@item 18086“The definition of close result set, which determines the accuracy of 18087certain fixed point multiplications and divisions. See G.2.3(5).” 18088@end itemize 18089 18090Operations in the close result set are performed using IEEE long format 18091floating-point arithmetic. The input operands are converted to 18092floating-point, the operation is done in floating-point, and the result 18093is converted to the target type. 18094 18095 18096@itemize * 18097 18098@item 18099“Conditions on a @emph{universal_real} operand of a fixed 18100point multiplication or division for which the result shall be in the 18101perfect result set. See G.2.3(22).” 18102@end itemize 18103 18104The result is only defined to be in the perfect result set if the result 18105can be computed by a single scaling operation involving a scale factor 18106representable in 64 bits. 18107 18108 18109@itemize * 18110 18111@item 18112“The result of a fixed point arithmetic operation in 18113overflow situations, when the @code{Machine_Overflows} attribute of the 18114result type is @code{False}. See G.2.3(27).” 18115@end itemize 18116 18117Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 18118types. 18119 18120 18121@itemize * 18122 18123@item 18124“The result of an elementary function reference in 18125overflow situations, when the @code{Machine_Overflows} attribute of the 18126result type is @code{False}. See G.2.4(4).” 18127@end itemize 18128 18129IEEE infinite and Nan values are produced as appropriate. 18130 18131 18132@itemize * 18133 18134@item 18135“The value of the angle threshold, within which certain 18136elementary functions, complex arithmetic operations, and complex 18137elementary functions yield results conforming to a maximum relative 18138error bound. See G.2.4(10).” 18139@end itemize 18140 18141Information on this subject is not yet available. 18142 18143 18144@itemize * 18145 18146@item 18147“The accuracy of certain elementary functions for 18148parameters beyond the angle threshold. See G.2.4(10).” 18149@end itemize 18150 18151Information on this subject is not yet available. 18152 18153 18154@itemize * 18155 18156@item 18157“The result of a complex arithmetic operation or complex 18158elementary function reference in overflow situations, when the 18159@code{Machine_Overflows} attribute of the corresponding real type is 18160@code{False}. See G.2.6(5).” 18161@end itemize 18162 18163IEEE infinite and Nan values are produced as appropriate. 18164 18165 18166@itemize * 18167 18168@item 18169“The accuracy of certain complex arithmetic operations and 18170certain complex elementary functions for parameters (or components 18171thereof) beyond the angle threshold. See G.2.6(8).” 18172@end itemize 18173 18174Information on those subjects is not yet available. 18175 18176 18177@itemize * 18178 18179@item 18180 18181@table @asis 18182 18183@item “The accuracy requirements for the subprograms Solve, Inverse, 18184 18185Determinant, Eigenvalues and Eigensystem for type Real_Matrix. 18186See G.3.1(81).” 18187@end table 18188@end itemize 18189 18190Information on those subjects is not yet available. 18191 18192 18193@itemize * 18194 18195@item 18196 18197@table @asis 18198 18199@item “The accuracy requirements for the subprograms Solve, Inverse, 18200 18201Determinant, Eigenvalues and Eigensystem for type Complex_Matrix. 18202See G.3.2(149).” 18203@end table 18204@end itemize 18205 18206Information on those subjects is not yet available. 18207 18208 18209@itemize * 18210 18211@item 18212“The consequences of violating No_Hidden_Indirect_Globals. See H.4(23.9).” 18213@end itemize 18214 18215Execution is erroneous in that case. 18216 18217@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top 18218@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} 18219@chapter Intrinsic Subprograms 18220 18221 18222@geindex Intrinsic Subprograms 18223 18224GNAT allows a user application program to write the declaration: 18225 18226@example 18227pragma Import (Intrinsic, name); 18228@end example 18229 18230providing that the name corresponds to one of the implemented intrinsic 18231subprograms in GNAT, and that the parameter profile of the referenced 18232subprogram meets the requirements. This chapter describes the set of 18233implemented intrinsic subprograms, and the requirements on parameter profiles. 18234Note that no body is supplied; as with other uses of pragma Import, the 18235body is supplied elsewhere (in this case by the compiler itself). Note 18236that any use of this feature is potentially non-portable, since the 18237Ada standard does not require Ada compilers to implement this feature. 18238 18239@menu 18240* Intrinsic Operators:: 18241* Compilation_ISO_Date:: 18242* Compilation_Date:: 18243* Compilation_Time:: 18244* Enclosing_Entity:: 18245* Exception_Information:: 18246* Exception_Message:: 18247* Exception_Name:: 18248* File:: 18249* Line:: 18250* Shifts and Rotates:: 18251* Source_Location:: 18252 18253@end menu 18254 18255@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms 18256@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{260} 18257@section Intrinsic Operators 18258 18259 18260@geindex Intrinsic operator 18261 18262All the predefined numeric operators in package Standard 18263in @code{pragma Import (Intrinsic,..)} 18264declarations. In the binary operator case, the operands must have the same 18265size. The operand or operands must also be appropriate for 18266the operator. For example, for addition, the operands must 18267both be floating-point or both be fixed-point, and the 18268right operand for @code{"**"} must have a root type of 18269@code{Standard.Integer'Base}. 18270You can use an intrinsic operator declaration as in the following example: 18271 18272@example 18273type Int1 is new Integer; 18274type Int2 is new Integer; 18275 18276function "+" (X1 : Int1; X2 : Int2) return Int1; 18277function "+" (X1 : Int1; X2 : Int2) return Int2; 18278pragma Import (Intrinsic, "+"); 18279@end example 18280 18281This declaration would permit ‘mixed mode’ arithmetic on items 18282of the differing types @code{Int1} and @code{Int2}. 18283It is also possible to specify such operators for private types, if the 18284full views are appropriate arithmetic types. 18285 18286@node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms 18287@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{262} 18288@section Compilation_ISO_Date 18289 18290 18291@geindex Compilation_ISO_Date 18292 18293This intrinsic subprogram is used in the implementation of the 18294library package @code{GNAT.Source_Info}. The only useful use of the 18295intrinsic import in this case is the one in this unit, so an 18296application program should simply call the function 18297@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of 18298the current compilation (in local time format YYYY-MM-DD). 18299 18300@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms 18301@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{264} 18302@section Compilation_Date 18303 18304 18305@geindex Compilation_Date 18306 18307Same as Compilation_ISO_Date, except the string is in the form 18308MMM DD YYYY. 18309 18310@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms 18311@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{266} 18312@section Compilation_Time 18313 18314 18315@geindex Compilation_Time 18316 18317This intrinsic subprogram is used in the implementation of the 18318library package @code{GNAT.Source_Info}. The only useful use of the 18319intrinsic import in this case is the one in this unit, so an 18320application program should simply call the function 18321@code{GNAT.Source_Info.Compilation_Time} to obtain the time of 18322the current compilation (in local time format HH:MM:SS). 18323 18324@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms 18325@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{268} 18326@section Enclosing_Entity 18327 18328 18329@geindex Enclosing_Entity 18330 18331This intrinsic subprogram is used in the implementation of the 18332library package @code{GNAT.Source_Info}. The only useful use of the 18333intrinsic import in this case is the one in this unit, so an 18334application program should simply call the function 18335@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 18336the current subprogram, package, task, entry, or protected subprogram. 18337 18338@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms 18339@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{26a} 18340@section Exception_Information 18341 18342 18343@geindex Exception_Information' 18344 18345This intrinsic subprogram is used in the implementation of the 18346library package @code{GNAT.Current_Exception}. The only useful 18347use of the intrinsic import in this case is the one in this unit, 18348so an application program should simply call the function 18349@code{GNAT.Current_Exception.Exception_Information} to obtain 18350the exception information associated with the current exception. 18351 18352@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms 18353@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26c} 18354@section Exception_Message 18355 18356 18357@geindex Exception_Message 18358 18359This intrinsic subprogram is used in the implementation of the 18360library package @code{GNAT.Current_Exception}. The only useful 18361use of the intrinsic import in this case is the one in this unit, 18362so an application program should simply call the function 18363@code{GNAT.Current_Exception.Exception_Message} to obtain 18364the message associated with the current exception. 18365 18366@node Exception_Name,File,Exception_Message,Intrinsic Subprograms 18367@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26e} 18368@section Exception_Name 18369 18370 18371@geindex Exception_Name 18372 18373This intrinsic subprogram is used in the implementation of the 18374library package @code{GNAT.Current_Exception}. The only useful 18375use of the intrinsic import in this case is the one in this unit, 18376so an application program should simply call the function 18377@code{GNAT.Current_Exception.Exception_Name} to obtain 18378the name of the current exception. 18379 18380@node File,Line,Exception_Name,Intrinsic Subprograms 18381@anchor{gnat_rm/intrinsic_subprograms file}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{270} 18382@section File 18383 18384 18385@geindex File 18386 18387This intrinsic subprogram is used in the implementation of the 18388library package @code{GNAT.Source_Info}. The only useful use of the 18389intrinsic import in this case is the one in this unit, so an 18390application program should simply call the function 18391@code{GNAT.Source_Info.File} to obtain the name of the current 18392file. 18393 18394@node Line,Shifts and Rotates,File,Intrinsic Subprograms 18395@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{272} 18396@section Line 18397 18398 18399@geindex Line 18400 18401This intrinsic subprogram is used in the implementation of the 18402library package @code{GNAT.Source_Info}. The only useful use of the 18403intrinsic import in this case is the one in this unit, so an 18404application program should simply call the function 18405@code{GNAT.Source_Info.Line} to obtain the number of the current 18406source line. 18407 18408@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms 18409@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{274} 18410@section Shifts and Rotates 18411 18412 18413@geindex Shift_Left 18414 18415@geindex Shift_Right 18416 18417@geindex Shift_Right_Arithmetic 18418 18419@geindex Rotate_Left 18420 18421@geindex Rotate_Right 18422 18423In standard Ada, the shift and rotate functions are available only 18424for the predefined modular types in package @code{Interfaces}. However, in 18425GNAT it is possible to define these functions for any integer 18426type (signed or modular), as in this example: 18427 18428@example 18429function Shift_Left 18430 (Value : T; 18431 Amount : Natural) return T 18432with Import, Convention => Intrinsic; 18433@end example 18434 18435The function name must be one of 18436Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 18437Rotate_Right. T must be an integer type. T’Size must be 184388, 16, 32 or 64 bits; if T is modular, the modulus 18439must be 2**8, 2**16, 2**32 or 2**64. 18440The result type must be the same as the type of @code{Value}. 18441The shift amount must be Natural. 18442The formal parameter names can be anything. 18443 18444A more convenient way of providing these shift operators is to use the 18445Provide_Shift_Operators pragma, which provides the function declarations and 18446corresponding pragma Import’s for all five shift functions. For signed types 18447the semantics of these operators is to interpret the bitwise result of the 18448corresponding operator for modular type. In particular, shifting a negative 18449number may change its sign bit to positive. 18450 18451@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms 18452@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{276} 18453@section Source_Location 18454 18455 18456@geindex Source_Location 18457 18458This intrinsic subprogram is used in the implementation of the 18459library routine @code{GNAT.Source_Info}. The only useful use of the 18460intrinsic import in this case is the one in this unit, so an 18461application program should simply call the function 18462@code{GNAT.Source_Info.Source_Location} to obtain the current 18463source file location. 18464 18465@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top 18466@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} 18467@chapter Representation Clauses and Pragmas 18468 18469 18470@geindex Representation Clauses 18471 18472@geindex Representation Clause 18473 18474@geindex Representation Pragma 18475 18476@geindex Pragma 18477@geindex representation 18478 18479This section describes the representation clauses accepted by GNAT, and 18480their effect on the representation of corresponding data objects. 18481 18482GNAT fully implements Annex C (Systems Programming). This means that all 18483the implementation advice sections in chapter 13 are fully implemented. 18484However, these sections only require a minimal level of support for 18485representation clauses. GNAT provides much more extensive capabilities, 18486and this section describes the additional capabilities provided. 18487 18488@menu 18489* Alignment Clauses:: 18490* Size Clauses:: 18491* Storage_Size Clauses:: 18492* Size of Variant Record Objects:: 18493* Biased Representation:: 18494* Value_Size and Object_Size Clauses:: 18495* Component_Size Clauses:: 18496* Bit_Order Clauses:: 18497* Effect of Bit_Order on Byte Ordering:: 18498* Pragma Pack for Arrays:: 18499* Pragma Pack for Records:: 18500* Record Representation Clauses:: 18501* Handling of Records with Holes:: 18502* Enumeration Clauses:: 18503* Address Clauses:: 18504* Use of Address Clauses for Memory-Mapped I/O:: 18505* Effect of Convention on Representation:: 18506* Conventions and Anonymous Access Types:: 18507* Determining the Representations chosen by GNAT:: 18508 18509@end menu 18510 18511@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas 18512@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{27a} 18513@section Alignment Clauses 18514 18515 18516@geindex Alignment Clause 18517 18518GNAT requires that all alignment clauses specify 0 or a power of 2, and 18519all default alignments are always a power of 2. Specifying 0 is the 18520same as specifying 1. 18521 18522The default alignment values are as follows: 18523 18524 18525@itemize * 18526 18527@item 18528@emph{Elementary Types}. 18529 18530For elementary types, the alignment is the minimum of the actual size of 18531objects of the type divided by @code{Storage_Unit}, 18532and the maximum alignment supported by the target. 18533(This maximum alignment is given by the GNAT-specific attribute 18534@code{Standard'Maximum_Alignment}; see @ref{18e,,Attribute Maximum_Alignment}.) 18535 18536@geindex Maximum_Alignment attribute 18537 18538For example, for type @code{Long_Float}, the object size is 8 bytes, and the 18539default alignment will be 8 on any target that supports alignments 18540this large, but on some targets, the maximum alignment may be smaller 18541than 8, in which case objects of type @code{Long_Float} will be maximally 18542aligned. 18543 18544@item 18545@emph{Arrays}. 18546 18547For arrays, the alignment is equal to the alignment of the component type 18548for the normal case where no packing or component size is given. If the 18549array is packed, and the packing is effective (see separate section on 18550packed arrays), then the alignment will be either 4, 2, or 1 for long packed 18551arrays or arrays whose length is not known at compile time, depending on 18552whether the component size is divisible by 4, 2, or is odd. For short packed 18553arrays, which are handled internally as modular types, the alignment 18554will be as described for elementary types, e.g. a packed array of length 1855531 bits will have an object size of four bytes, and an alignment of 4. 18556 18557@item 18558@emph{Records}. 18559 18560For the normal unpacked case, the alignment of a record is equal to 18561the maximum alignment of any of its components. For tagged records, this 18562includes the implicit access type used for the tag. If a pragma @code{Pack} 18563is used and all components are packable (see separate section on pragma 18564@code{Pack}), then the resulting alignment is 1, unless the layout of the 18565record makes it profitable to increase it. 18566 18567A special case is when: 18568 18569 18570@itemize * 18571 18572@item 18573the size of the record is given explicitly, or a 18574full record representation clause is given, and 18575 18576@item 18577the size of the record is 2, 4, or 8 bytes. 18578@end itemize 18579 18580In this case, an alignment is chosen to match the 18581size of the record. For example, if we have: 18582 18583@example 18584type Small is record 18585 A, B : Character; 18586end record; 18587for Small'Size use 16; 18588@end example 18589 18590then the default alignment of the record type @code{Small} is 2, not 1. This 18591leads to more efficient code when the record is treated as a unit, and also 18592allows the type to specified as @code{Atomic} on architectures requiring 18593strict alignment. 18594@end itemize 18595 18596An alignment clause may specify a larger alignment than the default value 18597up to some maximum value dependent on the target (obtainable by using the 18598attribute reference @code{Standard'Maximum_Alignment}). It may also specify 18599a smaller alignment than the default value for enumeration, integer and 18600fixed point types, as well as for record types, for example 18601 18602@example 18603type V is record 18604 A : Integer; 18605end record; 18606 18607for V'alignment use 1; 18608@end example 18609 18610@geindex Alignment 18611@geindex default 18612 18613The default alignment for the type @code{V} is 4, as a result of the 18614Integer field in the record, but it is permissible, as shown, to 18615override the default alignment of the record with a smaller value. 18616 18617@geindex Alignment 18618@geindex subtypes 18619 18620Note that according to the Ada standard, an alignment clause applies only 18621to the first named subtype. If additional subtypes are declared, then the 18622compiler is allowed to choose any alignment it likes, and there is no way 18623to control this choice. Consider: 18624 18625@example 18626type R is range 1 .. 10_000; 18627for R'Alignment use 1; 18628subtype RS is R range 1 .. 1000; 18629@end example 18630 18631The alignment clause specifies an alignment of 1 for the first named subtype 18632@code{R} but this does not necessarily apply to @code{RS}. When writing 18633portable Ada code, you should avoid writing code that explicitly or 18634implicitly relies on the alignment of such subtypes. 18635 18636For the GNAT compiler, if an explicit alignment clause is given, this 18637value is also used for any subsequent subtypes. So for GNAT, in the 18638above example, you can count on the alignment of @code{RS} being 1. But this 18639assumption is non-portable, and other compilers may choose different 18640alignments for the subtype @code{RS}. 18641 18642@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas 18643@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27c} 18644@section Size Clauses 18645 18646 18647@geindex Size Clause 18648 18649The default size for a type @code{T} is obtainable through the 18650language-defined attribute @code{T'Size} and also through the 18651equivalent GNAT-defined attribute @code{T'Value_Size}. 18652For objects of type @code{T}, GNAT will generally increase the type size 18653so that the object size (obtainable through the GNAT-defined attribute 18654@code{T'Object_Size}) 18655is a multiple of @code{T'Alignment * Storage_Unit}. 18656 18657For example: 18658 18659@example 18660type Smallint is range 1 .. 6; 18661 18662type Rec is record 18663 Y1 : integer; 18664 Y2 : boolean; 18665end record; 18666@end example 18667 18668In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 18669as specified by the RM rules, 18670but objects of this type will have a size of 8 18671(@code{Smallint'Object_Size} = 8), 18672since objects by default occupy an integral number 18673of storage units. On some targets, notably older 18674versions of the Digital Alpha, the size of stand 18675alone objects of this type may be 32, reflecting 18676the inability of the hardware to do byte load/stores. 18677 18678Similarly, the size of type @code{Rec} is 40 bits 18679(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 18680the alignment is 4, so objects of this type will have 18681their size increased to 64 bits so that it is a multiple 18682of the alignment (in bits). This decision is 18683in accordance with the specific Implementation Advice in RM 13.3(43): 18684 18685@quotation 18686 18687“A @code{Size} clause should be supported for an object if the specified 18688@code{Size} is at least as large as its subtype’s @code{Size}, and corresponds 18689to a size in storage elements that is a multiple of the object’s 18690@code{Alignment} (if the @code{Alignment} is nonzero).” 18691@end quotation 18692 18693An explicit size clause may be used to override the default size by 18694increasing it. For example, if we have: 18695 18696@example 18697type My_Boolean is new Boolean; 18698for My_Boolean'Size use 32; 18699@end example 18700 18701then values of this type will always be 32-bit long. In the case of discrete 18702types, the size can be increased up to 64 bits on 32-bit targets and 128 bits 18703on 64-bit targets, with the effect that the entire specified field is used to 18704hold the value, sign- or zero-extended as appropriate. If more than 64 bits 18705or 128 bits resp. is specified, then padding space is allocated after the 18706value, and a warning is issued that there are unused bits. 18707 18708Similarly the size of records and arrays may be increased, and the effect 18709is to add padding bits after the value. This also causes a warning message 18710to be generated. 18711 18712The largest Size value permitted in GNAT is 2**31-1. Since this is a 18713Size in bits, this corresponds to an object of size 256 megabytes (minus 18714one). This limitation is true on all targets. The reason for this 18715limitation is that it improves the quality of the code in many cases 18716if it is known that a Size value can be accommodated in an object of 18717type Integer. 18718 18719@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas 18720@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27e} 18721@section Storage_Size Clauses 18722 18723 18724@geindex Storage_Size Clause 18725 18726For tasks, the @code{Storage_Size} clause specifies the amount of space 18727to be allocated for the task stack. This cannot be extended, and if the 18728stack is exhausted, then @code{Storage_Error} will be raised (if stack 18729checking is enabled). Use a @code{Storage_Size} attribute definition clause, 18730or a @code{Storage_Size} pragma in the task definition to set the 18731appropriate required size. A useful technique is to include in every 18732task definition a pragma of the form: 18733 18734@example 18735pragma Storage_Size (Default_Stack_Size); 18736@end example 18737 18738Then @code{Default_Stack_Size} can be defined in a global package, and 18739modified as required. Any tasks requiring stack sizes different from the 18740default can have an appropriate alternative reference in the pragma. 18741 18742You can also use the @emph{-d} binder switch to modify the default stack 18743size. 18744 18745For access types, the @code{Storage_Size} clause specifies the maximum 18746space available for allocation of objects of the type. If this space is 18747exceeded then @code{Storage_Error} will be raised by an allocation attempt. 18748In the case where the access type is declared local to a subprogram, the 18749use of a @code{Storage_Size} clause triggers automatic use of a special 18750predefined storage pool (@code{System.Pool_Size}) that ensures that all 18751space for the pool is automatically reclaimed on exit from the scope in 18752which the type is declared. 18753 18754A special case recognized by the compiler is the specification of a 18755@code{Storage_Size} of zero for an access type. This means that no 18756items can be allocated from the pool, and this is recognized at compile 18757time, and all the overhead normally associated with maintaining a fixed 18758size storage pool is eliminated. Consider the following example: 18759 18760@example 18761procedure p is 18762 type R is array (Natural) of Character; 18763 type P is access all R; 18764 for P'Storage_Size use 0; 18765 -- Above access type intended only for interfacing purposes 18766 18767 y : P; 18768 18769 procedure g (m : P); 18770 pragma Import (C, g); 18771 18772 -- ... 18773 18774begin 18775 -- ... 18776 y := new R; 18777end; 18778@end example 18779 18780As indicated in this example, these dummy storage pools are often useful in 18781connection with interfacing where no object will ever be allocated. If you 18782compile the above example, you get the warning: 18783 18784@example 18785p.adb:16:09: warning: allocation from empty storage pool 18786p.adb:16:09: warning: Storage_Error will be raised at run time 18787@end example 18788 18789Of course in practice, there will not be any explicit allocators in the 18790case of such an access declaration. 18791 18792@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas 18793@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{280} 18794@section Size of Variant Record Objects 18795 18796 18797@geindex Size 18798@geindex variant record objects 18799 18800@geindex Variant record objects 18801@geindex size 18802 18803In the case of variant record objects, there is a question whether Size gives 18804information about a particular variant, or the maximum size required 18805for any variant. Consider the following program 18806 18807@example 18808with Text_IO; use Text_IO; 18809procedure q is 18810 type R1 (A : Boolean := False) is record 18811 case A is 18812 when True => X : Character; 18813 when False => null; 18814 end case; 18815 end record; 18816 18817 V1 : R1 (False); 18818 V2 : R1; 18819 18820begin 18821 Put_Line (Integer'Image (V1'Size)); 18822 Put_Line (Integer'Image (V2'Size)); 18823end q; 18824@end example 18825 18826Here we are dealing with a variant record, where the True variant 18827requires 16 bits, and the False variant requires 8 bits. 18828In the above example, both V1 and V2 contain the False variant, 18829which is only 8 bits long. However, the result of running the 18830program is: 18831 18832@example 188338 1883416 18835@end example 18836 18837The reason for the difference here is that the discriminant value of 18838V1 is fixed, and will always be False. It is not possible to assign 18839a True variant value to V1, therefore 8 bits is sufficient. On the 18840other hand, in the case of V2, the initial discriminant value is 18841False (from the default), but it is possible to assign a True 18842variant value to V2, therefore 16 bits must be allocated for V2 18843in the general case, even fewer bits may be needed at any particular 18844point during the program execution. 18845 18846As can be seen from the output of this program, the @code{'Size} 18847attribute applied to such an object in GNAT gives the actual allocated 18848size of the variable, which is the largest size of any of the variants. 18849The Ada Reference Manual is not completely clear on what choice should 18850be made here, but the GNAT behavior seems most consistent with the 18851language in the RM. 18852 18853In some cases, it may be desirable to obtain the size of the current 18854variant, rather than the size of the largest variant. This can be 18855achieved in GNAT by making use of the fact that in the case of a 18856subprogram parameter, GNAT does indeed return the size of the current 18857variant (because a subprogram has no way of knowing how much space 18858is actually allocated for the actual). 18859 18860Consider the following modified version of the above program: 18861 18862@example 18863with Text_IO; use Text_IO; 18864procedure q is 18865 type R1 (A : Boolean := False) is record 18866 case A is 18867 when True => X : Character; 18868 when False => null; 18869 end case; 18870 end record; 18871 18872 V2 : R1; 18873 18874 function Size (V : R1) return Integer is 18875 begin 18876 return V'Size; 18877 end Size; 18878 18879begin 18880 Put_Line (Integer'Image (V2'Size)); 18881 Put_Line (Integer'Image (Size (V2))); 18882 V2 := (True, 'x'); 18883 Put_Line (Integer'Image (V2'Size)); 18884 Put_Line (Integer'Image (Size (V2))); 18885end q; 18886@end example 18887 18888The output from this program is 18889 18890@example 1889116 188928 1889316 1889416 18895@end example 18896 18897Here we see that while the @code{'Size} attribute always returns 18898the maximum size, regardless of the current variant value, the 18899@code{Size} function does indeed return the size of the current 18900variant value. 18901 18902@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas 18903@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{282} 18904@section Biased Representation 18905 18906 18907@geindex Size for biased representation 18908 18909@geindex Biased representation 18910 18911In the case of scalars with a range starting at other than zero, it is 18912possible in some cases to specify a size smaller than the default minimum 18913value, and in such cases, GNAT uses an unsigned biased representation, 18914in which zero is used to represent the lower bound, and successive values 18915represent successive values of the type. 18916 18917For example, suppose we have the declaration: 18918 18919@example 18920type Small is range -7 .. -4; 18921for Small'Size use 2; 18922@end example 18923 18924Although the default size of type @code{Small} is 4, the @code{Size} 18925clause is accepted by GNAT and results in the following representation 18926scheme: 18927 18928@example 18929-7 is represented as 2#00# 18930-6 is represented as 2#01# 18931-5 is represented as 2#10# 18932-4 is represented as 2#11# 18933@end example 18934 18935Biased representation is only used if the specified @code{Size} clause 18936cannot be accepted in any other manner. These reduced sizes that force 18937biased representation can be used for all discrete types except for 18938enumeration types for which a representation clause is given. 18939 18940@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas 18941@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} 18942@section Value_Size and Object_Size Clauses 18943 18944 18945@geindex Value_Size 18946 18947@geindex Object_Size 18948 18949@geindex Size 18950@geindex of objects 18951 18952In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum 18953number of bits required to hold values of type @code{T}. 18954Although this interpretation was allowed in Ada 83, it was not required, 18955and this requirement in practice can cause some significant difficulties. 18956For example, in most Ada 83 compilers, @code{Natural'Size} was 32. 18957However, in Ada 95 and Ada 2005, 18958@code{Natural'Size} is 18959typically 31. This means that code may change in behavior when moving 18960from Ada 83 to Ada 95 or Ada 2005. For example, consider: 18961 18962@example 18963type Rec is record; 18964 A : Natural; 18965 B : Natural; 18966end record; 18967 18968for Rec use record 18969 at 0 range 0 .. Natural'Size - 1; 18970 at 0 range Natural'Size .. 2 * Natural'Size - 1; 18971end record; 18972@end example 18973 18974In the above code, since the typical size of @code{Natural} objects 18975is 32 bits and @code{Natural'Size} is 31, the above code can cause 18976unexpected inefficient packing in Ada 95 and Ada 2005, and in general 18977there are cases where the fact that the object size can exceed the 18978size of the type causes surprises. 18979 18980To help get around this problem GNAT provides two implementation 18981defined attributes, @code{Value_Size} and @code{Object_Size}. When 18982applied to a type, these attributes yield the size of the type 18983(corresponding to the RM defined size attribute), and the size of 18984objects of the type respectively. 18985 18986The @code{Object_Size} is used for determining the default size of 18987objects and components. This size value can be referred to using the 18988@code{Object_Size} attribute. The phrase ‘is used’ here means that it is 18989the basis of the determination of the size. The backend is free to 18990pad this up if necessary for efficiency, e.g., an 8-bit stand-alone 18991character might be stored in 32 bits on a machine with no efficient 18992byte access instructions such as the Alpha. 18993 18994The default rules for the value of @code{Object_Size} for 18995discrete types are as follows: 18996 18997 18998@itemize * 18999 19000@item 19001The @code{Object_Size} for base subtypes reflect the natural hardware 19002size in bits (run the compiler with @emph{-gnatS} to find those values 19003for numeric types). Enumeration types and fixed-point base subtypes have 190048, 16, 32, or 64 bits for this size, depending on the range of values 19005to be stored. 19006 19007@item 19008The @code{Object_Size} of a subtype is the same as the 19009@code{Object_Size} of 19010the type from which it is obtained. 19011 19012@item 19013The @code{Object_Size} of a derived base type is copied from the parent 19014base type, and the @code{Object_Size} of a derived first subtype is copied 19015from the parent first subtype. 19016@end itemize 19017 19018The @code{Value_Size} attribute 19019is the (minimum) number of bits required to store a value 19020of the type. 19021This value is used to determine how tightly to pack 19022records or arrays with components of this type, and also affects 19023the semantics of unchecked conversion (unchecked conversions where 19024the @code{Value_Size} values differ generate a warning, and are potentially 19025target dependent). 19026 19027The default rules for the value of @code{Value_Size} are as follows: 19028 19029 19030@itemize * 19031 19032@item 19033The @code{Value_Size} for a base subtype is the minimum number of bits 19034required to store all values of the type (including the sign bit 19035only if negative values are possible). 19036 19037@item 19038If a subtype statically matches the first subtype of a given type, then it has 19039by default the same @code{Value_Size} as the first subtype. This is a 19040consequence of RM 13.1(14): “if two subtypes statically match, 19041then their subtype-specific aspects are the same”.) 19042 19043@item 19044All other subtypes have a @code{Value_Size} corresponding to the minimum 19045number of bits required to store all values of the subtype. For 19046dynamic bounds, it is assumed that the value can range down or up 19047to the corresponding bound of the ancestor 19048@end itemize 19049 19050The RM defined attribute @code{Size} corresponds to the 19051@code{Value_Size} attribute. 19052 19053The @code{Size} attribute may be defined for a first-named subtype. This sets 19054the @code{Value_Size} of 19055the first-named subtype to the given value, and the 19056@code{Object_Size} of this first-named subtype to the given value padded up 19057to an appropriate boundary. It is a consequence of the default rules 19058above that this @code{Object_Size} will apply to all further subtypes. On the 19059other hand, @code{Value_Size} is affected only for the first subtype, any 19060dynamic subtypes obtained from it directly, and any statically matching 19061subtypes. The @code{Value_Size} of any other static subtypes is not affected. 19062 19063@code{Value_Size} and 19064@code{Object_Size} may be explicitly set for any subtype using 19065an attribute definition clause. Note that the use of these attributes 19066can cause the RM 13.1(14) rule to be violated. If two access types 19067reference aliased objects whose subtypes have differing @code{Object_Size} 19068values as a result of explicit attribute definition clauses, then it 19069is illegal to convert from one access subtype to the other. For a more 19070complete description of this additional legality rule, see the 19071description of the @code{Object_Size} attribute. 19072 19073To get a feel for the difference, consider the following examples (note 19074that in each case the base is @code{Short_Short_Integer} with a size of 8): 19075 19076 19077@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 19078@headitem 19079 19080Type or subtype declaration 19081 19082@tab 19083 19084Object_Size 19085 19086@tab 19087 19088Value_Size 19089 19090@item 19091 19092@code{type x1 is range 0 .. 5;} 19093 19094@tab 19095 190968 19097 19098@tab 19099 191003 19101 19102@item 19103 19104@code{type x2 is range 0 .. 5;} 19105@code{for x2'size use 12;} 19106 19107@tab 19108 1910916 19110 19111@tab 19112 1911312 19114 19115@item 19116 19117@code{subtype x3 is x2 range 0 .. 3;} 19118 19119@tab 19120 1912116 19122 19123@tab 19124 191252 19126 19127@item 19128 19129@code{subtype x4 is x2'base range 0 .. 10;} 19130 19131@tab 19132 191338 19134 19135@tab 19136 191374 19138 19139@item 19140 19141@code{dynamic : x2'Base range -64 .. +63;} 19142 19143@tab 19144 19145@tab 19146 19147@item 19148 19149@code{subtype x5 is x2 range 0 .. dynamic;} 19150 19151@tab 19152 1915316 19154 19155@tab 19156 191573* 19158 19159@item 19160 19161@code{subtype x6 is x2'base range 0 .. dynamic;} 19162 19163@tab 19164 191658 19166 19167@tab 19168 191697* 19170 19171@end multitable 19172 19173 19174Note: the entries marked ‘*’ are not actually specified by the Ada 19175Reference Manual, which has nothing to say about size in the dynamic 19176case. What GNAT does is to allocate sufficient bits to accommodate any 19177possible dynamic values for the bounds at run-time. 19178 19179So far, so good, but GNAT has to obey the RM rules, so the question is 19180under what conditions must the RM @code{Size} be used. 19181The following is a list 19182of the occasions on which the RM @code{Size} must be used: 19183 19184 19185@itemize * 19186 19187@item 19188Component size for packed arrays or records 19189 19190@item 19191Value of the attribute @code{Size} for a type 19192 19193@item 19194Warning about sizes not matching for unchecked conversion 19195@end itemize 19196 19197For record types, the @code{Object_Size} is always a multiple of the 19198alignment of the type (this is true for all types). In some cases the 19199@code{Value_Size} can be smaller. Consider: 19200 19201@example 19202type R is record 19203 X : Integer; 19204 Y : Character; 19205end record; 19206@end example 19207 19208On a typical 32-bit architecture, the X component will occupy four bytes 19209and the Y component will occupy one byte, for a total of 5 bytes. As a 19210result @code{R'Value_Size} will be 40 (bits) since this is the minimum size 19211required to store a value of this type. For example, it is permissible 19212to have a component of type R in an array whose component size is 19213specified to be 40 bits. 19214 19215However, @code{R'Object_Size} will be 64 (bits). The difference is due to 19216the alignment requirement for objects of the record type. The X 19217component will require four-byte alignment because that is what type 19218Integer requires, whereas the Y component, a Character, will only 19219require 1-byte alignment. Since the alignment required for X is the 19220greatest of all the components’ alignments, that is the alignment 19221required for the enclosing record type, i.e., 4 bytes or 32 bits. As 19222indicated above, the actual object size must be rounded up so that it is 19223a multiple of the alignment value. Therefore, 40 bits rounded up to the 19224next multiple of 32 yields 64 bits. 19225 19226For all other types, the @code{Object_Size} 19227and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). 19228Only @code{Size} may be specified for such types. 19229 19230Note that @code{Value_Size} can be used to force biased representation 19231for a particular subtype. Consider this example: 19232 19233@example 19234type R is (A, B, C, D, E, F); 19235subtype RAB is R range A .. B; 19236subtype REF is R range E .. F; 19237@end example 19238 19239By default, @code{RAB} 19240has a size of 1 (sufficient to accommodate the representation 19241of @code{A} and @code{B}, 0 and 1), and @code{REF} 19242has a size of 3 (sufficient to accommodate the representation 19243of @code{E} and @code{F}, 4 and 5). But if we add the 19244following @code{Value_Size} attribute definition clause: 19245 19246@example 19247for REF'Value_Size use 1; 19248@end example 19249 19250then biased representation is forced for @code{REF}, 19251and 0 will represent @code{E} and 1 will represent @code{F}. 19252A warning is issued when a @code{Value_Size} attribute 19253definition clause forces biased representation. This 19254warning can be turned off using @code{-gnatw.B}. 19255 19256@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas 19257@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{286} 19258@section Component_Size Clauses 19259 19260 19261@geindex Component_Size Clause 19262 19263Normally, the value specified in a component size clause must be consistent 19264with the subtype of the array component with regard to size and alignment. 19265In other words, the value specified must be at least equal to the size 19266of this subtype, and must be a multiple of the alignment value. 19267 19268In addition, component size clauses are allowed which cause the array 19269to be packed, by specifying a smaller value. A first case is for 19270component size values in the range 1 through 63 on 32-bit targets, 19271and 1 through 127 on 64-bit targets. The value specified may not 19272be smaller than the Size of the subtype. GNAT will accurately 19273honor all packing requests in this range. For example, if we have: 19274 19275@example 19276type r is array (1 .. 8) of Natural; 19277for r'Component_Size use 31; 19278@end example 19279 19280then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 19281Of course access to the components of such an array is considerably 19282less efficient than if the natural component size of 32 is used. 19283A second case is when the subtype of the component is a record type 19284padded because of its default alignment. For example, if we have: 19285 19286@example 19287type r is record 19288 i : Integer; 19289 j : Integer; 19290 b : Boolean; 19291end record; 19292 19293type a is array (1 .. 8) of r; 19294for a'Component_Size use 72; 19295@end example 19296 19297then the resulting array has a length of 72 bytes, instead of 96 bytes 19298if the alignment of the record (4) was obeyed. 19299 19300Note that there is no point in giving both a component size clause 19301and a pragma Pack for the same array type. if such duplicate 19302clauses are given, the pragma Pack will be ignored. 19303 19304@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas 19305@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{288} 19306@section Bit_Order Clauses 19307 19308 19309@geindex Bit_Order Clause 19310 19311@geindex bit ordering 19312 19313@geindex ordering 19314@geindex of bits 19315 19316For record subtypes, GNAT permits the specification of the @code{Bit_Order} 19317attribute. The specification may either correspond to the default bit 19318order for the target, in which case the specification has no effect and 19319places no additional restrictions, or it may be for the non-standard 19320setting (that is the opposite of the default). 19321 19322In the case where the non-standard value is specified, the effect is 19323to renumber bits within each byte, but the ordering of bytes is not 19324affected. There are certain 19325restrictions placed on component clauses as follows: 19326 19327 19328@itemize * 19329 19330@item 19331Components fitting within a single storage unit. 19332 19333These are unrestricted, and the effect is merely to renumber bits. For 19334example if we are on a little-endian machine with @code{Low_Order_First} 19335being the default, then the following two declarations have exactly 19336the same effect: 19337 19338@example 19339type R1 is record 19340 A : Boolean; 19341 B : Integer range 1 .. 120; 19342end record; 19343 19344for R1 use record 19345 A at 0 range 0 .. 0; 19346 B at 0 range 1 .. 7; 19347end record; 19348 19349type R2 is record 19350 A : Boolean; 19351 B : Integer range 1 .. 120; 19352end record; 19353 19354for R2'Bit_Order use High_Order_First; 19355 19356for R2 use record 19357 A at 0 range 7 .. 7; 19358 B at 0 range 0 .. 6; 19359end record; 19360@end example 19361 19362The useful application here is to write the second declaration with the 19363@code{Bit_Order} attribute definition clause, and know that it will be treated 19364the same, regardless of whether the target is little-endian or big-endian. 19365 19366@item 19367Components occupying an integral number of bytes. 19368 19369These are components that exactly fit in two or more bytes. Such component 19370declarations are allowed, but have no effect, since it is important to realize 19371that the @code{Bit_Order} specification does not affect the ordering of bytes. 19372In particular, the following attempt at getting an endian-independent integer 19373does not work: 19374 19375@example 19376type R2 is record 19377 A : Integer; 19378end record; 19379 19380for R2'Bit_Order use High_Order_First; 19381 19382for R2 use record 19383 A at 0 range 0 .. 31; 19384end record; 19385@end example 19386 19387This declaration will result in a little-endian integer on a 19388little-endian machine, and a big-endian integer on a big-endian machine. 19389If byte flipping is required for interoperability between big- and 19390little-endian machines, this must be explicitly programmed. This capability 19391is not provided by @code{Bit_Order}. 19392 19393@item 19394Components that are positioned across byte boundaries. 19395 19396but do not occupy an integral number of bytes. Given that bytes are not 19397reordered, such fields would occupy a non-contiguous sequence of bits 19398in memory, requiring non-trivial code to reassemble. They are for this 19399reason not permitted, and any component clause specifying such a layout 19400will be flagged as illegal by GNAT. 19401@end itemize 19402 19403Since the misconception that Bit_Order automatically deals with all 19404endian-related incompatibilities is a common one, the specification of 19405a component field that is an integral number of bytes will always 19406generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} 19407if desired. The following section contains additional 19408details regarding the issue of byte ordering. 19409 19410@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas 19411@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} 19412@section Effect of Bit_Order on Byte Ordering 19413 19414 19415@geindex byte ordering 19416 19417@geindex ordering 19418@geindex of bytes 19419 19420In this section we will review the effect of the @code{Bit_Order} attribute 19421definition clause on byte ordering. Briefly, it has no effect at all, but 19422a detailed example will be helpful. Before giving this 19423example, let us review the precise 19424definition of the effect of defining @code{Bit_Order}. The effect of a 19425non-standard bit order is described in section 13.5.3 of the Ada 19426Reference Manual: 19427 19428@quotation 19429 19430“2 A bit ordering is a method of interpreting the meaning of 19431the storage place attributes.” 19432@end quotation 19433 19434To understand the precise definition of storage place attributes in 19435this context, we visit section 13.5.1 of the manual: 19436 19437@quotation 19438 19439“13 A record_representation_clause (without the mod_clause) 19440specifies the layout. The storage place attributes (see 13.5.2) 19441are taken from the values of the position, first_bit, and last_bit 19442expressions after normalizing those values so that first_bit is 19443less than Storage_Unit.” 19444@end quotation 19445 19446The critical point here is that storage places are taken from 19447the values after normalization, not before. So the @code{Bit_Order} 19448interpretation applies to normalized values. The interpretation 19449is described in the later part of the 13.5.3 paragraph: 19450 19451@quotation 19452 19453“2 A bit ordering is a method of interpreting the meaning of 19454the storage place attributes. High_Order_First (known in the 19455vernacular as ‘big endian’) means that the first bit of a 19456storage element (bit 0) is the most significant bit (interpreting 19457the sequence of bits that represent a component as an unsigned 19458integer value). Low_Order_First (known in the vernacular as 19459‘little endian’) means the opposite: the first bit is the 19460least significant.” 19461@end quotation 19462 19463Note that the numbering is with respect to the bits of a storage 19464unit. In other words, the specification affects only the numbering 19465of bits within a single storage unit. 19466 19467We can make the effect clearer by giving an example. 19468 19469Suppose that we have an external device which presents two bytes, the first 19470byte presented, which is the first (low addressed byte) of the two byte 19471record is called Master, and the second byte is called Slave. 19472 19473The left most (most significant bit is called Control for each byte, and 19474the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost 19475(least significant) bit. 19476 19477On a big-endian machine, we can write the following representation clause 19478 19479@example 19480type Data is record 19481 Master_Control : Bit; 19482 Master_V1 : Bit; 19483 Master_V2 : Bit; 19484 Master_V3 : Bit; 19485 Master_V4 : Bit; 19486 Master_V5 : Bit; 19487 Master_V6 : Bit; 19488 Master_V7 : Bit; 19489 Slave_Control : Bit; 19490 Slave_V1 : Bit; 19491 Slave_V2 : Bit; 19492 Slave_V3 : Bit; 19493 Slave_V4 : Bit; 19494 Slave_V5 : Bit; 19495 Slave_V6 : Bit; 19496 Slave_V7 : Bit; 19497end record; 19498 19499for Data use record 19500 Master_Control at 0 range 0 .. 0; 19501 Master_V1 at 0 range 1 .. 1; 19502 Master_V2 at 0 range 2 .. 2; 19503 Master_V3 at 0 range 3 .. 3; 19504 Master_V4 at 0 range 4 .. 4; 19505 Master_V5 at 0 range 5 .. 5; 19506 Master_V6 at 0 range 6 .. 6; 19507 Master_V7 at 0 range 7 .. 7; 19508 Slave_Control at 1 range 0 .. 0; 19509 Slave_V1 at 1 range 1 .. 1; 19510 Slave_V2 at 1 range 2 .. 2; 19511 Slave_V3 at 1 range 3 .. 3; 19512 Slave_V4 at 1 range 4 .. 4; 19513 Slave_V5 at 1 range 5 .. 5; 19514 Slave_V6 at 1 range 6 .. 6; 19515 Slave_V7 at 1 range 7 .. 7; 19516end record; 19517@end example 19518 19519Now if we move this to a little endian machine, then the bit ordering within 19520the byte is backwards, so we have to rewrite the record rep clause as: 19521 19522@example 19523for Data use record 19524 Master_Control at 0 range 7 .. 7; 19525 Master_V1 at 0 range 6 .. 6; 19526 Master_V2 at 0 range 5 .. 5; 19527 Master_V3 at 0 range 4 .. 4; 19528 Master_V4 at 0 range 3 .. 3; 19529 Master_V5 at 0 range 2 .. 2; 19530 Master_V6 at 0 range 1 .. 1; 19531 Master_V7 at 0 range 0 .. 0; 19532 Slave_Control at 1 range 7 .. 7; 19533 Slave_V1 at 1 range 6 .. 6; 19534 Slave_V2 at 1 range 5 .. 5; 19535 Slave_V3 at 1 range 4 .. 4; 19536 Slave_V4 at 1 range 3 .. 3; 19537 Slave_V5 at 1 range 2 .. 2; 19538 Slave_V6 at 1 range 1 .. 1; 19539 Slave_V7 at 1 range 0 .. 0; 19540end record; 19541@end example 19542 19543It is a nuisance to have to rewrite the clause, especially if 19544the code has to be maintained on both machines. However, 19545this is a case that we can handle with the 19546@code{Bit_Order} attribute if it is implemented. 19547Note that the implementation is not required on byte addressed 19548machines, but it is indeed implemented in GNAT. 19549This means that we can simply use the 19550first record clause, together with the declaration 19551 19552@example 19553for Data'Bit_Order use High_Order_First; 19554@end example 19555 19556and the effect is what is desired, namely the layout is exactly the same, 19557independent of whether the code is compiled on a big-endian or little-endian 19558machine. 19559 19560The important point to understand is that byte ordering is not affected. 19561A @code{Bit_Order} attribute definition never affects which byte a field 19562ends up in, only where it ends up in that byte. 19563To make this clear, let us rewrite the record rep clause of the previous 19564example as: 19565 19566@example 19567for Data'Bit_Order use High_Order_First; 19568for Data use record 19569 Master_Control at 0 range 0 .. 0; 19570 Master_V1 at 0 range 1 .. 1; 19571 Master_V2 at 0 range 2 .. 2; 19572 Master_V3 at 0 range 3 .. 3; 19573 Master_V4 at 0 range 4 .. 4; 19574 Master_V5 at 0 range 5 .. 5; 19575 Master_V6 at 0 range 6 .. 6; 19576 Master_V7 at 0 range 7 .. 7; 19577 Slave_Control at 0 range 8 .. 8; 19578 Slave_V1 at 0 range 9 .. 9; 19579 Slave_V2 at 0 range 10 .. 10; 19580 Slave_V3 at 0 range 11 .. 11; 19581 Slave_V4 at 0 range 12 .. 12; 19582 Slave_V5 at 0 range 13 .. 13; 19583 Slave_V6 at 0 range 14 .. 14; 19584 Slave_V7 at 0 range 15 .. 15; 19585end record; 19586@end example 19587 19588This is exactly equivalent to saying (a repeat of the first example): 19589 19590@example 19591for Data'Bit_Order use High_Order_First; 19592for Data use record 19593 Master_Control at 0 range 0 .. 0; 19594 Master_V1 at 0 range 1 .. 1; 19595 Master_V2 at 0 range 2 .. 2; 19596 Master_V3 at 0 range 3 .. 3; 19597 Master_V4 at 0 range 4 .. 4; 19598 Master_V5 at 0 range 5 .. 5; 19599 Master_V6 at 0 range 6 .. 6; 19600 Master_V7 at 0 range 7 .. 7; 19601 Slave_Control at 1 range 0 .. 0; 19602 Slave_V1 at 1 range 1 .. 1; 19603 Slave_V2 at 1 range 2 .. 2; 19604 Slave_V3 at 1 range 3 .. 3; 19605 Slave_V4 at 1 range 4 .. 4; 19606 Slave_V5 at 1 range 5 .. 5; 19607 Slave_V6 at 1 range 6 .. 6; 19608 Slave_V7 at 1 range 7 .. 7; 19609end record; 19610@end example 19611 19612Why are they equivalent? Well take a specific field, the @code{Slave_V2} 19613field. The storage place attributes are obtained by normalizing the 19614values given so that the @code{First_Bit} value is less than 8. After 19615normalizing the values (0,10,10) we get (1,2,2) which is exactly what 19616we specified in the other case. 19617 19618Now one might expect that the @code{Bit_Order} attribute might affect 19619bit numbering within the entire record component (two bytes in this 19620case, thus affecting which byte fields end up in), but that is not 19621the way this feature is defined, it only affects numbering of bits, 19622not which byte they end up in. 19623 19624Consequently it never makes sense to specify a starting bit number 19625greater than 7 (for a byte addressable field) if an attribute 19626definition for @code{Bit_Order} has been given, and indeed it 19627may be actively confusing to specify such a value, so the compiler 19628generates a warning for such usage. 19629 19630If you do need to control byte ordering then appropriate conditional 19631values must be used. If in our example, the slave byte came first on 19632some machines we might write: 19633 19634@example 19635Master_Byte_First constant Boolean := ...; 19636 19637Master_Byte : constant Natural := 19638 1 - Boolean'Pos (Master_Byte_First); 19639Slave_Byte : constant Natural := 19640 Boolean'Pos (Master_Byte_First); 19641 19642for Data'Bit_Order use High_Order_First; 19643for Data use record 19644 Master_Control at Master_Byte range 0 .. 0; 19645 Master_V1 at Master_Byte range 1 .. 1; 19646 Master_V2 at Master_Byte range 2 .. 2; 19647 Master_V3 at Master_Byte range 3 .. 3; 19648 Master_V4 at Master_Byte range 4 .. 4; 19649 Master_V5 at Master_Byte range 5 .. 5; 19650 Master_V6 at Master_Byte range 6 .. 6; 19651 Master_V7 at Master_Byte range 7 .. 7; 19652 Slave_Control at Slave_Byte range 0 .. 0; 19653 Slave_V1 at Slave_Byte range 1 .. 1; 19654 Slave_V2 at Slave_Byte range 2 .. 2; 19655 Slave_V3 at Slave_Byte range 3 .. 3; 19656 Slave_V4 at Slave_Byte range 4 .. 4; 19657 Slave_V5 at Slave_Byte range 5 .. 5; 19658 Slave_V6 at Slave_Byte range 6 .. 6; 19659 Slave_V7 at Slave_Byte range 7 .. 7; 19660end record; 19661@end example 19662 19663Now to switch between machines, all that is necessary is 19664to set the boolean constant @code{Master_Byte_First} in 19665an appropriate manner. 19666 19667@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas 19668@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{28c} 19669@section Pragma Pack for Arrays 19670 19671 19672@geindex Pragma Pack (for arrays) 19673 19674Pragma @code{Pack} applied to an array has an effect that depends upon whether the 19675component type is @emph{packable}. For a component type to be @emph{packable}, it must 19676be one of the following cases: 19677 19678 19679@itemize * 19680 19681@item 19682Any elementary type. 19683 19684@item 19685Any small packed array type with a static size. 19686 19687@item 19688Any small simple record type with a static size. 19689@end itemize 19690 19691For all these cases, if the component subtype size is in the range 196921 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets, 19693then the effect of the pragma @code{Pack} is exactly as though a 19694component size were specified giving the component subtype size. 19695 19696All other types are non-packable, they occupy an integral number of storage 19697units and the only effect of pragma Pack is to remove alignment gaps. 19698 19699For example if we have: 19700 19701@example 19702type r is range 0 .. 17; 19703 19704type ar is array (1 .. 8) of r; 19705pragma Pack (ar); 19706@end example 19707 19708Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, 19709and the size of the array @code{ar} will be exactly 40 bits). 19710 19711Note that in some cases this rather fierce approach to packing can produce 19712unexpected effects. For example, in Ada 95 and Ada 2005, 19713subtype @code{Natural} typically has a size of 31, meaning that if you 19714pack an array of @code{Natural}, you get 31-bit 19715close packing, which saves a few bits, but results in far less efficient 19716access. Since many other Ada compilers will ignore such a packing request, 19717GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 19718might not be what is intended. You can easily remove this warning by 19719using an explicit @code{Component_Size} setting instead, which never generates 19720a warning, since the intention of the programmer is clear in this case. 19721 19722GNAT treats packed arrays in one of two ways. If the size of the array is 19723known at compile time and is at most 64 bits on 32-bit targets, and at most 19724128 bits on 64-bit targets, then internally the array is represented as a 19725single modular type, of exactly the appropriate number of bits. If the 19726length is greater than 64 bits on 32-bit targets, and greater than 128 19727bits on 64-bit targets, or is not known at compile time, then the packed 19728array is represented as an array of bytes, and its length is always a 19729multiple of 8 bits. 19730 19731Note that to represent a packed array as a modular type, the alignment must 19732be suitable for the modular type involved. For example, on typical machines 19733a 32-bit packed array will be represented by a 32-bit modular integer with 19734an alignment of four bytes. If you explicitly override the default alignment 19735with an alignment clause that is too small, the modular representation 19736cannot be used. For example, consider the following set of declarations: 19737 19738@example 19739type R is range 1 .. 3; 19740type S is array (1 .. 31) of R; 19741for S'Component_Size use 2; 19742for S'Size use 62; 19743for S'Alignment use 1; 19744@end example 19745 19746If the alignment clause were not present, then a 62-bit modular 19747representation would be chosen (typically with an alignment of 4 or 8 19748bytes depending on the target). But the default alignment is overridden 19749with the explicit alignment clause. This means that the modular 19750representation cannot be used, and instead the array of bytes 19751representation must be used, meaning that the length must be a multiple 19752of 8. Thus the above set of declarations will result in a diagnostic 19753rejecting the size clause and noting that the minimum size allowed is 64. 19754 19755@geindex Pragma Pack (for type Natural) 19756 19757@geindex Pragma Pack warning 19758 19759One special case that is worth noting occurs when the base type of the 19760component size is 8/16/32 and the subtype is one bit less. Notably this 19761occurs with subtype @code{Natural}. Consider: 19762 19763@example 19764type Arr is array (1 .. 32) of Natural; 19765pragma Pack (Arr); 19766@end example 19767 19768In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 19769since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 19770Ada 83 compilers did not attempt 31 bit packing. 19771 19772In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, 19773GNAT really does pack 31-bit subtype to 31 bits. This may result in a 19774substantial unintended performance penalty when porting legacy Ada 83 code. 19775To help prevent this, GNAT generates a warning in such cases. If you really 19776want 31 bit packing in a case like this, you can set the component size 19777explicitly: 19778 19779@example 19780type Arr is array (1 .. 32) of Natural; 19781for Arr'Component_Size use 31; 19782@end example 19783 19784Here 31-bit packing is achieved as required, and no warning is generated, 19785since in this case the programmer intention is clear. 19786 19787@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas 19788@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28e} 19789@section Pragma Pack for Records 19790 19791 19792@geindex Pragma Pack (for records) 19793 19794Pragma @code{Pack} applied to a record will pack the components to reduce 19795wasted space from alignment gaps and by reducing the amount of space 19796taken by components. We distinguish between @emph{packable} components and 19797@emph{non-packable} components. 19798Components of the following types are considered packable: 19799 19800 19801@itemize * 19802 19803@item 19804Components of an elementary type are packable unless they are aliased, 19805independent or atomic. 19806 19807@item 19808Small packed arrays, where the size is statically known, are represented 19809internally as modular integers, and so they are also packable. 19810 19811@item 19812Small simple records, where the size is statically known, are also packable. 19813@end itemize 19814 19815For all these cases, if the @code{'Size} value is in the range 1 through 64 on 1981632-bit targets, and 1 through 128 on 64-bit targets, the components occupy 19817the exact number of bits corresponding to this value and are packed with no 19818padding bits, i.e. they can start on an arbitrary bit boundary. 19819 19820All other types are non-packable, they occupy an integral number of storage 19821units and the only effect of pragma @code{Pack} is to remove alignment gaps. 19822 19823For example, consider the record 19824 19825@example 19826type Rb1 is array (1 .. 13) of Boolean; 19827pragma Pack (Rb1); 19828 19829type Rb2 is array (1 .. 65) of Boolean; 19830pragma Pack (Rb2); 19831 19832type AF is new Float with Atomic; 19833 19834type X2 is record 19835 L1 : Boolean; 19836 L2 : Duration; 19837 L3 : AF; 19838 L4 : Boolean; 19839 L5 : Rb1; 19840 L6 : Rb2; 19841end record; 19842pragma Pack (X2); 19843@end example 19844 19845The representation for the record @code{X2} is as follows on 32-bit targets: 19846 19847@example 19848for X2'Size use 224; 19849for X2 use record 19850 L1 at 0 range 0 .. 0; 19851 L2 at 0 range 1 .. 64; 19852 L3 at 12 range 0 .. 31; 19853 L4 at 16 range 0 .. 0; 19854 L5 at 16 range 1 .. 13; 19855 L6 at 18 range 0 .. 71; 19856end record; 19857@end example 19858 19859Studying this example, we see that the packable fields @code{L1} 19860and @code{L2} are of length equal to their sizes, and placed at 19861specific bit boundaries (and not byte boundaries) to eliminate 19862padding. But @code{L3} is of a non-packable float type (because 19863it is aliased), so it is on the next appropriate alignment boundary. 19864 19865The next two fields are fully packable, so @code{L4} and @code{L5} are 19866minimally packed with no gaps. However, type @code{Rb2} is a packed 19867array that is longer than 64 bits, so it is itself non-packable on 1986832-bit targets. Thus the @code{L6} field is aligned to the next byte 19869boundary, and takes an integral number of bytes, i.e., 72 bits. 19870 19871@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas 19872@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{290} 19873@section Record Representation Clauses 19874 19875 19876@geindex Record Representation Clause 19877 19878Record representation clauses may be given for all record types, including 19879types obtained by record extension. Component clauses are allowed for any 19880static component. The restrictions on component clauses depend on the type 19881of the component. 19882 19883@geindex Component Clause 19884 19885For all components of an elementary type, the only restriction on component 19886clauses is that the size must be at least the @code{'Size} value of the type 19887(actually the Value_Size). There are no restrictions due to alignment, 19888and such components may freely cross storage boundaries. 19889 19890Packed arrays with a size up to and including 64 bits on 32-bit targets, 19891and up to and including 128 bits on 64-bit targets, are represented 19892internally using a modular type with the appropriate number of bits, and 19893thus the same lack of restriction applies. For example, if you declare: 19894 19895@example 19896type R is array (1 .. 49) of Boolean; 19897pragma Pack (R); 19898for R'Size use 49; 19899@end example 19900 19901then a component clause for a component of type @code{R} may start on any 19902specified bit boundary, and may specify a value of 49 bits or greater. 19903 19904For packed bit arrays that are longer than 64 bits on 32-bit targets, 19905and longer than 128 bits on 64-bit targets, there are two cases. If the 19906component size is a power of 2 (1,2,4,8,16,32,64 bits), including the 19907important case of single bits or boolean values, then there are no 19908limitations on placement of such components, and they may start and 19909end at arbitrary bit boundaries. 19910 19911If the component size is not a power of 2 (e.g., 3 or 5), then an array 19912of this type must always be placed on on a storage unit (byte) boundary 19913and occupy an integral number of storage units (bytes). Any component 19914clause that does not meet this requirement will be rejected. 19915 19916Any aliased component, or component of an aliased type, must have its 19917normal alignment and size. A component clause that does not meet this 19918requirement will be rejected. 19919 19920The tag field of a tagged type always occupies an address sized field at 19921the start of the record. No component clause may attempt to overlay this 19922tag. When a tagged type appears as a component, the tag field must have 19923proper alignment 19924 19925In the case of a record extension @code{T1}, of a type @code{T}, no component 19926clause applied to the type @code{T1} can specify a storage location that 19927would overlap the first @code{T'Object_Size} bits of the record. 19928 19929For all other component types, including non-bit-packed arrays, 19930the component can be placed at an arbitrary bit boundary, 19931so for example, the following is permitted: 19932 19933@example 19934type R is array (1 .. 10) of Boolean; 19935for R'Size use 80; 19936 19937type Q is record 19938 G, H : Boolean; 19939 L, M : R; 19940end record; 19941 19942for Q use record 19943 G at 0 range 0 .. 0; 19944 H at 0 range 1 .. 1; 19945 L at 0 range 2 .. 81; 19946 R at 0 range 82 .. 161; 19947end record; 19948@end example 19949 19950@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas 19951@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{292} 19952@section Handling of Records with Holes 19953 19954 19955@geindex Handling of Records with Holes 19956 19957As a result of alignment considerations, records may contain “holes” 19958or gaps which do not correspond to the data bits of any of the components. 19959Record representation clauses can also result in holes in records. 19960 19961GNAT does not attempt to clear these holes, so in record objects, 19962they should be considered to hold undefined rubbish. The generated 19963equality routine just tests components so does not access these 19964undefined bits, and assignment and copy operations may or may not 19965preserve the contents of these holes (for assignments, the holes 19966in the target will in practice contain either the bits that are 19967present in the holes in the source, or the bits that were present 19968in the target before the assignment). 19969 19970If it is necessary to ensure that holes in records have all zero 19971bits, then record objects for which this initialization is desired 19972should be explicitly set to all zero values using Unchecked_Conversion 19973or address overlays. For example 19974 19975@example 19976type HRec is record 19977 C : Character; 19978 I : Integer; 19979end record; 19980@end example 19981 19982On typical machines, integers need to be aligned on a four-byte 19983boundary, resulting in three bytes of undefined rubbish following 19984the 8-bit field for C. To ensure that the hole in a variable of 19985type HRec is set to all zero bits, 19986you could for example do: 19987 19988@example 19989type Base is record 19990 Dummy1, Dummy2 : Integer := 0; 19991end record; 19992 19993BaseVar : Base; 19994RealVar : Hrec; 19995for RealVar'Address use BaseVar'Address; 19996@end example 19997 19998Now the 8-bytes of the value of RealVar start out containing all zero 19999bits. A safer approach is to just define dummy fields, avoiding the 20000holes, as in: 20001 20002@example 20003type HRec is record 20004 C : Character; 20005 Dummy1 : Short_Short_Integer := 0; 20006 Dummy2 : Short_Short_Integer := 0; 20007 Dummy3 : Short_Short_Integer := 0; 20008 I : Integer; 20009end record; 20010@end example 20011 20012And to make absolutely sure that the intent of this is followed, you 20013can use representation clauses: 20014 20015@example 20016for Hrec use record 20017 C at 0 range 0 .. 7; 20018 Dummy1 at 1 range 0 .. 7; 20019 Dummy2 at 2 range 0 .. 7; 20020 Dummy3 at 3 range 0 .. 7; 20021 I at 4 range 0 .. 31; 20022end record; 20023for Hrec'Size use 64; 20024@end example 20025 20026@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas 20027@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{294} 20028@section Enumeration Clauses 20029 20030 20031The only restriction on enumeration clauses is that the range of values 20032must be representable. For the signed case, if one or more of the 20033representation values are negative, all values must be in the range: 20034 20035@example 20036System.Min_Int .. System.Max_Int 20037@end example 20038 20039For the unsigned case, where all values are nonnegative, the values must 20040be in the range: 20041 20042@example 200430 .. System.Max_Binary_Modulus; 20044@end example 20045 20046A @emph{confirming} representation clause is one in which the values range 20047from 0 in sequence, i.e., a clause that confirms the default representation 20048for an enumeration type. 20049Such a confirming representation 20050is permitted by these rules, and is specially recognized by the compiler so 20051that no extra overhead results from the use of such a clause. 20052 20053If an array has an index type which is an enumeration type to which an 20054enumeration clause has been applied, then the array is stored in a compact 20055manner. Consider the declarations: 20056 20057@example 20058type r is (A, B, C); 20059for r use (A => 1, B => 5, C => 10); 20060type t is array (r) of Character; 20061@end example 20062 20063The array type t corresponds to a vector with exactly three elements and 20064has a default size equal to @code{3*Character'Size}. This ensures efficient 20065use of space, but means that accesses to elements of the array will incur 20066the overhead of converting representation values to the corresponding 20067positional values, (i.e., the value delivered by the @code{Pos} attribute). 20068 20069@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas 20070@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{296} 20071@section Address Clauses 20072 20073 20074@geindex Address Clause 20075 20076The reference manual allows a general restriction on representation clauses, 20077as found in RM 13.1(22): 20078 20079@quotation 20080 20081“An implementation need not support representation 20082items containing nonstatic expressions, except that 20083an implementation should support a representation item 20084for a given entity if each nonstatic expression in the 20085representation item is a name that statically denotes 20086a constant declared before the entity.” 20087@end quotation 20088 20089In practice this is applicable only to address clauses, since this is the 20090only case in which a nonstatic expression is permitted by the syntax. As 20091the AARM notes in sections 13.1 (22.a-22.h): 20092 20093@quotation 20094 2009522.a Reason: This is to avoid the following sort of thing: 20096 2009722.b X : Integer := F(…); 20098Y : Address := G(…); 20099for X’Address use Y; 20100 2010122.c In the above, we have to evaluate the 20102initialization expression for X before we 20103know where to put the result. This seems 20104like an unreasonable implementation burden. 20105 2010622.d The above code should instead be written 20107like this: 20108 2010922.e Y : constant Address := G(…); 20110X : Integer := F(…); 20111for X’Address use Y; 20112 2011322.f This allows the expression ‘Y’ to be safely 20114evaluated before X is created. 20115 2011622.g The constant could be a formal parameter of mode in. 20117 2011822.h An implementation can support other nonstatic 20119expressions if it wants to. Expressions of type 20120Address are hardly ever static, but their value 20121might be known at compile time anyway in many 20122cases. 20123@end quotation 20124 20125GNAT does indeed permit many additional cases of nonstatic expressions. In 20126particular, if the type involved is elementary there are no restrictions 20127(since in this case, holding a temporary copy of the initialization value, 20128if one is present, is inexpensive). In addition, if there is no implicit or 20129explicit initialization, then there are no restrictions. GNAT will reject 20130only the case where all three of these conditions hold: 20131 20132 20133@itemize * 20134 20135@item 20136The type of the item is non-elementary (e.g., a record or array). 20137 20138@item 20139There is explicit or implicit initialization required for the object. 20140Note that access values are always implicitly initialized. 20141 20142@item 20143The address value is nonstatic. Here GNAT is more permissive than the 20144RM, and allows the address value to be the address of a previously declared 20145stand-alone variable, as long as it does not itself have an address clause. 20146 20147@example 20148Anchor : Some_Initialized_Type; 20149Overlay : Some_Initialized_Type; 20150for Overlay'Address use Anchor'Address; 20151@end example 20152 20153However, the prefix of the address clause cannot be an array component, or 20154a component of a discriminated record. 20155@end itemize 20156 20157As noted above in section 22.h, address values are typically nonstatic. In 20158particular the To_Address function, even if applied to a literal value, is 20159a nonstatic function call. To avoid this minor annoyance, GNAT provides 20160the implementation defined attribute ‘To_Address. The following two 20161expressions have identical values: 20162 20163@geindex Attribute 20164 20165@geindex To_Address 20166 20167@example 20168To_Address (16#1234_0000#) 20169System'To_Address (16#1234_0000#); 20170@end example 20171 20172except that the second form is considered to be a static expression, and 20173thus when used as an address clause value is always permitted. 20174 20175Additionally, GNAT treats as static an address clause that is an 20176unchecked_conversion of a static integer value. This simplifies the porting 20177of legacy code, and provides a portable equivalent to the GNAT attribute 20178@code{To_Address}. 20179 20180Another issue with address clauses is the interaction with alignment 20181requirements. When an address clause is given for an object, the address 20182value must be consistent with the alignment of the object (which is usually 20183the same as the alignment of the type of the object). If an address clause 20184is given that specifies an inappropriately aligned address value, then the 20185program execution is erroneous. 20186 20187Since this source of erroneous behavior can have unfortunate effects on 20188machines with strict alignment requirements, GNAT 20189checks (at compile time if possible, generating a warning, or at execution 20190time with a run-time check) that the alignment is appropriate. If the 20191run-time check fails, then @code{Program_Error} is raised. This run-time 20192check is suppressed if range checks are suppressed, or if the special GNAT 20193check Alignment_Check is suppressed, or if 20194@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also 20195suppressed by default on non-strict alignment machines (such as the x86). 20196 20197Finally, GNAT does not permit overlaying of objects of class-wide types. In 20198most cases, the compiler can detect an attempt at such overlays and will 20199generate a warning at compile time and a Program_Error exception at run time. 20200 20201@geindex Export 20202 20203An address clause cannot be given for an exported object. More 20204understandably the real restriction is that objects with an address 20205clause cannot be exported. This is because such variables are not 20206defined by the Ada program, so there is no external object to export. 20207 20208@geindex Import 20209 20210It is permissible to give an address clause and a pragma Import for the 20211same object. In this case, the variable is not really defined by the 20212Ada program, so there is no external symbol to be linked. The link name 20213and the external name are ignored in this case. The reason that we allow this 20214combination is that it provides a useful idiom to avoid unwanted 20215initializations on objects with address clauses. 20216 20217When an address clause is given for an object that has implicit or 20218explicit initialization, then by default initialization takes place. This 20219means that the effect of the object declaration is to overwrite the 20220memory at the specified address. This is almost always not what the 20221programmer wants, so GNAT will output a warning: 20222 20223@example 20224with System; 20225package G is 20226 type R is record 20227 M : Integer := 0; 20228 end record; 20229 20230 Ext : R; 20231 for Ext'Address use System'To_Address (16#1234_1234#); 20232 | 20233>>> warning: implicit initialization of "Ext" may 20234 modify overlaid storage 20235>>> warning: use pragma Import for "Ext" to suppress 20236 initialization (RM B(24)) 20237 20238end G; 20239@end example 20240 20241As indicated by the warning message, the solution is to use a (dummy) pragma 20242Import to suppress this initialization. The pragma tell the compiler that the 20243object is declared and initialized elsewhere. The following package compiles 20244without warnings (and the initialization is suppressed): 20245 20246@example 20247with System; 20248package G is 20249 type R is record 20250 M : Integer := 0; 20251 end record; 20252 20253 Ext : R; 20254 for Ext'Address use System'To_Address (16#1234_1234#); 20255 pragma Import (Ada, Ext); 20256end G; 20257@end example 20258 20259A final issue with address clauses involves their use for overlaying 20260variables, as in the following example: 20261 20262@geindex Overlaying of objects 20263 20264@example 20265A : Integer; 20266B : Integer; 20267for B'Address use A'Address; 20268@end example 20269 20270or alternatively, using the form recommended by the RM: 20271 20272@example 20273A : Integer; 20274Addr : constant Address := A'Address; 20275B : Integer; 20276for B'Address use Addr; 20277@end example 20278 20279In both of these cases, @code{A} and @code{B} become aliased to one another 20280via the address clause. This use of address clauses to overlay 20281variables, achieving an effect similar to unchecked conversion 20282was erroneous in Ada 83, but in Ada 95 and Ada 2005 20283the effect is implementation defined. Furthermore, the 20284Ada RM specifically recommends that in a situation 20285like this, @code{B} should be subject to the following 20286implementation advice (RM 13.3(19)): 20287 20288@quotation 20289 20290“19 If the Address of an object is specified, or it is imported 20291or exported, then the implementation should not perform 20292optimizations based on assumptions of no aliases.” 20293@end quotation 20294 20295GNAT follows this recommendation, and goes further by also applying 20296this recommendation to the overlaid variable (@code{A} in the above example) 20297in this case. This means that the overlay works “as expected”, in that 20298a modification to one of the variables will affect the value of the other. 20299 20300More generally, GNAT interprets this recommendation conservatively for 20301address clauses: in the cases other than overlays, it considers that the 20302object is effectively subject to pragma @code{Volatile} and implements the 20303associated semantics. 20304 20305Note that when address clause overlays are used in this way, there is an 20306issue of unintentional initialization, as shown by this example: 20307 20308@example 20309package Overwrite_Record is 20310 type R is record 20311 A : Character := 'C'; 20312 B : Character := 'A'; 20313 end record; 20314 X : Short_Integer := 3; 20315 Y : R; 20316 for Y'Address use X'Address; 20317 | 20318>>> warning: default initialization of "Y" may 20319 modify "X", use pragma Import for "Y" to 20320 suppress initialization (RM B.1(24)) 20321 20322end Overwrite_Record; 20323@end example 20324 20325Here the default initialization of @code{Y} will clobber the value 20326of @code{X}, which justifies the warning. The warning notes that 20327this effect can be eliminated by adding a @code{pragma Import} 20328which suppresses the initialization: 20329 20330@example 20331package Overwrite_Record is 20332 type R is record 20333 A : Character := 'C'; 20334 B : Character := 'A'; 20335 end record; 20336 X : Short_Integer := 3; 20337 Y : R; 20338 for Y'Address use X'Address; 20339 pragma Import (Ada, Y); 20340end Overwrite_Record; 20341@end example 20342 20343Note that the use of @code{pragma Initialize_Scalars} may cause variables to 20344be initialized when they would not otherwise have been in the absence 20345of the use of this pragma. This may cause an overlay to have this 20346unintended clobbering effect. The compiler avoids this for scalar 20347types, but not for composite objects (where in general the effect 20348of @code{Initialize_Scalars} is part of the initialization routine 20349for the composite object): 20350 20351@example 20352pragma Initialize_Scalars; 20353with Ada.Text_IO; use Ada.Text_IO; 20354procedure Overwrite_Array is 20355 type Arr is array (1 .. 5) of Integer; 20356 X : Arr := (others => 1); 20357 A : Arr; 20358 for A'Address use X'Address; 20359 | 20360>>> warning: default initialization of "A" may 20361 modify "X", use pragma Import for "A" to 20362 suppress initialization (RM B.1(24)) 20363 20364begin 20365 if X /= Arr'(others => 1) then 20366 Put_Line ("X was clobbered"); 20367 else 20368 Put_Line ("X was not clobbered"); 20369 end if; 20370end Overwrite_Array; 20371@end example 20372 20373The above program generates the warning as shown, and at execution 20374time, prints @code{X was clobbered}. If the @code{pragma Import} is 20375added as suggested: 20376 20377@example 20378pragma Initialize_Scalars; 20379with Ada.Text_IO; use Ada.Text_IO; 20380procedure Overwrite_Array is 20381 type Arr is array (1 .. 5) of Integer; 20382 X : Arr := (others => 1); 20383 A : Arr; 20384 for A'Address use X'Address; 20385 pragma Import (Ada, A); 20386begin 20387 if X /= Arr'(others => 1) then 20388 Put_Line ("X was clobbered"); 20389 else 20390 Put_Line ("X was not clobbered"); 20391 end if; 20392end Overwrite_Array; 20393@end example 20394 20395then the program compiles without the warning and when run will generate 20396the output @code{X was not clobbered}. 20397 20398@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas 20399@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} 20400@section Use of Address Clauses for Memory-Mapped I/O 20401 20402 20403@geindex Memory-mapped I/O 20404 20405A common pattern is to use an address clause to map an atomic variable to 20406a location in memory that corresponds to a memory-mapped I/O operation or 20407operations, for example: 20408 20409@example 20410type Mem_Word is record 20411 A,B,C,D : Byte; 20412end record; 20413pragma Atomic (Mem_Word); 20414for Mem_Word_Size use 32; 20415 20416Mem : Mem_Word; 20417for Mem'Address use some-address; 20418... 20419Temp := Mem; 20420Temp.A := 32; 20421Mem := Temp; 20422@end example 20423 20424For a full access (reference or modification) of the variable (Mem) in this 20425case, as in the above examples, GNAT guarantees that the entire atomic word 20426will be accessed, in accordance with the RM C.6(15) clause. 20427 20428A problem arises with a component access such as: 20429 20430@example 20431Mem.A := 32; 20432@end example 20433 20434Note that the component A is not declared as atomic. This means that it is 20435not clear what this assignment means. It could correspond to full word read 20436and write as given in the first example, or on architectures that supported 20437such an operation it might be a single byte store instruction. The RM does 20438not have anything to say in this situation, and GNAT does not make any 20439guarantee. The code generated may vary from target to target. GNAT will issue 20440a warning in such a case: 20441 20442@example 20443Mem.A := 32; 20444| 20445>>> warning: access to non-atomic component of atomic array, 20446 may cause unexpected accesses to atomic object 20447@end example 20448 20449It is best to be explicit in this situation, by either declaring the 20450components to be atomic if you want the byte store, or explicitly writing 20451the full word access sequence if that is what the hardware requires. 20452Alternatively, if the full word access sequence is required, GNAT also 20453provides the pragma @code{Volatile_Full_Access} which can be used in lieu of 20454pragma @code{Atomic} and will give the additional guarantee. 20455 20456@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas 20457@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{29a} 20458@section Effect of Convention on Representation 20459 20460 20461@geindex Convention 20462@geindex effect on representation 20463 20464Normally the specification of a foreign language convention for a type or 20465an object has no effect on the chosen representation. In particular, the 20466representation chosen for data in GNAT generally meets the standard system 20467conventions, and for example records are laid out in a manner that is 20468consistent with C. This means that specifying convention C (for example) 20469has no effect. 20470 20471There are four exceptions to this general rule: 20472 20473 20474@itemize * 20475 20476@item 20477@emph{Convention Fortran and array subtypes}. 20478 20479If pragma Convention Fortran is specified for an array subtype, then in 20480accordance with the implementation advice in section 3.6.2(11) of the 20481Ada Reference Manual, the array will be stored in a Fortran-compatible 20482column-major manner, instead of the normal default row-major order. 20483 20484@item 20485@emph{Convention C and enumeration types} 20486 20487GNAT normally stores enumeration types in 8, 16, or 32 bits as required 20488to accommodate all values of the type. For example, for the enumeration 20489type declared by: 20490 20491@example 20492type Color is (Red, Green, Blue); 20493@end example 20494 204958 bits is sufficient to store all values of the type, so by default, objects 20496of type @code{Color} will be represented using 8 bits. However, normal C 20497convention is to use 32 bits for all enum values in C, since enum values 20498are essentially of type int. If pragma @code{Convention C} is specified for an 20499Ada enumeration type, then the size is modified as necessary (usually to 2050032 bits) to be consistent with the C convention for enum values. 20501 20502Note that this treatment applies only to types. If Convention C is given for 20503an enumeration object, where the enumeration type is not Convention C, then 20504Object_Size bits are allocated. For example, for a normal enumeration type, 20505with less than 256 elements, only 8 bits will be allocated for the object. 20506Since this may be a surprise in terms of what C expects, GNAT will issue a 20507warning in this situation. The warning can be suppressed by giving an explicit 20508size clause specifying the desired size. 20509 20510@item 20511@emph{Convention C/Fortran and Boolean types} 20512 20513In C, the usual convention for boolean values, that is values used for 20514conditions, is that zero represents false, and nonzero values represent 20515true. In Ada, the normal convention is that two specific values, typically 205160/1, are used to represent false/true respectively. 20517 20518Fortran has a similar convention for @code{LOGICAL} values (any nonzero 20519value represents true). 20520 20521To accommodate the Fortran and C conventions, if a pragma Convention specifies 20522C or Fortran convention for a derived Boolean, as in the following example: 20523 20524@example 20525type C_Switch is new Boolean; 20526pragma Convention (C, C_Switch); 20527@end example 20528 20529then the GNAT generated code will treat any nonzero value as true. For truth 20530values generated by GNAT, the conventional value 1 will be used for True, but 20531when one of these values is read, any nonzero value is treated as True. 20532@end itemize 20533 20534@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas 20535@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29c} 20536@section Conventions and Anonymous Access Types 20537 20538 20539@geindex Anonymous access types 20540 20541@geindex Convention for anonymous access types 20542 20543The RM is not entirely clear on convention handling in a number of cases, 20544and in particular, it is not clear on the convention to be given to 20545anonymous access types in general, and in particular what is to be 20546done for the case of anonymous access-to-subprogram. 20547 20548In GNAT, we decide that if an explicit Convention is applied 20549to an object or component, and its type is such an anonymous type, 20550then the convention will apply to this anonymous type as well. This 20551seems to make sense since it is anomolous in any case to have a 20552different convention for an object and its type, and there is clearly 20553no way to explicitly specify a convention for an anonymous type, since 20554it doesn’t have a name to specify! 20555 20556Furthermore, we decide that if a convention is applied to a record type, 20557then this convention is inherited by any of its components that are of an 20558anonymous access type which do not have an explicitly specified convention. 20559 20560The following program shows these conventions in action: 20561 20562@example 20563package ConvComp is 20564 type Foo is range 1 .. 10; 20565 type T1 is record 20566 A : access function (X : Foo) return Integer; 20567 B : Integer; 20568 end record; 20569 pragma Convention (C, T1); 20570 20571 type T2 is record 20572 A : access function (X : Foo) return Integer; 20573 pragma Convention (C, A); 20574 B : Integer; 20575 end record; 20576 pragma Convention (COBOL, T2); 20577 20578 type T3 is record 20579 A : access function (X : Foo) return Integer; 20580 pragma Convention (COBOL, A); 20581 B : Integer; 20582 end record; 20583 pragma Convention (C, T3); 20584 20585 type T4 is record 20586 A : access function (X : Foo) return Integer; 20587 B : Integer; 20588 end record; 20589 pragma Convention (COBOL, T4); 20590 20591 function F (X : Foo) return Integer; 20592 pragma Convention (C, F); 20593 20594 function F (X : Foo) return Integer is (13); 20595 20596 TV1 : T1 := (F'Access, 12); -- OK 20597 TV2 : T2 := (F'Access, 13); -- OK 20598 20599 TV3 : T3 := (F'Access, 13); -- ERROR 20600 | 20601>>> subprogram "F" has wrong convention 20602>>> does not match access to subprogram declared at line 17 20603 38. TV4 : T4 := (F'Access, 13); -- ERROR 20604 | 20605>>> subprogram "F" has wrong convention 20606>>> does not match access to subprogram declared at line 24 20607 39. end ConvComp; 20608@end example 20609 20610@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas 20611@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} 20612@section Determining the Representations chosen by GNAT 20613 20614 20615@geindex Representation 20616@geindex determination of 20617 20618@geindex -gnatR (gcc) 20619 20620Although the descriptions in this section are intended to be complete, it is 20621often easier to simply experiment to see what GNAT accepts and what the 20622effect is on the layout of types and objects. 20623 20624As required by the Ada RM, if a representation clause is not accepted, then 20625it must be rejected as illegal by the compiler. However, when a 20626representation clause or pragma is accepted, there can still be questions 20627of what the compiler actually does. For example, if a partial record 20628representation clause specifies the location of some components and not 20629others, then where are the non-specified components placed? Or if pragma 20630@code{Pack} is used on a record, then exactly where are the resulting 20631fields placed? The section on pragma @code{Pack} in this chapter can be 20632used to answer the second question, but it is often easier to just see 20633what the compiler does. 20634 20635For this purpose, GNAT provides the option @emph{-gnatR}. If you compile 20636with this option, then the compiler will output information on the actual 20637representations chosen, in a format similar to source representation 20638clauses. For example, if we compile the package: 20639 20640@example 20641package q is 20642 type r (x : boolean) is tagged record 20643 case x is 20644 when True => S : String (1 .. 100); 20645 when False => null; 20646 end case; 20647 end record; 20648 20649 type r2 is new r (false) with record 20650 y2 : integer; 20651 end record; 20652 20653 for r2 use record 20654 y2 at 16 range 0 .. 31; 20655 end record; 20656 20657 type x is record 20658 y : character; 20659 end record; 20660 20661 type x1 is array (1 .. 10) of x; 20662 for x1'component_size use 11; 20663 20664 type ia is access integer; 20665 20666 type Rb1 is array (1 .. 13) of Boolean; 20667 pragma Pack (rb1); 20668 20669 type Rb2 is array (1 .. 65) of Boolean; 20670 pragma Pack (rb2); 20671 20672 type x2 is record 20673 l1 : Boolean; 20674 l2 : Duration; 20675 l3 : Float; 20676 l4 : Boolean; 20677 l5 : Rb1; 20678 l6 : Rb2; 20679 end record; 20680 pragma Pack (x2); 20681end q; 20682@end example 20683 20684using the switch @emph{-gnatR} we obtain the following output: 20685 20686@example 20687Representation information for unit q 20688------------------------------------- 20689 20690for r'Size use ??; 20691for r'Alignment use 4; 20692for r use record 20693 x at 4 range 0 .. 7; 20694 _tag at 0 range 0 .. 31; 20695 s at 5 range 0 .. 799; 20696end record; 20697 20698for r2'Size use 160; 20699for r2'Alignment use 4; 20700for r2 use record 20701 x at 4 range 0 .. 7; 20702 _tag at 0 range 0 .. 31; 20703 _parent at 0 range 0 .. 63; 20704 y2 at 16 range 0 .. 31; 20705end record; 20706 20707for x'Size use 8; 20708for x'Alignment use 1; 20709for x use record 20710 y at 0 range 0 .. 7; 20711end record; 20712 20713for x1'Size use 112; 20714for x1'Alignment use 1; 20715for x1'Component_Size use 11; 20716 20717for rb1'Size use 13; 20718for rb1'Alignment use 2; 20719for rb1'Component_Size use 1; 20720 20721for rb2'Size use 72; 20722for rb2'Alignment use 1; 20723for rb2'Component_Size use 1; 20724 20725for x2'Size use 224; 20726for x2'Alignment use 4; 20727for x2 use record 20728 l1 at 0 range 0 .. 0; 20729 l2 at 0 range 1 .. 64; 20730 l3 at 12 range 0 .. 31; 20731 l4 at 16 range 0 .. 0; 20732 l5 at 16 range 1 .. 13; 20733 l6 at 18 range 0 .. 71; 20734end record; 20735@end example 20736 20737The Size values are actually the Object_Size, i.e., the default size that 20738will be allocated for objects of the type. 20739The @code{??} size for type r indicates that we have a variant record, and the 20740actual size of objects will depend on the discriminant value. 20741 20742The Alignment values show the actual alignment chosen by the compiler 20743for each record or array type. 20744 20745The record representation clause for type r shows where all fields 20746are placed, including the compiler generated tag field (whose location 20747cannot be controlled by the programmer). 20748 20749The record representation clause for the type extension r2 shows all the 20750fields present, including the parent field, which is a copy of the fields 20751of the parent type of r2, i.e., r1. 20752 20753The component size and size clauses for types rb1 and rb2 show 20754the exact effect of pragma @code{Pack} on these arrays, and the record 20755representation clause for type x2 shows how pragma @cite{Pack} affects 20756this record type. 20757 20758In some cases, it may be useful to cut and paste the representation clauses 20759generated by the compiler into the original source to fix and guarantee 20760the actual representation to be used. 20761 20762@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top 20763@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} 20764@chapter Standard Library Routines 20765 20766 20767The Ada Reference Manual contains in Annex A a full description of an 20768extensive set of standard library routines that can be used in any Ada 20769program, and which must be provided by all Ada compilers. They are 20770analogous to the standard C library used by C programs. 20771 20772GNAT implements all of the facilities described in annex A, and for most 20773purposes the description in the Ada Reference Manual, or appropriate Ada 20774text book, will be sufficient for making use of these facilities. 20775 20776In the case of the input-output facilities, 20777@ref{f,,The Implementation of Standard I/O}, 20778gives details on exactly how GNAT interfaces to the 20779file system. For the remaining packages, the Ada Reference Manual 20780should be sufficient. The following is a list of the packages included, 20781together with a brief description of the functionality that is provided. 20782 20783For completeness, references are included to other predefined library 20784routines defined in other sections of the Ada Reference Manual (these are 20785cross-indexed from Annex A). For further details see the relevant 20786package declarations in the run-time library. In particular, a few units 20787are not implemented, as marked by the presence of pragma Unimplemented_Unit, 20788and in this case the package declaration contains comments explaining why 20789the unit is not implemented. 20790 20791 20792@table @asis 20793 20794@item @code{Ada} @emph{(A.2)} 20795 20796This is a parent package for all the standard library packages. It is 20797usually included implicitly in your program, and itself contains no 20798useful data or routines. 20799 20800@item @code{Ada.Assertions} @emph{(11.4.2)} 20801 20802@code{Assertions} provides the @code{Assert} subprograms, and also 20803the declaration of the @code{Assertion_Error} exception. 20804 20805@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} 20806 20807@code{Asynchronous_Task_Control} provides low level facilities for task 20808synchronization. It is typically not implemented. See package spec for details. 20809 20810@item @code{Ada.Calendar} @emph{(9.6)} 20811 20812@code{Calendar} provides time of day access, and routines for 20813manipulating times and durations. 20814 20815@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} 20816 20817This package provides additional arithmetic 20818operations for @code{Calendar}. 20819 20820@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} 20821 20822This package provides formatting operations for @code{Calendar}. 20823 20824@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} 20825 20826This package provides additional @code{Calendar} facilities 20827for handling time zones. 20828 20829@item @code{Ada.Characters} @emph{(A.3.1)} 20830 20831This is a dummy parent package that contains no useful entities 20832 20833@item @code{Ada.Characters.Conversions} @emph{(A.3.2)} 20834 20835This package provides character conversion functions. 20836 20837@item @code{Ada.Characters.Handling} @emph{(A.3.2)} 20838 20839This package provides some basic character handling capabilities, 20840including classification functions for classes of characters (e.g., test 20841for letters, or digits). 20842 20843@item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} 20844 20845This package includes a complete set of definitions of the characters 20846that appear in type CHARACTER. It is useful for writing programs that 20847will run in international environments. For example, if you want an 20848upper case E with an acute accent in a string, it is often better to use 20849the definition of @code{UC_E_Acute} in this package. Then your program 20850will print in an understandable manner even if your environment does not 20851support these extended characters. 20852 20853@item @code{Ada.Command_Line} @emph{(A.15)} 20854 20855This package provides access to the command line parameters and the name 20856of the current program (analogous to the use of @code{argc} and @code{argv} 20857in C), and also allows the exit status for the program to be set in a 20858system-independent manner. 20859 20860@item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} 20861 20862This package provides text input and output of complex numbers. 20863 20864@item @code{Ada.Containers} @emph{(A.18.1)} 20865 20866A top level package providing a few basic definitions used by all the 20867following specific child packages that provide specific kinds of 20868containers. 20869@end table 20870 20871@code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} 20872 20873@code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} 20874 20875@code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} 20876 20877@code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} 20878 20879@code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} 20880 20881@code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} 20882 20883@code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} 20884 20885@code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} 20886 20887@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} 20888 20889@code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} 20890 20891@code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} 20892 20893@code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} 20894 20895@code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} 20896 20897@code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} 20898 20899@code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} 20900 20901@code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} 20902 20903@code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} 20904 20905@code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} 20906 20907@code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} 20908 20909@code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} 20910 20911@code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} 20912 20913@code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} 20914 20915@code{Ada.Containers.Vectors} @emph{(A.18.2)} 20916 20917 20918@table @asis 20919 20920@item @code{Ada.Directories} @emph{(A.16)} 20921 20922This package provides operations on directories. 20923 20924@item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} 20925 20926This package provides additional directory operations handling 20927hiearchical file names. 20928 20929@item @code{Ada.Directories.Information} @emph{(A.16)} 20930 20931This is an implementation defined package for additional directory 20932operations, which is not implemented in GNAT. 20933 20934@item @code{Ada.Decimal} @emph{(F.2)} 20935 20936This package provides constants describing the range of decimal numbers 20937implemented, and also a decimal divide routine (analogous to the COBOL 20938verb DIVIDE … GIVING … REMAINDER …) 20939 20940@item @code{Ada.Direct_IO} @emph{(A.8.4)} 20941 20942This package provides input-output using a model of a set of records of 20943fixed-length, containing an arbitrary definite Ada type, indexed by an 20944integer record number. 20945 20946@item @code{Ada.Dispatching} @emph{(D.2.1)} 20947 20948A parent package containing definitions for task dispatching operations. 20949 20950@item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} 20951 20952Not implemented in GNAT. 20953 20954@item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} 20955 20956Not implemented in GNAT. 20957 20958@item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} 20959 20960Not implemented in GNAT. 20961 20962@item @code{Ada.Dynamic_Priorities} @emph{(D.5)} 20963 20964This package allows the priorities of a task to be adjusted dynamically 20965as the task is running. 20966 20967@item @code{Ada.Environment_Variables} @emph{(A.17)} 20968 20969This package provides facilities for accessing environment variables. 20970 20971@item @code{Ada.Exceptions} @emph{(11.4.1)} 20972 20973This package provides additional information on exceptions, and also 20974contains facilities for treating exceptions as data objects, and raising 20975exceptions with associated messages. 20976 20977@item @code{Ada.Execution_Time} @emph{(D.14)} 20978 20979This package provides CPU clock functionalities. It is not implemented on 20980all targets (see package spec for details). 20981 20982@item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} 20983 20984Not implemented in GNAT. 20985 20986@item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)’} 20987 20988Not implemented in GNAT. 20989 20990@item @code{Ada.Finalization} @emph{(7.6)} 20991 20992This package contains the declarations and subprograms to support the 20993use of controlled types, providing for automatic initialization and 20994finalization (analogous to the constructors and destructors of C++). 20995 20996@item @code{Ada.Float_Text_IO} @emph{(A.10.9)} 20997 20998A library level instantiation of Text_IO.Float_IO for type Float. 20999 21000@item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} 21001 21002A library level instantiation of Wide_Text_IO.Float_IO for type Float. 21003 21004@item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} 21005 21006A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. 21007 21008@item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} 21009 21010A library level instantiation of Text_IO.Integer_IO for type Integer. 21011 21012@item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} 21013 21014A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. 21015 21016@item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} 21017 21018A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. 21019 21020@item @code{Ada.Interrupts} @emph{(C.3.2)} 21021 21022This package provides facilities for interfacing to interrupts, which 21023includes the set of signals or conditions that can be raised and 21024recognized as interrupts. 21025 21026@item @code{Ada.Interrupts.Names} @emph{(C.3.2)} 21027 21028This package provides the set of interrupt names (actually signal 21029or condition names) that can be handled by GNAT. 21030 21031@item @code{Ada.IO_Exceptions} @emph{(A.13)} 21032 21033This package defines the set of exceptions that can be raised by use of 21034the standard IO packages. 21035 21036@item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} 21037 21038This package provides a generic interface to generalized iterators. 21039 21040@item @code{Ada.Locales} @emph{(A.19)} 21041 21042This package provides declarations providing information (Language 21043and Country) about the current locale. 21044 21045@item @code{Ada.Numerics} 21046 21047This package contains some standard constants and exceptions used 21048throughout the numerics packages. Note that the constants pi and e are 21049defined here, and it is better to use these definitions than rolling 21050your own. 21051 21052@item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} 21053 21054Provides operations on arrays of complex numbers. 21055 21056@item @code{Ada.Numerics.Complex_Elementary_Functions} 21057 21058Provides the implementation of standard elementary functions (such as 21059log and trigonometric functions) operating on complex numbers using the 21060standard @code{Float} and the @code{Complex} and @code{Imaginary} types 21061created by the package @code{Numerics.Complex_Types}. 21062 21063@item @code{Ada.Numerics.Complex_Types} 21064 21065This is a predefined instantiation of 21066@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 21067build the type @code{Complex} and @code{Imaginary}. 21068 21069@item @code{Ada.Numerics.Discrete_Random} 21070 21071This generic package provides a random number generator suitable for generating 21072uniformly distributed values of a specified discrete subtype. 21073 21074@item @code{Ada.Numerics.Float_Random} 21075 21076This package provides a random number generator suitable for generating 21077uniformly distributed floating point values in the unit interval. 21078 21079@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} 21080 21081This is a generic version of the package that provides the 21082implementation of standard elementary functions (such as log and 21083trigonometric functions) for an arbitrary complex type. 21084 21085The following predefined instantiations of this package are provided: 21086 21087 21088@itemize * 21089 21090@item 21091@code{Short_Float} 21092 21093@code{Ada.Numerics.Short_Complex_Elementary_Functions} 21094 21095@item 21096@code{Float} 21097 21098@code{Ada.Numerics.Complex_Elementary_Functions} 21099 21100@item 21101@code{Long_Float} 21102 21103@code{Ada.Numerics.Long_Complex_Elementary_Functions} 21104@end itemize 21105 21106@item @code{Ada.Numerics.Generic_Complex_Types} 21107 21108This is a generic package that allows the creation of complex types, 21109with associated complex arithmetic operations. 21110 21111The following predefined instantiations of this package exist 21112 21113 21114@itemize * 21115 21116@item 21117@code{Short_Float} 21118 21119@code{Ada.Numerics.Short_Complex_Complex_Types} 21120 21121@item 21122@code{Float} 21123 21124@code{Ada.Numerics.Complex_Complex_Types} 21125 21126@item 21127@code{Long_Float} 21128 21129@code{Ada.Numerics.Long_Complex_Complex_Types} 21130@end itemize 21131 21132@item @code{Ada.Numerics.Generic_Elementary_Functions} 21133 21134This is a generic package that provides the implementation of standard 21135elementary functions (such as log an trigonometric functions) for an 21136arbitrary float type. 21137 21138The following predefined instantiations of this package exist 21139 21140 21141@itemize * 21142 21143@item 21144@code{Short_Float} 21145 21146@code{Ada.Numerics.Short_Elementary_Functions} 21147 21148@item 21149@code{Float} 21150 21151@code{Ada.Numerics.Elementary_Functions} 21152 21153@item 21154@code{Long_Float} 21155 21156@code{Ada.Numerics.Long_Elementary_Functions} 21157@end itemize 21158 21159@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} 21160 21161Generic operations on arrays of reals 21162 21163@item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} 21164 21165Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). 21166 21167@item @code{Ada.Real_Time} @emph{(D.8)} 21168 21169This package provides facilities similar to those of @code{Calendar}, but 21170operating with a finer clock suitable for real time control. Note that 21171annex D requires that there be no backward clock jumps, and GNAT generally 21172guarantees this behavior, but of course if the external clock on which 21173the GNAT runtime depends is deliberately reset by some external event, 21174then such a backward jump may occur. 21175 21176@item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} 21177 21178Not implemented in GNAT. 21179 21180@item @code{Ada.Sequential_IO} @emph{(A.8.1)} 21181 21182This package provides input-output facilities for sequential files, 21183which can contain a sequence of values of a single type, which can be 21184any Ada type, including indefinite (unconstrained) types. 21185 21186@item @code{Ada.Storage_IO} @emph{(A.9)} 21187 21188This package provides a facility for mapping arbitrary Ada types to and 21189from a storage buffer. It is primarily intended for the creation of new 21190IO packages. 21191 21192@item @code{Ada.Streams} @emph{(13.13.1)} 21193 21194This is a generic package that provides the basic support for the 21195concept of streams as used by the stream attributes (@code{Input}, 21196@code{Output}, @code{Read} and @code{Write}). 21197 21198@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} 21199 21200This package is a specialization of the type @code{Streams} defined in 21201package @code{Streams} together with a set of operations providing 21202Stream_IO capability. The Stream_IO model permits both random and 21203sequential access to a file which can contain an arbitrary set of values 21204of one or more Ada types. 21205 21206@item @code{Ada.Strings} @emph{(A.4.1)} 21207 21208This package provides some basic constants used by the string handling 21209packages. 21210 21211@item @code{Ada.Strings.Bounded} @emph{(A.4.4)} 21212 21213This package provides facilities for handling variable length 21214strings. The bounded model requires a maximum length. It is thus 21215somewhat more limited than the unbounded model, but avoids the use of 21216dynamic allocation or finalization. 21217 21218@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} 21219 21220Provides case-insensitive comparisons of bounded strings 21221 21222@item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} 21223 21224This package provides a generic hash function for bounded strings 21225 21226@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} 21227 21228This package provides a generic hash function for bounded strings that 21229converts the string to be hashed to lower case. 21230 21231@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} 21232 21233This package provides a comparison function for bounded strings that works 21234in a case insensitive manner by converting to lower case before the comparison. 21235 21236@item @code{Ada.Strings.Fixed} @emph{(A.4.3)} 21237 21238This package provides facilities for handling fixed length strings. 21239 21240@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} 21241 21242This package provides an equality function for fixed strings that compares 21243the strings after converting both to lower case. 21244 21245@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} 21246 21247This package provides a case insensitive hash function for fixed strings that 21248converts the string to lower case before computing the hash. 21249 21250@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} 21251 21252This package provides a comparison function for fixed strings that works 21253in a case insensitive manner by converting to lower case before the comparison. 21254 21255@item @code{Ada.Strings.Hash} @emph{(A.4.9)} 21256 21257This package provides a hash function for strings. 21258 21259@item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} 21260 21261This package provides a hash function for strings that is case insensitive. 21262The string is converted to lower case before computing the hash. 21263 21264@item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} 21265 21266This package provides a comparison function for\strings that works 21267in a case insensitive manner by converting to lower case before the comparison. 21268 21269@item @code{Ada.Strings.Maps} @emph{(A.4.2)} 21270 21271This package provides facilities for handling character mappings and 21272arbitrarily defined subsets of characters. For instance it is useful in 21273defining specialized translation tables. 21274 21275@item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} 21276 21277This package provides a standard set of predefined mappings and 21278predefined character sets. For example, the standard upper to lower case 21279conversion table is found in this package. Note that upper to lower case 21280conversion is non-trivial if you want to take the entire set of 21281characters, including extended characters like E with an acute accent, 21282into account. You should use the mappings in this package (rather than 21283adding 32 yourself) to do case mappings. 21284 21285@item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} 21286 21287This package provides facilities for handling variable length 21288strings. The unbounded model allows arbitrary length strings, but 21289requires the use of dynamic allocation and finalization. 21290 21291@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} 21292 21293Provides case-insensitive comparisons of unbounded strings 21294 21295@item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} 21296 21297This package provides a generic hash function for unbounded strings 21298 21299@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} 21300 21301This package provides a generic hash function for unbounded strings that 21302converts the string to be hashed to lower case. 21303 21304@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} 21305 21306This package provides a comparison function for unbounded strings that works 21307in a case insensitive manner by converting to lower case before the comparison. 21308 21309@item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} 21310 21311This package provides basic definitions for dealing with UTF-encoded strings. 21312 21313@item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} 21314 21315This package provides conversion functions for UTF-encoded strings. 21316@end table 21317 21318@code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} 21319 21320@code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} 21321 21322 21323@table @asis 21324 21325@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} 21326 21327These packages provide facilities for handling UTF encodings for 21328Strings, Wide_Strings and Wide_Wide_Strings. 21329@end table 21330 21331@code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} 21332 21333@code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} 21334 21335@code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} 21336 21337 21338@table @asis 21339 21340@item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} 21341 21342These packages provide analogous capabilities to the corresponding 21343packages without @code{Wide_} in the name, but operate with the types 21344@code{Wide_String} and @code{Wide_Character} instead of @code{String} 21345and @code{Character}. Versions of all the child packages are available. 21346@end table 21347 21348@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} 21349 21350@code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} 21351 21352@code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} 21353 21354 21355@table @asis 21356 21357@item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} 21358 21359These packages provide analogous capabilities to the corresponding 21360packages without @code{Wide_} in the name, but operate with the types 21361@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead 21362of @code{String} and @code{Character}. 21363 21364@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} 21365 21366This package provides facilities for synchronizing tasks at a low level 21367with barriers. 21368 21369@item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} 21370 21371This package provides some standard facilities for controlling task 21372communication in a synchronous manner. 21373 21374@item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} 21375 21376Not implemented in GNAT. 21377 21378@item @code{Ada.Tags} 21379 21380This package contains definitions for manipulation of the tags of tagged 21381values. 21382 21383@item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} 21384 21385This package provides a way of constructing tagged class-wide values given 21386only the tag value. 21387 21388@item @code{Ada.Task_Attributes} @emph{(C.7.2)} 21389 21390This package provides the capability of associating arbitrary 21391task-specific data with separate tasks. 21392 21393@item @code{Ada.Task_Identifification} @emph{(C.7.1)} 21394 21395This package provides capabilities for task identification. 21396 21397@item @code{Ada.Task_Termination} @emph{(C.7.3)} 21398 21399This package provides control over task termination. 21400 21401@item @code{Ada.Text_IO} 21402 21403This package provides basic text input-output capabilities for 21404character, string and numeric data. The subpackages of this 21405package are listed next. Note that although these are defined 21406as subpackages in the RM, they are actually transparently 21407implemented as child packages in GNAT, meaning that they 21408are only loaded if needed. 21409 21410@item @code{Ada.Text_IO.Decimal_IO} 21411 21412Provides input-output facilities for decimal fixed-point types 21413 21414@item @code{Ada.Text_IO.Enumeration_IO} 21415 21416Provides input-output facilities for enumeration types. 21417 21418@item @code{Ada.Text_IO.Fixed_IO} 21419 21420Provides input-output facilities for ordinary fixed-point types. 21421 21422@item @code{Ada.Text_IO.Float_IO} 21423 21424Provides input-output facilities for float types. The following 21425predefined instantiations of this generic package are available: 21426 21427 21428@itemize * 21429 21430@item 21431@code{Short_Float} 21432 21433@code{Short_Float_Text_IO} 21434 21435@item 21436@code{Float} 21437 21438@code{Float_Text_IO} 21439 21440@item 21441@code{Long_Float} 21442 21443@code{Long_Float_Text_IO} 21444@end itemize 21445 21446@item @code{Ada.Text_IO.Integer_IO} 21447 21448Provides input-output facilities for integer types. The following 21449predefined instantiations of this generic package are available: 21450 21451 21452@itemize * 21453 21454@item 21455@code{Short_Short_Integer} 21456 21457@code{Ada.Short_Short_Integer_Text_IO} 21458 21459@item 21460@code{Short_Integer} 21461 21462@code{Ada.Short_Integer_Text_IO} 21463 21464@item 21465@code{Integer} 21466 21467@code{Ada.Integer_Text_IO} 21468 21469@item 21470@code{Long_Integer} 21471 21472@code{Ada.Long_Integer_Text_IO} 21473 21474@item 21475@code{Long_Long_Integer} 21476 21477@code{Ada.Long_Long_Integer_Text_IO} 21478@end itemize 21479 21480@item @code{Ada.Text_IO.Modular_IO} 21481 21482Provides input-output facilities for modular (unsigned) types. 21483 21484@item @code{Ada.Text_IO.Bounded_IO (A.10.11)} 21485 21486Provides input-output facilities for bounded strings. 21487 21488@item @code{Ada.Text_IO.Complex_IO (G.1.3)} 21489 21490This package provides basic text input-output capabilities for complex 21491data. 21492 21493@item @code{Ada.Text_IO.Editing (F.3.3)} 21494 21495This package contains routines for edited output, analogous to the use 21496of pictures in COBOL. The picture formats used by this package are a 21497close copy of the facility in COBOL. 21498 21499@item @code{Ada.Text_IO.Text_Streams (A.12.2)} 21500 21501This package provides a facility that allows Text_IO files to be treated 21502as streams, so that the stream attributes can be used for writing 21503arbitrary data, including binary data, to Text_IO files. 21504 21505@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} 21506 21507This package provides input-output facilities for unbounded strings. 21508 21509@item @code{Ada.Unchecked_Conversion (13.9)} 21510 21511This generic package allows arbitrary conversion from one type to 21512another of the same size, providing for breaking the type safety in 21513special circumstances. 21514 21515If the types have the same Size (more accurately the same Value_Size), 21516then the effect is simply to transfer the bits from the source to the 21517target type without any modification. This usage is well defined, and 21518for simple types whose representation is typically the same across 21519all implementations, gives a portable method of performing such 21520conversions. 21521 21522If the types do not have the same size, then the result is implementation 21523defined, and thus may be non-portable. The following describes how GNAT 21524handles such unchecked conversion cases. 21525 21526If the types are of different sizes, and are both discrete types, then 21527the effect is of a normal type conversion without any constraint checking. 21528In particular if the result type has a larger size, the result will be 21529zero or sign extended. If the result type has a smaller size, the result 21530will be truncated by ignoring high order bits. 21531 21532If the types are of different sizes, and are not both discrete types, 21533then the conversion works as though pointers were created to the source 21534and target, and the pointer value is converted. The effect is that bits 21535are copied from successive low order storage units and bits of the source 21536up to the length of the target type. 21537 21538A warning is issued if the lengths differ, since the effect in this 21539case is implementation dependent, and the above behavior may not match 21540that of some other compiler. 21541 21542A pointer to one type may be converted to a pointer to another type using 21543unchecked conversion. The only case in which the effect is undefined is 21544when one or both pointers are pointers to unconstrained array types. In 21545this case, the bounds information may get incorrectly transferred, and in 21546particular, GNAT uses double size pointers for such types, and it is 21547meaningless to convert between such pointer types. GNAT will issue a 21548warning if the alignment of the target designated type is more strict 21549than the alignment of the source designated type (since the result may 21550be unaligned in this case). 21551 21552A pointer other than a pointer to an unconstrained array type may be 21553converted to and from System.Address. Such usage is common in Ada 83 21554programs, but note that Ada.Address_To_Access_Conversions is the 21555preferred method of performing such conversions in Ada 95 and Ada 2005. 21556Neither 21557unchecked conversion nor Ada.Address_To_Access_Conversions should be 21558used in conjunction with pointers to unconstrained objects, since 21559the bounds information cannot be handled correctly in this case. 21560 21561@item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} 21562 21563This generic package allows explicit freeing of storage previously 21564allocated by use of an allocator. 21565 21566@item @code{Ada.Wide_Text_IO} @emph{(A.11)} 21567 21568This package is similar to @code{Ada.Text_IO}, except that the external 21569file supports wide character representations, and the internal types are 21570@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21571and @code{String}. The corresponding set of nested packages and child 21572packages are defined. 21573 21574@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} 21575 21576This package is similar to @code{Ada.Text_IO}, except that the external 21577file supports wide character representations, and the internal types are 21578@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21579and @code{String}. The corresponding set of nested packages and child 21580packages are defined. 21581@end table 21582 21583For packages in Interfaces and System, all the RM defined packages are 21584available in GNAT, see the Ada 2012 RM for full details. 21585 21586@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top 21587@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} 21588@chapter The Implementation of Standard I/O 21589 21590 21591GNAT implements all the required input-output facilities described in 21592A.6 through A.14. These sections of the Ada Reference Manual describe the 21593required behavior of these packages from the Ada point of view, and if 21594you are writing a portable Ada program that does not need to know the 21595exact manner in which Ada maps to the outside world when it comes to 21596reading or writing external files, then you do not need to read this 21597chapter. As long as your files are all regular files (not pipes or 21598devices), and as long as you write and read the files only from Ada, the 21599description in the Ada Reference Manual is sufficient. 21600 21601However, if you want to do input-output to pipes or other devices, such 21602as the keyboard or screen, or if the files you are dealing with are 21603either generated by some other language, or to be read by some other 21604language, then you need to know more about the details of how the GNAT 21605implementation of these input-output facilities behaves. 21606 21607In this chapter we give a detailed description of exactly how GNAT 21608interfaces to the file system. As always, the sources of the system are 21609available to you for answering questions at an even more detailed level, 21610but for most purposes the information in this chapter will suffice. 21611 21612Another reason that you may need to know more about how input-output is 21613implemented arises when you have a program written in mixed languages 21614where, for example, files are shared between the C and Ada sections of 21615the same program. GNAT provides some additional facilities, in the form 21616of additional child library packages, that facilitate this sharing, and 21617these additional facilities are also described in this chapter. 21618 21619@menu 21620* Standard I/O Packages:: 21621* FORM Strings:: 21622* Direct_IO:: 21623* Sequential_IO:: 21624* Text_IO:: 21625* Wide_Text_IO:: 21626* Wide_Wide_Text_IO:: 21627* Stream_IO:: 21628* Text Translation:: 21629* Shared Files:: 21630* Filenames encoding:: 21631* File content encoding:: 21632* Open Modes:: 21633* Operations on C Streams:: 21634* Interfacing to C Streams:: 21635 21636@end menu 21637 21638@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O 21639@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} 21640@section Standard I/O Packages 21641 21642 21643The Standard I/O packages described in Annex A for 21644 21645 21646@itemize * 21647 21648@item 21649Ada.Text_IO 21650 21651@item 21652Ada.Text_IO.Complex_IO 21653 21654@item 21655Ada.Text_IO.Text_Streams 21656 21657@item 21658Ada.Wide_Text_IO 21659 21660@item 21661Ada.Wide_Text_IO.Complex_IO 21662 21663@item 21664Ada.Wide_Text_IO.Text_Streams 21665 21666@item 21667Ada.Wide_Wide_Text_IO 21668 21669@item 21670Ada.Wide_Wide_Text_IO.Complex_IO 21671 21672@item 21673Ada.Wide_Wide_Text_IO.Text_Streams 21674 21675@item 21676Ada.Stream_IO 21677 21678@item 21679Ada.Sequential_IO 21680 21681@item 21682Ada.Direct_IO 21683@end itemize 21684 21685are implemented using the C 21686library streams facility; where 21687 21688 21689@itemize * 21690 21691@item 21692All files are opened using @code{fopen}. 21693 21694@item 21695All input/output operations use @code{fread}/@cite{fwrite}. 21696@end itemize 21697 21698There is no internal buffering of any kind at the Ada library level. The only 21699buffering is that provided at the system level in the implementation of the 21700library routines that support streams. This facilitates shared use of these 21701streams by mixed language programs. Note though that system level buffering is 21702explicitly enabled at elaboration of the standard I/O packages and that can 21703have an impact on mixed language programs, in particular those using I/O before 21704calling the Ada elaboration routine (e.g., adainit). It is recommended to call 21705the Ada elaboration routine before performing any I/O or when impractical, 21706flush the common I/O streams and in particular Standard_Output before 21707elaborating the Ada code. 21708 21709@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O 21710@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} 21711@section FORM Strings 21712 21713 21714The format of a FORM string in GNAT is: 21715 21716@example 21717"keyword=value,keyword=value,...,keyword=value" 21718@end example 21719 21720where letters may be in upper or lower case, and there are no spaces 21721between values. The order of the entries is not important. Currently 21722the following keywords defined. 21723 21724@example 21725TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] 21726SHARED=[YES|NO] 21727WCEM=[n|h|u|s|e|8|b] 21728ENCODING=[UTF8|8BITS] 21729@end example 21730 21731The use of these parameters is described later in this section. If an 21732unrecognized keyword appears in a form string, it is silently ignored 21733and not considered invalid. 21734 21735@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O 21736@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} 21737@section Direct_IO 21738 21739 21740Direct_IO can only be instantiated for definite types. This is a 21741restriction of the Ada language, which means that the records are fixed 21742length (the length being determined by @code{type'Size}, rounded 21743up to the next storage unit boundary if necessary). 21744 21745The records of a Direct_IO file are simply written to the file in index 21746sequence, with the first record starting at offset zero, and subsequent 21747records following. There is no control information of any kind. For 21748example, if 32-bit integers are being written, each record takes 217494-bytes, so the record at index @code{K} starts at offset 21750(@code{K}-1)*4. 21751 21752There is no limit on the size of Direct_IO files, they are expanded as 21753necessary to accommodate whatever records are written to the file. 21754 21755@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O 21756@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} 21757@section Sequential_IO 21758 21759 21760Sequential_IO may be instantiated with either a definite (constrained) 21761or indefinite (unconstrained) type. 21762 21763For the definite type case, the elements written to the file are simply 21764the memory images of the data values with no control information of any 21765kind. The resulting file should be read using the same type, no validity 21766checking is performed on input. 21767 21768For the indefinite type case, the elements written consist of two 21769parts. First is the size of the data item, written as the memory image 21770of a @code{Interfaces.C.size_t} value, followed by the memory image of 21771the data value. The resulting file can only be read using the same 21772(unconstrained) type. Normal assignment checks are performed on these 21773read operations, and if these checks fail, @code{Data_Error} is 21774raised. In particular, in the array case, the lengths must match, and in 21775the variant record case, if the variable for a particular read operation 21776is constrained, the discriminants must match. 21777 21778Note that it is not possible to use Sequential_IO to write variable 21779length array items, and then read the data back into different length 21780arrays. For example, the following will raise @code{Data_Error}: 21781 21782@example 21783package IO is new Sequential_IO (String); 21784F : IO.File_Type; 21785S : String (1..4); 21786... 21787IO.Create (F) 21788IO.Write (F, "hello!") 21789IO.Reset (F, Mode=>In_File); 21790IO.Read (F, S); 21791Put_Line (S); 21792@end example 21793 21794On some Ada implementations, this will print @code{hell}, but the program is 21795clearly incorrect, since there is only one element in the file, and that 21796element is the string @code{hello!}. 21797 21798In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 21799using Stream_IO, and this is the preferred mechanism. In particular, the 21800above program fragment rewritten to use Stream_IO will work correctly. 21801 21802@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O 21803@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} 21804@section Text_IO 21805 21806 21807Text_IO files consist of a stream of characters containing the following 21808special control characters: 21809 21810@example 21811LF (line feed, 16#0A#) Line Mark 21812FF (form feed, 16#0C#) Page Mark 21813@end example 21814 21815A canonical Text_IO file is defined as one in which the following 21816conditions are met: 21817 21818 21819@itemize * 21820 21821@item 21822The character @code{LF} is used only as a line mark, i.e., to mark the end 21823of the line. 21824 21825@item 21826The character @code{FF} is used only as a page mark, i.e., to mark the 21827end of a page and consequently can appear only immediately following a 21828@code{LF} (line mark) character. 21829 21830@item 21831The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} 21832(line mark, page mark). In the former case, the page mark is implicitly 21833assumed to be present. 21834@end itemize 21835 21836A file written using Text_IO will be in canonical form provided that no 21837explicit @code{LF} or @code{FF} characters are written using @code{Put} 21838or @code{Put_Line}. There will be no @code{FF} character at the end of 21839the file unless an explicit @code{New_Page} operation was performed 21840before closing the file. 21841 21842A canonical Text_IO file that is a regular file (i.e., not a device or a 21843pipe) can be read using any of the routines in Text_IO. The 21844semantics in this case will be exactly as defined in the Ada Reference 21845Manual, and all the routines in Text_IO are fully implemented. 21846 21847A text file that does not meet the requirements for a canonical Text_IO 21848file has one of the following: 21849 21850 21851@itemize * 21852 21853@item 21854The file contains @code{FF} characters not immediately following a 21855@code{LF} character. 21856 21857@item 21858The file contains @code{LF} or @code{FF} characters written by 21859@code{Put} or @code{Put_Line}, which are not logically considered to be 21860line marks or page marks. 21861 21862@item 21863The file ends in a character other than @code{LF} or @code{FF}, 21864i.e., there is no explicit line mark or page mark at the end of the file. 21865@end itemize 21866 21867Text_IO can be used to read such non-standard text files but subprograms 21868to do with line or page numbers do not have defined meanings. In 21869particular, a @code{FF} character that does not follow a @code{LF} 21870character may or may not be treated as a page mark from the point of 21871view of page and line numbering. Every @code{LF} character is considered 21872to end a line, and there is an implied @code{LF} character at the end of 21873the file. 21874 21875@menu 21876* Stream Pointer Positioning:: 21877* Reading and Writing Non-Regular Files:: 21878* Get_Immediate:: 21879* Treating Text_IO Files as Streams:: 21880* Text_IO Extensions:: 21881* Text_IO Facilities for Unbounded Strings:: 21882 21883@end menu 21884 21885@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO 21886@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} 21887@subsection Stream Pointer Positioning 21888 21889 21890@code{Ada.Text_IO} has a definition of current position for a file that 21891is being read. No internal buffering occurs in Text_IO, and usually the 21892physical position in the stream used to implement the file corresponds 21893to this logical position defined by Text_IO. There are two exceptions: 21894 21895 21896@itemize * 21897 21898@item 21899After a call to @code{End_Of_Page} that returns @code{True}, the stream 21900is positioned past the @code{LF} (line mark) that precedes the page 21901mark. Text_IO maintains an internal flag so that subsequent read 21902operations properly handle the logical position which is unchanged by 21903the @code{End_Of_Page} call. 21904 21905@item 21906After a call to @code{End_Of_File} that returns @code{True}, if the 21907Text_IO file was positioned before the line mark at the end of file 21908before the call, then the logical position is unchanged, but the stream 21909is physically positioned right at the end of file (past the line mark, 21910and past a possible page mark following the line mark. Again Text_IO 21911maintains internal flags so that subsequent read operations properly 21912handle the logical position. 21913@end itemize 21914 21915These discrepancies have no effect on the observable behavior of 21916Text_IO, but if a single Ada stream is shared between a C program and 21917Ada program, or shared (using @code{shared=yes} in the form string) 21918between two Ada files, then the difference may be observable in some 21919situations. 21920 21921@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO 21922@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} 21923@subsection Reading and Writing Non-Regular Files 21924 21925 21926A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 21927can be used for reading and writing. Writing is not affected and the 21928sequence of characters output is identical to the normal file case, but 21929for reading, the behavior of Text_IO is modified to avoid undesirable 21930look-ahead as follows: 21931 21932An input file that is not a regular file is considered to have no page 21933marks. Any @code{Ascii.FF} characters (the character normally used for a 21934page mark) appearing in the file are considered to be data 21935characters. In particular: 21936 21937 21938@itemize * 21939 21940@item 21941@code{Get_Line} and @code{Skip_Line} do not test for a page mark 21942following a line mark. If a page mark appears, it will be treated as a 21943data character. 21944 21945@item 21946This avoids the need to wait for an extra character to be typed or 21947entered from the pipe to complete one of these operations. 21948 21949@item 21950@code{End_Of_Page} always returns @code{False} 21951 21952@item 21953@code{End_Of_File} will return @code{False} if there is a page mark at 21954the end of the file. 21955@end itemize 21956 21957Output to non-regular files is the same as for regular files. Page marks 21958may be written to non-regular files using @code{New_Page}, but as noted 21959above they will not be treated as page marks on input if the output is 21960piped to another Ada program. 21961 21962Another important discrepancy when reading non-regular files is that the end 21963of file indication is not ‘sticky’. If an end of file is entered, e.g., by 21964pressing the @code{EOT} key, 21965then end of file 21966is signaled once (i.e., the test @code{End_Of_File} 21967will yield @code{True}, or a read will 21968raise @code{End_Error}), but then reading can resume 21969to read data past that end of 21970file indication, until another end of file indication is entered. 21971 21972@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO 21973@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} 21974@subsection Get_Immediate 21975 21976 21977@geindex Get_Immediate 21978 21979Get_Immediate returns the next character (including control characters) 21980from the input file. In particular, Get_Immediate will return LF or FF 21981characters used as line marks or page marks. Such operations leave the 21982file positioned past the control character, and it is thus not treated 21983as having its normal function. This means that page, line and column 21984counts after this kind of Get_Immediate call are set as though the mark 21985did not occur. In the case where a Get_Immediate leaves the file 21986positioned between the line mark and page mark (which is not normally 21987possible), it is undefined whether the FF character will be treated as a 21988page mark. 21989 21990@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO 21991@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} 21992@subsection Treating Text_IO Files as Streams 21993 21994 21995@geindex Stream files 21996 21997The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated 21998as a stream. Data written to a @code{Text_IO} file in this stream mode is 21999binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 2200016#0C# (@code{FF}), the resulting file may have non-standard 22001format. Similarly if read operations are used to read from a Text_IO 22002file treated as a stream, then @code{LF} and @code{FF} characters may be 22003skipped and the effect is similar to that described above for 22004@code{Get_Immediate}. 22005 22006@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO 22007@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} 22008@subsection Text_IO Extensions 22009 22010 22011@geindex Text_IO extensions 22012 22013A package GNAT.IO_Aux in the GNAT library provides some useful extensions 22014to the standard @code{Text_IO} package: 22015 22016 22017@itemize * 22018 22019@item 22020function File_Exists (Name : String) return Boolean; 22021Determines if a file of the given name exists. 22022 22023@item 22024function Get_Line return String; 22025Reads a string from the standard input file. The value returned is exactly 22026the length of the line that was read. 22027 22028@item 22029function Get_Line (File : Ada.Text_IO.File_Type) return String; 22030Similar, except that the parameter File specifies the file from which 22031the string is to be read. 22032@end itemize 22033 22034@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO 22035@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} 22036@subsection Text_IO Facilities for Unbounded Strings 22037 22038 22039@geindex Text_IO for unbounded strings 22040 22041@geindex Unbounded_String 22042@geindex Text_IO operations 22043 22044The package @code{Ada.Strings.Unbounded.Text_IO} 22045in library files @code{a-suteio.ads/adb} contains some GNAT-specific 22046subprograms useful for Text_IO operations on unbounded strings: 22047 22048 22049@itemize * 22050 22051@item 22052function Get_Line (File : File_Type) return Unbounded_String; 22053Reads a line from the specified file 22054and returns the result as an unbounded string. 22055 22056@item 22057procedure Put (File : File_Type; U : Unbounded_String); 22058Writes the value of the given unbounded string to the specified file 22059Similar to the effect of 22060@code{Put (To_String (U))} except that an extra copy is avoided. 22061 22062@item 22063procedure Put_Line (File : File_Type; U : Unbounded_String); 22064Writes the value of the given unbounded string to the specified file, 22065followed by a @code{New_Line}. 22066Similar to the effect of @code{Put_Line (To_String (U))} except 22067that an extra copy is avoided. 22068@end itemize 22069 22070In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 22071and is optional. If the parameter is omitted, then the standard input or 22072output file is referenced as appropriate. 22073 22074The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 22075files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended 22076@code{Wide_Text_IO} functionality for unbounded wide strings. 22077 22078The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 22079files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended 22080@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 22081 22082@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O 22083@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} 22084@section Wide_Text_IO 22085 22086 22087@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 22088both input and output files may contain special sequences that represent 22089wide character values. The encoding scheme for a given file may be 22090specified using a FORM parameter: 22091 22092@example 22093WCEM=`x` 22094@end example 22095 22096as part of the FORM string (WCEM = wide character encoding method), 22097where @code{x} is one of the following characters 22098 22099 22100@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 22101@headitem 22102 22103Character 22104 22105@tab 22106 22107Encoding 22108 22109@item 22110 22111@emph{h} 22112 22113@tab 22114 22115Hex ESC encoding 22116 22117@item 22118 22119@emph{u} 22120 22121@tab 22122 22123Upper half encoding 22124 22125@item 22126 22127@emph{s} 22128 22129@tab 22130 22131Shift-JIS encoding 22132 22133@item 22134 22135@emph{e} 22136 22137@tab 22138 22139EUC Encoding 22140 22141@item 22142 22143@emph{8} 22144 22145@tab 22146 22147UTF-8 encoding 22148 22149@item 22150 22151@emph{b} 22152 22153@tab 22154 22155Brackets encoding 22156 22157@end multitable 22158 22159 22160The encoding methods match those that 22161can be used in a source 22162program, but there is no requirement that the encoding method used for 22163the source program be the same as the encoding method used for files, 22164and different files may use different encoding methods. 22165 22166The default encoding method for the standard files, and for opened files 22167for which no WCEM parameter is given in the FORM string matches the 22168wide character encoding specified for the main program (the default 22169being brackets encoding if no coding method was specified with -gnatW). 22170 22171 22172@table @asis 22173 22174@item @emph{Hex Coding} 22175 22176In this encoding, a wide character is represented by a five character 22177sequence: 22178@end table 22179 22180@example 22181ESC a b c d 22182@end example 22183 22184 22185@quotation 22186 22187where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 22188characters (using upper case letters) of the wide character code. For 22189example, ESC A345 is used to represent the wide character with code 2219016#A345#. This scheme is compatible with use of the full 22191@code{Wide_Character} set. 22192@end quotation 22193 22194 22195@table @asis 22196 22197@item @emph{Upper Half Coding} 22198 22199The wide character with encoding 16#abcd#, where the upper bit is on 22200(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and 2220116#cd#. The second byte may never be a format control character, but is 22202not required to be in the upper half. This method can be also used for 22203shift-JIS or EUC where the internal coding matches the external coding. 22204 22205@item @emph{Shift JIS Coding} 22206 22207A wide character is represented by a two character sequence 16#ab# and 2220816#cd#, with the restrictions described for upper half encoding as 22209described above. The internal character code is the corresponding JIS 22210character according to the standard algorithm for Shift-JIS 22211conversion. Only characters defined in the JIS code set table can be 22212used with this encoding method. 22213 22214@item @emph{EUC Coding} 22215 22216A wide character is represented by a two character sequence 16#ab# and 2221716#cd#, with both characters being in the upper half. The internal 22218character code is the corresponding JIS character according to the EUC 22219encoding algorithm. Only characters defined in the JIS code set table 22220can be used with this encoding method. 22221 22222@item @emph{UTF-8 Coding} 22223 22224A wide character is represented using 22225UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2222610646-1/Am.2. Depending on the character value, the representation 22227is a one, two, or three byte sequence: 22228@end table 22229 22230@example 2223116#0000#-16#007f#: 2#0xxxxxxx# 2223216#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 2223316#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 22234@end example 22235 22236 22237@quotation 22238 22239where the @code{xxx} bits correspond to the left-padded bits of the 2224016-bit character value. Note that all lower half ASCII characters 22241are represented as ASCII bytes and all upper half characters and 22242other wide characters are represented as sequences of upper-half 22243(The full UTF-8 scheme allows for encoding 31-bit characters as 222446-byte sequences, but in this implementation, all UTF-8 sequences 22245of four or more bytes length will raise a Constraint_Error, as 22246will all invalid UTF-8 sequences.) 22247@end quotation 22248 22249 22250@table @asis 22251 22252@item @emph{Brackets Coding} 22253 22254In this encoding, a wide character is represented by the following eight 22255character sequence: 22256@end table 22257 22258@example 22259[ " a b c d " ] 22260@end example 22261 22262 22263@quotation 22264 22265where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 22266characters (using uppercase letters) of the wide character code. For 22267example, @code{["A345"]} is used to represent the wide character with code 22268@code{16#A345#}. 22269This scheme is compatible with use of the full Wide_Character set. 22270On input, brackets coding can also be used for upper half characters, 22271e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 22272is only used for wide characters with a code greater than @code{16#FF#}. 22273 22274Note that brackets coding is not normally used in the context of 22275Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 22276a portable way of encoding source files. In the context of Wide_Text_IO 22277or Wide_Wide_Text_IO, it can only be used if the file does not contain 22278any instance of the left bracket character other than to encode wide 22279character values using the brackets encoding method. In practice it is 22280expected that some standard wide character encoding method such 22281as UTF-8 will be used for text input output. 22282 22283If brackets notation is used, then any occurrence of a left bracket 22284in the input file which is not the start of a valid wide character 22285sequence will cause Constraint_Error to be raised. It is possible to 22286encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO 22287input will interpret this as a left bracket. 22288 22289However, when a left bracket is output, it will be output as a left bracket 22290and not as [“5B”]. We make this decision because for normal use of 22291Wide_Text_IO for outputting messages, it is unpleasant to clobber left 22292brackets. For example, if we write: 22293 22294@example 22295Put_Line ("Start of output [first run]"); 22296@end example 22297 22298we really do not want to have the left bracket in this message clobbered so 22299that the output reads: 22300@end quotation 22301 22302@example 22303Start of output ["5B"]first run] 22304@end example 22305 22306 22307@quotation 22308 22309In practice brackets encoding is reasonably useful for normal Put_Line use 22310since we won’t get confused between left brackets and wide character 22311sequences in the output. But for input, or when files are written out 22312and read back in, it really makes better sense to use one of the standard 22313encoding methods such as UTF-8. 22314@end quotation 22315 22316For the coding schemes other than UTF-8, Hex, or Brackets encoding, 22317not all wide character 22318values can be represented. An attempt to output a character that cannot 22319be represented using the encoding scheme for the file causes 22320Constraint_Error to be raised. An invalid wide character sequence on 22321input also causes Constraint_Error to be raised. 22322 22323@menu 22324* Stream Pointer Positioning: Stream Pointer Positioning<2>. 22325* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 22326 22327@end menu 22328 22329@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO 22330@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} 22331@subsection Stream Pointer Positioning 22332 22333 22334@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22335of stream pointer positioning (@ref{2ac,,Text_IO}). There is one additional 22336case: 22337 22338If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 22339normal lower ASCII set (i.e., a character in the range: 22340 22341@example 22342Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 22343@end example 22344 22345then although the logical position of the file pointer is unchanged by 22346the @code{Look_Ahead} call, the stream is physically positioned past the 22347wide character sequence. Again this is to avoid the need for buffering 22348or backup, and all @code{Wide_Text_IO} routines check the internal 22349indication that this situation has occurred so that this is not visible 22350to a normal program using @code{Wide_Text_IO}. However, this discrepancy 22351can be observed if the wide text file shares a stream with another file. 22352 22353@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO 22354@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} 22355@subsection Reading and Writing Non-Regular Files 22356 22357 22358As in the case of Text_IO, when a non-regular file is read, it is 22359assumed that the file contains no page marks (any form characters are 22360treated as data characters), and @code{End_Of_Page} always returns 22361@code{False}. Similarly, the end of file indication is not sticky, so 22362it is possible to read beyond an end of file. 22363 22364@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O 22365@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} 22366@section Wide_Wide_Text_IO 22367 22368 22369@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 22370both input and output files may contain special sequences that represent 22371wide wide character values. The encoding scheme for a given file may be 22372specified using a FORM parameter: 22373 22374@example 22375WCEM=`x` 22376@end example 22377 22378as part of the FORM string (WCEM = wide character encoding method), 22379where @code{x} is one of the following characters 22380 22381 22382@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 22383@headitem 22384 22385Character 22386 22387@tab 22388 22389Encoding 22390 22391@item 22392 22393@emph{h} 22394 22395@tab 22396 22397Hex ESC encoding 22398 22399@item 22400 22401@emph{u} 22402 22403@tab 22404 22405Upper half encoding 22406 22407@item 22408 22409@emph{s} 22410 22411@tab 22412 22413Shift-JIS encoding 22414 22415@item 22416 22417@emph{e} 22418 22419@tab 22420 22421EUC Encoding 22422 22423@item 22424 22425@emph{8} 22426 22427@tab 22428 22429UTF-8 encoding 22430 22431@item 22432 22433@emph{b} 22434 22435@tab 22436 22437Brackets encoding 22438 22439@end multitable 22440 22441 22442The encoding methods match those that 22443can be used in a source 22444program, but there is no requirement that the encoding method used for 22445the source program be the same as the encoding method used for files, 22446and different files may use different encoding methods. 22447 22448The default encoding method for the standard files, and for opened files 22449for which no WCEM parameter is given in the FORM string matches the 22450wide character encoding specified for the main program (the default 22451being brackets encoding if no coding method was specified with -gnatW). 22452 22453 22454@table @asis 22455 22456@item @emph{UTF-8 Coding} 22457 22458A wide character is represented using 22459UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2246010646-1/Am.2. Depending on the character value, the representation 22461is a one, two, three, or four byte sequence: 22462@end table 22463 22464@example 2246516#000000#-16#00007f#: 2#0xxxxxxx# 2246616#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 2246716#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 2246816#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# 22469@end example 22470 22471 22472@quotation 22473 22474where the @code{xxx} bits correspond to the left-padded bits of the 2247521-bit character value. Note that all lower half ASCII characters 22476are represented as ASCII bytes and all upper half characters and 22477other wide characters are represented as sequences of upper-half 22478characters. 22479@end quotation 22480 22481 22482@table @asis 22483 22484@item @emph{Brackets Coding} 22485 22486In this encoding, a wide wide character is represented by the following eight 22487character sequence if is in wide character range 22488@end table 22489 22490@example 22491[ " a b c d " ] 22492@end example 22493 22494 22495@quotation 22496 22497and by the following ten character sequence if not 22498@end quotation 22499 22500@example 22501[ " a b c d e f " ] 22502@end example 22503 22504 22505@quotation 22506 22507where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} 22508are the four or six hexadecimal 22509characters (using uppercase letters) of the wide wide character code. For 22510example, @code{["01A345"]} is used to represent the wide wide character 22511with code @code{16#01A345#}. 22512 22513This scheme is compatible with use of the full Wide_Wide_Character set. 22514On input, brackets coding can also be used for upper half characters, 22515e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 22516is only used for wide characters with a code greater than @code{16#FF#}. 22517@end quotation 22518 22519If is also possible to use the other Wide_Character encoding methods, 22520such as Shift-JIS, but the other schemes cannot support the full range 22521of wide wide characters. 22522An attempt to output a character that cannot 22523be represented using the encoding scheme for the file causes 22524Constraint_Error to be raised. An invalid wide character sequence on 22525input also causes Constraint_Error to be raised. 22526 22527@menu 22528* Stream Pointer Positioning: Stream Pointer Positioning<3>. 22529* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 22530 22531@end menu 22532 22533@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO 22534@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} 22535@subsection Stream Pointer Positioning 22536 22537 22538@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22539of stream pointer positioning (@ref{2ac,,Text_IO}). There is one additional 22540case: 22541 22542If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 22543normal lower ASCII set (i.e., a character in the range: 22544 22545@example 22546Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 22547@end example 22548 22549then although the logical position of the file pointer is unchanged by 22550the @code{Look_Ahead} call, the stream is physically positioned past the 22551wide character sequence. Again this is to avoid the need for buffering 22552or backup, and all @code{Wide_Wide_Text_IO} routines check the internal 22553indication that this situation has occurred so that this is not visible 22554to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy 22555can be observed if the wide text file shares a stream with another file. 22556 22557@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO 22558@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} 22559@subsection Reading and Writing Non-Regular Files 22560 22561 22562As in the case of Text_IO, when a non-regular file is read, it is 22563assumed that the file contains no page marks (any form characters are 22564treated as data characters), and @code{End_Of_Page} always returns 22565@code{False}. Similarly, the end of file indication is not sticky, so 22566it is possible to read beyond an end of file. 22567 22568@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O 22569@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} 22570@section Stream_IO 22571 22572 22573A stream file is a sequence of bytes, where individual elements are 22574written to the file as described in the Ada Reference Manual. The type 22575@code{Stream_Element} is simply a byte. There are two ways to read or 22576write a stream file. 22577 22578 22579@itemize * 22580 22581@item 22582The operations @code{Read} and @code{Write} directly read or write a 22583sequence of stream elements with no control information. 22584 22585@item 22586The stream attributes applied to a stream file transfer data in the 22587manner described for stream attributes. 22588@end itemize 22589 22590@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O 22591@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} 22592@section Text Translation 22593 22594 22595@code{Text_Translation=xxx} may be used as the Form parameter 22596passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} 22597has no effect on Unix systems. Possible values are: 22598 22599 22600@itemize * 22601 22602@item 22603@code{Yes} or @code{Text} is the default, which means to 22604translate LF to/from CR/LF on Windows systems. 22605 22606@code{No} disables this translation; i.e. it 22607uses binary mode. For output files, @code{Text_Translation=No} 22608may be used to create Unix-style files on 22609Windows. 22610 22611@item 22612@code{wtext} translation enabled in Unicode mode. 22613(corresponds to _O_WTEXT). 22614 22615@item 22616@code{u8text} translation enabled in Unicode UTF-8 mode. 22617(corresponds to O_U8TEXT). 22618 22619@item 22620@code{u16text} translation enabled in Unicode UTF-16 22621mode. (corresponds to_O_U16TEXT). 22622@end itemize 22623 22624@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O 22625@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} 22626@section Shared Files 22627 22628 22629Section A.14 of the Ada Reference Manual allows implementations to 22630provide a wide variety of behavior if an attempt is made to access the 22631same external file with two or more internal files. 22632 22633To provide a full range of functionality, while at the same time 22634minimizing the problems of portability caused by this implementation 22635dependence, GNAT handles file sharing as follows: 22636 22637 22638@itemize * 22639 22640@item 22641In the absence of a @code{shared=xxx} form parameter, an attempt 22642to open two or more files with the same full name is considered an error 22643and is not supported. The exception @code{Use_Error} will be 22644raised. Note that a file that is not explicitly closed by the program 22645remains open until the program terminates. 22646 22647@item 22648If the form parameter @code{shared=no} appears in the form string, the 22649file can be opened or created with its own separate stream identifier, 22650regardless of whether other files sharing the same external file are 22651opened. The exact effect depends on how the C stream routines handle 22652multiple accesses to the same external files using separate streams. 22653 22654@item 22655If the form parameter @code{shared=yes} appears in the form string for 22656each of two or more files opened using the same full name, the same 22657stream is shared between these files, and the semantics are as described 22658in Ada Reference Manual, Section A.14. 22659@end itemize 22660 22661When a program that opens multiple files with the same name is ported 22662from another Ada compiler to GNAT, the effect will be that 22663@code{Use_Error} is raised. 22664 22665The documentation of the original compiler and the documentation of the 22666program should then be examined to determine if file sharing was 22667expected, and @code{shared=xxx} parameters added to @code{Open} 22668and @code{Create} calls as required. 22669 22670When a program is ported from GNAT to some other Ada compiler, no 22671special attention is required unless the @code{shared=xxx} form 22672parameter is used in the program. In this case, you must examine the 22673documentation of the new compiler to see if it supports the required 22674file sharing semantics, and form strings modified appropriately. Of 22675course it may be the case that the program cannot be ported if the 22676target compiler does not support the required functionality. The best 22677approach in writing portable code is to avoid file sharing (and hence 22678the use of the @code{shared=xxx} parameter in the form string) 22679completely. 22680 22681One common use of file sharing in Ada 83 is the use of instantiations of 22682Sequential_IO on the same file with different types, to achieve 22683heterogeneous input-output. Although this approach will work in GNAT if 22684@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO 22685for this purpose (using the stream attributes) 22686 22687@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O 22688@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} 22689@section Filenames encoding 22690 22691 22692An encoding form parameter can be used to specify the filename 22693encoding @code{encoding=xxx}. 22694 22695 22696@itemize * 22697 22698@item 22699If the form parameter @code{encoding=utf8} appears in the form string, the 22700filename must be encoded in UTF-8. 22701 22702@item 22703If the form parameter @code{encoding=8bits} appears in the form 22704string, the filename must be a standard 8bits string. 22705@end itemize 22706 22707In the absence of a @code{encoding=xxx} form parameter, the 22708encoding is controlled by the @code{GNAT_CODE_PAGE} environment 22709variable. And if not set @code{utf8} is assumed. 22710 22711 22712@table @asis 22713 22714@item @emph{CP_ACP} 22715 22716The current system Windows ANSI code page. 22717 22718@item @emph{CP_UTF8} 22719 22720UTF-8 encoding 22721@end table 22722 22723This encoding form parameter is only supported on the Windows 22724platform. On the other Operating Systems the run-time is supporting 22725UTF-8 natively. 22726 22727@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O 22728@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} 22729@section File content encoding 22730 22731 22732For text files it is possible to specify the encoding to use. This is 22733controlled by the by the @code{GNAT_CCS_ENCODING} environment 22734variable. And if not set @code{TEXT} is assumed. 22735 22736The possible values are those supported on Windows: 22737 22738 22739@table @asis 22740 22741@item @emph{TEXT} 22742 22743Translated text mode 22744 22745@item @emph{WTEXT} 22746 22747Translated unicode encoding 22748 22749@item @emph{U16TEXT} 22750 22751Unicode 16-bit encoding 22752 22753@item @emph{U8TEXT} 22754 22755Unicode 8-bit encoding 22756@end table 22757 22758This encoding is only supported on the Windows platform. 22759 22760@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O 22761@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} 22762@section Open Modes 22763 22764 22765@code{Open} and @code{Create} calls result in a call to @code{fopen} 22766using the mode shown in the following table: 22767 22768 22769@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 22770@headitem 22771 22772@code{Open} and @code{Create} Call Modes 22773 22774@tab 22775 22776@tab 22777 22778@item 22779 22780@tab 22781 22782@strong{OPEN} 22783 22784@tab 22785 22786@strong{CREATE} 22787 22788@item 22789 22790Append_File 22791 22792@tab 22793 22794“r+” 22795 22796@tab 22797 22798“w+” 22799 22800@item 22801 22802In_File 22803 22804@tab 22805 22806“r” 22807 22808@tab 22809 22810“w+” 22811 22812@item 22813 22814Out_File (Direct_IO) 22815 22816@tab 22817 22818“r+” 22819 22820@tab 22821 22822“w” 22823 22824@item 22825 22826Out_File (all other cases) 22827 22828@tab 22829 22830“w” 22831 22832@tab 22833 22834“w” 22835 22836@item 22837 22838Inout_File 22839 22840@tab 22841 22842“r+” 22843 22844@tab 22845 22846“w+” 22847 22848@end multitable 22849 22850 22851If text file translation is required, then either @code{b} or @code{t} 22852is added to the mode, depending on the setting of Text. Text file 22853translation refers to the mapping of CR/LF sequences in an external file 22854to LF characters internally. This mapping only occurs in DOS and 22855DOS-like systems, and is not relevant to other systems. 22856 22857A special case occurs with Stream_IO. As shown in the above table, the 22858file is initially opened in @code{r} or @code{w} mode for the 22859@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 22860subsequently requires switching from reading to writing or vice-versa, 22861then the file is reopened in @code{r+} mode to permit the required operation. 22862 22863@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O 22864@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} 22865@section Operations on C Streams 22866 22867 22868The package @code{Interfaces.C_Streams} provides an Ada program with direct 22869access to the C library functions for operations on C streams: 22870 22871@example 22872package Interfaces.C_Streams is 22873 -- Note: the reason we do not use the types that are in 22874 -- Interfaces.C is that we want to avoid dragging in the 22875 -- code in this unit if possible. 22876 subtype chars is System.Address; 22877 -- Pointer to null-terminated array of characters 22878 subtype FILEs is System.Address; 22879 -- Corresponds to the C type FILE* 22880 subtype voids is System.Address; 22881 -- Corresponds to the C type void* 22882 subtype int is Integer; 22883 subtype long is Long_Integer; 22884 -- Note: the above types are subtypes deliberately, and it 22885 -- is part of this spec that the above correspondences are 22886 -- guaranteed. This means that it is legitimate to, for 22887 -- example, use Integer instead of int. We provide these 22888 -- synonyms for clarity, but in some cases it may be 22889 -- convenient to use the underlying types (for example to 22890 -- avoid an unnecessary dependency of a spec on the spec 22891 -- of this unit). 22892 type size_t is mod 2 ** Standard'Address_Size; 22893 NULL_Stream : constant FILEs; 22894 -- Value returned (NULL in C) to indicate an 22895 -- fdopen/fopen/tmpfile error 22896 ---------------------------------- 22897 -- Constants Defined in stdio.h -- 22898 ---------------------------------- 22899 EOF : constant int; 22900 -- Used by a number of routines to indicate error or 22901 -- end of file 22902 IOFBF : constant int; 22903 IOLBF : constant int; 22904 IONBF : constant int; 22905 -- Used to indicate buffering mode for setvbuf call 22906 SEEK_CUR : constant int; 22907 SEEK_END : constant int; 22908 SEEK_SET : constant int; 22909 -- Used to indicate origin for fseek call 22910 function stdin return FILEs; 22911 function stdout return FILEs; 22912 function stderr return FILEs; 22913 -- Streams associated with standard files 22914 -------------------------- 22915 -- Standard C functions -- 22916 -------------------------- 22917 -- The functions selected below are ones that are 22918 -- available in UNIX (but not necessarily in ANSI C). 22919 -- These are very thin interfaces 22920 -- which copy exactly the C headers. For more 22921 -- documentation on these functions, see the Microsoft C 22922 -- "Run-Time Library Reference" (Microsoft Press, 1990, 22923 -- ISBN 1-55615-225-6), which includes useful information 22924 -- on system compatibility. 22925 procedure clearerr (stream : FILEs); 22926 function fclose (stream : FILEs) return int; 22927 function fdopen (handle : int; mode : chars) return FILEs; 22928 function feof (stream : FILEs) return int; 22929 function ferror (stream : FILEs) return int; 22930 function fflush (stream : FILEs) return int; 22931 function fgetc (stream : FILEs) return int; 22932 function fgets (strng : chars; n : int; stream : FILEs) 22933 return chars; 22934 function fileno (stream : FILEs) return int; 22935 function fopen (filename : chars; Mode : chars) 22936 return FILEs; 22937 -- Note: to maintain target independence, use 22938 -- text_translation_required, a boolean variable defined in 22939 -- a-sysdep.c to deal with the target dependent text 22940 -- translation requirement. If this variable is set, 22941 -- then b/t should be appended to the standard mode 22942 -- argument to set the text translation mode off or on 22943 -- as required. 22944 function fputc (C : int; stream : FILEs) return int; 22945 function fputs (Strng : chars; Stream : FILEs) return int; 22946 function fread 22947 (buffer : voids; 22948 size : size_t; 22949 count : size_t; 22950 stream : FILEs) 22951 return size_t; 22952 function freopen 22953 (filename : chars; 22954 mode : chars; 22955 stream : FILEs) 22956 return FILEs; 22957 function fseek 22958 (stream : FILEs; 22959 offset : long; 22960 origin : int) 22961 return int; 22962 function ftell (stream : FILEs) return long; 22963 function fwrite 22964 (buffer : voids; 22965 size : size_t; 22966 count : size_t; 22967 stream : FILEs) 22968 return size_t; 22969 function isatty (handle : int) return int; 22970 procedure mktemp (template : chars); 22971 -- The return value (which is just a pointer to template) 22972 -- is discarded 22973 procedure rewind (stream : FILEs); 22974 function rmtmp return int; 22975 function setvbuf 22976 (stream : FILEs; 22977 buffer : chars; 22978 mode : int; 22979 size : size_t) 22980 return int; 22981 22982 function tmpfile return FILEs; 22983 function ungetc (c : int; stream : FILEs) return int; 22984 function unlink (filename : chars) return int; 22985 --------------------- 22986 -- Extra functions -- 22987 --------------------- 22988 -- These functions supply slightly thicker bindings than 22989 -- those above. They are derived from functions in the 22990 -- C Run-Time Library, but may do a bit more work than 22991 -- just directly calling one of the Library functions. 22992 function is_regular_file (handle : int) return int; 22993 -- Tests if given handle is for a regular file (result 1) 22994 -- or for a non-regular file (pipe or device, result 0). 22995 --------------------------------- 22996 -- Control of Text/Binary Mode -- 22997 --------------------------------- 22998 -- If text_translation_required is true, then the following 22999 -- functions may be used to dynamically switch a file from 23000 -- binary to text mode or vice versa. These functions have 23001 -- no effect if text_translation_required is false (i.e., in 23002 -- normal UNIX mode). Use fileno to get a stream handle. 23003 procedure set_binary_mode (handle : int); 23004 procedure set_text_mode (handle : int); 23005 ---------------------------- 23006 -- Full Path Name support -- 23007 ---------------------------- 23008 procedure full_name (nam : chars; buffer : chars); 23009 -- Given a NUL terminated string representing a file 23010 -- name, returns in buffer a NUL terminated string 23011 -- representing the full path name for the file name. 23012 -- On systems where it is relevant the drive is also 23013 -- part of the full path name. It is the responsibility 23014 -- of the caller to pass an actual parameter for buffer 23015 -- that is big enough for any full path name. Use 23016 -- max_path_len given below as the size of buffer. 23017 max_path_len : integer; 23018 -- Maximum length of an allowable full path name on the 23019 -- system, including a terminating NUL character. 23020end Interfaces.C_Streams; 23021@end example 23022 23023@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O 23024@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} 23025@section Interfacing to C Streams 23026 23027 23028The packages in this section permit interfacing Ada files to C Stream 23029operations. 23030 23031@example 23032with Interfaces.C_Streams; 23033package Ada.Sequential_IO.C_Streams is 23034 function C_Stream (F : File_Type) 23035 return Interfaces.C_Streams.FILEs; 23036 procedure Open 23037 (File : in out File_Type; 23038 Mode : in File_Mode; 23039 C_Stream : in Interfaces.C_Streams.FILEs; 23040 Form : in String := ""); 23041end Ada.Sequential_IO.C_Streams; 23042 23043 with Interfaces.C_Streams; 23044 package Ada.Direct_IO.C_Streams is 23045 function C_Stream (F : File_Type) 23046 return Interfaces.C_Streams.FILEs; 23047 procedure Open 23048 (File : in out File_Type; 23049 Mode : in File_Mode; 23050 C_Stream : in Interfaces.C_Streams.FILEs; 23051 Form : in String := ""); 23052 end Ada.Direct_IO.C_Streams; 23053 23054 with Interfaces.C_Streams; 23055 package Ada.Text_IO.C_Streams is 23056 function C_Stream (F : File_Type) 23057 return Interfaces.C_Streams.FILEs; 23058 procedure Open 23059 (File : in out File_Type; 23060 Mode : in File_Mode; 23061 C_Stream : in Interfaces.C_Streams.FILEs; 23062 Form : in String := ""); 23063 end Ada.Text_IO.C_Streams; 23064 23065 with Interfaces.C_Streams; 23066 package Ada.Wide_Text_IO.C_Streams is 23067 function C_Stream (F : File_Type) 23068 return Interfaces.C_Streams.FILEs; 23069 procedure Open 23070 (File : in out File_Type; 23071 Mode : in File_Mode; 23072 C_Stream : in Interfaces.C_Streams.FILEs; 23073 Form : in String := ""); 23074end Ada.Wide_Text_IO.C_Streams; 23075 23076 with Interfaces.C_Streams; 23077 package Ada.Wide_Wide_Text_IO.C_Streams is 23078 function C_Stream (F : File_Type) 23079 return Interfaces.C_Streams.FILEs; 23080 procedure Open 23081 (File : in out File_Type; 23082 Mode : in File_Mode; 23083 C_Stream : in Interfaces.C_Streams.FILEs; 23084 Form : in String := ""); 23085end Ada.Wide_Wide_Text_IO.C_Streams; 23086 23087with Interfaces.C_Streams; 23088package Ada.Stream_IO.C_Streams is 23089 function C_Stream (F : File_Type) 23090 return Interfaces.C_Streams.FILEs; 23091 procedure Open 23092 (File : in out File_Type; 23093 Mode : in File_Mode; 23094 C_Stream : in Interfaces.C_Streams.FILEs; 23095 Form : in String := ""); 23096end Ada.Stream_IO.C_Streams; 23097@end example 23098 23099In each of these six packages, the @code{C_Stream} function obtains the 23100@code{FILE} pointer from a currently opened Ada file. It is then 23101possible to use the @code{Interfaces.C_Streams} package to operate on 23102this stream, or the stream can be passed to a C program which can 23103operate on it directly. Of course the program is responsible for 23104ensuring that only appropriate sequences of operations are executed. 23105 23106One particular use of relevance to an Ada program is that the 23107@code{setvbuf} function can be used to control the buffering of the 23108stream used by an Ada file. In the absence of such a call the standard 23109default buffering is used. 23110 23111The @code{Open} procedures in these packages open a file giving an 23112existing C Stream instead of a file name. Typically this stream is 23113imported from a C program, allowing an Ada file to operate on an 23114existing C file. 23115 23116@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top 23117@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} 23118@chapter The GNAT Library 23119 23120 23121The GNAT library contains a number of general and special purpose packages. 23122It represents functionality that the GNAT developers have found useful, and 23123which is made available to GNAT users. The packages described here are fully 23124supported, and upwards compatibility will be maintained in future releases, 23125so you can use these facilities with the confidence that the same functionality 23126will be available in future releases. 23127 23128The chapter here simply gives a brief summary of the facilities available. 23129The full documentation is found in the spec file for the package. The full 23130sources of these library packages, including both spec and body, are provided 23131with all GNAT releases. For example, to find out the full specifications of 23132the SPITBOL pattern matching capability, including a full tutorial and 23133extensive examples, look in the @code{g-spipat.ads} file in the library. 23134 23135For each entry here, the package name (as it would appear in a @code{with} 23136clause) is given, followed by the name of the corresponding spec file in 23137parentheses. The packages are children in four hierarchies, @code{Ada}, 23138@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 23139GNAT-specific hierarchy. 23140 23141Note that an application program should only use packages in one of these 23142four hierarchies if the package is defined in the Ada Reference Manual, 23143or is listed in this section of the GNAT Programmers Reference Manual. 23144All other units should be considered internal implementation units and 23145should not be directly @code{with}ed by application code. The use of 23146a @code{with} clause that references one of these internal implementation 23147units makes an application potentially dependent on changes in versions 23148of GNAT, and will generate a warning message. 23149 23150@menu 23151* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 23152* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 23153* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 23154* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 23155* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 23156* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 23157* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 23158* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 23159* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 23160* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 23161* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 23162* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 23163* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 23164* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 23165* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 23166* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 23167* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 23168* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 23169* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 23170* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 23171* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 23172* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 23173* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 23174* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 23175* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 23176* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 23177* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 23178* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 23179* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. 23180* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 23181* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 23182* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 23183* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 23184* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 23185* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 23186* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 23187* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 23188* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 23189* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 23190* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 23191* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 23192* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 23193* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 23194* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 23195* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 23196* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 23197* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 23198* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 23199* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 23200* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 23201* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 23202* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 23203* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 23204* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 23205* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 23206* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 23207* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 23208* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 23209* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 23210* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 23211* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 23212* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 23213* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 23214* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 23215* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 23216* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 23217* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 23218* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 23219* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 23220* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 23221* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 23222* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 23223* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 23224* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 23225* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 23226* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 23227* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 23228* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 23229* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 23230* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 23231* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 23232* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 23233* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 23234* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 23235* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 23236* GNAT.IO (g-io.ads): GNAT IO g-io ads. 23237* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 23238* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 23239* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 23240* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 23241* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 23242* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 23243* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 23244* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 23245* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 23246* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 23247* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 23248* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 23249* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 23250* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 23251* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 23252* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 23253* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 23254* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 23255* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 23256* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 23257* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 23258* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 23259* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 23260* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 23261* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 23262* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 23263* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 23264* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 23265* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 23266* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 23267* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 23268* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 23269* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 23270* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 23271* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 23272* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 23273* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 23274* GNAT.Table (g-table.ads): GNAT Table g-table ads. 23275* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 23276* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 23277* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 23278* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 23279* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 23280* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 23281* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 23282* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 23283* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 23284* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 23285* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 23286* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 23287* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 23288* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 23289* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 23290* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 23291* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 23292* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 23293* System.Assertions (s-assert.ads): System Assertions s-assert ads. 23294* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 23295* System.Memory (s-memory.ads): System Memory s-memory ads. 23296* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 23297* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 23298* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 23299* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 23300* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 23301* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 23302* System.Rident (s-rident.ads): System Rident s-rident ads. 23303* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 23304* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 23305* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 23306* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 23307 23308@end menu 23309 23310@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library 23311@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id2}@anchor{2d8} 23312@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) 23313 23314 23315@geindex Ada.Characters.Latin_9 (a-chlat9.ads) 23316 23317@geindex Latin_9 constants for Character 23318 23319This child of @code{Ada.Characters} 23320provides a set of definitions corresponding to those in the 23321RM-defined package @code{Ada.Characters.Latin_1} but with the 23322few modifications required for @code{Latin-9} 23323The provision of such a package 23324is specifically authorized by the Ada Reference Manual 23325(RM A.3.3(27)). 23326 23327@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 23328@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} 23329@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) 23330 23331 23332@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 23333 23334@geindex Latin_1 constants for Wide_Character 23335 23336This child of @code{Ada.Characters} 23337provides a set of definitions corresponding to those in the 23338RM-defined package @code{Ada.Characters.Latin_1} but with the 23339types of the constants being @code{Wide_Character} 23340instead of @code{Character}. The provision of such a package 23341is specifically authorized by the Ada Reference Manual 23342(RM A.3.3(27)). 23343 23344@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 23345@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} 23346@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) 23347 23348 23349@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) 23350 23351@geindex Latin_9 constants for Wide_Character 23352 23353This child of @code{Ada.Characters} 23354provides a set of definitions corresponding to those in the 23355GNAT defined package @code{Ada.Characters.Latin_9} but with the 23356types of the constants being @code{Wide_Character} 23357instead of @code{Character}. The provision of such a package 23358is specifically authorized by the Ada Reference Manual 23359(RM A.3.3(27)). 23360 23361@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 23362@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} 23363@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) 23364 23365 23366@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 23367 23368@geindex Latin_1 constants for Wide_Wide_Character 23369 23370This child of @code{Ada.Characters} 23371provides a set of definitions corresponding to those in the 23372RM-defined package @code{Ada.Characters.Latin_1} but with the 23373types of the constants being @code{Wide_Wide_Character} 23374instead of @code{Character}. The provision of such a package 23375is specifically authorized by the Ada Reference Manual 23376(RM A.3.3(27)). 23377 23378@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 23379@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} 23380@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) 23381 23382 23383@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 23384 23385@geindex Latin_9 constants for Wide_Wide_Character 23386 23387This child of @code{Ada.Characters} 23388provides a set of definitions corresponding to those in the 23389GNAT defined package @code{Ada.Characters.Latin_9} but with the 23390types of the constants being @code{Wide_Wide_Character} 23391instead of @code{Character}. The provision of such a package 23392is specifically authorized by the Ada Reference Manual 23393(RM A.3.3(27)). 23394 23395@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 23396@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} 23397@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads}) 23398 23399 23400@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 23401 23402@geindex Formal container for doubly linked lists 23403 23404This child of @code{Ada.Containers} defines a modified version of the 23405Ada 2005 container for doubly linked lists, meant to facilitate formal 23406verification of code using such containers. The specification of this 23407unit is compatible with SPARK 2014. 23408 23409Note that although this container was designed with formal verification 23410in mind, it may well be generally useful in that it is a simplified more 23411efficient version than the one defined in the standard. In particular it 23412does not have the complex overhead required to detect cursor tampering. 23413 23414@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 23415@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} 23416@section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads}) 23417 23418 23419@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 23420 23421@geindex Formal container for hashed maps 23422 23423This child of @code{Ada.Containers} defines a modified version of the 23424Ada 2005 container for hashed maps, meant to facilitate formal 23425verification of code using such containers. The specification of this 23426unit is compatible with SPARK 2014. 23427 23428Note that although this container was designed with formal verification 23429in mind, it may well be generally useful in that it is a simplified more 23430efficient version than the one defined in the standard. In particular it 23431does not have the complex overhead required to detect cursor tampering. 23432 23433@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 23434@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} 23435@section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads}) 23436 23437 23438@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 23439 23440@geindex Formal container for hashed sets 23441 23442This child of @code{Ada.Containers} defines a modified version of the 23443Ada 2005 container for hashed sets, meant to facilitate formal 23444verification of code using such containers. The specification of this 23445unit is compatible with SPARK 2014. 23446 23447Note that although this container was designed with formal verification 23448in mind, it may well be generally useful in that it is a simplified more 23449efficient version than the one defined in the standard. In particular it 23450does not have the complex overhead required to detect cursor tampering. 23451 23452@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 23453@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} 23454@section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads}) 23455 23456 23457@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 23458 23459@geindex Formal container for ordered maps 23460 23461This child of @code{Ada.Containers} defines a modified version of the 23462Ada 2005 container for ordered maps, meant to facilitate formal 23463verification of code using such containers. The specification of this 23464unit is compatible with SPARK 2014. 23465 23466Note that although this container was designed with formal verification 23467in mind, it may well be generally useful in that it is a simplified more 23468efficient version than the one defined in the standard. In particular it 23469does not have the complex overhead required to detect cursor tampering. 23470 23471@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 23472@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} 23473@section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads}) 23474 23475 23476@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 23477 23478@geindex Formal container for ordered sets 23479 23480This child of @code{Ada.Containers} defines a modified version of the 23481Ada 2005 container for ordered sets, meant to facilitate formal 23482verification of code using such containers. The specification of this 23483unit is compatible with SPARK 2014. 23484 23485Note that although this container was designed with formal verification 23486in mind, it may well be generally useful in that it is a simplified more 23487efficient version than the one defined in the standard. In particular it 23488does not have the complex overhead required to detect cursor tampering. 23489 23490@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 23491@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id12}@anchor{2ec} 23492@section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads}) 23493 23494 23495@geindex Ada.Containers.Formal_Vectors (a-cofove.ads) 23496 23497@geindex Formal container for vectors 23498 23499This child of @code{Ada.Containers} defines a modified version of the 23500Ada 2005 container for vectors, meant to facilitate formal 23501verification of code using such containers. The specification of this 23502unit is compatible with SPARK 2014. 23503 23504Note that although this container was designed with formal verification 23505in mind, it may well be generally useful in that it is a simplified more 23506efficient version than the one defined in the standard. In particular it 23507does not have the complex overhead required to detect cursor tampering. 23508 23509@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 23510@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} 23511@section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads}) 23512 23513 23514@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) 23515 23516@geindex Formal container for vectors 23517 23518This child of @code{Ada.Containers} defines a modified version of the 23519Ada 2005 container for vectors of indefinite elements, meant to 23520facilitate formal verification of code using such containers. The 23521specification of this unit is compatible with SPARK 2014. 23522 23523Note that although this container was designed with formal verification 23524in mind, it may well be generally useful in that it is a simplified more 23525efficient version than the one defined in the standard. In particular it 23526does not have the complex overhead required to detect cursor tampering. 23527 23528@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 23529@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f0} 23530@section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads}) 23531 23532 23533@geindex Ada.Containers.Functional_Vectors (a-cofuve.ads) 23534 23535@geindex Functional vectors 23536 23537This child of @code{Ada.Containers} defines immutable vectors. These 23538containers are unbounded and may contain indefinite elements. Furthermore, to 23539be usable in every context, they are neither controlled nor limited. As they 23540are functional, that is, no primitives are provided which would allow modifying 23541an existing container, these containers can still be used safely. 23542 23543Their API features functions creating new containers from existing ones. 23544As a consequence, these containers are highly inefficient. They are also 23545memory consuming, as the allocated memory is not reclaimed when the container 23546is no longer referenced. Thus, they should in general be used in ghost code 23547and annotations, so that they can be removed from the final executable. The 23548specification of this unit is compatible with SPARK 2014. 23549 23550@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 23551@anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f2} 23552@section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads}) 23553 23554 23555@geindex Ada.Containers.Functional_Sets (a-cofuse.ads) 23556 23557@geindex Functional sets 23558 23559This child of @code{Ada.Containers} defines immutable sets. These containers are 23560unbounded and may contain indefinite elements. Furthermore, to be usable in 23561every context, they are neither controlled nor limited. As they are functional, 23562that is, no primitives are provided which would allow modifying an existing 23563container, these containers can still be used safely. 23564 23565Their API features functions creating new containers from existing ones. 23566As a consequence, these containers are highly inefficient. They are also 23567memory consuming, as the allocated memory is not reclaimed when the container 23568is no longer referenced. Thus, they should in general be used in ghost code 23569and annotations, so that they can be removed from the final executable. The 23570specification of this unit is compatible with SPARK 2014. 23571 23572@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 23573@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id16}@anchor{2f4} 23574@section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads}) 23575 23576 23577@geindex Ada.Containers.Functional_Maps (a-cofuma.ads) 23578 23579@geindex Functional maps 23580 23581This child of @code{Ada.Containers} defines immutable maps. These containers are 23582unbounded and may contain indefinite elements. Furthermore, to be usable in 23583every context, they are neither controlled nor limited. As they are functional, 23584that is, no primitives are provided which would allow modifying an existing 23585container, these containers can still be used safely. 23586 23587Their API features functions creating new containers from existing ones. 23588As a consequence, these containers are highly inefficient. They are also 23589memory consuming, as the allocated memory is not reclaimed when the container 23590is no longer referenced. Thus, they should in general be used in ghost code 23591and annotations, so that they can be removed from the final executable. The 23592specification of this unit is compatible with SPARK 2014. 23593 23594@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 23595@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f6} 23596@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) 23597 23598 23599@geindex Ada.Containers.Bounded_Holders (a-coboho.ads) 23600 23601@geindex Formal container for vectors 23602 23603This child of @code{Ada.Containers} defines a modified version of 23604Indefinite_Holders that avoids heap allocation. 23605 23606@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 23607@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f8} 23608@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) 23609 23610 23611@geindex Ada.Command_Line.Environment (a-colien.ads) 23612 23613@geindex Environment entries 23614 23615This child of @code{Ada.Command_Line} 23616provides a mechanism for obtaining environment values on systems 23617where this concept makes sense. 23618 23619@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 23620@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id19}@anchor{2fa} 23621@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) 23622 23623 23624@geindex Ada.Command_Line.Remove (a-colire.ads) 23625 23626@geindex Removing command line arguments 23627 23628@geindex Command line 23629@geindex argument removal 23630 23631This child of @code{Ada.Command_Line} 23632provides a mechanism for logically removing 23633arguments from the argument list. Once removed, an argument is not visible 23634to further calls on the subprograms in @code{Ada.Command_Line} will not 23635see the removed argument. 23636 23637@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 23638@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} 23639@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) 23640 23641 23642@geindex Ada.Command_Line.Response_File (a-clrefi.ads) 23643 23644@geindex Response file for command line 23645 23646@geindex Command line 23647@geindex response file 23648 23649@geindex Command line 23650@geindex handling long command lines 23651 23652This child of @code{Ada.Command_Line} provides a mechanism facilities for 23653getting command line arguments from a text file, called a “response file”. 23654Using a response file allow passing a set of arguments to an executable longer 23655than the maximum allowed by the system on the command line. 23656 23657@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 23658@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} 23659@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) 23660 23661 23662@geindex Ada.Direct_IO.C_Streams (a-diocst.ads) 23663 23664@geindex C Streams 23665@geindex Interfacing with Direct_IO 23666 23667This package provides subprograms that allow interfacing between 23668C streams and @code{Direct_IO}. The stream identifier can be 23669extracted from a file opened on the Ada side, and an Ada file 23670can be constructed from a stream opened on the C side. 23671 23672@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 23673@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} 23674@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) 23675 23676 23677@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 23678 23679@geindex Null_Occurrence 23680@geindex testing for 23681 23682This child subprogram provides a way of testing for the null 23683exception occurrence (@code{Null_Occurrence}) without raising 23684an exception. 23685 23686@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 23687@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} 23688@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) 23689 23690 23691@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 23692 23693@geindex Null_Occurrence 23694@geindex testing for 23695 23696This child subprogram is used for handling otherwise unhandled 23697exceptions (hence the name last chance), and perform clean ups before 23698terminating the program. Note that this subprogram never returns. 23699 23700@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 23701@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id24}@anchor{304} 23702@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) 23703 23704 23705@geindex Ada.Exceptions.Traceback (a-exctra.ads) 23706 23707@geindex Traceback for Exception Occurrence 23708 23709This child package provides the subprogram (@code{Tracebacks}) to 23710give a traceback array of addresses based on an exception 23711occurrence. 23712 23713@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 23714@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} 23715@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) 23716 23717 23718@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) 23719 23720@geindex C Streams 23721@geindex Interfacing with Sequential_IO 23722 23723This package provides subprograms that allow interfacing between 23724C streams and @code{Sequential_IO}. The stream identifier can be 23725extracted from a file opened on the Ada side, and an Ada file 23726can be constructed from a stream opened on the C side. 23727 23728@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 23729@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} 23730@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) 23731 23732 23733@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 23734 23735@geindex C Streams 23736@geindex Interfacing with Stream_IO 23737 23738This package provides subprograms that allow interfacing between 23739C streams and @code{Stream_IO}. The stream identifier can be 23740extracted from a file opened on the Ada side, and an Ada file 23741can be constructed from a stream opened on the C side. 23742 23743@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 23744@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} 23745@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) 23746 23747 23748@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 23749 23750@geindex Unbounded_String 23751@geindex IO support 23752 23753@geindex Text_IO 23754@geindex extensions for unbounded strings 23755 23756This package provides subprograms for Text_IO for unbounded 23757strings, avoiding the necessity for an intermediate operation 23758with ordinary strings. 23759 23760@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 23761@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} 23762@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) 23763 23764 23765@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 23766 23767@geindex Unbounded_Wide_String 23768@geindex IO support 23769 23770@geindex Text_IO 23771@geindex extensions for unbounded wide strings 23772 23773This package provides subprograms for Text_IO for unbounded 23774wide strings, avoiding the necessity for an intermediate operation 23775with ordinary wide strings. 23776 23777@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 23778@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} 23779@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) 23780 23781 23782@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 23783 23784@geindex Unbounded_Wide_Wide_String 23785@geindex IO support 23786 23787@geindex Text_IO 23788@geindex extensions for unbounded wide wide strings 23789 23790This package provides subprograms for Text_IO for unbounded 23791wide wide strings, avoiding the necessity for an intermediate operation 23792with ordinary wide wide strings. 23793 23794@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 23795@anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id30}@anchor{310} 23796@section @code{Ada.Task_Initialization} (@code{a-tasini.ads}) 23797 23798 23799@geindex Ada.Task_Initialization (a-tasini.ads) 23800 23801This package provides a way to set a global initialization handler that 23802is automatically invoked whenever a task is activated. Handlers are 23803parameterless procedures. Note that such a handler is only invoked for 23804those tasks activated after the handler is set. 23805 23806@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 23807@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} 23808@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) 23809 23810 23811@geindex Ada.Text_IO.C_Streams (a-tiocst.ads) 23812 23813@geindex C Streams 23814@geindex Interfacing with `@w{`}Text_IO`@w{`} 23815 23816This package provides subprograms that allow interfacing between 23817C streams and @code{Text_IO}. The stream identifier can be 23818extracted from a file opened on the Ada side, and an Ada file 23819can be constructed from a stream opened on the C side. 23820 23821@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 23822@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} 23823@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) 23824 23825 23826@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 23827 23828@geindex Text_IO resetting standard files 23829 23830This procedure is used to reset the status of the standard files used 23831by Ada.Text_IO. This is useful in a situation (such as a restart in an 23832embedded application) where the status of the files may change during 23833execution (for example a standard input file may be redefined to be 23834interactive). 23835 23836@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 23837@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id33}@anchor{316} 23838@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) 23839 23840 23841@geindex Ada.Wide_Characters.Unicode (a-wichun.ads) 23842 23843@geindex Unicode categorization 23844@geindex Wide_Character 23845 23846This package provides subprograms that allow categorization of 23847Wide_Character values according to Unicode categories. 23848 23849@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 23850@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} 23851@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) 23852 23853 23854@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 23855 23856@geindex C Streams 23857@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} 23858 23859This package provides subprograms that allow interfacing between 23860C streams and @code{Wide_Text_IO}. The stream identifier can be 23861extracted from a file opened on the Ada side, and an Ada file 23862can be constructed from a stream opened on the C side. 23863 23864@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 23865@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} 23866@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) 23867 23868 23869@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 23870 23871@geindex Wide_Text_IO resetting standard files 23872 23873This procedure is used to reset the status of the standard files used 23874by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 23875embedded application) where the status of the files may change during 23876execution (for example a standard input file may be redefined to be 23877interactive). 23878 23879@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 23880@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} 23881@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) 23882 23883 23884@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 23885 23886@geindex Unicode categorization 23887@geindex Wide_Wide_Character 23888 23889This package provides subprograms that allow categorization of 23890Wide_Wide_Character values according to Unicode categories. 23891 23892@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 23893@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} 23894@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) 23895 23896 23897@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 23898 23899@geindex C Streams 23900@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} 23901 23902This package provides subprograms that allow interfacing between 23903C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be 23904extracted from a file opened on the Ada side, and an Ada file 23905can be constructed from a stream opened on the C side. 23906 23907@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 23908@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} 23909@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) 23910 23911 23912@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 23913 23914@geindex Wide_Wide_Text_IO resetting standard files 23915 23916This procedure is used to reset the status of the standard files used 23917by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 23918restart in an embedded application) where the status of the files may 23919change during execution (for example a standard input file may be 23920redefined to be interactive). 23921 23922@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 23923@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id39}@anchor{322} 23924@section @code{GNAT.Altivec} (@code{g-altive.ads}) 23925 23926 23927@geindex GNAT.Altivec (g-altive.ads) 23928 23929@geindex AltiVec 23930 23931This is the root package of the GNAT AltiVec binding. It provides 23932definitions of constants and types common to all the versions of the 23933binding. 23934 23935@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library 23936@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id40}@anchor{324} 23937@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) 23938 23939 23940@geindex GNAT.Altivec.Conversions (g-altcon.ads) 23941 23942@geindex AltiVec 23943 23944This package provides the Vector/View conversion routines. 23945 23946@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library 23947@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id41}@anchor{326} 23948@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) 23949 23950 23951@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) 23952 23953@geindex AltiVec 23954 23955This package exposes the Ada interface to the AltiVec operations on 23956vector objects. A soft emulation is included by default in the GNAT 23957library. The hard binding is provided as a separate package. This unit 23958is common to both bindings. 23959 23960@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 23961@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id42}@anchor{328} 23962@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) 23963 23964 23965@geindex GNAT.Altivec.Vector_Types (g-alvety.ads) 23966 23967@geindex AltiVec 23968 23969This package exposes the various vector types part of the Ada binding 23970to AltiVec facilities. 23971 23972@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library 23973@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id43}@anchor{32a} 23974@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) 23975 23976 23977@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) 23978 23979@geindex AltiVec 23980 23981This package provides public ‘View’ data types from/to which private 23982vector representations can be converted via 23983GNAT.Altivec.Conversions. This allows convenient access to individual 23984vector elements and provides a simple way to initialize vector 23985objects. 23986 23987@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library 23988@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id44}@anchor{32c} 23989@section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) 23990 23991 23992@geindex GNAT.Array_Split (g-arrspl.ads) 23993 23994@geindex Array splitter 23995 23996Useful array-manipulation routines: given a set of separators, split 23997an array wherever the separators appear, and provide direct access 23998to the resulting slices. 23999 24000@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library 24001@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id45}@anchor{32e} 24002@section @code{GNAT.AWK} (@code{g-awk.ads}) 24003 24004 24005@geindex GNAT.AWK (g-awk.ads) 24006 24007@geindex Parsing 24008 24009@geindex AWK 24010 24011Provides AWK-like parsing functions, with an easy interface for parsing one 24012or more files containing formatted data. The file is viewed as a database 24013where each record is a line and a field is a data element in this line. 24014 24015@node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT AWK g-awk ads,The GNAT Library 24016@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id46}@anchor{330} 24017@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) 24018 24019 24020@geindex GNAT.Bind_Environment (g-binenv.ads) 24021 24022@geindex Bind environment 24023 24024Provides access to key=value associations captured at bind time. 24025These associations can be specified using the @code{-V} binder command 24026line switch. 24027 24028@node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library 24029@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id47}@anchor{332} 24030@section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) 24031 24032 24033@geindex GNAT.Branch_Prediction (g-brapre.ads) 24034 24035@geindex Branch Prediction 24036 24037Provides routines giving hints to the branch predictor of the code generator. 24038 24039@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library 24040@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id48}@anchor{334} 24041@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) 24042 24043 24044@geindex GNAT.Bounded_Buffers (g-boubuf.ads) 24045 24046@geindex Parsing 24047 24048@geindex Bounded Buffers 24049 24050Provides a concurrent generic bounded buffer abstraction. Instances are 24051useful directly or as parts of the implementations of other abstractions, 24052such as mailboxes. 24053 24054@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library 24055@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id49}@anchor{336} 24056@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) 24057 24058 24059@geindex GNAT.Bounded_Mailboxes (g-boumai.ads) 24060 24061@geindex Parsing 24062 24063@geindex Mailboxes 24064 24065Provides a thread-safe asynchronous intertask mailbox communication facility. 24066 24067@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library 24068@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id50}@anchor{338} 24069@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) 24070 24071 24072@geindex GNAT.Bubble_Sort (g-bubsor.ads) 24073 24074@geindex Sorting 24075 24076@geindex Bubble sort 24077 24078Provides a general implementation of bubble sort usable for sorting arbitrary 24079data items. Exchange and comparison procedures are provided by passing 24080access-to-procedure values. 24081 24082@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library 24083@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id51}@anchor{33a} 24084@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) 24085 24086 24087@geindex GNAT.Bubble_Sort_A (g-busora.ads) 24088 24089@geindex Sorting 24090 24091@geindex Bubble sort 24092 24093Provides a general implementation of bubble sort usable for sorting arbitrary 24094data items. Move and comparison procedures are provided by passing 24095access-to-procedure values. This is an older version, retained for 24096compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 24097 24098@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 24099@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id52}@anchor{33c} 24100@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) 24101 24102 24103@geindex GNAT.Bubble_Sort_G (g-busorg.ads) 24104 24105@geindex Sorting 24106 24107@geindex Bubble sort 24108 24109Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 24110are provided as generic parameters, this improves efficiency, especially 24111if the procedures can be inlined, at the expense of duplicating code for 24112multiple instantiations. 24113 24114@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library 24115@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id53}@anchor{33e} 24116@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) 24117 24118 24119@geindex GNAT.Byte_Order_Mark (g-byorma.ads) 24120 24121@geindex UTF-8 representation 24122 24123@geindex Wide characte representations 24124 24125Provides a routine which given a string, reads the start of the string to 24126see whether it is one of the standard byte order marks (BOM’s) which signal 24127the encoding of the string. The routine includes detection of special XML 24128sequences for various UCS input formats. 24129 24130@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library 24131@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id54}@anchor{340} 24132@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) 24133 24134 24135@geindex GNAT.Byte_Swapping (g-bytswa.ads) 24136 24137@geindex Byte swapping 24138 24139@geindex Endianness 24140 24141General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 24142Machine-specific implementations are available in some cases. 24143 24144@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library 24145@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id55}@anchor{342} 24146@section @code{GNAT.Calendar} (@code{g-calend.ads}) 24147 24148 24149@geindex GNAT.Calendar (g-calend.ads) 24150 24151@geindex Calendar 24152 24153Extends the facilities provided by @code{Ada.Calendar} to include handling 24154of days of the week, an extended @code{Split} and @code{Time_Of} capability. 24155Also provides conversion of @code{Ada.Calendar.Time} values to and from the 24156C @code{timeval} format. 24157 24158@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library 24159@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id56}@anchor{344} 24160@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) 24161 24162 24163@geindex Calendar 24164 24165@geindex Time 24166 24167@geindex GNAT.Calendar.Time_IO (g-catiio.ads) 24168 24169@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library 24170@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id57}@anchor{346} 24171@section @code{GNAT.CRC32} (@code{g-crc32.ads}) 24172 24173 24174@geindex GNAT.CRC32 (g-crc32.ads) 24175 24176@geindex CRC32 24177 24178@geindex Cyclic Redundancy Check 24179 24180This package implements the CRC-32 algorithm. For a full description 24181of this algorithm see 24182@emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, 24183@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, 24184Aug. 1988. Sarwate, D.V. 24185 24186@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library 24187@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id58}@anchor{348} 24188@section @code{GNAT.Case_Util} (@code{g-casuti.ads}) 24189 24190 24191@geindex GNAT.Case_Util (g-casuti.ads) 24192 24193@geindex Casing utilities 24194 24195@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) 24196 24197A set of simple routines for handling upper and lower casing of strings 24198without the overhead of the full casing tables 24199in @code{Ada.Characters.Handling}. 24200 24201@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library 24202@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id59}@anchor{34a} 24203@section @code{GNAT.CGI} (@code{g-cgi.ads}) 24204 24205 24206@geindex GNAT.CGI (g-cgi.ads) 24207 24208@geindex CGI (Common Gateway Interface) 24209 24210This is a package for interfacing a GNAT program with a Web server via the 24211Common Gateway Interface (CGI). Basically this package parses the CGI 24212parameters, which are a set of key/value pairs sent by the Web server. It 24213builds a table whose index is the key and provides some services to deal 24214with this table. 24215 24216@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library 24217@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id60}@anchor{34c} 24218@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) 24219 24220 24221@geindex GNAT.CGI.Cookie (g-cgicoo.ads) 24222 24223@geindex CGI (Common Gateway Interface) cookie support 24224 24225@geindex Cookie support in CGI 24226 24227This is a package to interface a GNAT program with a Web server via the 24228Common Gateway Interface (CGI). It exports services to deal with Web 24229cookies (piece of information kept in the Web client software). 24230 24231@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library 24232@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id61}@anchor{34e} 24233@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) 24234 24235 24236@geindex GNAT.CGI.Debug (g-cgideb.ads) 24237 24238@geindex CGI (Common Gateway Interface) debugging 24239 24240This is a package to help debugging CGI (Common Gateway Interface) 24241programs written in Ada. 24242 24243@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library 24244@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id62}@anchor{350} 24245@section @code{GNAT.Command_Line} (@code{g-comlin.ads}) 24246 24247 24248@geindex GNAT.Command_Line (g-comlin.ads) 24249 24250@geindex Command line 24251 24252Provides a high level interface to @code{Ada.Command_Line} facilities, 24253including the ability to scan for named switches with optional parameters 24254and expand file names using wildcard notations. 24255 24256@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library 24257@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id63}@anchor{352} 24258@section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) 24259 24260 24261@geindex GNAT.Compiler_Version (g-comver.ads) 24262 24263@geindex Compiler Version 24264 24265@geindex Version 24266@geindex of compiler 24267 24268Provides a routine for obtaining the version of the compiler used to 24269compile the program. More accurately this is the version of the binder 24270used to bind the program (this will normally be the same as the version 24271of the compiler if a consistent tool set is used to compile all units 24272of a partition). 24273 24274@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library 24275@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id64}@anchor{354} 24276@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) 24277 24278 24279@geindex GNAT.Ctrl_C (g-ctrl_c.ads) 24280 24281@geindex Interrupt 24282 24283Provides a simple interface to handle Ctrl-C keyboard events. 24284 24285@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library 24286@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id65}@anchor{356} 24287@section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) 24288 24289 24290@geindex GNAT.Current_Exception (g-curexc.ads) 24291 24292@geindex Current exception 24293 24294@geindex Exception retrieval 24295 24296Provides access to information on the current exception that has been raised 24297without the need for using the Ada 95 / Ada 2005 exception choice parameter 24298specification syntax. 24299This is particularly useful in simulating typical facilities for 24300obtaining information about exceptions provided by Ada 83 compilers. 24301 24302@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library 24303@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id66}@anchor{358} 24304@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) 24305 24306 24307@geindex GNAT.Debug_Pools (g-debpoo.ads) 24308 24309@geindex Debugging 24310 24311@geindex Debug pools 24312 24313@geindex Memory corruption debugging 24314 24315Provide a debugging storage pools that helps tracking memory corruption 24316problems. 24317See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}. 24318 24319@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library 24320@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id67}@anchor{35a} 24321@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) 24322 24323 24324@geindex GNAT.Debug_Utilities (g-debuti.ads) 24325 24326@geindex Debugging 24327 24328Provides a few useful utilities for debugging purposes, including conversion 24329to and from string images of address values. Supports both C and Ada formats 24330for hexadecimal literals. 24331 24332@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library 24333@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id68}@anchor{35c} 24334@section @code{GNAT.Decode_String} (@code{g-decstr.ads}) 24335 24336 24337@geindex GNAT.Decode_String (g-decstr.ads) 24338 24339@geindex Decoding strings 24340 24341@geindex String decoding 24342 24343@geindex Wide character encoding 24344 24345@geindex UTF-8 24346 24347@geindex Unicode 24348 24349A generic package providing routines for decoding wide character and wide wide 24350character strings encoded as sequences of 8-bit characters using a specified 24351encoding method. Includes validation routines, and also routines for stepping 24352to next or previous encoded character in an encoded string. 24353Useful in conjunction with Unicode character coding. Note there is a 24354preinstantiation for UTF-8. See next entry. 24355 24356@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library 24357@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id69}@anchor{35e} 24358@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) 24359 24360 24361@geindex GNAT.Decode_UTF8_String (g-deutst.ads) 24362 24363@geindex Decoding strings 24364 24365@geindex Decoding UTF-8 strings 24366 24367@geindex UTF-8 string decoding 24368 24369@geindex Wide character decoding 24370 24371@geindex UTF-8 24372 24373@geindex Unicode 24374 24375A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 24376 24377@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library 24378@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id70}@anchor{360} 24379@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) 24380 24381 24382@geindex GNAT.Directory_Operations (g-dirope.ads) 24383 24384@geindex Directory operations 24385 24386Provides a set of routines for manipulating directories, including changing 24387the current directory, making new directories, and scanning the files in a 24388directory. 24389 24390@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library 24391@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id71}@anchor{362} 24392@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) 24393 24394 24395@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) 24396 24397@geindex Directory operations iteration 24398 24399A child unit of GNAT.Directory_Operations providing additional operations 24400for iterating through directories. 24401 24402@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library 24403@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id72}@anchor{364} 24404@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) 24405 24406 24407@geindex GNAT.Dynamic_HTables (g-dynhta.ads) 24408 24409@geindex Hash tables 24410 24411A generic implementation of hash tables that can be used to hash arbitrary 24412data. Provided in two forms, a simple form with built in hash functions, 24413and a more complex form in which the hash function is supplied. 24414 24415This package provides a facility similar to that of @code{GNAT.HTable}, 24416except that this package declares a type that can be used to define 24417dynamic instances of the hash table, while an instantiation of 24418@code{GNAT.HTable} creates a single instance of the hash table. 24419 24420@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library 24421@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id73}@anchor{366} 24422@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) 24423 24424 24425@geindex GNAT.Dynamic_Tables (g-dyntab.ads) 24426 24427@geindex Table implementation 24428 24429@geindex Arrays 24430@geindex extendable 24431 24432A generic package providing a single dimension array abstraction where the 24433length of the array can be dynamically modified. 24434 24435This package provides a facility similar to that of @code{GNAT.Table}, 24436except that this package declares a type that can be used to define 24437dynamic instances of the table, while an instantiation of 24438@code{GNAT.Table} creates a single instance of the table type. 24439 24440@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library 24441@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id74}@anchor{368} 24442@section @code{GNAT.Encode_String} (@code{g-encstr.ads}) 24443 24444 24445@geindex GNAT.Encode_String (g-encstr.ads) 24446 24447@geindex Encoding strings 24448 24449@geindex String encoding 24450 24451@geindex Wide character encoding 24452 24453@geindex UTF-8 24454 24455@geindex Unicode 24456 24457A generic package providing routines for encoding wide character and wide 24458wide character strings as sequences of 8-bit characters using a specified 24459encoding method. Useful in conjunction with Unicode character coding. 24460Note there is a preinstantiation for UTF-8. See next entry. 24461 24462@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library 24463@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id75}@anchor{36a} 24464@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) 24465 24466 24467@geindex GNAT.Encode_UTF8_String (g-enutst.ads) 24468 24469@geindex Encoding strings 24470 24471@geindex Encoding UTF-8 strings 24472 24473@geindex UTF-8 string encoding 24474 24475@geindex Wide character encoding 24476 24477@geindex UTF-8 24478 24479@geindex Unicode 24480 24481A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 24482 24483@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library 24484@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id76}@anchor{36c} 24485@section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) 24486 24487 24488@geindex GNAT.Exception_Actions (g-excact.ads) 24489 24490@geindex Exception actions 24491 24492Provides callbacks when an exception is raised. Callbacks can be registered 24493for specific exceptions, or when any exception is raised. This 24494can be used for instance to force a core dump to ease debugging. 24495 24496@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library 24497@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id77}@anchor{36e} 24498@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) 24499 24500 24501@geindex GNAT.Exception_Traces (g-exctra.ads) 24502 24503@geindex Exception traces 24504 24505@geindex Debugging 24506 24507Provides an interface allowing to control automatic output upon exception 24508occurrences. 24509 24510@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library 24511@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id78}@anchor{370} 24512@section @code{GNAT.Exceptions} (@code{g-except.ads}) 24513 24514 24515@geindex GNAT.Exceptions (g-except.ads) 24516 24517@geindex Exceptions 24518@geindex Pure 24519 24520@geindex Pure packages 24521@geindex exceptions 24522 24523Normally it is not possible to raise an exception with 24524a message from a subprogram in a pure package, since the 24525necessary types and subprograms are in @code{Ada.Exceptions} 24526which is not a pure unit. @code{GNAT.Exceptions} provides a 24527facility for getting around this limitation for a few 24528predefined exceptions, and for example allow raising 24529@code{Constraint_Error} with a message from a pure subprogram. 24530 24531@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library 24532@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id79}@anchor{372} 24533@section @code{GNAT.Expect} (@code{g-expect.ads}) 24534 24535 24536@geindex GNAT.Expect (g-expect.ads) 24537 24538Provides a set of subprograms similar to what is available 24539with the standard Tcl Expect tool. 24540It allows you to easily spawn and communicate with an external process. 24541You can send commands or inputs to the process, and compare the output 24542with some expected regular expression. Currently @code{GNAT.Expect} 24543is implemented on all native GNAT ports. 24544It is not implemented for cross ports, and in particular is not 24545implemented for VxWorks or LynxOS. 24546 24547@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library 24548@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id80}@anchor{374} 24549@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) 24550 24551 24552@geindex GNAT.Expect.TTY (g-exptty.ads) 24553 24554As GNAT.Expect but using pseudo-terminal. 24555Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT 24556ports. It is not implemented for cross ports, and 24557in particular is not implemented for VxWorks or LynxOS. 24558 24559@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library 24560@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id81}@anchor{376} 24561@section @code{GNAT.Float_Control} (@code{g-flocon.ads}) 24562 24563 24564@geindex GNAT.Float_Control (g-flocon.ads) 24565 24566@geindex Floating-Point Processor 24567 24568Provides an interface for resetting the floating-point processor into the 24569mode required for correct semantic operation in Ada. Some third party 24570library calls may cause this mode to be modified, and the Reset procedure 24571in this package can be used to reestablish the required mode. 24572 24573@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library 24574@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id82}@anchor{378} 24575@section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) 24576 24577 24578@geindex GNAT.Formatted_String (g-forstr.ads) 24579 24580@geindex Formatted String 24581 24582Provides support for C/C++ printf() formatted strings. The format is 24583copied from the printf() routine and should therefore gives identical 24584output. Some generic routines are provided to be able to use types 24585derived from Integer, Float or enumerations as values for the 24586formatted string. 24587 24588@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library 24589@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id83}@anchor{37a} 24590@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) 24591 24592 24593@geindex GNAT.Heap_Sort (g-heasor.ads) 24594 24595@geindex Sorting 24596 24597Provides a general implementation of heap sort usable for sorting arbitrary 24598data items. Exchange and comparison procedures are provided by passing 24599access-to-procedure values. The algorithm used is a modified heap sort 24600that performs approximately N*log(N) comparisons in the worst case. 24601 24602@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library 24603@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id84}@anchor{37c} 24604@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) 24605 24606 24607@geindex GNAT.Heap_Sort_A (g-hesora.ads) 24608 24609@geindex Sorting 24610 24611Provides a general implementation of heap sort usable for sorting arbitrary 24612data items. Move and comparison procedures are provided by passing 24613access-to-procedure values. The algorithm used is a modified heap sort 24614that performs approximately N*log(N) comparisons in the worst case. 24615This differs from @code{GNAT.Heap_Sort} in having a less convenient 24616interface, but may be slightly more efficient. 24617 24618@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library 24619@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id85}@anchor{37e} 24620@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) 24621 24622 24623@geindex GNAT.Heap_Sort_G (g-hesorg.ads) 24624 24625@geindex Sorting 24626 24627Similar to @code{Heap_Sort_A} except that the move and sorting procedures 24628are provided as generic parameters, this improves efficiency, especially 24629if the procedures can be inlined, at the expense of duplicating code for 24630multiple instantiations. 24631 24632@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library 24633@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id86}@anchor{380} 24634@section @code{GNAT.HTable} (@code{g-htable.ads}) 24635 24636 24637@geindex GNAT.HTable (g-htable.ads) 24638 24639@geindex Hash tables 24640 24641A generic implementation of hash tables that can be used to hash arbitrary 24642data. Provides two approaches, one a simple static approach, and the other 24643allowing arbitrary dynamic hash tables. 24644 24645@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library 24646@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id87}@anchor{382} 24647@section @code{GNAT.IO} (@code{g-io.ads}) 24648 24649 24650@geindex GNAT.IO (g-io.ads) 24651 24652@geindex Simple I/O 24653 24654@geindex Input/Output facilities 24655 24656A simple preelaborable input-output package that provides a subset of 24657simple Text_IO functions for reading characters and strings from 24658Standard_Input, and writing characters, strings and integers to either 24659Standard_Output or Standard_Error. 24660 24661@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library 24662@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id88}@anchor{384} 24663@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) 24664 24665 24666@geindex GNAT.IO_Aux (g-io_aux.ads) 24667 24668@geindex Text_IO 24669 24670@geindex Input/Output facilities 24671 24672Provides some auxiliary functions for use with Text_IO, including a test 24673for whether a file exists, and functions for reading a line of text. 24674 24675@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library 24676@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{385}@anchor{gnat_rm/the_gnat_library id89}@anchor{386} 24677@section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) 24678 24679 24680@geindex GNAT.Lock_Files (g-locfil.ads) 24681 24682@geindex File locking 24683 24684@geindex Locking using files 24685 24686Provides a general interface for using files as locks. Can be used for 24687providing program level synchronization. 24688 24689@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library 24690@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{387}@anchor{gnat_rm/the_gnat_library id90}@anchor{388} 24691@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) 24692 24693 24694@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) 24695 24696@geindex Random number generation 24697 24698The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses 24699a modified version of the Blum-Blum-Shub generator. 24700 24701@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library 24702@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{389}@anchor{gnat_rm/the_gnat_library id91}@anchor{38a} 24703@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) 24704 24705 24706@geindex GNAT.MBBS_Float_Random (g-mbflra.ads) 24707 24708@geindex Random number generation 24709 24710The original implementation of @code{Ada.Numerics.Float_Random}. Uses 24711a modified version of the Blum-Blum-Shub generator. 24712 24713@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library 24714@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{38b}@anchor{gnat_rm/the_gnat_library id92}@anchor{38c} 24715@section @code{GNAT.MD5} (@code{g-md5.ads}) 24716 24717 24718@geindex GNAT.MD5 (g-md5.ads) 24719 24720@geindex Message Digest MD5 24721 24722Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and 24723the HMAC-MD5 message authentication function as described in RFC 2104 and 24724FIPS PUB 198. 24725 24726@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library 24727@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{38d}@anchor{gnat_rm/the_gnat_library id93}@anchor{38e} 24728@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) 24729 24730 24731@geindex GNAT.Memory_Dump (g-memdum.ads) 24732 24733@geindex Dump Memory 24734 24735Provides a convenient routine for dumping raw memory to either the 24736standard output or standard error files. Uses GNAT.IO for actual 24737output. 24738 24739@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library 24740@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{38f}@anchor{gnat_rm/the_gnat_library id94}@anchor{390} 24741@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) 24742 24743 24744@geindex GNAT.Most_Recent_Exception (g-moreex.ads) 24745 24746@geindex Exception 24747@geindex obtaining most recent 24748 24749Provides access to the most recently raised exception. Can be used for 24750various logging purposes, including duplicating functionality of some 24751Ada 83 implementation dependent extensions. 24752 24753@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 24754@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{391}@anchor{gnat_rm/the_gnat_library id95}@anchor{392} 24755@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) 24756 24757 24758@geindex GNAT.OS_Lib (g-os_lib.ads) 24759 24760@geindex Operating System interface 24761 24762@geindex Spawn capability 24763 24764Provides a range of target independent operating system interface functions, 24765including time/date management, file operations, subprocess management, 24766including a portable spawn procedure, and access to environment variables 24767and error return codes. 24768 24769@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library 24770@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{393}@anchor{gnat_rm/the_gnat_library id96}@anchor{394} 24771@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) 24772 24773 24774@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) 24775 24776@geindex Hash functions 24777 24778Provides a generator of static minimal perfect hash functions. No 24779collisions occur and each item can be retrieved from the table in one 24780probe (perfect property). The hash table size corresponds to the exact 24781size of the key set and no larger (minimal property). The key set has to 24782be know in advance (static property). The hash functions are also order 24783preserving. If w2 is inserted after w1 in the generator, their 24784hashcode are in the same order. These hashing functions are very 24785convenient for use with realtime applications. 24786 24787@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library 24788@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{395}@anchor{gnat_rm/the_gnat_library id97}@anchor{396} 24789@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) 24790 24791 24792@geindex GNAT.Random_Numbers (g-rannum.ads) 24793 24794@geindex Random number generation 24795 24796Provides random number capabilities which extend those available in the 24797standard Ada library and are more convenient to use. 24798 24799@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library 24800@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{25c}@anchor{gnat_rm/the_gnat_library id98}@anchor{397} 24801@section @code{GNAT.Regexp} (@code{g-regexp.ads}) 24802 24803 24804@geindex GNAT.Regexp (g-regexp.ads) 24805 24806@geindex Regular expressions 24807 24808@geindex Pattern matching 24809 24810A simple implementation of regular expressions, using a subset of regular 24811expression syntax copied from familiar Unix style utilities. This is the 24812simplest of the three pattern matching packages provided, and is particularly 24813suitable for ‘file globbing’ applications. 24814 24815@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library 24816@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id99}@anchor{399} 24817@section @code{GNAT.Registry} (@code{g-regist.ads}) 24818 24819 24820@geindex GNAT.Registry (g-regist.ads) 24821 24822@geindex Windows Registry 24823 24824This is a high level binding to the Windows registry. It is possible to 24825do simple things like reading a key value, creating a new key. For full 24826registry API, but at a lower level of abstraction, refer to the Win32.Winreg 24827package provided with the Win32Ada binding 24828 24829@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library 24830@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id100}@anchor{39b} 24831@section @code{GNAT.Regpat} (@code{g-regpat.ads}) 24832 24833 24834@geindex GNAT.Regpat (g-regpat.ads) 24835 24836@geindex Regular expressions 24837 24838@geindex Pattern matching 24839 24840A complete implementation of Unix-style regular expression matching, copied 24841from the original V7 style regular expression library written in C by 24842Henry Spencer (and binary compatible with this C library). 24843 24844@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library 24845@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id101}@anchor{39d} 24846@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) 24847 24848 24849@geindex GNAT.Rewrite_Data (g-rewdat.ads) 24850 24851@geindex Rewrite data 24852 24853A unit to rewrite on-the-fly string occurrences in a stream of 24854data. The implementation has a very minimal memory footprint as the 24855full content to be processed is not loaded into memory all at once. This makes 24856this interface usable for large files or socket streams. 24857 24858@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library 24859@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id102}@anchor{39f} 24860@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) 24861 24862 24863@geindex GNAT.Secondary_Stack_Info (g-sestin.ads) 24864 24865@geindex Secondary Stack Info 24866 24867Provide the capability to query the high water mark of the current task’s 24868secondary stack. 24869 24870@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library 24871@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id103}@anchor{3a1} 24872@section @code{GNAT.Semaphores} (@code{g-semaph.ads}) 24873 24874 24875@geindex GNAT.Semaphores (g-semaph.ads) 24876 24877@geindex Semaphores 24878 24879Provides classic counting and binary semaphores using protected types. 24880 24881@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library 24882@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a3} 24883@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) 24884 24885 24886@geindex GNAT.Serial_Communications (g-sercom.ads) 24887 24888@geindex Serial_Communications 24889 24890Provides a simple interface to send and receive data over a serial 24891port. This is only supported on GNU/Linux and Windows. 24892 24893@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library 24894@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a5} 24895@section @code{GNAT.SHA1} (@code{g-sha1.ads}) 24896 24897 24898@geindex GNAT.SHA1 (g-sha1.ads) 24899 24900@geindex Secure Hash Algorithm SHA-1 24901 24902Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 24903and RFC 3174, and the HMAC-SHA1 message authentication function as described 24904in RFC 2104 and FIPS PUB 198. 24905 24906@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library 24907@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a7} 24908@section @code{GNAT.SHA224} (@code{g-sha224.ads}) 24909 24910 24911@geindex GNAT.SHA224 (g-sha224.ads) 24912 24913@geindex Secure Hash Algorithm SHA-224 24914 24915Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, 24916and the HMAC-SHA224 message authentication function as described 24917in RFC 2104 and FIPS PUB 198. 24918 24919@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library 24920@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a9} 24921@section @code{GNAT.SHA256} (@code{g-sha256.ads}) 24922 24923 24924@geindex GNAT.SHA256 (g-sha256.ads) 24925 24926@geindex Secure Hash Algorithm SHA-256 24927 24928Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, 24929and the HMAC-SHA256 message authentication function as described 24930in RFC 2104 and FIPS PUB 198. 24931 24932@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library 24933@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id108}@anchor{3ab} 24934@section @code{GNAT.SHA384} (@code{g-sha384.ads}) 24935 24936 24937@geindex GNAT.SHA384 (g-sha384.ads) 24938 24939@geindex Secure Hash Algorithm SHA-384 24940 24941Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, 24942and the HMAC-SHA384 message authentication function as described 24943in RFC 2104 and FIPS PUB 198. 24944 24945@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library 24946@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id109}@anchor{3ad} 24947@section @code{GNAT.SHA512} (@code{g-sha512.ads}) 24948 24949 24950@geindex GNAT.SHA512 (g-sha512.ads) 24951 24952@geindex Secure Hash Algorithm SHA-512 24953 24954Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, 24955and the HMAC-SHA512 message authentication function as described 24956in RFC 2104 and FIPS PUB 198. 24957 24958@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library 24959@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id110}@anchor{3af} 24960@section @code{GNAT.Signals} (@code{g-signal.ads}) 24961 24962 24963@geindex GNAT.Signals (g-signal.ads) 24964 24965@geindex Signals 24966 24967Provides the ability to manipulate the blocked status of signals on supported 24968targets. 24969 24970@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library 24971@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b1} 24972@section @code{GNAT.Sockets} (@code{g-socket.ads}) 24973 24974 24975@geindex GNAT.Sockets (g-socket.ads) 24976 24977@geindex Sockets 24978 24979A high level and portable interface to develop sockets based applications. 24980This package is based on the sockets thin binding found in 24981@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 24982on all native GNAT ports and on VxWorks cross prots. It is not implemented for 24983the LynxOS cross port. 24984 24985@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library 24986@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b3} 24987@section @code{GNAT.Source_Info} (@code{g-souinf.ads}) 24988 24989 24990@geindex GNAT.Source_Info (g-souinf.ads) 24991 24992@geindex Source Information 24993 24994Provides subprograms that give access to source code information known at 24995compile time, such as the current file name and line number. Also provides 24996subprograms yielding the date and time of the current compilation (like the 24997C macros @code{__DATE__} and @code{__TIME__}) 24998 24999@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library 25000@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b5} 25001@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) 25002 25003 25004@geindex GNAT.Spelling_Checker (g-speche.ads) 25005 25006@geindex Spell checking 25007 25008Provides a function for determining whether one string is a plausible 25009near misspelling of another string. 25010 25011@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library 25012@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b7} 25013@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) 25014 25015 25016@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) 25017 25018@geindex Spell checking 25019 25020Provides a generic function that can be instantiated with a string type for 25021determining whether one string is a plausible near misspelling of another 25022string. 25023 25024@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library 25025@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b9} 25026@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) 25027 25028 25029@geindex GNAT.Spitbol.Patterns (g-spipat.ads) 25030 25031@geindex SPITBOL pattern matching 25032 25033@geindex Pattern matching 25034 25035A complete implementation of SNOBOL4 style pattern matching. This is the 25036most elaborate of the pattern matching packages provided. It fully duplicates 25037the SNOBOL4 dynamic pattern construction and matching capabilities, using the 25038efficient algorithm developed by Robert Dewar for the SPITBOL system. 25039 25040@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library 25041@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id116}@anchor{3bb} 25042@section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) 25043 25044 25045@geindex GNAT.Spitbol (g-spitbo.ads) 25046 25047@geindex SPITBOL interface 25048 25049The top level package of the collection of SPITBOL-style functionality, this 25050package provides basic SNOBOL4 string manipulation functions, such as 25051Pad, Reverse, Trim, Substr capability, as well as a generic table function 25052useful for constructing arbitrary mappings from strings in the style of 25053the SNOBOL4 TABLE function. 25054 25055@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library 25056@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3bc}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bd} 25057@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) 25058 25059 25060@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 25061 25062@geindex Sets of strings 25063 25064@geindex SPITBOL Tables 25065 25066A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 25067for type @code{Standard.Boolean}, giving an implementation of sets of 25068string values. 25069 25070@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 25071@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id118}@anchor{3bf} 25072@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) 25073 25074 25075@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) 25076 25077@geindex Integer maps 25078 25079@geindex Maps 25080 25081@geindex SPITBOL Tables 25082 25083A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 25084for type @code{Standard.Integer}, giving an implementation of maps 25085from string to integer values. 25086 25087@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library 25088@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id119}@anchor{3c1} 25089@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) 25090 25091 25092@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) 25093 25094@geindex String maps 25095 25096@geindex Maps 25097 25098@geindex SPITBOL Tables 25099 25100A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 25101a variable length string type, giving an implementation of general 25102maps from strings to strings. 25103 25104@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library 25105@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c3} 25106@section @code{GNAT.SSE} (@code{g-sse.ads}) 25107 25108 25109@geindex GNAT.SSE (g-sse.ads) 25110 25111Root of a set of units aimed at offering Ada bindings to a subset of 25112the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 25113targets. It exposes vector component types together with a general 25114introduction to the binding contents and use. 25115 25116@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library 25117@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c5} 25118@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) 25119 25120 25121@geindex GNAT.SSE.Vector_Types (g-ssvety.ads) 25122 25123SSE vector types for use with SSE related intrinsics. 25124 25125@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library 25126@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c7} 25127@section @code{GNAT.String_Hash} (@code{g-strhas.ads}) 25128 25129 25130@geindex GNAT.String_Hash (g-strhas.ads) 25131 25132@geindex Hash functions 25133 25134Provides a generic hash function working on arrays of scalars. Both the scalar 25135type and the hash result type are parameters. 25136 25137@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library 25138@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c9} 25139@section @code{GNAT.Strings} (@code{g-string.ads}) 25140 25141 25142@geindex GNAT.Strings (g-string.ads) 25143 25144Common String access types and related subprograms. Basically it 25145defines a string access and an array of string access types. 25146 25147@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library 25148@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id124}@anchor{3cb} 25149@section @code{GNAT.String_Split} (@code{g-strspl.ads}) 25150 25151 25152@geindex GNAT.String_Split (g-strspl.ads) 25153 25154@geindex String splitter 25155 25156Useful string manipulation routines: given a set of separators, split 25157a string wherever the separators appear, and provide direct access 25158to the resulting slices. This package is instantiated from 25159@code{GNAT.Array_Split}. 25160 25161@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library 25162@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id125}@anchor{3cd} 25163@section @code{GNAT.Table} (@code{g-table.ads}) 25164 25165 25166@geindex GNAT.Table (g-table.ads) 25167 25168@geindex Table implementation 25169 25170@geindex Arrays 25171@geindex extendable 25172 25173A generic package providing a single dimension array abstraction where the 25174length of the array can be dynamically modified. 25175 25176This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 25177except that this package declares a single instance of the table type, 25178while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 25179used to define dynamic instances of the table. 25180 25181@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library 25182@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id126}@anchor{3cf} 25183@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) 25184 25185 25186@geindex GNAT.Task_Lock (g-tasloc.ads) 25187 25188@geindex Task synchronization 25189 25190@geindex Task locking 25191 25192@geindex Locking 25193 25194A very simple facility for locking and unlocking sections of code using a 25195single global task lock. Appropriate for use in situations where contention 25196between tasks is very rarely expected. 25197 25198@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library 25199@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id127}@anchor{3d1} 25200@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) 25201 25202 25203@geindex GNAT.Time_Stamp (g-timsta.ads) 25204 25205@geindex Time stamp 25206 25207@geindex Current time 25208 25209Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 25210represents the current date and time in ISO 8601 format. This is a very simple 25211routine with minimal code and there are no dependencies on any other unit. 25212 25213@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library 25214@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d3} 25215@section @code{GNAT.Threads} (@code{g-thread.ads}) 25216 25217 25218@geindex GNAT.Threads (g-thread.ads) 25219 25220@geindex Foreign threads 25221 25222@geindex Threads 25223@geindex foreign 25224 25225Provides facilities for dealing with foreign threads which need to be known 25226by the GNAT run-time system. Consult the documentation of this package for 25227further details if your program has threads that are created by a non-Ada 25228environment which then accesses Ada code. 25229 25230@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library 25231@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3d4}@anchor{gnat_rm/the_gnat_library id129}@anchor{3d5} 25232@section @code{GNAT.Traceback} (@code{g-traceb.ads}) 25233 25234 25235@geindex GNAT.Traceback (g-traceb.ads) 25236 25237@geindex Trace back facilities 25238 25239Provides a facility for obtaining non-symbolic traceback information, useful 25240in various debugging situations. 25241 25242@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library 25243@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3d6}@anchor{gnat_rm/the_gnat_library id130}@anchor{3d7} 25244@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) 25245 25246 25247@geindex GNAT.Traceback.Symbolic (g-trasym.ads) 25248 25249@geindex Trace back facilities 25250 25251@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library 25252@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3d8}@anchor{gnat_rm/the_gnat_library id131}@anchor{3d9} 25253@section @code{GNAT.UTF_32} (@code{g-table.ads}) 25254 25255 25256@geindex GNAT.UTF_32 (g-table.ads) 25257 25258@geindex Wide character codes 25259 25260This is a package intended to be used in conjunction with the 25261@code{Wide_Character} type in Ada 95 and the 25262@code{Wide_Wide_Character} type in Ada 2005 (available 25263in @code{GNAT} in Ada 2005 mode). This package contains 25264Unicode categorization routines, as well as lexical 25265categorization routines corresponding to the Ada 2005 25266lexical rules for identifiers and strings, and also a 25267lower case to upper case fold routine corresponding to 25268the Ada 2005 rules for identifier equivalence. 25269 25270@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library 25271@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3da}@anchor{gnat_rm/the_gnat_library id132}@anchor{3db} 25272@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) 25273 25274 25275@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) 25276 25277@geindex Spell checking 25278 25279Provides a function for determining whether one wide wide string is a plausible 25280near misspelling of another wide wide string, where the strings are represented 25281using the UTF_32_String type defined in System.Wch_Cnv. 25282 25283@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 25284@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3dc}@anchor{gnat_rm/the_gnat_library id133}@anchor{3dd} 25285@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) 25286 25287 25288@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) 25289 25290@geindex Spell checking 25291 25292Provides a function for determining whether one wide string is a plausible 25293near misspelling of another wide string. 25294 25295@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 25296@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3de}@anchor{gnat_rm/the_gnat_library id134}@anchor{3df} 25297@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) 25298 25299 25300@geindex GNAT.Wide_String_Split (g-wistsp.ads) 25301 25302@geindex Wide_String splitter 25303 25304Useful wide string manipulation routines: given a set of separators, split 25305a wide string wherever the separators appear, and provide direct access 25306to the resulting slices. This package is instantiated from 25307@code{GNAT.Array_Split}. 25308 25309@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 25310@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} 25311@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) 25312 25313 25314@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 25315 25316@geindex Spell checking 25317 25318Provides a function for determining whether one wide wide string is a plausible 25319near misspelling of another wide wide string. 25320 25321@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 25322@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} 25323@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) 25324 25325 25326@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) 25327 25328@geindex Wide_Wide_String splitter 25329 25330Useful wide wide string manipulation routines: given a set of separators, split 25331a wide wide string wherever the separators appear, and provide direct access 25332to the resulting slices. This package is instantiated from 25333@code{GNAT.Array_Split}. 25334 25335@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library 25336@anchor{gnat_rm/the_gnat_library id137}@anchor{3e4}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3e5} 25337@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) 25338 25339 25340@geindex Interfaces.C.Extensions (i-cexten.ads) 25341 25342This package contains additional C-related definitions, intended 25343for use with either manually or automatically generated bindings 25344to C libraries. 25345 25346@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library 25347@anchor{gnat_rm/the_gnat_library id138}@anchor{3e6}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e7} 25348@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) 25349 25350 25351@geindex Interfaces.C.Streams (i-cstrea.ads) 25352 25353@geindex C streams 25354@geindex interfacing 25355 25356This package is a binding for the most commonly used operations 25357on C streams. 25358 25359@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library 25360@anchor{gnat_rm/the_gnat_library id139}@anchor{3e8}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e9} 25361@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) 25362 25363 25364@geindex Interfaces.Packed_Decimal (i-pacdec.ads) 25365 25366@geindex IBM Packed Format 25367 25368@geindex Packed Decimal 25369 25370This package provides a set of routines for conversions to and 25371from a packed decimal format compatible with that used on IBM 25372mainframes. 25373 25374@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library 25375@anchor{gnat_rm/the_gnat_library id140}@anchor{3ea}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3eb} 25376@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) 25377 25378 25379@geindex Interfaces.VxWorks (i-vxwork.ads) 25380 25381@geindex Interfacing to VxWorks 25382 25383@geindex VxWorks 25384@geindex interfacing 25385 25386This package provides a limited binding to the VxWorks API. 25387In particular, it interfaces with the 25388VxWorks hardware interrupt facilities. 25389 25390@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library 25391@anchor{gnat_rm/the_gnat_library id141}@anchor{3ec}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3ed} 25392@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) 25393 25394 25395@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) 25396 25397@geindex Interfacing to VxWorks 25398 25399@geindex VxWorks 25400@geindex interfacing 25401 25402This package provides a way for users to replace the use of 25403intConnect() with a custom routine for installing interrupt 25404handlers. 25405 25406@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library 25407@anchor{gnat_rm/the_gnat_library id142}@anchor{3ee}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3ef} 25408@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) 25409 25410 25411@geindex Interfaces.VxWorks.IO (i-vxwoio.ads) 25412 25413@geindex Interfacing to VxWorks' I/O 25414 25415@geindex VxWorks 25416@geindex I/O interfacing 25417 25418@geindex VxWorks 25419@geindex Get_Immediate 25420 25421@geindex Get_Immediate 25422@geindex VxWorks 25423 25424This package provides a binding to the ioctl (IO/Control) 25425function of VxWorks, defining a set of option values and 25426function codes. A particular use of this package is 25427to enable the use of Get_Immediate under VxWorks. 25428 25429@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library 25430@anchor{gnat_rm/the_gnat_library id143}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3f1} 25431@section @code{System.Address_Image} (@code{s-addima.ads}) 25432 25433 25434@geindex System.Address_Image (s-addima.ads) 25435 25436@geindex Address image 25437 25438@geindex Image 25439@geindex of an address 25440 25441This function provides a useful debugging 25442function that gives an (implementation dependent) 25443string which identifies an address. 25444 25445@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library 25446@anchor{gnat_rm/the_gnat_library id144}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3f3} 25447@section @code{System.Assertions} (@code{s-assert.ads}) 25448 25449 25450@geindex System.Assertions (s-assert.ads) 25451 25452@geindex Assertions 25453 25454@geindex Assert_Failure 25455@geindex exception 25456 25457This package provides the declaration of the exception raised 25458by an run-time assertion failure, as well as the routine that 25459is used internally to raise this assertion. 25460 25461@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library 25462@anchor{gnat_rm/the_gnat_library id145}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3f5} 25463@section @code{System.Atomic_Counters} (@code{s-atocou.ads}) 25464 25465 25466@geindex System.Atomic_Counters (s-atocou.ads) 25467 25468This package provides the declaration of an atomic counter type, 25469together with efficient routines (using hardware 25470synchronization primitives) for incrementing, decrementing, 25471and testing of these counters. This package is implemented 25472on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9, 25473x86, and x86_64 platforms. 25474 25475@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library 25476@anchor{gnat_rm/the_gnat_library id146}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f7} 25477@section @code{System.Memory} (@code{s-memory.ads}) 25478 25479 25480@geindex System.Memory (s-memory.ads) 25481 25482@geindex Memory allocation 25483 25484This package provides the interface to the low level routines used 25485by the generated code for allocation and freeing storage for the 25486default storage pool (analogous to the C routines malloc and free. 25487It also provides a reallocation interface analogous to the C routine 25488realloc. The body of this unit may be modified to provide alternative 25489allocation mechanisms for the default pool, and in addition, direct 25490calls to this unit may be made for low level allocation uses (for 25491example see the body of @code{GNAT.Tables}). 25492 25493@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library 25494@anchor{gnat_rm/the_gnat_library id147}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f9} 25495@section @code{System.Multiprocessors} (@code{s-multip.ads}) 25496 25497 25498@geindex System.Multiprocessors (s-multip.ads) 25499 25500@geindex Multiprocessor interface 25501 25502This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25503in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25504technically an implementation-defined addition). 25505 25506@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library 25507@anchor{gnat_rm/the_gnat_library id148}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3fb} 25508@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) 25509 25510 25511@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) 25512 25513@geindex Multiprocessor interface 25514 25515This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 25516in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 25517technically an implementation-defined addition). 25518 25519@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library 25520@anchor{gnat_rm/the_gnat_library id149}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3fd} 25521@section @code{System.Partition_Interface} (@code{s-parint.ads}) 25522 25523 25524@geindex System.Partition_Interface (s-parint.ads) 25525 25526@geindex Partition interfacing functions 25527 25528This package provides facilities for partition interfacing. It 25529is used primarily in a distribution context when using Annex E 25530with @code{GLADE}. 25531 25532@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library 25533@anchor{gnat_rm/the_gnat_library id150}@anchor{3fe}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3ff} 25534@section @code{System.Pool_Global} (@code{s-pooglo.ads}) 25535 25536 25537@geindex System.Pool_Global (s-pooglo.ads) 25538 25539@geindex Storage pool 25540@geindex global 25541 25542@geindex Global storage pool 25543 25544This package provides a storage pool that is equivalent to the default 25545storage pool used for access types for which no pool is specifically 25546declared. It uses malloc/free to allocate/free and does not attempt to 25547do any automatic reclamation. 25548 25549@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library 25550@anchor{gnat_rm/the_gnat_library id151}@anchor{400}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{401} 25551@section @code{System.Pool_Local} (@code{s-pooloc.ads}) 25552 25553 25554@geindex System.Pool_Local (s-pooloc.ads) 25555 25556@geindex Storage pool 25557@geindex local 25558 25559@geindex Local storage pool 25560 25561This package provides a storage pool that is intended for use with locally 25562defined access types. It uses malloc/free for allocate/free, and maintains 25563a list of allocated blocks, so that all storage allocated for the pool can 25564be freed automatically when the pool is finalized. 25565 25566@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library 25567@anchor{gnat_rm/the_gnat_library id152}@anchor{402}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{403} 25568@section @code{System.Restrictions} (@code{s-restri.ads}) 25569 25570 25571@geindex System.Restrictions (s-restri.ads) 25572 25573@geindex Run-time restrictions access 25574 25575This package provides facilities for accessing at run time 25576the status of restrictions specified at compile time for 25577the partition. Information is available both with regard 25578to actual restrictions specified, and with regard to 25579compiler determined information on which restrictions 25580are violated by one or more packages in the partition. 25581 25582@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library 25583@anchor{gnat_rm/the_gnat_library id153}@anchor{404}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{405} 25584@section @code{System.Rident} (@code{s-rident.ads}) 25585 25586 25587@geindex System.Rident (s-rident.ads) 25588 25589@geindex Restrictions definitions 25590 25591This package provides definitions of the restrictions 25592identifiers supported by GNAT, and also the format of 25593the restrictions provided in package System.Restrictions. 25594It is not normally necessary to @code{with} this generic package 25595since the necessary instantiation is included in 25596package System.Restrictions. 25597 25598@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library 25599@anchor{gnat_rm/the_gnat_library id154}@anchor{406}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{407} 25600@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) 25601 25602 25603@geindex System.Strings.Stream_Ops (s-ststop.ads) 25604 25605@geindex Stream operations 25606 25607@geindex String stream operations 25608 25609This package provides a set of stream subprograms for standard string types. 25610It is intended primarily to support implicit use of such subprograms when 25611stream attributes are applied to string types, but the subprograms in this 25612package can be used directly by application programs. 25613 25614@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library 25615@anchor{gnat_rm/the_gnat_library id155}@anchor{408}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{409} 25616@section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) 25617 25618 25619@geindex System.Unsigned_Types (s-unstyp.ads) 25620 25621This package contains definitions of standard unsigned types that 25622correspond in size to the standard signed types declared in Standard, 25623and (unlike the types in Interfaces) have corresponding names. It 25624also contains some related definitions for other specialized types 25625used by the compiler in connection with packed array types. 25626 25627@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library 25628@anchor{gnat_rm/the_gnat_library id156}@anchor{40a}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{40b} 25629@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) 25630 25631 25632@geindex System.Wch_Cnv (s-wchcnv.ads) 25633 25634@geindex Wide Character 25635@geindex Representation 25636 25637@geindex Wide String 25638@geindex Conversion 25639 25640@geindex Representation of wide characters 25641 25642This package provides routines for converting between 25643wide and wide wide characters and a representation as a value of type 25644@code{Standard.String}, using a specified wide character 25645encoding method. It uses definitions in 25646package @code{System.Wch_Con}. 25647 25648@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library 25649@anchor{gnat_rm/the_gnat_library id157}@anchor{40c}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{40d} 25650@section @code{System.Wch_Con} (@code{s-wchcon.ads}) 25651 25652 25653@geindex System.Wch_Con (s-wchcon.ads) 25654 25655This package provides definitions and descriptions of 25656the various methods used for encoding wide characters 25657in ordinary strings. These definitions are used by 25658the package @code{System.Wch_Cnv}. 25659 25660@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top 25661@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} 25662@chapter Interfacing to Other Languages 25663 25664 25665The facilities in Annex B of the Ada Reference Manual are fully 25666implemented in GNAT, and in addition, a full interface to C++ is 25667provided. 25668 25669@menu 25670* Interfacing to C:: 25671* Interfacing to C++:: 25672* Interfacing to COBOL:: 25673* Interfacing to Fortran:: 25674* Interfacing to non-GNAT Ada code:: 25675 25676@end menu 25677 25678@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages 25679@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{410}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{411} 25680@section Interfacing to C 25681 25682 25683Interfacing to C with GNAT can use one of two approaches: 25684 25685 25686@itemize * 25687 25688@item 25689The types in the package @code{Interfaces.C} may be used. 25690 25691@item 25692Standard Ada types may be used directly. This may be less portable to 25693other compilers, but will work on all GNAT compilers, which guarantee 25694correspondence between the C and Ada types. 25695@end itemize 25696 25697Pragma @code{Convention C} may be applied to Ada types, but mostly has no 25698effect, since this is the default. The following table shows the 25699correspondence between Ada scalar types and the corresponding C types. 25700 25701 25702@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 25703@headitem 25704 25705Ada Type 25706 25707@tab 25708 25709C Type 25710 25711@item 25712 25713@code{Integer} 25714 25715@tab 25716 25717@code{int} 25718 25719@item 25720 25721@code{Short_Integer} 25722 25723@tab 25724 25725@code{short} 25726 25727@item 25728 25729@code{Short_Short_Integer} 25730 25731@tab 25732 25733@code{signed char} 25734 25735@item 25736 25737@code{Long_Integer} 25738 25739@tab 25740 25741@code{long} 25742 25743@item 25744 25745@code{Long_Long_Integer} 25746 25747@tab 25748 25749@code{long long} 25750 25751@item 25752 25753@code{Short_Float} 25754 25755@tab 25756 25757@code{float} 25758 25759@item 25760 25761@code{Float} 25762 25763@tab 25764 25765@code{float} 25766 25767@item 25768 25769@code{Long_Float} 25770 25771@tab 25772 25773@code{double} 25774 25775@item 25776 25777@code{Long_Long_Float} 25778 25779@tab 25780 25781This is the longest floating-point type supported by the hardware. 25782 25783@end multitable 25784 25785 25786Additionally, there are the following general correspondences between Ada 25787and C types: 25788 25789 25790@itemize * 25791 25792@item 25793Ada enumeration types map to C enumeration types directly if pragma 25794@code{Convention C} is specified, which causes them to have a length of 2579532 bits, except for boolean types which map to C99 @code{bool} and for 25796which the length is 8 bits. 25797Without pragma @code{Convention C}, Ada enumeration types map to 257988, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, 25799@code{int}, respectively) depending on the number of values passed. 25800This is the only case in which pragma @code{Convention C} affects the 25801representation of an Ada type. 25802 25803@item 25804Ada access types map to C pointers, except for the case of pointers to 25805unconstrained types in Ada, which have no direct C equivalent. 25806 25807@item 25808Ada arrays map directly to C arrays. 25809 25810@item 25811Ada records map directly to C structures. 25812 25813@item 25814Packed Ada records map to C structures where all members are bit fields 25815of the length corresponding to the @code{type'Size} value in Ada. 25816@end itemize 25817 25818@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages 25819@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{48}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{412} 25820@section Interfacing to C++ 25821 25822 25823The interface to C++ makes use of the following pragmas, which are 25824primarily intended to be constructed automatically using a binding generator 25825tool, although it is possible to construct them by hand. 25826 25827Using these pragmas it is possible to achieve complete 25828inter-operability between Ada tagged types and C++ class definitions. 25829See @ref{7,,Implementation Defined Pragmas}, for more details. 25830 25831 25832@table @asis 25833 25834@item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})} 25835 25836The argument denotes an entity in the current declarative region that is 25837declared as a tagged or untagged record type. It indicates that the type 25838corresponds to an externally declared C++ class type, and is to be laid 25839out the same way that C++ would lay out the type. 25840 25841Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 25842for backward compatibility but its functionality is available 25843using pragma @code{Import} with @code{Convention} = @code{CPP}. 25844 25845@item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})} 25846 25847This pragma identifies an imported function (imported in the usual way 25848with pragma @code{Import}) as corresponding to a C++ constructor. 25849@end table 25850 25851A few restrictions are placed on the use of the @code{Access} attribute 25852in conjunction with subprograms subject to convention @code{CPP}: the 25853attribute may be used neither on primitive operations of a tagged 25854record type with convention @code{CPP}, imported or not, nor on 25855subprograms imported with pragma @code{CPP_Constructor}. 25856 25857In addition, C++ exceptions are propagated and can be handled in an 25858@code{others} choice of an exception handler. The corresponding Ada 25859occurrence has no message, and the simple name of the exception identity 25860contains @code{Foreign_Exception}. Finalization and awaiting dependent 25861tasks works properly when such foreign exceptions are propagated. 25862 25863It is also possible to import a C++ exception using the following syntax: 25864 25865@example 25866LOCAL_NAME : exception; 25867pragma Import (Cpp, 25868 [Entity =>] LOCAL_NAME, 25869 [External_Name =>] static_string_EXPRESSION); 25870@end example 25871 25872The @code{External_Name} is the name of the C++ RTTI symbol. You can then 25873cover a specific C++ exception in an exception handler. 25874 25875@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages 25876@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{413}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{414} 25877@section Interfacing to COBOL 25878 25879 25880Interfacing to COBOL is achieved as described in section B.4 of 25881the Ada Reference Manual. 25882 25883@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages 25884@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{415}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{416} 25885@section Interfacing to Fortran 25886 25887 25888Interfacing to Fortran is achieved as described in section B.5 of the 25889Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a 25890multi-dimensional array causes the array to be stored in column-major 25891order as required for convenient interface to Fortran. 25892 25893@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages 25894@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} 25895@section Interfacing to non-GNAT Ada code 25896 25897 25898It is possible to specify the convention @code{Ada} in a pragma 25899@code{Import} or pragma @code{Export}. However this refers to 25900the calling conventions used by GNAT, which may or may not be 25901similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 25902compiler to allow interoperation. 25903 25904If arguments types are kept simple, and if the foreign compiler generally 25905follows system calling conventions, then it may be possible to integrate 25906files compiled by other Ada compilers, provided that the elaboration 25907issues are adequately addressed (for example by eliminating the 25908need for any load time elaboration). 25909 25910In particular, GNAT running on VMS is designed to 25911be highly compatible with the DEC Ada 83 compiler, so this is one 25912case in which it is possible to import foreign units of this type, 25913provided that the data items passed are restricted to simple scalar 25914values or simple record types without variants, or simple array 25915types with fixed bounds. 25916 25917@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top 25918@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} 25919@chapter Specialized Needs Annexes 25920 25921 25922Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not 25923required in all implementations. However, as described in this chapter, 25924GNAT implements all of these annexes: 25925 25926 25927@table @asis 25928 25929@item @emph{Systems Programming (Annex C)} 25930 25931The Systems Programming Annex is fully implemented. 25932 25933@item @emph{Real-Time Systems (Annex D)} 25934 25935The Real-Time Systems Annex is fully implemented. 25936 25937@item @emph{Distributed Systems (Annex E)} 25938 25939Stub generation is fully implemented in the GNAT compiler. In addition, 25940a complete compatible PCS is available as part of the GLADE system, 25941a separate product. When the two 25942products are used in conjunction, this annex is fully implemented. 25943 25944@item @emph{Information Systems (Annex F)} 25945 25946The Information Systems annex is fully implemented. 25947 25948@item @emph{Numerics (Annex G)} 25949 25950The Numerics Annex is fully implemented. 25951 25952@item @emph{Safety and Security / High-Integrity Systems (Annex H)} 25953 25954The Safety and Security Annex (termed the High-Integrity Systems Annex 25955in Ada 2005) is fully implemented. 25956@end table 25957 25958@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top 25959@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} 25960@chapter Implementation of Specific Ada Features 25961 25962 25963This chapter describes the GNAT implementation of several Ada language 25964facilities. 25965 25966@menu 25967* Machine Code Insertions:: 25968* GNAT Implementation of Tasking:: 25969* GNAT Implementation of Shared Passive Packages:: 25970* Code Generation for Array Aggregates:: 25971* The Size of Discriminated Records with Default Discriminants:: 25972* Image Values For Nonscalar Types:: 25973* Strict Conformance to the Ada Reference Manual:: 25974 25975@end menu 25976 25977@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features 25978@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{167} 25979@section Machine Code Insertions 25980 25981 25982@geindex Machine Code insertions 25983 25984Package @code{Machine_Code} provides machine code support as described 25985in the Ada Reference Manual in two separate forms: 25986 25987 25988@itemize * 25989 25990@item 25991Machine code statements, consisting of qualified expressions that 25992fit the requirements of RM section 13.8. 25993 25994@item 25995An intrinsic callable procedure, providing an alternative mechanism of 25996including machine instructions in a subprogram. 25997@end itemize 25998 25999The two features are similar, and both are closely related to the mechanism 26000provided by the asm instruction in the GNU C compiler. Full understanding 26001and use of the facilities in this package requires understanding the asm 26002instruction, see the section on Extended Asm in 26003@cite{Using_the_GNU_Compiler_Collection_(GCC)}. 26004 26005Calls to the function @code{Asm} and the procedure @code{Asm} have identical 26006semantic restrictions and effects as described below. Both are provided so 26007that the procedure call can be used as a statement, and the function call 26008can be used to form a code_statement. 26009 26010Consider this C @code{asm} instruction: 26011 26012@example 26013asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 26014@end example 26015 26016The equivalent can be written for GNAT as: 26017 26018@example 26019Asm ("fsinx %1 %0", 26020 My_Float'Asm_Output ("=f", result), 26021 My_Float'Asm_Input ("f", angle)); 26022@end example 26023 26024The first argument to @code{Asm} is the assembler template, and is 26025identical to what is used in GNU C. This string must be a static 26026expression. The second argument is the output operand list. It is 26027either a single @code{Asm_Output} attribute reference, or a list of such 26028references enclosed in parentheses (technically an array aggregate of 26029such references). 26030 26031The @code{Asm_Output} attribute denotes a function that takes two 26032parameters. The first is a string, the second is the name of a variable 26033of the type designated by the attribute prefix. The first (string) 26034argument is required to be a static expression and designates the 26035constraint (see the section on Constraints in 26036@cite{Using_the_GNU_Compiler_Collection_(GCC)}) 26037for the parameter; e.g., what kind of register is required. The second 26038argument is the variable to be written or updated with the 26039result. The possible values for constraint are the same as those used in 26040the RTL, and are dependent on the configuration file used to build the 26041GCC back end. If there are no output operands, then this argument may 26042either be omitted, or explicitly given as @code{No_Output_Operands}. 26043No support is provided for GNU C’s symbolic names for output parameters. 26044 26045The second argument of @code{my_float'Asm_Output} functions as 26046though it were an @code{out} parameter, which is a little curious, but 26047all names have the form of expressions, so there is no syntactic 26048irregularity, even though normally functions would not be permitted 26049@code{out} parameters. The third argument is the list of input 26050operands. It is either a single @code{Asm_Input} attribute reference, or 26051a list of such references enclosed in parentheses (technically an array 26052aggregate of such references). 26053 26054The @code{Asm_Input} attribute denotes a function that takes two 26055parameters. The first is a string, the second is an expression of the 26056type designated by the prefix. The first (string) argument is required 26057to be a static expression, and is the constraint for the parameter, 26058(e.g., what kind of register is required). The second argument is the 26059value to be used as the input argument. The possible values for the 26060constraint are the same as those used in the RTL, and are dependent on 26061the configuration file used to built the GCC back end. 26062No support is provided for GNU C’s symbolic names for input parameters. 26063 26064If there are no input operands, this argument may either be omitted, or 26065explicitly given as @code{No_Input_Operands}. The fourth argument, not 26066present in the above example, is a list of register names, called the 26067@emph{clobber} argument. This argument, if given, must be a static string 26068expression, and is a space or comma separated list of names of registers 26069that must be considered destroyed as a result of the @code{Asm} call. If 26070this argument is the null string (the default value), then the code 26071generator assumes that no additional registers are destroyed. 26072In addition to registers, the special clobbers @code{memory} and 26073@code{cc} as described in the GNU C docs are both supported. 26074 26075The fifth argument, not present in the above example, called the 26076@emph{volatile} argument, is by default @code{False}. It can be set to 26077the literal value @code{True} to indicate to the code generator that all 26078optimizations with respect to the instruction specified should be 26079suppressed, and in particular an instruction that has outputs 26080will still be generated, even if none of the outputs are 26081used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} 26082for the full description. 26083Generally it is strongly advisable to use Volatile for any ASM statement 26084that is missing either input or output operands or to avoid unwanted 26085optimizations. A warning is generated if this advice is not followed. 26086 26087No support is provided for GNU C’s @code{asm goto} feature. 26088 26089The @code{Asm} subprograms may be used in two ways. First the procedure 26090forms can be used anywhere a procedure call would be valid, and 26091correspond to what the RM calls ‘intrinsic’ routines. Such calls can 26092be used to intersperse machine instructions with other Ada statements. 26093Second, the function forms, which return a dummy value of the limited 26094private type @code{Asm_Insn}, can be used in code statements, and indeed 26095this is the only context where such calls are allowed. Code statements 26096appear as aggregates of the form: 26097 26098@example 26099Asm_Insn'(Asm (...)); 26100Asm_Insn'(Asm_Volatile (...)); 26101@end example 26102 26103In accordance with RM rules, such code statements are allowed only 26104within subprograms whose entire body consists of such statements. It is 26105not permissible to intermix such statements with other Ada statements. 26106 26107Typically the form using intrinsic procedure calls is more convenient 26108and more flexible. The code statement form is provided to meet the RM 26109suggestion that such a facility should be made available. The following 26110is the exact syntax of the call to @code{Asm}. As usual, if named notation 26111is used, the arguments may be given in arbitrary order, following the 26112normal rules for use of positional and named arguments: 26113 26114@example 26115ASM_CALL ::= Asm ( 26116 [Template =>] static_string_EXPRESSION 26117 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 26118 [,[Inputs =>] INPUT_OPERAND_LIST ] 26119 [,[Clobber =>] static_string_EXPRESSION ] 26120 [,[Volatile =>] static_boolean_EXPRESSION] ) 26121 26122OUTPUT_OPERAND_LIST ::= 26123 [PREFIX.]No_Output_Operands 26124| OUTPUT_OPERAND_ATTRIBUTE 26125| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 26126 26127OUTPUT_OPERAND_ATTRIBUTE ::= 26128 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 26129 26130INPUT_OPERAND_LIST ::= 26131 [PREFIX.]No_Input_Operands 26132| INPUT_OPERAND_ATTRIBUTE 26133| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 26134 26135INPUT_OPERAND_ATTRIBUTE ::= 26136 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 26137@end example 26138 26139The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 26140are declared in the package @code{Machine_Code} and must be referenced 26141according to normal visibility rules. In particular if there is no 26142@code{use} clause for this package, then appropriate package name 26143qualification is required. 26144 26145@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features 26146@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} 26147@section GNAT Implementation of Tasking 26148 26149 26150This chapter outlines the basic GNAT approach to tasking (in particular, 26151a multi-layered library for portability) and discusses issues related 26152to compliance with the Real-Time Systems Annex. 26153 26154@menu 26155* Mapping Ada Tasks onto the Underlying Kernel Threads:: 26156* Ensuring Compliance with the Real-Time Annex:: 26157* Support for Locking Policies:: 26158 26159@end menu 26160 26161@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking 26162@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} 26163@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 26164 26165 26166GNAT’s run-time support comprises two layers: 26167 26168 26169@itemize * 26170 26171@item 26172GNARL (GNAT Run-time Layer) 26173 26174@item 26175GNULL (GNAT Low-level Library) 26176@end itemize 26177 26178In GNAT, Ada’s tasking services rely on a platform and OS independent 26179layer known as GNARL. This code is responsible for implementing the 26180correct semantics of Ada’s task creation, rendezvous, protected 26181operations etc. 26182 26183GNARL decomposes Ada’s tasking semantics into simpler lower level 26184operations such as create a thread, set the priority of a thread, 26185yield, create a lock, lock/unlock, etc. The spec for these low-level 26186operations constitutes GNULLI, the GNULL Interface. This interface is 26187directly inspired from the POSIX real-time API. 26188 26189If the underlying executive or OS implements the POSIX standard 26190faithfully, the GNULL Interface maps as is to the services offered by 26191the underlying kernel. Otherwise, some target dependent glue code maps 26192the services offered by the underlying kernel to the semantics expected 26193by GNARL. 26194 26195Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 26196key point is that each Ada task is mapped on a thread in the underlying 26197kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 26198 26199In addition Ada task priorities map onto the underlying thread priorities. 26200Mapping Ada tasks onto the underlying kernel threads has several advantages: 26201 26202 26203@itemize * 26204 26205@item 26206The underlying scheduler is used to schedule the Ada tasks. This 26207makes Ada tasks as efficient as kernel threads from a scheduling 26208standpoint. 26209 26210@item 26211Interaction with code written in C containing threads is eased 26212since at the lowest level Ada tasks and C threads map onto the same 26213underlying kernel concept. 26214 26215@item 26216When an Ada task is blocked during I/O the remaining Ada tasks are 26217able to proceed. 26218 26219@item 26220On multiprocessor systems Ada tasks can execute in parallel. 26221@end itemize 26222 26223Some threads libraries offer a mechanism to fork a new process, with the 26224child process duplicating the threads from the parent. 26225GNAT does not 26226support this functionality when the parent contains more than one task. 26227 26228@geindex Forking a new process 26229 26230@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking 26231@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} 26232@subsection Ensuring Compliance with the Real-Time Annex 26233 26234 26235@geindex Real-Time Systems Annex compliance 26236 26237Although mapping Ada tasks onto 26238the underlying threads has significant advantages, it does create some 26239complications when it comes to respecting the scheduling semantics 26240specified in the real-time annex (Annex D). 26241 26242For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 26243scheduling policy states: 26244 26245@quotation 26246 26247@emph{When the active priority of a ready task that is not running 26248changes, or the setting of its base priority takes effect, the 26249task is removed from the ready queue for its old active priority 26250and is added at the tail of the ready queue for its new active 26251priority, except in the case where the active priority is lowered 26252due to the loss of inherited priority, in which case the task is 26253added at the head of the ready queue for its new active priority.} 26254@end quotation 26255 26256While most kernels do put tasks at the end of the priority queue when 26257a task changes its priority, (which respects the main 26258FIFO_Within_Priorities requirement), almost none keep a thread at the 26259beginning of its priority queue when its priority drops from the loss 26260of inherited priority. 26261 26262As a result most vendors have provided incomplete Annex D implementations. 26263 26264The GNAT run-time, has a nice cooperative solution to this problem 26265which ensures that accurate FIFO_Within_Priorities semantics are 26266respected. 26267 26268The principle is as follows. When an Ada task T is about to start 26269running, it checks whether some other Ada task R with the same 26270priority as T has been suspended due to the loss of priority 26271inheritance. If this is the case, T yields and is placed at the end of 26272its priority queue. When R arrives at the front of the queue it 26273executes. 26274 26275Note that this simple scheme preserves the relative order of the tasks 26276that were ready to execute in the priority queue where R has been 26277placed at the end. 26278 26279@c Support_for_Locking_Policies 26280 26281@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking 26282@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{424} 26283@subsection Support for Locking Policies 26284 26285 26286This section specifies which policies specified by pragma Locking_Policy 26287are supported on which platforms. 26288 26289GNAT supports the standard @code{Ceiling_Locking} policy, and the 26290implementation defined @code{Inheritance_Locking} and 26291@code{Concurrent_Readers_Locking} policies. 26292 26293@code{Ceiling_Locking} is supported on all platforms if the operating system 26294supports it. In particular, @code{Ceiling_Locking} is not supported on 26295VxWorks. 26296@code{Inheritance_Locking} is supported on 26297Linux, 26298Darwin (Mac OS X), 26299LynxOS 178, 26300and VxWorks. 26301@code{Concurrent_Readers_Locking} is supported on Linux. 26302 26303Notes about @code{Ceiling_Locking} on Linux: 26304If the process is running as ‘root’, ceiling locking is used. 26305If the capabilities facility is installed 26306(“sudo apt-get –assume-yes install libcap-dev” on Ubuntu, 26307for example), 26308and the program is linked against that library 26309(“-largs -lcap”), 26310and the executable file has the cap_sys_nice capability 26311(“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”), 26312then ceiling locking is used. 26313Otherwise, the @code{Ceiling_Locking} policy is ignored. 26314 26315@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features 26316@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} 26317@section GNAT Implementation of Shared Passive Packages 26318 26319 26320@geindex Shared passive packages 26321 26322GNAT fully implements the 26323@geindex pragma Shared_Passive 26324pragma 26325@code{Shared_Passive} for 26326the purpose of designating shared passive packages. 26327This allows the use of passive partitions in the 26328context described in the Ada Reference Manual; i.e., for communication 26329between separate partitions of a distributed application using the 26330features in Annex E. 26331 26332@geindex Annex E 26333 26334@geindex Distribution Systems Annex 26335 26336However, the implementation approach used by GNAT provides for more 26337extensive usage as follows: 26338 26339 26340@table @asis 26341 26342@item @emph{Communication between separate programs} 26343 26344This allows separate programs to access the data in passive 26345partitions, using protected objects for synchronization where 26346needed. The only requirement is that the two programs have a 26347common shared file system. It is even possible for programs 26348running on different machines with different architectures 26349(e.g., different endianness) to communicate via the data in 26350a passive partition. 26351 26352@item @emph{Persistence between program runs} 26353 26354The data in a passive package can persist from one run of a 26355program to another, so that a later program sees the final 26356values stored by a previous run of the same program. 26357@end table 26358 26359The implementation approach used is to store the data in files. A 26360separate stream file is created for each object in the package, and 26361an access to an object causes the corresponding file to be read or 26362written. 26363 26364@geindex SHARED_MEMORY_DIRECTORY environment variable 26365 26366The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 26367set to the directory to be used for these files. 26368The files in this directory 26369have names that correspond to their fully qualified names. For 26370example, if we have the package 26371 26372@example 26373package X is 26374 pragma Shared_Passive (X); 26375 Y : Integer; 26376 Z : Float; 26377end X; 26378@end example 26379 26380and the environment variable is set to @code{/stemp/}, then the files created 26381will have the names: 26382 26383@example 26384/stemp/x.y 26385/stemp/x.z 26386@end example 26387 26388These files are created when a value is initially written to the object, and 26389the files are retained until manually deleted. This provides the persistence 26390semantics. If no file exists, it means that no partition has assigned a value 26391to the variable; in this case the initial value declared in the package 26392will be used. This model ensures that there are no issues in synchronizing 26393the elaboration process, since elaboration of passive packages elaborates the 26394initial values, but does not create the files. 26395 26396The files are written using normal @code{Stream_IO} access. 26397If you want to be able 26398to communicate between programs or partitions running on different 26399architectures, then you should use the XDR versions of the stream attribute 26400routines, since these are architecture independent. 26401 26402If active synchronization is required for access to the variables in the 26403shared passive package, then as described in the Ada Reference Manual, the 26404package may contain protected objects used for this purpose. In this case 26405a lock file (whose name is @code{___lock} (three underscores) 26406is created in the shared memory directory. 26407 26408@geindex ___lock file (for shared passive packages) 26409 26410This is used to provide the required locking 26411semantics for proper protected object synchronization. 26412 26413@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 26414@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} 26415@section Code Generation for Array Aggregates 26416 26417 26418Aggregates have a rich syntax and allow the user to specify the values of 26419complex data structures by means of a single construct. As a result, the 26420code generated for aggregates can be quite complex and involve loops, case 26421statements and multiple assignments. In the simplest cases, however, the 26422compiler will recognize aggregates whose components and constraints are 26423fully static, and in those cases the compiler will generate little or no 26424executable code. The following is an outline of the code that GNAT generates 26425for various aggregate constructs. For further details, you will find it 26426useful to examine the output produced by the -gnatG flag to see the expanded 26427source that is input to the code generator. You may also want to examine 26428the assembly code generated at various levels of optimization. 26429 26430The code generated for aggregates depends on the context, the component values, 26431and the type. In the context of an object declaration the code generated is 26432generally simpler than in the case of an assignment. As a general rule, static 26433component values and static subtypes also lead to simpler code. 26434 26435@menu 26436* Static constant aggregates with static bounds:: 26437* Constant aggregates with unconstrained nominal types:: 26438* Aggregates with static bounds:: 26439* Aggregates with nonstatic bounds:: 26440* Aggregates in assignment statements:: 26441 26442@end menu 26443 26444@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates 26445@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} 26446@subsection Static constant aggregates with static bounds 26447 26448 26449For the declarations: 26450 26451@example 26452type One_Dim is array (1..10) of integer; 26453ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 26454@end example 26455 26456GNAT generates no executable code: the constant ar0 is placed in static memory. 26457The same is true for constant aggregates with named associations: 26458 26459@example 26460Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 26461Cr3 : constant One_Dim := (others => 7777); 26462@end example 26463 26464The same is true for multidimensional constant arrays such as: 26465 26466@example 26467type two_dim is array (1..3, 1..3) of integer; 26468Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 26469@end example 26470 26471The same is true for arrays of one-dimensional arrays: the following are 26472static: 26473 26474@example 26475type ar1b is array (1..3) of boolean; 26476type ar_ar is array (1..3) of ar1b; 26477None : constant ar1b := (others => false); -- fully static 26478None2 : constant ar_ar := (1..3 => None); -- fully static 26479@end example 26480 26481However, for multidimensional aggregates with named associations, GNAT will 26482generate assignments and loops, even if all associations are static. The 26483following two declarations generate a loop for the first dimension, and 26484individual component assignments for the second dimension: 26485 26486@example 26487Zero1: constant two_dim := (1..3 => (1..3 => 0)); 26488Zero2: constant two_dim := (others => (others => 0)); 26489@end example 26490 26491@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates 26492@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} 26493@subsection Constant aggregates with unconstrained nominal types 26494 26495 26496In such cases the aggregate itself establishes the subtype, so that 26497associations with @code{others} cannot be used. GNAT determines the 26498bounds for the actual subtype of the aggregate, and allocates the 26499aggregate statically as well. No code is generated for the following: 26500 26501@example 26502type One_Unc is array (natural range <>) of integer; 26503Cr_Unc : constant One_Unc := (12,24,36); 26504@end example 26505 26506@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates 26507@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} 26508@subsection Aggregates with static bounds 26509 26510 26511In all previous examples the aggregate was the initial (and immutable) value 26512of a constant. If the aggregate initializes a variable, then code is generated 26513for it as a combination of individual assignments and loops over the target 26514object. The declarations 26515 26516@example 26517Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 26518Cr_Var2 : One_Dim := (others > -1); 26519@end example 26520 26521generate the equivalent of 26522 26523@example 26524Cr_Var1 (1) := 2; 26525Cr_Var1 (2) := 3; 26526Cr_Var1 (3) := 5; 26527Cr_Var1 (4) := 11; 26528 26529for I in Cr_Var2'range loop 26530 Cr_Var2 (I) := -1; 26531end loop; 26532@end example 26533 26534@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates 26535@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} 26536@subsection Aggregates with nonstatic bounds 26537 26538 26539If the bounds of the aggregate are not statically compatible with the bounds 26540of the nominal subtype of the target, then constraint checks have to be 26541generated on the bounds. For a multidimensional array, constraint checks may 26542have to be applied to sub-arrays individually, if they do not have statically 26543compatible subtypes. 26544 26545@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates 26546@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} 26547@subsection Aggregates in assignment statements 26548 26549 26550In general, aggregate assignment requires the construction of a temporary, 26551and a copy from the temporary to the target of the assignment. This is because 26552it is not always possible to convert the assignment into a series of individual 26553component assignments. For example, consider the simple case: 26554 26555@example 26556A := (A(2), A(1)); 26557@end example 26558 26559This cannot be converted into: 26560 26561@example 26562A(1) := A(2); 26563A(2) := A(1); 26564@end example 26565 26566So the aggregate has to be built first in a separate location, and then 26567copied into the target. GNAT recognizes simple cases where this intermediate 26568step is not required, and the assignments can be performed in place, directly 26569into the target. The following sufficient criteria are applied: 26570 26571 26572@itemize * 26573 26574@item 26575The bounds of the aggregate are static, and the associations are static. 26576 26577@item 26578The components of the aggregate are static constants, names of 26579simple variables that are not renamings, or expressions not involving 26580indexed components whose operands obey these rules. 26581@end itemize 26582 26583If any of these conditions are violated, the aggregate will be built in 26584a temporary (created either by the front-end or the code generator) and then 26585that temporary will be copied onto the target. 26586 26587@node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features 26588@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} 26589@section The Size of Discriminated Records with Default Discriminants 26590 26591 26592If a discriminated type @code{T} has discriminants with default values, it is 26593possible to declare an object of this type without providing an explicit 26594constraint: 26595 26596@example 26597type Size is range 1..100; 26598 26599type Rec (D : Size := 15) is record 26600 Name : String (1..D); 26601end T; 26602 26603Word : Rec; 26604@end example 26605 26606Such an object is said to be @emph{unconstrained}. 26607The discriminant of the object 26608can be modified by a full assignment to the object, as long as it preserves the 26609relation between the value of the discriminant, and the value of the components 26610that depend on it: 26611 26612@example 26613Word := (3, "yes"); 26614 26615Word := (5, "maybe"); 26616 26617Word := (5, "no"); -- raises Constraint_Error 26618@end example 26619 26620In order to support this behavior efficiently, an unconstrained object is 26621given the maximum size that any value of the type requires. In the case 26622above, @code{Word} has storage for the discriminant and for 26623a @code{String} of length 100. 26624It is important to note that unconstrained objects do not require dynamic 26625allocation. It would be an improper implementation to place on the heap those 26626components whose size depends on discriminants. (This improper implementation 26627was used by some Ada83 compilers, where the @code{Name} component above 26628would have 26629been stored as a pointer to a dynamic string). Following the principle that 26630dynamic storage management should never be introduced implicitly, 26631an Ada compiler should reserve the full size for an unconstrained declared 26632object, and place it on the stack. 26633 26634This maximum size approach 26635has been a source of surprise to some users, who expect the default 26636values of the discriminants to determine the size reserved for an 26637unconstrained object: “If the default is 15, why should the object occupy 26638a larger size?” 26639The answer, of course, is that the discriminant may be later modified, 26640and its full range of values must be taken into account. This is why the 26641declaration: 26642 26643@example 26644type Rec (D : Positive := 15) is record 26645 Name : String (1..D); 26646end record; 26647 26648Too_Large : Rec; 26649@end example 26650 26651is flagged by the compiler with a warning: 26652an attempt to create @code{Too_Large} will raise @code{Storage_Error}, 26653because the required size includes @code{Positive'Last} 26654bytes. As the first example indicates, the proper approach is to declare an 26655index type of ‘reasonable’ range so that unconstrained objects are not too 26656large. 26657 26658One final wrinkle: if the object is declared to be @code{aliased}, or if it is 26659created in the heap by means of an allocator, then it is @emph{not} 26660unconstrained: 26661it is constrained by the default values of the discriminants, and those values 26662cannot be modified by full assignment. This is because in the presence of 26663aliasing all views of the object (which may be manipulated by different tasks, 26664say) must be consistent, so it is imperative that the object, once created, 26665remain invariant. 26666 26667@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 26668@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} 26669@section Image Values For Nonscalar Types 26670 26671 26672Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes 26673for nonscalar types; earlier Ada versions defined these attributes only 26674for scalar types. Ada RM 4.10 provides some general guidance regarding 26675the default implementation of these attributes and the GNAT compiler 26676follows that guidance. However, beyond that the precise details of the 26677image text generated in these cases are deliberately not documented and are 26678subject to change. In particular, users should not rely on formatting details 26679(such as spaces or line breaking), record field order, image values for access 26680types, image values for types that have ancestor or subcomponent types 26681declared in non-Ada2022 code, image values for predefined types, or the 26682compiler’s choices regarding the implementation permissions described in 26683Ada RM 4.10. This list is not intended to be exhaustive. If more precise 26684control of image text is required for some type T, then T’Put_Image should be 26685explicitly specified. 26686 26687@node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features 26688@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} 26689@section Strict Conformance to the Ada Reference Manual 26690 26691 26692The dynamic semantics defined by the Ada Reference Manual impose a set of 26693run-time checks to be generated. By default, the GNAT compiler will insert many 26694run-time checks into the compiled code, including most of those required by the 26695Ada Reference Manual. However, there are two checks that are not enabled in 26696the default mode for efficiency reasons: checks for access before elaboration 26697on subprogram calls, and stack overflow checking (most operating systems do not 26698perform this check by default). 26699 26700Strict conformance to the Ada Reference Manual can be achieved by adding two 26701compiler options for dynamic checks for access-before-elaboration on subprogram 26702calls and generic instantiations (@emph{-gnatE}), and stack overflow checking 26703(@emph{-fstack-check}). 26704 26705Note that the result of a floating point arithmetic operation in overflow and 26706invalid situations, when the @code{Machine_Overflows} attribute of the result 26707type is @code{False}, is to generate IEEE NaN and infinite values. This is the 26708case for machines compliant with the IEEE floating-point standard, but on 26709machines that are not fully compliant with this standard, such as Alpha, the 26710@emph{-mieee} compiler flag must be used for achieving IEEE confirming 26711behavior (although at the cost of a significant performance penalty), so 26712infinite and NaN values are properly generated. 26713 26714@node Implementation of Ada 2012 Features,Security Hardening Features,Implementation of Specific Ada Features,Top 26715@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} 26716@chapter Implementation of Ada 2012 Features 26717 26718 26719@geindex Ada 2012 implementation status 26720 26721@geindex -gnat12 option (gcc) 26722 26723@geindex pragma Ada_2012 26724 26725@geindex configuration pragma Ada_2012 26726 26727@geindex Ada_2012 configuration pragma 26728 26729This chapter contains a complete list of Ada 2012 features that have been 26730implemented. 26731Generally, these features are only 26732available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, 26733which is the default behavior, 26734or if the configuration pragma @code{Ada_2012} is used. 26735 26736However, new pragmas, attributes, and restrictions are 26737unconditionally available, since the Ada 95 standard allows the addition of 26738new pragmas, attributes, and restrictions (there are exceptions, which are 26739documented in the individual descriptions), and also certain packages 26740were made available in earlier versions of Ada. 26741 26742An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 26743This date shows the implementation date of the feature. Any wavefront 26744subsequent to this date will contain the indicated feature, as will any 26745subsequent releases. A date of 0000-00-00 means that GNAT has always 26746implemented the feature, or implemented it as soon as it appeared as a 26747binding interpretation. 26748 26749Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada 26750standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 26751The features are ordered based on the relevant sections of the Ada 26752Reference Manual (“RM”). When a given AI relates to multiple points 26753in the RM, the earliest is used. 26754 26755A complete description of the AIs may be found in 26756@indicateurl{http://www.ada-auth.org/ai05-summary.html}. 26757 26758@geindex AI-0176 (Ada 2012 feature) 26759 26760 26761@itemize * 26762 26763@item 26764@emph{AI-0176 Quantified expressions (2010-09-29)} 26765 26766Both universally and existentially quantified expressions are implemented. 26767They use the new syntax for iterators proposed in AI05-139-2, as well as 26768the standard Ada loop syntax. 26769 26770RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 26771@end itemize 26772 26773@geindex AI-0079 (Ada 2012 feature) 26774 26775 26776@itemize * 26777 26778@item 26779@emph{AI-0079 Allow other_format characters in source (2010-07-10)} 26780 26781Wide characters in the unicode category @emph{other_format} are now allowed in 26782source programs between tokens, but not within a token such as an identifier. 26783 26784RM References: 2.01 (4/2) 2.02 (7) 26785@end itemize 26786 26787@geindex AI-0091 (Ada 2012 feature) 26788 26789 26790@itemize * 26791 26792@item 26793@emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} 26794 26795Wide characters in the unicode category @emph{other_format} are not permitted 26796within an identifier, since this can be a security problem. The error 26797message for this case has been improved to be more specific, but GNAT has 26798never allowed such characters to appear in identifiers. 26799 26800RM 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) 26801@end itemize 26802 26803@geindex AI-0100 (Ada 2012 feature) 26804 26805 26806@itemize * 26807 26808@item 26809@emph{AI-0100 Placement of pragmas (2010-07-01)} 26810 26811This AI is an earlier version of AI-163. It simplifies the rules 26812for legal placement of pragmas. In the case of lists that allow pragmas, if 26813the list may have no elements, then the list may consist solely of pragmas. 26814 26815RM References: 2.08 (7) 26816@end itemize 26817 26818@geindex AI-0163 (Ada 2012 feature) 26819 26820 26821@itemize * 26822 26823@item 26824@emph{AI-0163 Pragmas in place of null (2010-07-01)} 26825 26826A statement sequence may be composed entirely of pragmas. It is no longer 26827necessary to add a dummy @code{null} statement to make the sequence legal. 26828 26829RM References: 2.08 (7) 2.08 (16) 26830@end itemize 26831 26832@geindex AI-0080 (Ada 2012 feature) 26833 26834 26835@itemize * 26836 26837@item 26838@emph{AI-0080 ‘View of’ not needed if clear from context (0000-00-00)} 26839 26840This is an editorial change only, described as non-testable in the AI. 26841 26842RM References: 3.01 (7) 26843@end itemize 26844 26845@geindex AI-0183 (Ada 2012 feature) 26846 26847 26848@itemize * 26849 26850@item 26851@emph{AI-0183 Aspect specifications (2010-08-16)} 26852 26853Aspect specifications have been fully implemented except for pre and post- 26854conditions, and type invariants, which have their own separate AI’s. All 26855forms of declarations listed in the AI are supported. The following is a 26856list of the aspects supported (with GNAT implementation aspects marked) 26857@end itemize 26858 26859 26860@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 26861@headitem 26862 26863Supported Aspect 26864 26865@tab 26866 26867Source 26868 26869@item 26870 26871@code{Ada_2005} 26872 26873@tab 26874 26875– GNAT 26876 26877@item 26878 26879@code{Ada_2012} 26880 26881@tab 26882 26883– GNAT 26884 26885@item 26886 26887@code{Address} 26888 26889@tab 26890 26891@item 26892 26893@code{Alignment} 26894 26895@tab 26896 26897@item 26898 26899@code{Atomic} 26900 26901@tab 26902 26903@item 26904 26905@code{Atomic_Components} 26906 26907@tab 26908 26909@item 26910 26911@code{Bit_Order} 26912 26913@tab 26914 26915@item 26916 26917@code{Component_Size} 26918 26919@tab 26920 26921@item 26922 26923@code{Contract_Cases} 26924 26925@tab 26926 26927– GNAT 26928 26929@item 26930 26931@code{Discard_Names} 26932 26933@tab 26934 26935@item 26936 26937@code{External_Tag} 26938 26939@tab 26940 26941@item 26942 26943@code{Favor_Top_Level} 26944 26945@tab 26946 26947– GNAT 26948 26949@item 26950 26951@code{Inline} 26952 26953@tab 26954 26955@item 26956 26957@code{Inline_Always} 26958 26959@tab 26960 26961– GNAT 26962 26963@item 26964 26965@code{Invariant} 26966 26967@tab 26968 26969– GNAT 26970 26971@item 26972 26973@code{Machine_Radix} 26974 26975@tab 26976 26977@item 26978 26979@code{No_Return} 26980 26981@tab 26982 26983@item 26984 26985@code{Object_Size} 26986 26987@tab 26988 26989– GNAT 26990 26991@item 26992 26993@code{Pack} 26994 26995@tab 26996 26997@item 26998 26999@code{Persistent_BSS} 27000 27001@tab 27002 27003– GNAT 27004 27005@item 27006 27007@code{Post} 27008 27009@tab 27010 27011@item 27012 27013@code{Pre} 27014 27015@tab 27016 27017@item 27018 27019@code{Predicate} 27020 27021@tab 27022 27023@item 27024 27025@code{Preelaborable_Initialization} 27026 27027@tab 27028 27029@item 27030 27031@code{Pure_Function} 27032 27033@tab 27034 27035– GNAT 27036 27037@item 27038 27039@code{Remote_Access_Type} 27040 27041@tab 27042 27043– GNAT 27044 27045@item 27046 27047@code{Shared} 27048 27049@tab 27050 27051– GNAT 27052 27053@item 27054 27055@code{Size} 27056 27057@tab 27058 27059@item 27060 27061@code{Storage_Pool} 27062 27063@tab 27064 27065@item 27066 27067@code{Storage_Size} 27068 27069@tab 27070 27071@item 27072 27073@code{Stream_Size} 27074 27075@tab 27076 27077@item 27078 27079@code{Suppress} 27080 27081@tab 27082 27083@item 27084 27085@code{Suppress_Debug_Info} 27086 27087@tab 27088 27089– GNAT 27090 27091@item 27092 27093@code{Test_Case} 27094 27095@tab 27096 27097– GNAT 27098 27099@item 27100 27101@code{Thread_Local_Storage} 27102 27103@tab 27104 27105– GNAT 27106 27107@item 27108 27109@code{Type_Invariant} 27110 27111@tab 27112 27113@item 27114 27115@code{Unchecked_Union} 27116 27117@tab 27118 27119@item 27120 27121@code{Universal_Aliasing} 27122 27123@tab 27124 27125– GNAT 27126 27127@item 27128 27129@code{Unmodified} 27130 27131@tab 27132 27133– GNAT 27134 27135@item 27136 27137@code{Unreferenced} 27138 27139@tab 27140 27141– GNAT 27142 27143@item 27144 27145@code{Unreferenced_Objects} 27146 27147@tab 27148 27149– GNAT 27150 27151@item 27152 27153@code{Unsuppress} 27154 27155@tab 27156 27157@item 27158 27159@code{Value_Size} 27160 27161@tab 27162 27163– GNAT 27164 27165@item 27166 27167@code{Volatile} 27168 27169@tab 27170 27171@item 27172 27173@code{Volatile_Components} 27174 27175@tab 27176 27177@item 27178 27179@code{Warnings} 27180 27181@tab 27182 27183– GNAT 27184 27185@end multitable 27186 27187 27188@quotation 27189 27190Note that for aspects with an expression, e.g. @code{Size}, the expression is 27191treated like a default expression (visibility is analyzed at the point of 27192occurrence of the aspect, but evaluation of the expression occurs at the 27193freeze point of the entity involved). 27194 27195RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 271963.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 27197(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 271989.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 2719912.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 2720013.03.01 (0) 27201@end quotation 27202 27203@geindex AI-0128 (Ada 2012 feature) 27204 27205 27206@itemize * 27207 27208@item 27209@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 27210 27211If an equality operator (“=”) is declared for a type, then the implicitly 27212declared inequality operator (“/=”) is a primitive operation of the type. 27213This is the only reasonable interpretation, and is the one always implemented 27214by GNAT, but the RM was not entirely clear in making this point. 27215 27216RM References: 3.02.03 (6) 6.06 (6) 27217@end itemize 27218 27219@geindex AI-0003 (Ada 2012 feature) 27220 27221 27222@itemize * 27223 27224@item 27225@emph{AI-0003 Qualified expressions as names (2010-07-11)} 27226 27227In Ada 2012, a qualified expression is considered to be syntactically a name, 27228meaning that constructs such as @code{A'(F(X)).B} are now legal. This is 27229useful in disambiguating some cases of overloading. 27230 27231RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 272325.04 (7) 27233@end itemize 27234 27235@geindex AI-0120 (Ada 2012 feature) 27236 27237 27238@itemize * 27239 27240@item 27241@emph{AI-0120 Constant instance of protected object (0000-00-00)} 27242 27243This is an RM editorial change only. The section that lists objects that are 27244constant failed to include the current instance of a protected object 27245within a protected function. This has always been treated as a constant 27246in GNAT. 27247 27248RM References: 3.03 (21) 27249@end itemize 27250 27251@geindex AI-0008 (Ada 2012 feature) 27252 27253 27254@itemize * 27255 27256@item 27257@emph{AI-0008 General access to constrained objects (0000-00-00)} 27258 27259The wording in the RM implied that if you have a general access to a 27260constrained object, it could be used to modify the discriminants. This was 27261obviously not intended. @code{Constraint_Error} should be raised, and GNAT 27262has always done so in this situation. 27263 27264RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 27265@end itemize 27266 27267@geindex AI-0093 (Ada 2012 feature) 27268 27269 27270@itemize * 27271 27272@item 27273@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 27274 27275This is an editorial change only, to make more widespread use of the Ada 2012 27276‘immutably limited’. 27277 27278RM References: 3.03 (23.4/3) 27279@end itemize 27280 27281@geindex AI-0096 (Ada 2012 feature) 27282 27283 27284@itemize * 27285 27286@item 27287@emph{AI-0096 Deriving from formal private types (2010-07-20)} 27288 27289In general it is illegal for a type derived from a formal limited type to be 27290nonlimited. This AI makes an exception to this rule: derivation is legal 27291if it appears in the private part of the generic, and the formal type is not 27292tagged. If the type is tagged, the legality check must be applied to the 27293private part of the package. 27294 27295RM References: 3.04 (5.1/2) 6.02 (7) 27296@end itemize 27297 27298@geindex AI-0181 (Ada 2012 feature) 27299 27300 27301@itemize * 27302 27303@item 27304@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 27305 27306From Ada 2005 on, soft hyphen is considered a non-graphic character, which 27307means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the 27308@code{Image} and @code{Value} attributes for the character types. Strictly 27309speaking this is an inconsistency with Ada 95, but in practice the use of 27310these attributes is so obscure that it will not cause problems. 27311 27312RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 27313@end itemize 27314 27315@geindex AI-0182 (Ada 2012 feature) 27316 27317 27318@itemize * 27319 27320@item 27321@emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)} 27322 27323This AI allows @code{Character'Value} to accept the string @code{'?'} where 27324@code{?} is any character including non-graphic control characters. GNAT has 27325always accepted such strings. It also allows strings such as 27326@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this 27327permission and raises @code{Constraint_Error}, as is certainly still 27328permitted. 27329 27330RM References: 3.05 (56/2) 27331@end itemize 27332 27333@geindex AI-0214 (Ada 2012 feature) 27334 27335 27336@itemize * 27337 27338@item 27339@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 27340 27341Ada 2012 relaxes the restriction that forbids discriminants of tagged types 27342to have default expressions by allowing them when the type is limited. It 27343is often useful to define a default value for a discriminant even though 27344it can’t be changed by assignment. 27345 27346RM References: 3.07 (9.1/2) 3.07.02 (3) 27347@end itemize 27348 27349@geindex AI-0102 (Ada 2012 feature) 27350 27351 27352@itemize * 27353 27354@item 27355@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 27356 27357It is illegal to assign an anonymous access constant to an anonymous access 27358variable. The RM did not have a clear rule to prevent this, but GNAT has 27359always generated an error for this usage. 27360 27361RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 27362@end itemize 27363 27364@geindex AI-0158 (Ada 2012 feature) 27365 27366 27367@itemize * 27368 27369@item 27370@emph{AI-0158 Generalizing membership tests (2010-09-16)} 27371 27372This AI extends the syntax of membership tests to simplify complex conditions 27373that can be expressed as membership in a subset of values of any type. It 27374introduces syntax for a list of expressions that may be used in loop contexts 27375as well. 27376 27377RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 27378@end itemize 27379 27380@geindex AI-0173 (Ada 2012 feature) 27381 27382 27383@itemize * 27384 27385@item 27386@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 27387 27388The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked 27389with the tag of an abstract type, and @code{False} otherwise. 27390 27391RM References: 3.09 (7.4/2) 3.09 (12.4/2) 27392@end itemize 27393 27394@geindex AI-0076 (Ada 2012 feature) 27395 27396 27397@itemize * 27398 27399@item 27400@emph{AI-0076 function with controlling result (0000-00-00)} 27401 27402This is an editorial change only. The RM defines calls with controlling 27403results, but uses the term ‘function with controlling result’ without an 27404explicit definition. 27405 27406RM References: 3.09.02 (2/2) 27407@end itemize 27408 27409@geindex AI-0126 (Ada 2012 feature) 27410 27411 27412@itemize * 27413 27414@item 27415@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 27416 27417This AI clarifies dispatching rules, and simply confirms that dispatching 27418executes the operation of the parent type when there is no explicitly or 27419implicitly declared operation for the descendant type. This has always been 27420the case in all versions of GNAT. 27421 27422RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 27423@end itemize 27424 27425@geindex AI-0097 (Ada 2012 feature) 27426 27427 27428@itemize * 27429 27430@item 27431@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 27432 27433The RM as written implied that in some cases it was possible to create an 27434object of an abstract type, by having an abstract extension inherit a non- 27435abstract constructor from its parent type. This mistake has been corrected 27436in GNAT and in the RM, and this construct is now illegal. 27437 27438RM References: 3.09.03 (4/2) 27439@end itemize 27440 27441@geindex AI-0203 (Ada 2012 feature) 27442 27443 27444@itemize * 27445 27446@item 27447@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 27448 27449A return_subtype_indication cannot denote an abstract subtype. GNAT has never 27450permitted such usage. 27451 27452RM References: 3.09.03 (8/3) 27453@end itemize 27454 27455@geindex AI-0198 (Ada 2012 feature) 27456 27457 27458@itemize * 27459 27460@item 27461@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 27462 27463This AI resolves a conflict between two rules involving inherited abstract 27464operations and predefined operators. If a derived numeric type inherits 27465an abstract operator, it overrides the predefined one. This interpretation 27466was always the one implemented in GNAT. 27467 27468RM References: 3.09.03 (4/3) 27469@end itemize 27470 27471@geindex AI-0073 (Ada 2012 feature) 27472 27473 27474@itemize * 27475 27476@item 27477@emph{AI-0073 Functions returning abstract types (2010-07-10)} 27478 27479This AI covers a number of issues regarding returning abstract types. In 27480particular generic functions cannot have abstract result types or access 27481result types designated an abstract type. There are some other cases which 27482are detailed in the AI. Note that this binding interpretation has not been 27483retrofitted to operate before Ada 2012 mode, since it caused a significant 27484number of regressions. 27485 27486RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 27487@end itemize 27488 27489@geindex AI-0070 (Ada 2012 feature) 27490 27491 27492@itemize * 27493 27494@item 27495@emph{AI-0070 Elaboration of interface types (0000-00-00)} 27496 27497This is an editorial change only, there are no testable consequences short of 27498checking for the absence of generated code for an interface declaration. 27499 27500RM References: 3.09.04 (18/2) 27501@end itemize 27502 27503@geindex AI-0208 (Ada 2012 feature) 27504 27505 27506@itemize * 27507 27508@item 27509@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 27510 27511The wording in the Ada 2005 RM concerning characteristics of incomplete views 27512was incorrect and implied that some programs intended to be legal were now 27513illegal. GNAT had never considered such programs illegal, so it has always 27514implemented the intent of this AI. 27515 27516RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 27517@end itemize 27518 27519@geindex AI-0162 (Ada 2012 feature) 27520 27521 27522@itemize * 27523 27524@item 27525@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 27526 27527Incomplete types are made more useful by allowing them to be completed by 27528private types and private extensions. 27529 27530RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 27531@end itemize 27532 27533@geindex AI-0098 (Ada 2012 feature) 27534 27535 27536@itemize * 27537 27538@item 27539@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 27540 27541An unintentional omission in the RM implied some inconsistent restrictions on 27542the use of anonymous access to subprogram values. These restrictions were not 27543intentional, and have never been enforced by GNAT. 27544 27545RM References: 3.10.01 (6) 3.10.01 (9.2/2) 27546@end itemize 27547 27548@geindex AI-0199 (Ada 2012 feature) 27549 27550 27551@itemize * 27552 27553@item 27554@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 27555 27556A choice list in a record aggregate can include several components of 27557(distinct) anonymous access types as long as they have matching designated 27558subtypes. 27559 27560RM References: 4.03.01 (16) 27561@end itemize 27562 27563@geindex AI-0220 (Ada 2012 feature) 27564 27565 27566@itemize * 27567 27568@item 27569@emph{AI-0220 Needed components for aggregates (0000-00-00)} 27570 27571This AI addresses a wording problem in the RM that appears to permit some 27572complex cases of aggregates with nonstatic discriminants. GNAT has always 27573implemented the intended semantics. 27574 27575RM References: 4.03.01 (17) 27576@end itemize 27577 27578@geindex AI-0147 (Ada 2012 feature) 27579 27580 27581@itemize * 27582 27583@item 27584@emph{AI-0147 Conditional expressions (2009-03-29)} 27585 27586Conditional expressions are permitted. The form of such an expression is: 27587 27588@example 27589(if expr then expr @{elsif expr then expr@} [else expr]) 27590@end example 27591 27592The parentheses can be omitted in contexts where parentheses are present 27593anyway, such as subprogram arguments and pragma arguments. If the @strong{else} 27594clause is omitted, @strong{else} @emph{True} is assumed; 27595thus @code{(if A then B)} is a way to conveniently represent 27596@emph{(A implies B)} in standard logic. 27597 27598RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 275994.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 27600@end itemize 27601 27602@geindex AI-0037 (Ada 2012 feature) 27603 27604 27605@itemize * 27606 27607@item 27608@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 27609 27610This AI confirms that an association of the form @code{Indx => <>} in an 27611array aggregate must raise @code{Constraint_Error} if @code{Indx} 27612is out of range. The RM specified a range check on other associations, but 27613not when the value of the association was defaulted. GNAT has always inserted 27614a constraint check on the index value. 27615 27616RM References: 4.03.03 (29) 27617@end itemize 27618 27619@geindex AI-0123 (Ada 2012 feature) 27620 27621 27622@itemize * 27623 27624@item 27625@emph{AI-0123 Composability of equality (2010-04-13)} 27626 27627Equality of untagged record composes, so that the predefined equality for a 27628composite type that includes a component of some untagged record type 27629@code{R} uses the equality operation of @code{R} (which may be user-defined 27630or predefined). This makes the behavior of untagged records identical to that 27631of tagged types in this respect. 27632 27633This change is an incompatibility with previous versions of Ada, but it 27634corrects a non-uniformity that was often a source of confusion. Analysis of 27635a large number of industrial programs indicates that in those rare cases 27636where a composite type had an untagged record component with a user-defined 27637equality, either there was no use of the composite equality, or else the code 27638expected the same composability as for tagged types, and thus had a bug that 27639would be fixed by this change. 27640 27641RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 276428.05.04 (8) 27643@end itemize 27644 27645@geindex AI-0088 (Ada 2012 feature) 27646 27647 27648@itemize * 27649 27650@item 27651@emph{AI-0088 The value of exponentiation (0000-00-00)} 27652 27653This AI clarifies the equivalence rule given for the dynamic semantics of 27654exponentiation: the value of the operation can be obtained by repeated 27655multiplication, but the operation can be implemented otherwise (for example 27656using the familiar divide-by-two-and-square algorithm, even if this is less 27657accurate), and does not imply repeated reads of a volatile base. 27658 27659RM References: 4.05.06 (11) 27660@end itemize 27661 27662@geindex AI-0188 (Ada 2012 feature) 27663 27664 27665@itemize * 27666 27667@item 27668@emph{AI-0188 Case expressions (2010-01-09)} 27669 27670Case expressions are permitted. This allows use of constructs such as: 27671 27672@example 27673X := (case Y is when 1 => 2, when 2 => 3, when others => 31) 27674@end example 27675 27676RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 27677@end itemize 27678 27679@geindex AI-0104 (Ada 2012 feature) 27680 27681 27682@itemize * 27683 27684@item 27685@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 27686 27687The assignment @code{Ptr := new not null Some_Ptr;} will raise 27688@code{Constraint_Error} because the default value of the allocated object is 27689@strong{null}. This useless construct is illegal in Ada 2012. 27690 27691RM References: 4.08 (2) 27692@end itemize 27693 27694@geindex AI-0157 (Ada 2012 feature) 27695 27696 27697@itemize * 27698 27699@item 27700@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 27701 27702Allocation and Deallocation from an empty storage pool (i.e. allocation or 27703deallocation of a pointer for which a static storage size clause of zero 27704has been given) is now illegal and is detected as such. GNAT 27705previously gave a warning but not an error. 27706 27707RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 27708@end itemize 27709 27710@geindex AI-0179 (Ada 2012 feature) 27711 27712 27713@itemize * 27714 27715@item 27716@emph{AI-0179 Statement not required after label (2010-04-10)} 27717 27718It is not necessary to have a statement following a label, so a label 27719can appear at the end of a statement sequence without the need for putting a 27720null statement afterwards, but it is not allowable to have only labels and 27721no real statements in a statement sequence. 27722 27723RM References: 5.01 (2) 27724@end itemize 27725 27726@geindex AI-0139-2 (Ada 2012 feature) 27727 27728 27729@itemize * 27730 27731@item 27732@emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} 27733 27734The new syntax for iterating over arrays and containers is now implemented. 27735Iteration over containers is for now limited to read-only iterators. Only 27736default iterators are supported, with the syntax: @code{for Elem of C}. 27737 27738RM References: 5.05 27739@end itemize 27740 27741@geindex AI-0134 (Ada 2012 feature) 27742 27743 27744@itemize * 27745 27746@item 27747@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 27748 27749For full conformance, the profiles of anonymous-access-to-subprogram 27750parameters must match. GNAT has always enforced this rule. 27751 27752RM References: 6.03.01 (18) 27753@end itemize 27754 27755@geindex AI-0207 (Ada 2012 feature) 27756 27757 27758@itemize * 27759 27760@item 27761@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 27762 27763This AI confirms that access_to_constant indication must match for mode 27764conformance. This was implemented in GNAT when the qualifier was originally 27765introduced in Ada 2005. 27766 27767RM References: 6.03.01 (16/2) 27768@end itemize 27769 27770@geindex AI-0046 (Ada 2012 feature) 27771 27772 27773@itemize * 27774 27775@item 27776@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 27777 27778For full conformance, in the case of access parameters, the null exclusion 27779must match (either both or neither must have @code{not null}). 27780 27781RM References: 6.03.02 (18) 27782@end itemize 27783 27784@geindex AI-0118 (Ada 2012 feature) 27785 27786 27787@itemize * 27788 27789@item 27790@emph{AI-0118 The association of parameter associations (0000-00-00)} 27791 27792This AI clarifies the rules for named associations in subprogram calls and 27793generic instantiations. The rules have been in place since Ada 83. 27794 27795RM References: 6.04.01 (2) 12.03 (9) 27796@end itemize 27797 27798@geindex AI-0196 (Ada 2012 feature) 27799 27800 27801@itemize * 27802 27803@item 27804@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 27805 27806Null exclusion checks are not made for @code{out} parameters when 27807evaluating the actual parameters. GNAT has never generated these checks. 27808 27809RM References: 6.04.01 (13) 27810@end itemize 27811 27812@geindex AI-0015 (Ada 2012 feature) 27813 27814 27815@itemize * 27816 27817@item 27818@emph{AI-0015 Constant return objects (0000-00-00)} 27819 27820The return object declared in an @emph{extended_return_statement} may be 27821declared constant. This was always intended, and GNAT has always allowed it. 27822 27823RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 278246.05 (5.7/2) 27825@end itemize 27826 27827@geindex AI-0032 (Ada 2012 feature) 27828 27829 27830@itemize * 27831 27832@item 27833@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 27834 27835If a function returns a class-wide type, the object of an extended return 27836statement can be declared with a specific type that is covered by the class- 27837wide type. This has been implemented in GNAT since the introduction of 27838extended returns. Note AI-0103 complements this AI by imposing matching 27839rules for constrained return types. 27840 27841RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 278426.05 (8/2) 27843@end itemize 27844 27845@geindex AI-0103 (Ada 2012 feature) 27846 27847 27848@itemize * 27849 27850@item 27851@emph{AI-0103 Static matching for extended return (2010-07-23)} 27852 27853If the return subtype of a function is an elementary type or a constrained 27854type, the subtype indication in an extended return statement must match 27855statically this return subtype. 27856 27857RM References: 6.05 (5.2/2) 27858@end itemize 27859 27860@geindex AI-0058 (Ada 2012 feature) 27861 27862 27863@itemize * 27864 27865@item 27866@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 27867 27868The RM had some incorrect wording implying wrong treatment of abnormal 27869completion in an extended return. GNAT has always implemented the intended 27870correct semantics as described by this AI. 27871 27872RM References: 6.05 (22/2) 27873@end itemize 27874 27875@geindex AI-0050 (Ada 2012 feature) 27876 27877 27878@itemize * 27879 27880@item 27881@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 27882 27883The implementation permissions for raising @code{Constraint_Error} early on a function call 27884when it was clear an exception would be raised were over-permissive and allowed 27885mishandling of discriminants in some cases. GNAT did 27886not take advantage of these incorrect permissions in any case. 27887 27888RM References: 6.05 (24/2) 27889@end itemize 27890 27891@geindex AI-0125 (Ada 2012 feature) 27892 27893 27894@itemize * 27895 27896@item 27897@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 27898 27899In Ada 2012, the declaration of a primitive operation of a type extension 27900or private extension can also override an inherited primitive that is not 27901visible at the point of this declaration. 27902 27903RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 27904@end itemize 27905 27906@geindex AI-0062 (Ada 2012 feature) 27907 27908 27909@itemize * 27910 27911@item 27912@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 27913 27914A full constant may have a null exclusion even if its associated deferred 27915constant does not. GNAT has always allowed this. 27916 27917RM References: 7.04 (6/2) 7.04 (7.1/2) 27918@end itemize 27919 27920@geindex AI-0178 (Ada 2012 feature) 27921 27922 27923@itemize * 27924 27925@item 27926@emph{AI-0178 Incomplete views are limited (0000-00-00)} 27927 27928This AI clarifies the role of incomplete views and plugs an omission in the 27929RM. GNAT always correctly restricted the use of incomplete views and types. 27930 27931RM References: 7.05 (3/2) 7.05 (6/2) 27932@end itemize 27933 27934@geindex AI-0087 (Ada 2012 feature) 27935 27936 27937@itemize * 27938 27939@item 27940@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 27941 27942The actual for a formal nonlimited derived type cannot be limited. In 27943particular, a formal derived type that extends a limited interface but which 27944is not explicitly limited cannot be instantiated with a limited type. 27945 27946RM References: 7.05 (5/2) 12.05.01 (5.1/2) 27947@end itemize 27948 27949@geindex AI-0099 (Ada 2012 feature) 27950 27951 27952@itemize * 27953 27954@item 27955@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 27956 27957This AI clarifies that ‘needs finalization’ is part of dynamic semantics, 27958and therefore depends on the run-time characteristics of an object (i.e. its 27959tag) and not on its nominal type. As the AI indicates: “we do not expect 27960this to affect any implementation’’. 27961 27962RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 27963@end itemize 27964 27965@geindex AI-0064 (Ada 2012 feature) 27966 27967 27968@itemize * 27969 27970@item 27971@emph{AI-0064 Redundant finalization rule (0000-00-00)} 27972 27973This is an editorial change only. The intended behavior is already checked 27974by an existing ACATS test, which GNAT has always executed correctly. 27975 27976RM References: 7.06.01 (17.1/1) 27977@end itemize 27978 27979@geindex AI-0026 (Ada 2012 feature) 27980 27981 27982@itemize * 27983 27984@item 27985@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 27986 27987Record representation clauses concerning Unchecked_Union types cannot mention 27988the discriminant of the type. The type of a component declared in the variant 27989part of an Unchecked_Union cannot be controlled, have controlled components, 27990nor have protected or task parts. If an Unchecked_Union type is declared 27991within the body of a generic unit or its descendants, then the type of a 27992component declared in the variant part cannot be a formal private type or a 27993formal private extension declared within the same generic unit. 27994 27995RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 27996@end itemize 27997 27998@geindex AI-0205 (Ada 2012 feature) 27999 28000 28001@itemize * 28002 28003@item 28004@emph{AI-0205 Extended return declares visible name (0000-00-00)} 28005 28006This AI corrects a simple omission in the RM. Return objects have always 28007been visible within an extended return statement. 28008 28009RM References: 8.03 (17) 28010@end itemize 28011 28012@geindex AI-0042 (Ada 2012 feature) 28013 28014 28015@itemize * 28016 28017@item 28018@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 28019 28020This AI fixes a wording gap in the RM. An operation of a synchronized 28021interface can be implemented by a protected or task entry, but the abstract 28022operation is not being overridden in the usual sense, and it must be stated 28023separately that this implementation is legal. This has always been the case 28024in GNAT. 28025 28026RM References: 9.01 (9.2/2) 9.04 (11.1/2) 28027@end itemize 28028 28029@geindex AI-0030 (Ada 2012 feature) 28030 28031 28032@itemize * 28033 28034@item 28035@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 28036 28037Requeue is permitted to a protected, synchronized or task interface primitive 28038providing it is known that the overriding operation is an entry. Otherwise 28039the requeue statement has the same effect as a procedure call. Use of pragma 28040@code{Implemented} provides a way to impose a static requirement on the 28041overriding operation by adhering to one of the implementation kinds: entry, 28042protected procedure or any of the above. 28043 28044RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 280459.05.04 (6) 9.05.04 (7) 9.05.04 (12) 28046@end itemize 28047 28048@geindex AI-0201 (Ada 2012 feature) 28049 28050 28051@itemize * 28052 28053@item 28054@emph{AI-0201 Independence of atomic object components (2010-07-22)} 28055 28056If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} 28057attribute, then individual components may not be addressable by independent 28058tasks. However, if the representation clause has no effect (is confirming), 28059then independence is not compromised. Furthermore, in GNAT, specification of 28060other appropriately addressable component sizes (e.g. 16 for 8-bit 28061characters) also preserves independence. GNAT now gives very clear warnings 28062both for the declaration of such a type, and for any assignment to its components. 28063 28064RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 28065@end itemize 28066 28067@geindex AI-0009 (Ada 2012 feature) 28068 28069 28070@itemize * 28071 28072@item 28073@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 28074 28075This AI introduces the new pragmas @code{Independent} and 28076@code{Independent_Components}, 28077which control guaranteeing independence of access to objects and components. 28078The AI also requires independence not unaffected by confirming rep clauses. 28079 28080RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 28081C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 28082@end itemize 28083 28084@geindex AI-0072 (Ada 2012 feature) 28085 28086 28087@itemize * 28088 28089@item 28090@emph{AI-0072 Task signalling using ‘Terminated (0000-00-00)} 28091 28092This AI clarifies that task signalling for reading @code{'Terminated} only 28093occurs if the result is True. GNAT semantics has always been consistent with 28094this notion of task signalling. 28095 28096RM References: 9.10 (6.1/1) 28097@end itemize 28098 28099@geindex AI-0108 (Ada 2012 feature) 28100 28101 28102@itemize * 28103 28104@item 28105@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 28106 28107This AI confirms that an incomplete type from a limited view does not have 28108discriminants. This has always been the case in GNAT. 28109 28110RM References: 10.01.01 (12.3/2) 28111@end itemize 28112 28113@geindex AI-0129 (Ada 2012 feature) 28114 28115 28116@itemize * 28117 28118@item 28119@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 28120 28121This AI clarifies the description of limited views: a limited view of a 28122package includes only one view of a type that has an incomplete declaration 28123and a full declaration (there is no possible ambiguity in a client package). 28124This AI also fixes an omission: a nested package in the private part has no 28125limited view. GNAT always implemented this correctly. 28126 28127RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 28128@end itemize 28129 28130@geindex AI-0077 (Ada 2012 feature) 28131 28132 28133@itemize * 28134 28135@item 28136@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 28137 28138This AI clarifies that a declaration does not include a context clause, 28139and confirms that it is illegal to have a context in which both a limited 28140and a nonlimited view of a package are accessible. Such double visibility 28141was always rejected by GNAT. 28142 28143RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 28144@end itemize 28145 28146@geindex AI-0122 (Ada 2012 feature) 28147 28148 28149@itemize * 28150 28151@item 28152@emph{AI-0122 Private with and children of generics (0000-00-00)} 28153 28154This AI clarifies the visibility of private children of generic units within 28155instantiations of a parent. GNAT has always handled this correctly. 28156 28157RM References: 10.01.02 (12/2) 28158@end itemize 28159 28160@geindex AI-0040 (Ada 2012 feature) 28161 28162 28163@itemize * 28164 28165@item 28166@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 28167 28168This AI confirms that a limited with clause in a child unit cannot name 28169an ancestor of the unit. This has always been checked in GNAT. 28170 28171RM References: 10.01.02 (20/2) 28172@end itemize 28173 28174@geindex AI-0132 (Ada 2012 feature) 28175 28176 28177@itemize * 28178 28179@item 28180@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 28181 28182This AI fills a gap in the description of library unit pragmas. The pragma 28183clearly must apply to a library unit, even if it does not carry the name 28184of the enclosing unit. GNAT has always enforced the required check. 28185 28186RM References: 10.01.05 (7) 28187@end itemize 28188 28189@geindex AI-0034 (Ada 2012 feature) 28190 28191 28192@itemize * 28193 28194@item 28195@emph{AI-0034 Categorization of limited views (0000-00-00)} 28196 28197The RM makes certain limited with clauses illegal because of categorization 28198considerations, when the corresponding normal with would be legal. This is 28199not intended, and GNAT has always implemented the recommended behavior. 28200 28201RM References: 10.02.01 (11/1) 10.02.01 (17/2) 28202@end itemize 28203 28204@geindex AI-0035 (Ada 2012 feature) 28205 28206 28207@itemize * 28208 28209@item 28210@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 28211 28212This AI remedies some inconsistencies in the legality rules for Pure units. 28213Derived access types are legal in a pure unit (on the assumption that the 28214rule for a zero storage pool size has been enforced on the ancestor type). 28215The rules are enforced in generic instances and in subunits. GNAT has always 28216implemented the recommended behavior. 28217 28218RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) 28219@end itemize 28220 28221@geindex AI-0219 (Ada 2012 feature) 28222 28223 28224@itemize * 28225 28226@item 28227@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 28228 28229This AI refines the rules for the cases with limited parameters which do not 28230allow the implementations to omit ‘redundant’. GNAT now properly conforms 28231to the requirements of this binding interpretation. 28232 28233RM References: 10.02.01 (18/2) 28234@end itemize 28235 28236@geindex AI-0043 (Ada 2012 feature) 28237 28238 28239@itemize * 28240 28241@item 28242@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 28243 28244This AI covers various omissions in the RM regarding the raising of 28245exceptions. GNAT has always implemented the intended semantics. 28246 28247RM References: 11.04.01 (10.1/2) 11 (2) 28248@end itemize 28249 28250@geindex AI-0200 (Ada 2012 feature) 28251 28252 28253@itemize * 28254 28255@item 28256@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 28257 28258This AI plugs a gap in the RM which appeared to allow some obviously intended 28259illegal instantiations. GNAT has never allowed these instantiations. 28260 28261RM References: 12.07 (16) 28262@end itemize 28263 28264@geindex AI-0112 (Ada 2012 feature) 28265 28266 28267@itemize * 28268 28269@item 28270@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 28271 28272This AI concerns giving names to various representation aspects, but the 28273practical effect is simply to make the use of duplicate 28274@code{Atomic[_Components]}, 28275@code{Volatile[_Components]}, and 28276@code{Independent[_Components]} pragmas illegal, and GNAT 28277now performs this required check. 28278 28279RM References: 13.01 (8) 28280@end itemize 28281 28282@geindex AI-0106 (Ada 2012 feature) 28283 28284 28285@itemize * 28286 28287@item 28288@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 28289 28290The RM appeared to allow representation pragmas on generic formal parameters, 28291but this was not intended, and GNAT has never permitted this usage. 28292 28293RM References: 13.01 (9.1/1) 28294@end itemize 28295 28296@geindex AI-0012 (Ada 2012 feature) 28297 28298 28299@itemize * 28300 28301@item 28302@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 28303 28304It is now illegal to give an inappropriate component size or a pragma 28305@code{Pack} that attempts to change the component size in the case of atomic 28306or aliased components. Previously GNAT ignored such an attempt with a 28307warning. 28308 28309RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 28310@end itemize 28311 28312@geindex AI-0039 (Ada 2012 feature) 28313 28314 28315@itemize * 28316 28317@item 28318@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 28319 28320The RM permitted the use of dynamic expressions (such as @code{ptr.all})` 28321for stream attributes, but these were never useful and are now illegal. GNAT 28322has always regarded such expressions as illegal. 28323 28324RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 28325@end itemize 28326 28327@geindex AI-0095 (Ada 2012 feature) 28328 28329 28330@itemize * 28331 28332@item 28333@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 28334 28335The prefix of @code{'Address} cannot statically denote a subprogram with 28336convention @code{Intrinsic}. The use of the @code{Address} attribute raises 28337@code{Program_Error} if the prefix denotes a subprogram with convention 28338@code{Intrinsic}. 28339 28340RM References: 13.03 (11/1) 28341@end itemize 28342 28343@geindex AI-0116 (Ada 2012 feature) 28344 28345 28346@itemize * 28347 28348@item 28349@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 28350 28351This AI requires that the alignment of a class-wide object be no greater 28352than the alignment of any type in the class. GNAT has always followed this 28353recommendation. 28354 28355RM References: 13.03 (29) 13.11 (16) 28356@end itemize 28357 28358@geindex AI-0146 (Ada 2012 feature) 28359 28360 28361@itemize * 28362 28363@item 28364@emph{AI-0146 Type invariants (2009-09-21)} 28365 28366Type invariants may be specified for private types using the aspect notation. 28367Aspect @code{Type_Invariant} may be specified for any private type, 28368@code{Type_Invariant'Class} can 28369only be specified for tagged types, and is inherited by any descendent of the 28370tagged types. The invariant is a boolean expression that is tested for being 28371true in the following situations: conversions to the private type, object 28372declarations for the private type that are default initialized, and 28373[@strong{in}] @strong{out} 28374parameters and returned result on return from any primitive operation for 28375the type that is visible to a client. 28376GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and 28377@code{Invariant'Class} for @code{Type_Invariant'Class}. 28378 28379RM References: 13.03.03 (00) 28380@end itemize 28381 28382@geindex AI-0078 (Ada 2012 feature) 28383 28384 28385@itemize * 28386 28387@item 28388@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 28389 28390In Ada 2012, compilers are required to support unchecked conversion where the 28391target alignment is a multiple of the source alignment. GNAT always supported 28392this case (and indeed all cases of differing alignments, doing copies where 28393required if the alignment was reduced). 28394 28395RM References: 13.09 (7) 28396@end itemize 28397 28398@geindex AI-0195 (Ada 2012 feature) 28399 28400 28401@itemize * 28402 28403@item 28404@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 28405 28406The handling of invalid values is now designated to be implementation 28407defined. This is a documentation change only, requiring Annex M in the GNAT 28408Reference Manual to document this handling. 28409In GNAT, checks for invalid values are made 28410only when necessary to avoid erroneous behavior. Operations like assignments 28411which cannot cause erroneous behavior ignore the possibility of invalid 28412values and do not do a check. The date given above applies only to the 28413documentation change, this behavior has always been implemented by GNAT. 28414 28415RM References: 13.09.01 (10) 28416@end itemize 28417 28418@geindex AI-0193 (Ada 2012 feature) 28419 28420 28421@itemize * 28422 28423@item 28424@emph{AI-0193 Alignment of allocators (2010-09-16)} 28425 28426This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, 28427analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead 28428of size. 28429 28430RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 2843113.11.01 (2) 13.11.01 (3) 28432@end itemize 28433 28434@geindex AI-0177 (Ada 2012 feature) 28435 28436 28437@itemize * 28438 28439@item 28440@emph{AI-0177 Parameterized expressions (2010-07-10)} 28441 28442The new Ada 2012 notion of parameterized expressions is implemented. The form 28443is: 28444 28445@example 28446function-specification is (expression) 28447@end example 28448 28449This is exactly equivalent to the 28450corresponding function body that returns the expression, but it can appear 28451in a package spec. Note that the expression must be parenthesized. 28452 28453RM References: 13.11.01 (3/2) 28454@end itemize 28455 28456@geindex AI-0033 (Ada 2012 feature) 28457 28458 28459@itemize * 28460 28461@item 28462@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 28463 28464Neither of these two pragmas may appear within a generic template, because 28465the generic might be instantiated at other than the library level. 28466 28467RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 28468@end itemize 28469 28470@geindex AI-0161 (Ada 2012 feature) 28471 28472 28473@itemize * 28474 28475@item 28476@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 28477 28478A new restriction @code{No_Default_Stream_Attributes} prevents the use of any 28479of the default stream attributes for elementary types. If this restriction is 28480in force, then it is necessary to provide explicit subprograms for any 28481stream attributes used. 28482 28483RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 28484@end itemize 28485 28486@geindex AI-0194 (Ada 2012 feature) 28487 28488 28489@itemize * 28490 28491@item 28492@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 28493 28494The @code{Stream_Size} attribute returns the default number of bits in the 28495stream representation of the given type. 28496This value is not affected by the presence 28497of stream subprogram attributes for the type. GNAT has always implemented 28498this interpretation. 28499 28500RM References: 13.13.02 (1.2/2) 28501@end itemize 28502 28503@geindex AI-0109 (Ada 2012 feature) 28504 28505 28506@itemize * 28507 28508@item 28509@emph{AI-0109 Redundant check in S’Class’Input (0000-00-00)} 28510 28511This AI is an editorial change only. It removes the need for a tag check 28512that can never fail. 28513 28514RM References: 13.13.02 (34/2) 28515@end itemize 28516 28517@geindex AI-0007 (Ada 2012 feature) 28518 28519 28520@itemize * 28521 28522@item 28523@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 28524 28525The RM as written appeared to limit the possibilities of declaring read 28526attribute procedures for private scalar types. This limitation was not 28527intended, and has never been enforced by GNAT. 28528 28529RM References: 13.13.02 (50/2) 13.13.02 (51/2) 28530@end itemize 28531 28532@geindex AI-0065 (Ada 2012 feature) 28533 28534 28535@itemize * 28536 28537@item 28538@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 28539 28540This AI clarifies the fact that all remote access types support external 28541streaming. This fixes an obvious oversight in the definition of the 28542language, and GNAT always implemented the intended correct rules. 28543 28544RM References: 13.13.02 (52/2) 28545@end itemize 28546 28547@geindex AI-0019 (Ada 2012 feature) 28548 28549 28550@itemize * 28551 28552@item 28553@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 28554 28555The RM suggests that primitive subprograms of a specific tagged type are 28556frozen when the tagged type is frozen. This would be an incompatible change 28557and is not intended. GNAT has never attempted this kind of freezing and its 28558behavior is consistent with the recommendation of this AI. 28559 28560RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) 28561@end itemize 28562 28563@geindex AI-0017 (Ada 2012 feature) 28564 28565 28566@itemize * 28567 28568@item 28569@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 28570 28571So-called ‘Taft-amendment types’ (i.e., types that are completed in package 28572bodies) are not frozen by the occurrence of bodies in the 28573enclosing declarative part. GNAT always implemented this properly. 28574 28575RM References: 13.14 (3/1) 28576@end itemize 28577 28578@geindex AI-0060 (Ada 2012 feature) 28579 28580 28581@itemize * 28582 28583@item 28584@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 28585 28586This AI extends the definition of remote access types to include access 28587to limited, synchronized, protected or task class-wide interface types. 28588GNAT already implemented this extension. 28589 28590RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 28591@end itemize 28592 28593@geindex AI-0114 (Ada 2012 feature) 28594 28595 28596@itemize * 28597 28598@item 28599@emph{AI-0114 Classification of letters (0000-00-00)} 28600 28601The code points 170 (@code{FEMININE ORDINAL INDICATOR}), 28602181 (@code{MICRO SIGN}), and 28603186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered 28604lower case letters by Unicode. 28605However, they are not allowed in identifiers, and they 28606return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. 28607This behavior is consistent with that defined in Ada 95. 28608 28609RM References: A.03.02 (59) A.04.06 (7) 28610@end itemize 28611 28612@geindex AI-0185 (Ada 2012 feature) 28613 28614 28615@itemize * 28616 28617@item 28618@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 28619 28620Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide 28621classification functions for @code{Wide_Character} and 28622@code{Wide_Wide_Character}, as well as providing 28623case folding routines for @code{Wide_[Wide_]Character} and 28624@code{Wide_[Wide_]String}. 28625 28626RM References: A.03.05 (0) A.03.06 (0) 28627@end itemize 28628 28629@geindex AI-0031 (Ada 2012 feature) 28630 28631 28632@itemize * 28633 28634@item 28635@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 28636 28637A new version of @code{Find_Token} is added to all relevant string packages, 28638with an extra parameter @code{From}. Instead of starting at the first 28639character of the string, the search for a matching Token starts at the 28640character indexed by the value of @code{From}. 28641These procedures are available in all versions of Ada 28642but if used in versions earlier than Ada 2012 they will generate a warning 28643that an Ada 2012 subprogram is being used. 28644 28645RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 28646A.04.05 (46) 28647@end itemize 28648 28649@geindex AI-0056 (Ada 2012 feature) 28650 28651 28652@itemize * 28653 28654@item 28655@emph{AI-0056 Index on null string returns zero (0000-00-00)} 28656 28657The wording in the Ada 2005 RM implied an incompatible handling of the 28658@code{Index} functions, resulting in raising an exception instead of 28659returning zero in some situations. 28660This was not intended and has been corrected. 28661GNAT always returned zero, and is thus consistent with this AI. 28662 28663RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 28664@end itemize 28665 28666@geindex AI-0137 (Ada 2012 feature) 28667 28668 28669@itemize * 28670 28671@item 28672@emph{AI-0137 String encoding package (2010-03-25)} 28673 28674The packages @code{Ada.Strings.UTF_Encoding}, together with its child 28675packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, 28676and @code{Wide_Wide_Strings} have been 28677implemented. These packages (whose documentation can be found in the spec 28678files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, 28679@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of 28680@code{String}, @code{Wide_String}, and @code{Wide_Wide_String} 28681values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 28682UTF-16), as well as conversions between the different UTF encodings. With 28683the exception of @code{Wide_Wide_Strings}, these packages are available in 28684Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 28685The @code{Wide_Wide_Strings} package 28686is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 28687mode since it uses @code{Wide_Wide_Character}). 28688 28689RM References: A.04.11 28690@end itemize 28691 28692@geindex AI-0038 (Ada 2012 feature) 28693 28694 28695@itemize * 28696 28697@item 28698@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 28699 28700These are minor errors in the description on three points. The intent on 28701all these points has always been clear, and GNAT has always implemented the 28702correct intended semantics. 28703 28704RM 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) 28705@end itemize 28706 28707@geindex AI-0044 (Ada 2012 feature) 28708 28709 28710@itemize * 28711 28712@item 28713@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 28714 28715This AI places restrictions on allowed instantiations of generic containers. 28716These restrictions are not checked by the compiler, so there is nothing to 28717change in the implementation. This affects only the RM documentation. 28718 28719RM 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) 28720@end itemize 28721 28722@geindex AI-0127 (Ada 2012 feature) 28723 28724 28725@itemize * 28726 28727@item 28728@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 28729 28730This package provides an interface for identifying the current locale. 28731 28732RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 28733A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 28734@end itemize 28735 28736@geindex AI-0002 (Ada 2012 feature) 28737 28738 28739@itemize * 28740 28741@item 28742@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 28743 28744The compiler is not required to support exporting an Ada subprogram with 28745convention C if there are parameters or a return type of an unconstrained 28746array type (such as @code{String}). GNAT allows such declarations but 28747generates warnings. It is possible, but complicated, to write the 28748corresponding C code and certainly such code would be specific to GNAT and 28749non-portable. 28750 28751RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 28752@end itemize 28753 28754@geindex AI05-0216 (Ada 2012 feature) 28755 28756 28757@itemize * 28758 28759@item 28760@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 28761 28762It is clearly the intention that @code{No_Task_Hierarchy} is intended to 28763forbid tasks declared locally within subprograms, or functions returning task 28764objects, and that is the implementation that GNAT has always provided. 28765However the language in the RM was not sufficiently clear on this point. 28766Thus this is a documentation change in the RM only. 28767 28768RM References: D.07 (3/3) 28769@end itemize 28770 28771@geindex AI-0211 (Ada 2012 feature) 28772 28773 28774@itemize * 28775 28776@item 28777@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 28778 28779The restriction @code{No_Relative_Delays} forbids any calls to the subprogram 28780@code{Ada.Real_Time.Timing_Events.Set_Handler}. 28781 28782RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 28783@end itemize 28784 28785@geindex AI-0190 (Ada 2012 feature) 28786 28787 28788@itemize * 28789 28790@item 28791@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 28792 28793This AI introduces a new pragma @code{Default_Storage_Pool}, which can be 28794used to control storage pools globally. 28795In particular, you can force every access 28796type that is used for allocation (@strong{new}) to have an explicit storage pool, 28797or you can declare a pool globally to be used for all access types that lack 28798an explicit one. 28799 28800RM References: D.07 (8) 28801@end itemize 28802 28803@geindex AI-0189 (Ada 2012 feature) 28804 28805 28806@itemize * 28807 28808@item 28809@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 28810 28811This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, 28812which says that no dynamic allocation will occur once elaboration is 28813completed. 28814In general this requires a run-time check, which is not required, and which 28815GNAT does not attempt. But the static cases of allocators in a task body or 28816in the body of the main program are detected and flagged at compile or bind 28817time. 28818 28819RM References: D.07 (19.1/2) H.04 (23.3/2) 28820@end itemize 28821 28822@geindex AI-0171 (Ada 2012 feature) 28823 28824 28825@itemize * 28826 28827@item 28828@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 28829 28830A new package @code{System.Multiprocessors} is added, together with the 28831definition of pragma @code{CPU} for controlling task affinity. A new no 28832dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, 28833is added to the Ravenscar profile. 28834 28835RM References: D.13.01 (4/2) D.16 28836@end itemize 28837 28838@geindex AI-0210 (Ada 2012 feature) 28839 28840 28841@itemize * 28842 28843@item 28844@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 28845 28846This is a documentation only issue regarding wording of metric requirements, 28847that does not affect the implementation of the compiler. 28848 28849RM References: D.15 (24/2) 28850@end itemize 28851 28852@geindex AI-0206 (Ada 2012 feature) 28853 28854 28855@itemize * 28856 28857@item 28858@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 28859 28860Remote types packages are now allowed to depend on preelaborated packages. 28861This was formerly considered illegal. 28862 28863RM References: E.02.02 (6) 28864@end itemize 28865 28866@geindex AI-0152 (Ada 2012 feature) 28867 28868 28869@itemize * 28870 28871@item 28872@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 28873 28874Restriction @code{No_Anonymous_Allocators} prevents the use of allocators 28875where the type of the returned value is an anonymous access type. 28876 28877RM References: H.04 (8/1) 28878@end itemize 28879 28880@node Security Hardening Features,Obsolescent Features,Implementation of Ada 2012 Features,Top 28881@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} 28882@chapter Security Hardening Features 28883 28884 28885This chapter describes Ada extensions aimed at security hardening that 28886are provided by GNAT. 28887 28888@c Register Scrubbing: 28889 28890@menu 28891* Register Scrubbing:: 28892* Stack Scrubbing:: 28893* Hardened Conditionals:: 28894 28895@end menu 28896 28897@node Register Scrubbing,Stack Scrubbing,,Security Hardening Features 28898@anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{43d} 28899@section Register Scrubbing 28900 28901 28902GNAT can generate code to zero-out hardware registers before returning 28903from a subprogram. 28904 28905It can be enabled with the @emph{-fzero-call-used-regs} command line 28906option, to affect all subprograms in a compilation, and with a 28907@code{Machine_Attribute} pragma, to affect only specific subprograms. 28908 28909@example 28910procedure Foo; 28911pragma Machine_Attribute (Foo, "zero_call_used_regs", "used"); 28912-- Before returning, Foo scrubs only call-clobbered registers 28913-- that it uses itself. 28914 28915function Bar return Integer; 28916pragma Machine_Attribute (Bar, "zero_call_used_regs", "all"); 28917-- Before returning, Bar scrubs all call-clobbered registers. 28918@end example 28919 28920For usage and more details on the command line option, and on the 28921@code{zero_call_used_regs} attribute, see @cite{Using the GNU Compiler Collection (GCC)}. 28922 28923@c Stack Scrubbing: 28924 28925@node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features 28926@anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{43e} 28927@section Stack Scrubbing 28928 28929 28930GNAT can generate code to zero-out stack frames used by subprograms. 28931 28932It can be activated with the @code{Machine_Attribute} pragma, on 28933specific subprograms and variables. 28934 28935@example 28936function Foo returns Integer; 28937pragma Machine_Attribute (Foo, "strub"); 28938-- Foo and its callers are modified so as to scrub the stack 28939-- space used by Foo after it returns. 28940 28941procedure Bar; 28942pragma Machine_Attribute (Bar, "strub", "internal"); 28943-- Bar is turned into a wrapper for its original body, 28944-- and they scrub the stack used by the original body. 28945 28946Var : Integer; 28947pragma Machine_Attribute (Var, "strub"); 28948-- Reading from Var in a subprogram enables stack scrubbing 28949-- of the stack space used by the subprogram. 28950@end example 28951 28952There are also @emph{-fstrub} command line options to control default 28953settings. For usage and more details on the command line option, and 28954on the @code{strub} attribute, see @cite{Using the GNU Compiler Collection (GCC)}. 28955 28956Note that Ada secondary stacks are not scrubbed. The restriction 28957@code{No_Secondary_Stack} avoids their use, and thus their accidental 28958preservation of data that should be scrubbed. 28959 28960Attributes @code{Access} and @code{Unconstrained_Access} of variables and 28961constants with @code{strub} enabled require types with @code{strub} enabled; 28962there is no way to express an access-to-strub type otherwise. 28963@code{Unchecked_Access} bypasses this constraint, but the resulting 28964access type designates a non-strub type. 28965 28966@example 28967VI : Integer; 28968XsVI : access Integer := VI'Access; -- Error. 28969UXsVI : access Integer := VI'Unchecked_Access; -- OK, 28970-- UXsVI.all does not enable strub in the enclosing subprogram. 28971 28972type Strub_Int is new Integer; 28973pragma Machine_Attribute (Strub_Int, "strub"); 28974VSI : Strub_Int; 28975XsVSI : access Strub_Int := VSI'Access; -- OK. 28976-- XsVSI.all enables strub in the enclosing subprogram. 28977@end example 28978 28979Every access-to-subprogram type, renaming, and overriding and 28980overridden dispatching operations that may refer to a subprogram with 28981an attribute-modified interface must be annotated with the same 28982interface-modifying attribute. Access-to-subprogram types can be 28983explicitly converted to different strub modes, as long as they are 28984interface-compatible (i.e., adding or removing @code{at-calls} is not 28985allowed). For example, a @code{strub}-@code{disabled} subprogram can be 28986turned @code{callable} through such an explicit conversion: 28987 28988@example 28989type TBar is access procedure; 28990 28991type TBar_Callable is access procedure; 28992pragma Machine_Attribute (TBar_Callable, "strub", "callable"); 28993 28994Bar_Callable_Ptr : constant TBar_Callable 28995 := TBar_Callable (TBar'(Bar'Access)); 28996 28997procedure Bar_Callable renames Bar_Callable_Ptr.all; 28998pragma Machine_Attribute (Bar_Callable, "strub", "callable"); 28999@end example 29000 29001Note that the renaming declaration is expanded to a full subprogram 29002body, it won’t be just an alias. Only if it is inlined will it be as 29003efficient as a call by dereferencing the access-to-subprogram constant 29004Bar_Callable_Ptr. 29005 29006@c Hardened Conditionals: 29007 29008@node Hardened Conditionals,,Stack Scrubbing,Security Hardening Features 29009@anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{43f} 29010@section Hardened Conditionals 29011 29012 29013GNAT can harden conditionals to protect against control flow attacks. 29014 29015This is accomplished by two complementary transformations, each 29016activated by a separate command-line option. 29017 29018The option @emph{-fharden-compares} enables hardening of compares that 29019compute results stored in variables, adding verification that the 29020reversed compare yields the opposite result. 29021 29022The option @emph{-fharden-conditional-branches} enables hardening of 29023compares that guard conditional branches, adding verification of the 29024reversed compare to both execution paths. 29025 29026These transformations are introduced late in the compilation pipeline, 29027long after boolean expressions are decomposed into separate compares, 29028each one turned into either a conditional branch or a compare whose 29029result is stored in a boolean variable or temporary. Compiler 29030optimizations, if enabled, may also turn conditional branches into 29031stored compares, and vice-versa, or into operations with implied 29032conditionals (e.g. MIN and MAX). Conditionals may also be optimized 29033out entirely, if their value can be determined at compile time, and 29034occasionally multiple compares can be combined into one. 29035 29036It is thus difficult to predict which of these two options will affect 29037a specific compare operation expressed in source code. Using both 29038options ensures that every compare that is neither optimized out nor 29039optimized into implied conditionals will be hardened. 29040 29041The addition of reversed compares can be observed by enabling the dump 29042files of the corresponding passes, through command line options 29043@emph{-fdump-tree-hardcmp} and @emph{-fdump-tree-hardcbr}, respectively. 29044 29045They are separate options, however, because of the significantly 29046different performance impact of the hardening transformations. 29047 29048@node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top 29049@anchor{gnat_rm/obsolescent_features doc}@anchor{440}@anchor{gnat_rm/obsolescent_features id1}@anchor{441}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16} 29050@chapter Obsolescent Features 29051 29052 29053This chapter describes features that are provided by GNAT, but are 29054considered obsolescent since there are preferred ways of achieving 29055the same effect. These features are provided solely for historical 29056compatibility purposes. 29057 29058@menu 29059* pragma No_Run_Time:: 29060* pragma Ravenscar:: 29061* pragma Restricted_Run_Time:: 29062* pragma Task_Info:: 29063* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 29064 29065@end menu 29066 29067@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features 29068@anchor{gnat_rm/obsolescent_features id2}@anchor{442}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{443} 29069@section pragma No_Run_Time 29070 29071 29072The pragma @code{No_Run_Time} is used to achieve an affect similar 29073to the use of the “Zero Foot Print” configurable run time, but without 29074requiring a specially configured run time. The result of using this 29075pragma, which must be used for all units in a partition, is to restrict 29076the use of any language features requiring run-time support code. The 29077preferred usage is to use an appropriately configured run-time that 29078includes just those features that are to be made accessible. 29079 29080@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features 29081@anchor{gnat_rm/obsolescent_features id3}@anchor{444}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{445} 29082@section pragma Ravenscar 29083 29084 29085The pragma @code{Ravenscar} has exactly the same effect as pragma 29086@code{Profile (Ravenscar)}. The latter usage is preferred since it 29087is part of the new Ada 2005 standard. 29088 29089@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features 29090@anchor{gnat_rm/obsolescent_features id4}@anchor{446}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{447} 29091@section pragma Restricted_Run_Time 29092 29093 29094The pragma @code{Restricted_Run_Time} has exactly the same effect as 29095pragma @code{Profile (Restricted)}. The latter usage is 29096preferred since the Ada 2005 pragma @code{Profile} is intended for 29097this kind of implementation dependent addition. 29098 29099@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features 29100@anchor{gnat_rm/obsolescent_features id5}@anchor{448}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{449} 29101@section pragma Task_Info 29102 29103 29104The functionality provided by pragma @code{Task_Info} is now part of the 29105Ada language. The @code{CPU} aspect and the package 29106@code{System.Multiprocessors} offer a less system-dependent way to specify 29107task affinity or to query the number of processors. 29108 29109Syntax 29110 29111@example 29112pragma Task_Info (EXPRESSION); 29113@end example 29114 29115This pragma appears within a task definition (like pragma 29116@code{Priority}) and applies to the task in which it appears. The 29117argument must be of type @code{System.Task_Info.Task_Info_Type}. 29118The @code{Task_Info} pragma provides system dependent control over 29119aspects of tasking implementation, for example, the ability to map 29120tasks to specific processors. For details on the facilities available 29121for the version of GNAT that you are using, see the documentation 29122in the spec of package System.Task_Info in the runtime 29123library. 29124 29125@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features 29126@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{44a}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{44b} 29127@section package System.Task_Info (@code{s-tasinf.ads}) 29128 29129 29130This package provides target dependent functionality that is used 29131to support the @code{Task_Info} pragma. The predefined Ada package 29132@code{System.Multiprocessors} and the @code{CPU} aspect now provide a 29133standard replacement for GNAT’s @code{Task_Info} functionality. 29134 29135@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top 29136@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{44d} 29137@chapter Compatibility and Porting Guide 29138 29139 29140This chapter presents some guidelines for developing portable Ada code, 29141describes the compatibility issues that may arise between 29142GNAT and other Ada compilation systems (including those for Ada 83), 29143and shows how GNAT can expedite porting 29144applications developed in other Ada environments. 29145 29146@menu 29147* Writing Portable Fixed-Point Declarations:: 29148* Compatibility with Ada 83:: 29149* Compatibility between Ada 95 and Ada 2005:: 29150* Implementation-dependent characteristics:: 29151* Compatibility with Other Ada Systems:: 29152* Representation Clauses:: 29153* Compatibility with HP Ada 83:: 29154 29155@end menu 29156 29157@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide 29158@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{44f} 29159@section Writing Portable Fixed-Point Declarations 29160 29161 29162The Ada Reference Manual gives an implementation freedom to choose bounds 29163that are narrower by @code{Small} from the given bounds. 29164For example, if we write 29165 29166@example 29167type F1 is delta 1.0 range -128.0 .. +128.0; 29168@end example 29169 29170then the implementation is allowed to choose -128.0 .. +127.0 if it 29171likes, but is not required to do so. 29172 29173This leads to possible portability problems, so let’s have a closer 29174look at this, and figure out how to avoid these problems. 29175 29176First, why does this freedom exist, and why would an implementation 29177take advantage of it? To answer this, take a closer look at the type 29178declaration for @code{F1} above. If the compiler uses the given bounds, 29179it would need 9 bits to hold the largest positive value (and typically 29180that means 16 bits on all machines). But if the implementation chooses 29181the +127.0 bound then it can fit values of the type in 8 bits. 29182 29183Why not make the user write +127.0 if that’s what is wanted? 29184The rationale is that if you are thinking of fixed point 29185as a kind of ‘poor man’s floating-point’, then you don’t want 29186to be thinking about the scaled integers that are used in its 29187representation. Let’s take another example: 29188 29189@example 29190type F2 is delta 2.0**(-15) range -1.0 .. +1.0; 29191@end example 29192 29193Looking at this declaration, it seems casually as though 29194it should fit in 16 bits, but again that extra positive value 29195+1.0 has the scaled integer equivalent of 2**15 which is one too 29196big for signed 16 bits. The implementation can treat this as: 29197 29198@example 29199type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); 29200@end example 29201 29202and the Ada language design team felt that this was too annoying 29203to require. We don’t need to debate this decision at this point, 29204since it is well established (the rule about narrowing the ranges 29205dates to Ada 83). 29206 29207But the important point is that an implementation is not required 29208to do this narrowing, so we have a potential portability problem. 29209We could imagine three types of implementation: 29210 29211 29212@enumerate a 29213 29214@item 29215those that narrow the range automatically if they can figure 29216out that the narrower range will allow storage in a smaller machine unit, 29217 29218@item 29219those that will narrow only if forced to by a @code{'Size} clause, and 29220 29221@item 29222those that will never narrow. 29223@end enumerate 29224 29225Now if we are language theoreticians, we can imagine a fourth 29226approach: to narrow all the time, e.g. to treat 29227 29228@example 29229type F3 is delta 1.0 range -10.0 .. +23.0; 29230@end example 29231 29232as though it had been written: 29233 29234@example 29235type F3 is delta 1.0 range -9.0 .. +22.0; 29236@end example 29237 29238But although technically allowed, such a behavior would be hostile and silly, 29239and no real compiler would do this. All real compilers will fall into one of 29240the categories (a), (b) or (c) above. 29241 29242So, how do you get the compiler to do what you want? The answer is give the 29243actual bounds you want, and then use a @code{'Small} clause and a 29244@code{'Size} clause to absolutely pin down what the compiler does. 29245E.g., for @code{F2} above, we will write: 29246 29247@example 29248My_Small : constant := 2.0**(-15); 29249My_First : constant := -1.0; 29250My_Last : constant := +1.0 - My_Small; 29251 29252type F2 is delta My_Small range My_First .. My_Last; 29253@end example 29254 29255and then add 29256 29257@example 29258for F2'Small use my_Small; 29259for F2'Size use 16; 29260@end example 29261 29262In practice all compilers will do the same thing here and will give you 29263what you want, so the above declarations are fully portable. If you really 29264want to play language lawyer and guard against ludicrous behavior by the 29265compiler you could add 29266 29267@example 29268Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); 29269Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); 29270@end example 29271 29272One or other or both are allowed to be illegal if the compiler is 29273behaving in a silly manner, but at least the silly compiler will not 29274get away with silently messing with your (very clear) intentions. 29275 29276If you follow this scheme you will be guaranteed that your fixed-point 29277types will be portable. 29278 29279@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide 29280@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{451} 29281@section Compatibility with Ada 83 29282 29283 29284@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) 29285 29286Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 29287are highly upwards compatible with Ada 83. In 29288particular, the design intention was that the difficulties associated 29289with moving from Ada 83 to later versions of the standard should be no greater 29290than those that occur when moving from one Ada 83 system to another. 29291 29292However, there are a number of points at which there are minor 29293incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains 29294full details of these issues as they relate to Ada 95, 29295and should be consulted for a complete treatment. 29296In practice the 29297following subsections treat the most likely issues to be encountered. 29298 29299@menu 29300* Legal Ada 83 programs that are illegal in Ada 95:: 29301* More deterministic semantics:: 29302* Changed semantics:: 29303* Other language compatibility issues:: 29304 29305@end menu 29306 29307@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 29308@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{453} 29309@subsection Legal Ada 83 programs that are illegal in Ada 95 29310 29311 29312Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in 29313Ada 95 and later versions of the standard: 29314 29315 29316@itemize * 29317 29318@item 29319@emph{Character literals} 29320 29321Some uses of character literals are ambiguous. Since Ada 95 has introduced 29322@code{Wide_Character} as a new predefined character type, some uses of 29323character literals that were legal in Ada 83 are illegal in Ada 95. 29324For example: 29325 29326@example 29327for Char in 'A' .. 'Z' loop ... end loop; 29328@end example 29329 29330The problem is that ‘A’ and ‘Z’ could be from either 29331@code{Character} or @code{Wide_Character}. The simplest correction 29332is to make the type explicit; e.g.: 29333 29334@example 29335for Char in Character range 'A' .. 'Z' loop ... end loop; 29336@end example 29337 29338@item 29339@emph{New reserved words} 29340 29341The identifiers @code{abstract}, @code{aliased}, @code{protected}, 29342@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. 29343Existing Ada 83 code using any of these identifiers must be edited to 29344use some alternative name. 29345 29346@item 29347@emph{Freezing rules} 29348 29349The rules in Ada 95 are slightly different with regard to the point at 29350which entities are frozen, and representation pragmas and clauses are 29351not permitted past the freeze point. This shows up most typically in 29352the form of an error message complaining that a representation item 29353appears too late, and the appropriate corrective action is to move 29354the item nearer to the declaration of the entity to which it refers. 29355 29356A particular case is that representation pragmas 29357cannot be applied to a subprogram body. If necessary, a separate subprogram 29358declaration must be introduced to which the pragma can be applied. 29359 29360@item 29361@emph{Optional bodies for library packages} 29362 29363In Ada 83, a package that did not require a package body was nevertheless 29364allowed to have one. This lead to certain surprises in compiling large 29365systems (situations in which the body could be unexpectedly ignored by the 29366binder). In Ada 95, if a package does not require a body then it is not 29367permitted to have a body. To fix this problem, simply remove a redundant 29368body if it is empty, or, if it is non-empty, introduce a dummy declaration 29369into the spec that makes the body required. One approach is to add a private 29370part to the package declaration (if necessary), and define a parameterless 29371procedure called @code{Requires_Body}, which must then be given a dummy 29372procedure body in the package body, which then becomes required. 29373Another approach (assuming that this does not introduce elaboration 29374circularities) is to add an @code{Elaborate_Body} pragma to the package spec, 29375since one effect of this pragma is to require the presence of a package body. 29376 29377@item 29378@emph{Numeric_Error is the same exception as Constraint_Error} 29379 29380In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. 29381This means that it is illegal to have separate exception handlers for 29382the two exceptions. The fix is simply to remove the handler for the 29383@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise 29384@code{Constraint_Error} in place of @code{Numeric_Error} in all cases). 29385 29386@item 29387@emph{Indefinite subtypes in generics} 29388 29389In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) 29390as the actual for a generic formal private type, but then the instantiation 29391would be illegal if there were any instances of declarations of variables 29392of this type in the generic body. In Ada 95, to avoid this clear violation 29393of the methodological principle known as the ‘contract model’, 29394the generic declaration explicitly indicates whether 29395or not such instantiations are permitted. If a generic formal parameter 29396has explicit unknown discriminants, indicated by using @code{(<>)} after the 29397subtype name, then it can be instantiated with indefinite types, but no 29398stand-alone variables can be declared of this type. Any attempt to declare 29399such a variable will result in an illegality at the time the generic is 29400declared. If the @code{(<>)} notation is not used, then it is illegal 29401to instantiate the generic with an indefinite type. 29402This is the potential incompatibility issue when porting Ada 83 code to Ada 95. 29403It will show up as a compile time error, and 29404the fix is usually simply to add the @code{(<>)} to the generic declaration. 29405@end itemize 29406 29407@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 29408@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{455} 29409@subsection More deterministic semantics 29410 29411 29412 29413@itemize * 29414 29415@item 29416@emph{Conversions} 29417 29418Conversions from real types to integer types round away from 0. In Ada 83 29419the conversion Integer(2.5) could deliver either 2 or 3 as its value. This 29420implementation freedom was intended to support unbiased rounding in 29421statistical applications, but in practice it interfered with portability. 29422In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 29423is required. Numeric code may be affected by this change in semantics. 29424Note, though, that this issue is no worse than already existed in Ada 83 29425when porting code from one vendor to another. 29426 29427@item 29428@emph{Tasking} 29429 29430The Real-Time Annex introduces a set of policies that define the behavior of 29431features that were implementation dependent in Ada 83, such as the order in 29432which open select branches are executed. 29433@end itemize 29434 29435@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 29436@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{457} 29437@subsection Changed semantics 29438 29439 29440The worst kind of incompatibility is one where a program that is legal in 29441Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not 29442possible in Ada 83. Fortunately this is extremely rare, but the one 29443situation that you should be alert to is the change in the predefined type 29444@code{Character} from 7-bit ASCII to 8-bit Latin-1. 29445 29446@quotation 29447 29448@geindex Latin-1 29449@end quotation 29450 29451 29452@itemize * 29453 29454@item 29455@emph{Range of type `@w{`}Character`@w{`}} 29456 29457The range of @code{Standard.Character} is now the full 256 characters 29458of Latin-1, whereas in most Ada 83 implementations it was restricted 29459to 128 characters. Although some of the effects of 29460this change will be manifest in compile-time rejection of legal 29461Ada 83 programs it is possible for a working Ada 83 program to have 29462a different effect in Ada 95, one that was not permitted in Ada 83. 29463As an example, the expression 29464@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now 29465delivers @code{255} as its value. 29466In general, you should look at the logic of any 29467character-processing Ada 83 program and see whether it needs to be adapted 29468to work correctly with Latin-1. Note that the predefined Ada 95 API has a 29469character handling package that may be relevant if code needs to be adapted 29470to account for the additional Latin-1 elements. 29471The desirable fix is to 29472modify the program to accommodate the full character set, but in some cases 29473it may be convenient to define a subtype or derived type of Character that 29474covers only the restricted range. 29475@end itemize 29476 29477@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 29478@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{459} 29479@subsection Other language compatibility issues 29480 29481 29482 29483@itemize * 29484 29485@item 29486@emph{-gnat83} switch 29487 29488All implementations of GNAT provide a switch that causes GNAT to operate 29489in Ada 83 mode. In this mode, some but not all compatibility problems 29490of the type described above are handled automatically. For example, the 29491new reserved words introduced in Ada 95 and Ada 2005 are treated simply 29492as identifiers as in Ada 83. However, 29493in practice, it is usually advisable to make the necessary modifications 29494to the program to remove the need for using this switch. 29495See the @code{Compiling Different Versions of Ada} section in 29496the @cite{GNAT User’s Guide}. 29497 29498@item 29499Support for removed Ada 83 pragmas and attributes 29500 29501A number of pragmas and attributes from Ada 83 were removed from Ada 95, 29502generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 29503compilers are allowed, but not required, to implement these missing 29504elements. In contrast with some other compilers, GNAT implements all 29505such pragmas and attributes, eliminating this compatibility concern. These 29506include @code{pragma Interface} and the floating point type attributes 29507(@code{Emax}, @code{Mantissa}, etc.), among other items. 29508@end itemize 29509 29510@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide 29511@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{45a}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{45b} 29512@section Compatibility between Ada 95 and Ada 2005 29513 29514 29515@geindex Compatibility between Ada 95 and Ada 2005 29516 29517Although Ada 2005 was designed to be upwards compatible with Ada 95, there are 29518a number of incompatibilities. Several are enumerated below; 29519for a complete description please see the 29520@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in 29521@cite{Rationale for Ada 2005}. 29522 29523 29524@itemize * 29525 29526@item 29527@emph{New reserved words.} 29528 29529The words @code{interface}, @code{overriding} and @code{synchronized} are 29530reserved in Ada 2005. 29531A pre-Ada 2005 program that uses any of these as an identifier will be 29532illegal. 29533 29534@item 29535@emph{New declarations in predefined packages.} 29536 29537A number of packages in the predefined environment contain new declarations: 29538@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, 29539@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, 29540@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, 29541@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, 29542@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. 29543If an Ada 95 program does a @code{with} and @code{use} of any of these 29544packages, the new declarations may cause name clashes. 29545 29546@item 29547@emph{Access parameters.} 29548 29549A nondispatching subprogram with an access parameter cannot be renamed 29550as a dispatching operation. This was permitted in Ada 95. 29551 29552@item 29553@emph{Access types, discriminants, and constraints.} 29554 29555Rule changes in this area have led to some incompatibilities; for example, 29556constrained subtypes of some access types are not permitted in Ada 2005. 29557 29558@item 29559@emph{Aggregates for limited types.} 29560 29561The allowance of aggregates for limited types in Ada 2005 raises the 29562possibility of ambiguities in legal Ada 95 programs, since additional types 29563now need to be considered in expression resolution. 29564 29565@item 29566@emph{Fixed-point multiplication and division.} 29567 29568Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which 29569were legal in Ada 95 and invoked the predefined versions of these operations, 29570are now ambiguous. 29571The ambiguity may be resolved either by applying a type conversion to the 29572expression, or by explicitly invoking the operation from package 29573@code{Standard}. 29574 29575@item 29576@emph{Return-by-reference types.} 29577 29578The Ada 95 return-by-reference mechanism has been removed. Instead, the user 29579can declare a function returning a value from an anonymous access type. 29580@end itemize 29581 29582@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide 29583@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{45c}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{45d} 29584@section Implementation-dependent characteristics 29585 29586 29587Although the Ada language defines the semantics of each construct as 29588precisely as practical, in some situations (for example for reasons of 29589efficiency, or where the effect is heavily dependent on the host or target 29590platform) the implementation is allowed some freedom. In porting Ada 83 29591code to GNAT, you need to be aware of whether / how the existing code 29592exercised such implementation dependencies. Such characteristics fall into 29593several categories, and GNAT offers specific support in assisting the 29594transition from certain Ada 83 compilers. 29595 29596@menu 29597* Implementation-defined pragmas:: 29598* Implementation-defined attributes:: 29599* Libraries:: 29600* Elaboration order:: 29601* Target-specific aspects:: 29602 29603@end menu 29604 29605@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics 29606@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{45f} 29607@subsection Implementation-defined pragmas 29608 29609 29610Ada compilers are allowed to supplement the language-defined pragmas, and 29611these are a potential source of non-portability. All GNAT-defined pragmas 29612are described in @ref{7,,Implementation Defined Pragmas}, 29613and these include several that are specifically 29614intended to correspond to other vendors’ Ada 83 pragmas. 29615For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. 29616For compatibility with HP Ada 83, GNAT supplies the pragmas 29617@code{Extend_System}, @code{Ident}, @code{Inline_Generic}, 29618@code{Interface_Name}, @code{Passive}, @code{Suppress_All}, 29619and @code{Volatile}. 29620Other relevant pragmas include @code{External} and @code{Link_With}. 29621Some vendor-specific 29622Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are 29623recognized, thus 29624avoiding compiler rejection of units that contain such pragmas; they are not 29625relevant in a GNAT context and hence are not otherwise implemented. 29626 29627@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics 29628@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{460}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{461} 29629@subsection Implementation-defined attributes 29630 29631 29632Analogous to pragmas, the set of attributes may be extended by an 29633implementation. All GNAT-defined attributes are described in 29634@ref{8,,Implementation Defined Attributes}, 29635and these include several that are specifically intended 29636to correspond to other vendors’ Ada 83 attributes. For migrating from VADS, 29637the attribute @code{VADS_Size} may be useful. For compatibility with HP 29638Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and 29639@code{Type_Class}. 29640 29641@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics 29642@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{462}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{463} 29643@subsection Libraries 29644 29645 29646Vendors may supply libraries to supplement the standard Ada API. If Ada 83 29647code uses vendor-specific libraries then there are several ways to manage 29648this in Ada 95 and later versions of the standard: 29649 29650 29651@itemize * 29652 29653@item 29654If the source code for the libraries (specs and bodies) are 29655available, then the libraries can be migrated in the same way as the 29656application. 29657 29658@item 29659If the source code for the specs but not the bodies are 29660available, then you can reimplement the bodies. 29661 29662@item 29663Some features introduced by Ada 95 obviate the need for library support. For 29664example most Ada 83 vendors supplied a package for unsigned integers. The 29665Ada 95 modular type feature is the preferred way to handle this need, so 29666instead of migrating or reimplementing the unsigned integer package it may 29667be preferable to retrofit the application using modular types. 29668@end itemize 29669 29670@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics 29671@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{464}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{465} 29672@subsection Elaboration order 29673 29674 29675The implementation can choose any elaboration order consistent with the unit 29676dependency relationship. This freedom means that some orders can result in 29677Program_Error being raised due to an ‘Access Before Elaboration’: an attempt 29678to invoke a subprogram before its body has been elaborated, or to instantiate 29679a generic before the generic body has been elaborated. By default GNAT 29680attempts to choose a safe order (one that will not encounter access before 29681elaboration problems) by implicitly inserting @code{Elaborate} or 29682@code{Elaborate_All} pragmas where 29683needed. However, this can lead to the creation of elaboration circularities 29684and a resulting rejection of the program by gnatbind. This issue is 29685thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix 29686in the @cite{GNAT User’s Guide}. 29687In brief, there are several 29688ways to deal with this situation: 29689 29690 29691@itemize * 29692 29693@item 29694Modify the program to eliminate the circularities, e.g., by moving 29695elaboration-time code into explicitly-invoked procedures 29696 29697@item 29698Constrain the elaboration order by including explicit @code{Elaborate_Body} or 29699@code{Elaborate} pragmas, and then inhibit the generation of implicit 29700@code{Elaborate_All} 29701pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally 29702(by selectively suppressing elaboration checks via pragma 29703@code{Suppress(Elaboration_Check)} when it is safe to do so). 29704@end itemize 29705 29706@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics 29707@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{466}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{467} 29708@subsection Target-specific aspects 29709 29710 29711Low-level applications need to deal with machine addresses, data 29712representations, interfacing with assembler code, and similar issues. If 29713such an Ada 83 application is being ported to different target hardware (for 29714example where the byte endianness has changed) then you will need to 29715carefully examine the program logic; the porting effort will heavily depend 29716on the robustness of the original design. Moreover, Ada 95 (and thus 29717Ada 2005 and Ada 2012) are sometimes 29718incompatible with typical Ada 83 compiler practices regarding implicit 29719packing, the meaning of the Size attribute, and the size of access values. 29720GNAT’s approach to these issues is described in @ref{468,,Representation Clauses}. 29721 29722@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide 29723@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{469}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{46a} 29724@section Compatibility with Other Ada Systems 29725 29726 29727If programs avoid the use of implementation dependent and 29728implementation defined features, as documented in the 29729@cite{Ada Reference Manual}, there should be a high degree of portability between 29730GNAT and other Ada systems. The following are specific items which 29731have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 29732compilers, but do not affect porting code to GNAT. 29733(As of January 2007, GNAT is the only compiler available for Ada 2005; 29734the following issues may or may not arise for Ada 2005 programs 29735when other compilers appear.) 29736 29737 29738@itemize * 29739 29740@item 29741@emph{Ada 83 Pragmas and Attributes} 29742 29743Ada 95 compilers are allowed, but not required, to implement the missing 29744Ada 83 pragmas and attributes that are no longer defined in Ada 95. 29745GNAT implements all such pragmas and attributes, eliminating this as 29746a compatibility concern, but some other Ada 95 compilers reject these 29747pragmas and attributes. 29748 29749@item 29750@emph{Specialized Needs Annexes} 29751 29752GNAT implements the full set of special needs annexes. At the 29753current time, it is the only Ada 95 compiler to do so. This means that 29754programs making use of these features may not be portable to other Ada 2975595 compilation systems. 29756 29757@item 29758@emph{Representation Clauses} 29759 29760Some other Ada 95 compilers implement only the minimal set of 29761representation clauses required by the Ada 95 reference manual. GNAT goes 29762far beyond this minimal set, as described in the next section. 29763@end itemize 29764 29765@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide 29766@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{46b}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{468} 29767@section Representation Clauses 29768 29769 29770The Ada 83 reference manual was quite vague in describing both the minimal 29771required implementation of representation clauses, and also their precise 29772effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the 29773minimal set of capabilities required is still quite limited. 29774 29775GNAT implements the full required set of capabilities in 29776Ada 95 and Ada 2005, but also goes much further, and in particular 29777an effort has been made to be compatible with existing Ada 83 usage to the 29778greatest extent possible. 29779 29780A few cases exist in which Ada 83 compiler behavior is incompatible with 29781the requirements in Ada 95 (and thus also Ada 2005). These are instances of 29782intentional or accidental dependence on specific implementation dependent 29783characteristics of these Ada 83 compilers. The following is a list of 29784the cases most likely to arise in existing Ada 83 code. 29785 29786 29787@itemize * 29788 29789@item 29790@emph{Implicit Packing} 29791 29792Some Ada 83 compilers allowed a Size specification to cause implicit 29793packing of an array or record. This could cause expensive implicit 29794conversions for change of representation in the presence of derived 29795types, and the Ada design intends to avoid this possibility. 29796Subsequent AI’s were issued to make it clear that such implicit 29797change of representation in response to a Size clause is inadvisable, 29798and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) 29799Reference Manuals as implementation advice that is followed by GNAT. 29800The problem will show up as an error 29801message rejecting the size clause. The fix is simply to provide 29802the explicit pragma @code{Pack}, or for more fine tuned control, provide 29803a Component_Size clause. 29804 29805@item 29806@emph{Meaning of Size Attribute} 29807 29808The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as 29809the minimal number of bits required to hold values of the type. For example, 29810on a 32-bit machine, the size of @code{Natural} will typically be 31 and not 2981132 (since no sign bit is required). Some Ada 83 compilers gave 31, and 29812some 32 in this situation. This problem will usually show up as a compile 29813time error, but not always. It is a good idea to check all uses of the 29814‘Size attribute when porting Ada 83 code. The GNAT specific attribute 29815Object_Size can provide a useful way of duplicating the behavior of 29816some Ada 83 compiler systems. 29817 29818@item 29819@emph{Size of Access Types} 29820 29821A common assumption in Ada 83 code is that an access type is in fact a pointer, 29822and that therefore it will be the same size as a System.Address value. This 29823assumption is true for GNAT in most cases with one exception. For the case of 29824a pointer to an unconstrained array type (where the bounds may vary from one 29825value of the access type to another), the default is to use a ‘fat pointer’, 29826which is represented as two separate pointers, one to the bounds, and one to 29827the array. This representation has a number of advantages, including improved 29828efficiency. However, it may cause some difficulties in porting existing Ada 83 29829code which makes the assumption that, for example, pointers fit in 32 bits on 29830a machine with 32-bit addressing. 29831 29832To get around this problem, GNAT also permits the use of ‘thin pointers’ for 29833access types in this case (where the designated type is an unconstrained array 29834type). These thin pointers are indeed the same size as a System.Address value. 29835To specify a thin pointer, use a size clause for the type, for example: 29836 29837@example 29838type X is access all String; 29839for X'Size use Standard'Address_Size; 29840@end example 29841 29842which will cause the type X to be represented using a single pointer. 29843When using this representation, the bounds are right behind the array. 29844This representation is slightly less efficient, and does not allow quite 29845such flexibility in the use of foreign pointers or in using the 29846Unrestricted_Access attribute to create pointers to non-aliased objects. 29847But for any standard portable use of the access type it will work in 29848a functionally correct manner and allow porting of existing code. 29849Note that another way of forcing a thin pointer representation 29850is to use a component size clause for the element size in an array, 29851or a record representation clause for an access field in a record. 29852 29853See the documentation of Unrestricted_Access in the GNAT RM for a 29854full discussion of possible problems using this attribute in conjunction 29855with thin pointers. 29856@end itemize 29857 29858@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide 29859@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{46c}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{46d} 29860@section Compatibility with HP Ada 83 29861 29862 29863All the HP Ada 83 pragmas and attributes are recognized, although only a subset 29864of them can sensibly be implemented. The description of pragmas in 29865@ref{7,,Implementation Defined Pragmas} indicates whether or not they are 29866applicable to GNAT. 29867 29868 29869@itemize * 29870 29871@item 29872@emph{Default floating-point representation} 29873 29874In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, 29875it is VMS format. 29876 29877@item 29878@emph{System} 29879 29880the package System in GNAT exactly corresponds to the definition in the 29881Ada 95 reference manual, which means that it excludes many of the 29882HP Ada 83 extensions. However, a separate package Aux_DEC is provided 29883that contains the additional definitions, and a special pragma, 29884Extend_System allows this package to be treated transparently as an 29885extension of package System. 29886@end itemize 29887 29888@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top 29889@anchor{share/gnu_free_documentation_license doc}@anchor{46e}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{46f} 29890@chapter GNU Free Documentation License 29891 29892 29893Version 1.3, 3 November 2008 29894 29895Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc 29896@indicateurl{http://fsf.org/} 29897 29898Everyone is permitted to copy and distribute verbatim copies of this 29899license document, but changing it is not allowed. 29900 29901@strong{Preamble} 29902 29903The purpose of this License is to make a manual, textbook, or other 29904functional and useful document “free” in the sense of freedom: to 29905assure everyone the effective freedom to copy and redistribute it, 29906with or without modifying it, either commercially or noncommercially. 29907Secondarily, this License preserves for the author and publisher a way 29908to get credit for their work, while not being considered responsible 29909for modifications made by others. 29910 29911This License is a kind of “copyleft”, which means that derivative 29912works of the document must themselves be free in the same sense. It 29913complements the GNU General Public License, which is a copyleft 29914license designed for free software. 29915 29916We have designed this License in order to use it for manuals for free 29917software, because free software needs free documentation: a free 29918program should come with manuals providing the same freedoms that the 29919software does. But this License is not limited to software manuals; 29920it can be used for any textual work, regardless of subject matter or 29921whether it is published as a printed book. We recommend this License 29922principally for works whose purpose is instruction or reference. 29923 29924@strong{1. APPLICABILITY AND DEFINITIONS} 29925 29926This License applies to any manual or other work, in any medium, that 29927contains a notice placed by the copyright holder saying it can be 29928distributed under the terms of this License. Such a notice grants a 29929world-wide, royalty-free license, unlimited in duration, to use that 29930work under the conditions stated herein. The @strong{Document}, below, 29931refers to any such manual or work. Any member of the public is a 29932licensee, and is addressed as “@strong{you}”. You accept the license if you 29933copy, modify or distribute the work in a way requiring permission 29934under copyright law. 29935 29936A “@strong{Modified Version}” of the Document means any work containing the 29937Document or a portion of it, either copied verbatim, or with 29938modifications and/or translated into another language. 29939 29940A “@strong{Secondary Section}” is a named appendix or a front-matter section of 29941the Document that deals exclusively with the relationship of the 29942publishers or authors of the Document to the Document’s overall subject 29943(or to related matters) and contains nothing that could fall directly 29944within that overall subject. (Thus, if the Document is in part a 29945textbook of mathematics, a Secondary Section may not explain any 29946mathematics.) The relationship could be a matter of historical 29947connection with the subject or with related matters, or of legal, 29948commercial, philosophical, ethical or political position regarding 29949them. 29950 29951The “@strong{Invariant Sections}” are certain Secondary Sections whose titles 29952are designated, as being those of Invariant Sections, in the notice 29953that says that the Document is released under this License. If a 29954section does not fit the above definition of Secondary then it is not 29955allowed to be designated as Invariant. The Document may contain zero 29956Invariant Sections. If the Document does not identify any Invariant 29957Sections then there are none. 29958 29959The “@strong{Cover Texts}” are certain short passages of text that are listed, 29960as Front-Cover Texts or Back-Cover Texts, in the notice that says that 29961the Document is released under this License. A Front-Cover Text may 29962be at most 5 words, and a Back-Cover Text may be at most 25 words. 29963 29964A “@strong{Transparent}” copy of the Document means a machine-readable copy, 29965represented in a format whose specification is available to the 29966general public, that is suitable for revising the document 29967straightforwardly with generic text editors or (for images composed of 29968pixels) generic paint programs or (for drawings) some widely available 29969drawing editor, and that is suitable for input to text formatters or 29970for automatic translation to a variety of formats suitable for input 29971to text formatters. A copy made in an otherwise Transparent file 29972format whose markup, or absence of markup, has been arranged to thwart 29973or discourage subsequent modification by readers is not Transparent. 29974An image format is not Transparent if used for any substantial amount 29975of text. A copy that is not “Transparent” is called @strong{Opaque}. 29976 29977Examples of suitable formats for Transparent copies include plain 29978ASCII without markup, Texinfo input format, LaTeX input format, SGML 29979or XML using a publicly available DTD, and standard-conforming simple 29980HTML, PostScript or PDF designed for human modification. Examples of 29981transparent image formats include PNG, XCF and JPG. Opaque formats 29982include proprietary formats that can be read and edited only by 29983proprietary word processors, SGML or XML for which the DTD and/or 29984processing tools are not generally available, and the 29985machine-generated HTML, PostScript or PDF produced by some word 29986processors for output purposes only. 29987 29988The “@strong{Title Page}” means, for a printed book, the title page itself, 29989plus such following pages as are needed to hold, legibly, the material 29990this License requires to appear in the title page. For works in 29991formats which do not have any title page as such, “Title Page” means 29992the text near the most prominent appearance of the work’s title, 29993preceding the beginning of the body of the text. 29994 29995The “@strong{publisher}” means any person or entity that distributes 29996copies of the Document to the public. 29997 29998A section “@strong{Entitled XYZ}” means a named subunit of the Document whose 29999title either is precisely XYZ or contains XYZ in parentheses following 30000text that translates XYZ in another language. (Here XYZ stands for a 30001specific section name mentioned below, such as “@strong{Acknowledgements}”, 30002“@strong{Dedications}”, “@strong{Endorsements}”, or “@strong{History}”.) 30003To “@strong{Preserve the Title}” 30004of such a section when you modify the Document means that it remains a 30005section “Entitled XYZ” according to this definition. 30006 30007The Document may include Warranty Disclaimers next to the notice which 30008states that this License applies to the Document. These Warranty 30009Disclaimers are considered to be included by reference in this 30010License, but only as regards disclaiming warranties: any other 30011implication that these Warranty Disclaimers may have is void and has 30012no effect on the meaning of this License. 30013 30014@strong{2. VERBATIM COPYING} 30015 30016You may copy and distribute the Document in any medium, either 30017commercially or noncommercially, provided that this License, the 30018copyright notices, and the license notice saying this License applies 30019to the Document are reproduced in all copies, and that you add no other 30020conditions whatsoever to those of this License. You may not use 30021technical measures to obstruct or control the reading or further 30022copying of the copies you make or distribute. However, you may accept 30023compensation in exchange for copies. If you distribute a large enough 30024number of copies you must also follow the conditions in section 3. 30025 30026You may also lend copies, under the same conditions stated above, and 30027you may publicly display copies. 30028 30029@strong{3. COPYING IN QUANTITY} 30030 30031If you publish printed copies (or copies in media that commonly have 30032printed covers) of the Document, numbering more than 100, and the 30033Document’s license notice requires Cover Texts, you must enclose the 30034copies in covers that carry, clearly and legibly, all these Cover 30035Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 30036the back cover. Both covers must also clearly and legibly identify 30037you as the publisher of these copies. The front cover must present 30038the full title with all words of the title equally prominent and 30039visible. You may add other material on the covers in addition. 30040Copying with changes limited to the covers, as long as they preserve 30041the title of the Document and satisfy these conditions, can be treated 30042as verbatim copying in other respects. 30043 30044If the required texts for either cover are too voluminous to fit 30045legibly, you should put the first ones listed (as many as fit 30046reasonably) on the actual cover, and continue the rest onto adjacent 30047pages. 30048 30049If you publish or distribute Opaque copies of the Document numbering 30050more than 100, you must either include a machine-readable Transparent 30051copy along with each Opaque copy, or state in or with each Opaque copy 30052a computer-network location from which the general network-using 30053public has access to download using public-standard network protocols 30054a complete Transparent copy of the Document, free of added material. 30055If you use the latter option, you must take reasonably prudent steps, 30056when you begin distribution of Opaque copies in quantity, to ensure 30057that this Transparent copy will remain thus accessible at the stated 30058location until at least one year after the last time you distribute an 30059Opaque copy (directly or through your agents or retailers) of that 30060edition to the public. 30061 30062It is requested, but not required, that you contact the authors of the 30063Document well before redistributing any large number of copies, to give 30064them a chance to provide you with an updated version of the Document. 30065 30066@strong{4. MODIFICATIONS} 30067 30068You may copy and distribute a Modified Version of the Document under 30069the conditions of sections 2 and 3 above, provided that you release 30070the Modified Version under precisely this License, with the Modified 30071Version filling the role of the Document, thus licensing distribution 30072and modification of the Modified Version to whoever possesses a copy 30073of it. In addition, you must do these things in the Modified Version: 30074 30075 30076@enumerate A 30077 30078@item 30079Use in the Title Page (and on the covers, if any) a title distinct 30080from that of the Document, and from those of previous versions 30081(which should, if there were any, be listed in the History section 30082of the Document). You may use the same title as a previous version 30083if the original publisher of that version gives permission. 30084 30085@item 30086List on the Title Page, as authors, one or more persons or entities 30087responsible for authorship of the modifications in the Modified 30088Version, together with at least five of the principal authors of the 30089Document (all of its principal authors, if it has fewer than five), 30090unless they release you from this requirement. 30091 30092@item 30093State on the Title page the name of the publisher of the 30094Modified Version, as the publisher. 30095 30096@item 30097Preserve all the copyright notices of the Document. 30098 30099@item 30100Add an appropriate copyright notice for your modifications 30101adjacent to the other copyright notices. 30102 30103@item 30104Include, immediately after the copyright notices, a license notice 30105giving the public permission to use the Modified Version under the 30106terms of this License, in the form shown in the Addendum below. 30107 30108@item 30109Preserve in that license notice the full lists of Invariant Sections 30110and required Cover Texts given in the Document’s license notice. 30111 30112@item 30113Include an unaltered copy of this License. 30114 30115@item 30116Preserve the section Entitled “History”, Preserve its Title, and add 30117to it an item stating at least the title, year, new authors, and 30118publisher of the Modified Version as given on the Title Page. If 30119there is no section Entitled “History” in the Document, create one 30120stating the title, year, authors, and publisher of the Document as 30121given on its Title Page, then add an item describing the Modified 30122Version as stated in the previous sentence. 30123 30124@item 30125Preserve the network location, if any, given in the Document for 30126public access to a Transparent copy of the Document, and likewise 30127the network locations given in the Document for previous versions 30128it was based on. These may be placed in the “History” section. 30129You may omit a network location for a work that was published at 30130least four years before the Document itself, or if the original 30131publisher of the version it refers to gives permission. 30132 30133@item 30134For any section Entitled “Acknowledgements” or “Dedications”, 30135Preserve the Title of the section, and preserve in the section all 30136the substance and tone of each of the contributor acknowledgements 30137and/or dedications given therein. 30138 30139@item 30140Preserve all the Invariant Sections of the Document, 30141unaltered in their text and in their titles. Section numbers 30142or the equivalent are not considered part of the section titles. 30143 30144@item 30145Delete any section Entitled “Endorsements”. Such a section 30146may not be included in the Modified Version. 30147 30148@item 30149Do not retitle any existing section to be Entitled “Endorsements” 30150or to conflict in title with any Invariant Section. 30151 30152@item 30153Preserve any Warranty Disclaimers. 30154@end enumerate 30155 30156If the Modified Version includes new front-matter sections or 30157appendices that qualify as Secondary Sections and contain no material 30158copied from the Document, you may at your option designate some or all 30159of these sections as invariant. To do this, add their titles to the 30160list of Invariant Sections in the Modified Version’s license notice. 30161These titles must be distinct from any other section titles. 30162 30163You may add a section Entitled “Endorsements”, provided it contains 30164nothing but endorsements of your Modified Version by various 30165parties—for example, statements of peer review or that the text has 30166been approved by an organization as the authoritative definition of a 30167standard. 30168 30169You may add a passage of up to five words as a Front-Cover Text, and a 30170passage of up to 25 words as a Back-Cover Text, to the end of the list 30171of Cover Texts in the Modified Version. Only one passage of 30172Front-Cover Text and one of Back-Cover Text may be added by (or 30173through arrangements made by) any one entity. If the Document already 30174includes a cover text for the same cover, previously added by you or 30175by arrangement made by the same entity you are acting on behalf of, 30176you may not add another; but you may replace the old one, on explicit 30177permission from the previous publisher that added the old one. 30178 30179The author(s) and publisher(s) of the Document do not by this License 30180give permission to use their names for publicity for or to assert or 30181imply endorsement of any Modified Version. 30182 30183@strong{5. COMBINING DOCUMENTS} 30184 30185You may combine the Document with other documents released under this 30186License, under the terms defined in section 4 above for modified 30187versions, provided that you include in the combination all of the 30188Invariant Sections of all of the original documents, unmodified, and 30189list them all as Invariant Sections of your combined work in its 30190license notice, and that you preserve all their Warranty Disclaimers. 30191 30192The combined work need only contain one copy of this License, and 30193multiple identical Invariant Sections may be replaced with a single 30194copy. If there are multiple Invariant Sections with the same name but 30195different contents, make the title of each such section unique by 30196adding at the end of it, in parentheses, the name of the original 30197author or publisher of that section if known, or else a unique number. 30198Make the same adjustment to the section titles in the list of 30199Invariant Sections in the license notice of the combined work. 30200 30201In the combination, you must combine any sections Entitled “History” 30202in the various original documents, forming one section Entitled 30203“History”; likewise combine any sections Entitled “Acknowledgements”, 30204and any sections Entitled “Dedications”. You must delete all sections 30205Entitled “Endorsements”. 30206 30207@strong{6. COLLECTIONS OF DOCUMENTS} 30208 30209You may make a collection consisting of the Document and other documents 30210released under this License, and replace the individual copies of this 30211License in the various documents with a single copy that is included in 30212the collection, provided that you follow the rules of this License for 30213verbatim copying of each of the documents in all other respects. 30214 30215You may extract a single document from such a collection, and distribute 30216it individually under this License, provided you insert a copy of this 30217License into the extracted document, and follow this License in all 30218other respects regarding verbatim copying of that document. 30219 30220@strong{7. AGGREGATION WITH INDEPENDENT WORKS} 30221 30222A compilation of the Document or its derivatives with other separate 30223and independent documents or works, in or on a volume of a storage or 30224distribution medium, is called an “aggregate” if the copyright 30225resulting from the compilation is not used to limit the legal rights 30226of the compilation’s users beyond what the individual works permit. 30227When the Document is included in an aggregate, this License does not 30228apply to the other works in the aggregate which are not themselves 30229derivative works of the Document. 30230 30231If the Cover Text requirement of section 3 is applicable to these 30232copies of the Document, then if the Document is less than one half of 30233the entire aggregate, the Document’s Cover Texts may be placed on 30234covers that bracket the Document within the aggregate, or the 30235electronic equivalent of covers if the Document is in electronic form. 30236Otherwise they must appear on printed covers that bracket the whole 30237aggregate. 30238 30239@strong{8. TRANSLATION} 30240 30241Translation is considered a kind of modification, so you may 30242distribute translations of the Document under the terms of section 4. 30243Replacing Invariant Sections with translations requires special 30244permission from their copyright holders, but you may include 30245translations of some or all Invariant Sections in addition to the 30246original versions of these Invariant Sections. You may include a 30247translation of this License, and all the license notices in the 30248Document, and any Warranty Disclaimers, provided that you also include 30249the original English version of this License and the original versions 30250of those notices and disclaimers. In case of a disagreement between 30251the translation and the original version of this License or a notice 30252or disclaimer, the original version will prevail. 30253 30254If a section in the Document is Entitled “Acknowledgements”, 30255“Dedications”, or “History”, the requirement (section 4) to Preserve 30256its Title (section 1) will typically require changing the actual 30257title. 30258 30259@strong{9. TERMINATION} 30260 30261You may not copy, modify, sublicense, or distribute the Document 30262except as expressly provided under this License. Any attempt 30263otherwise to copy, modify, sublicense, or distribute it is void, and 30264will automatically terminate your rights under this License. 30265 30266However, if you cease all violation of this License, then your license 30267from a particular copyright holder is reinstated (a) provisionally, 30268unless and until the copyright holder explicitly and finally 30269terminates your license, and (b) permanently, if the copyright holder 30270fails to notify you of the violation by some reasonable means prior to 3027160 days after the cessation. 30272 30273Moreover, your license from a particular copyright holder is 30274reinstated permanently if the copyright holder notifies you of the 30275violation by some reasonable means, this is the first time you have 30276received notice of violation of this License (for any work) from that 30277copyright holder, and you cure the violation prior to 30 days after 30278your receipt of the notice. 30279 30280Termination of your rights under this section does not terminate the 30281licenses of parties who have received copies or rights from you under 30282this License. If your rights have been terminated and not permanently 30283reinstated, receipt of a copy of some or all of the same material does 30284not give you any rights to use it. 30285 30286@strong{10. FUTURE REVISIONS OF THIS LICENSE} 30287 30288The Free Software Foundation may publish new, revised versions 30289of the GNU Free Documentation License from time to time. Such new 30290versions will be similar in spirit to the present version, but may 30291differ in detail to address new problems or concerns. See 30292@indicateurl{http://www.gnu.org/copyleft/}. 30293 30294Each version of the License is given a distinguishing version number. 30295If the Document specifies that a particular numbered version of this 30296License “or any later version” applies to it, you have the option of 30297following the terms and conditions either of that specified version or 30298of any later version that has been published (not as a draft) by the 30299Free Software Foundation. If the Document does not specify a version 30300number of this License, you may choose any version ever published (not 30301as a draft) by the Free Software Foundation. If the Document 30302specifies that a proxy can decide which future versions of this 30303License can be used, that proxy’s public statement of acceptance of a 30304version permanently authorizes you to choose that version for the 30305Document. 30306 30307@strong{11. RELICENSING} 30308 30309“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any 30310World Wide Web server that publishes copyrightable works and also 30311provides prominent facilities for anybody to edit those works. A 30312public wiki that anybody can edit is an example of such a server. A 30313“Massive Multiauthor Collaboration” (or “MMC”) contained in the 30314site means any set of copyrightable works thus published on the MMC 30315site. 30316 30317“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 30318license published by Creative Commons Corporation, a not-for-profit 30319corporation with a principal place of business in San Francisco, 30320California, as well as future copyleft versions of that license 30321published by that same organization. 30322 30323“Incorporate” means to publish or republish a Document, in whole or 30324in part, as part of another Document. 30325 30326An MMC is “eligible for relicensing” if it is licensed under this 30327License, and if all works that were first published under this License 30328somewhere other than this MMC, and subsequently incorporated in whole 30329or in part into the MMC, (1) had no cover texts or invariant sections, 30330and (2) were thus incorporated prior to November 1, 2008. 30331 30332The operator of an MMC Site may republish an MMC contained in the site 30333under CC-BY-SA on the same site at any time before August 1, 2009, 30334provided the MMC is eligible for relicensing. 30335 30336@strong{ADDENDUM: How to use this License for your documents} 30337 30338To use this License in a document you have written, include a copy of 30339the License in the document and put the following copyright and 30340license notices just after the title page: 30341 30342@quotation 30343 30344Copyright © YEAR YOUR NAME. 30345Permission is granted to copy, distribute and/or modify this document 30346under the terms of the GNU Free Documentation License, Version 1.3 30347or any later version published by the Free Software Foundation; 30348with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 30349A copy of the license is included in the section entitled “GNU 30350Free Documentation License”. 30351@end quotation 30352 30353If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 30354replace the “with … Texts.” line with this: 30355 30356@quotation 30357 30358with the Invariant Sections being LIST THEIR TITLES, with the 30359Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 30360@end quotation 30361 30362If you have Invariant Sections without Cover Texts, or some other 30363combination of the three, merge those two alternatives to suit the 30364situation. 30365 30366If your document contains nontrivial examples of program code, we 30367recommend releasing these examples in parallel under your choice of 30368free software license, such as the GNU General Public License, 30369to permit their use in free software. 30370 30371@node Index,,GNU Free Documentation License,Top 30372@unnumbered Index 30373 30374 30375@printindex ge 30376 30377 30378@c %**end of body 30379@bye 30380